achra-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Achra Guidelines

Achra 指南

Overview

概述

Achra platform guidelines for architecture, conventions, business domains, and technical patterns. This skill covers where code lives, how to name and structure it, when to use feature flags, and how domains and routes map.

WIP: These guidelines are a draft. When a task is not covered here or in linked references, prefer consistency with existing Achra code and patterns.

Achra平台在架构、约定、业务领域及技术模式方面的指南。本指南涵盖代码存放位置、命名与结构方式、功能标志的使用时机，以及领域与路由的映射关系。

注意： 本指南为草稿版本。若某项任务未在本指南或关联参考文档中提及，请优先与现有Achra代码及模式保持一致。

When to Apply

适用场景

Reference these guidelines when:

Writing new code in the Achra codebase (components, pages, services, hooks, providers, etc)
Creating skeleton loaders, loading placeholders, Suspense fallbacks, or Next.js loading.tsx
Refactoring or reviewing code for Achra consistency
Adding a new module, feature, or route
Answering questions about Achra architecture, business domains, or conventions
Deciding where to place a component or whether to add a feature flag
Answering questions about Achra's tech stack or choosing libraries/tools

在以下场景中参考本指南：

在Achra代码库中编写新代码（组件、页面、服务、Hooks、Providers等）
创建骨架加载器、加载占位符、Suspense回退组件或Next.js的loading.tsx文件
重构或评审代码以确保与Achra规范一致
添加新模块、功能或路由
解答关于Achra架构、业务领域或约定的问题
决定组件的存放位置或是否添加功能标志
解答关于Achra技术栈或选择库/工具的问题

Quick Reference

快速参考

Topic	Rule	Details
Module placement	Shared vs domain, promotion rules	Used in 2+ modules or app root → check Promotion rules; single domain → `modules/{domain}/` . See architecture.md.
Naming	kebab-case	Files and directories: `component-name.tsx` , `use-hook-name.ts` . See conventions.md.
Components	Directory + index	One dir per component; one component per file (subcomponents in separate files). Helpers in lib/utils, not in component files. Named function, named export. See conventions.md.
Feature flags	Shared, env-specific	`modules/shared/lib/feature-flags/` . Use for gating domains/sections (workstreams, finances, roadmaps). See feature-flags-and-env.md.
Data / GraphQL	Domain graphql, generated	Queries in `modules/<domain>/graphql/*.graphql` ; generated in `modules/__generated__/graphql/` . See data-and-graphql.md.
Types	Props in file; reusable at module root	conventions.md
Tech stack	Next 16, React 19, TS, Tailwind 4, shadcn, GraphQL + TanStack Query	Framework, UI, data, forms, and tooling. See tech-stack.md.
Skeleton loading	Mirror layout with Skeleton	Use `Skeleton` from `@/shared/components/ui/skeleton` ; place `*-skeleton.tsx` next to source component. See skeleton-loading.md.

主题	规则	详情
模块放置	共享模块 vs 领域模块，晋升规则	若在2个及以上模块或应用根目录中使用 → 查看晋升规则；仅单个领域使用 → `modules/{domain}/` 。详见architecture.md。
命名规范	短横线分隔命名（kebab-case）	文件与目录： `component-name.tsx` 、 `use-hook-name.ts` 。详见conventions.md。
组件规范	单组件单目录 + 索引文件	每个组件对应一个目录；每个文件仅包含一个组件（子组件存放在单独文件中）。工具函数放在lib/utils中，而非组件文件内。使用命名函数与命名导出。详见conventions.md。
功能标志	共享、环境特定	存放于 `modules/shared/lib/feature-flags/` 。用于控制领域/模块的访问（如工作流、财务、路线图）。详见feature-flags-and-env.md。
数据 / GraphQL	领域专属GraphQL，代码生成	查询语句存放在 `modules/<domain>/graphql/*.graphql` ；生成的代码存放在 `modules/__generated__/graphql/` 。详见data-and-graphql.md。
类型定义	组件Props在文件内定义；可复用类型放在模块根目录	详见conventions.md
技术栈	Next 16, React 19, TS, Tailwind 4, shadcn, GraphQL + TanStack Query	包含框架、UI、数据、表单及工具链。详见tech-stack.md。
骨架加载	用Skeleton组件镜像布局	使用 `@/shared/components/ui/skeleton` 中的 `Skeleton` 组件；将 `*-skeleton.tsx` 文件与源组件放在同一目录下。详见skeleton-loading.md。

Skeleton loading

骨架加载

Skeleton loading is an Achra pattern for loading states. Use it for route loading (

loading.tsx

), Suspense fallbacks, or any placeholder that should match the final layout to avoid shift.

Workflow: Locate the target UI → create a sibling

{component-name}-skeleton.tsx

→ mirror structure and replace content with

Skeleton

elements sized to match → remove interactivity and data logic → validate layout parity and contrast.

Quick checklist:

Mirror layout containers and responsive classes (
```
sm:
```
,
```
md:
```
, etc.).
Replace text with
```
Skeleton
```
using line-height-derived heights; for multi-line with
```
gap-1
```
, subtract 2px per line to prevent layout shift.
Remove buttons, links, state, effects, and data fetching.
Use
```
bg-border
```
on skeletons inside
```
bg-accent
```
,
```
bg-muted
```
, or
```
bg-secondary
```
.
Reuse existing skeleton subcomponents when available.

Required import:

import { Skeleton } from '@/shared/components/ui/skeleton'

Full rules, sizing, contrast, and accessibility: skeleton-loading.md. Patterns and examples: skeleton-loading-examples.md.

骨架加载是Achra用于处理加载状态的模式。适用于路由加载（

loading.tsx

）、Suspense回退组件，或任何需要匹配最终布局以避免布局偏移的占位符。

工作流程： 定位目标UI → 创建同级文件

{component-name}-skeleton.tsx

→ 镜像原结构并将内容替换为尺寸匹配的

Skeleton

元素 → 移除交互性与数据逻辑 → 验证布局一致性与对比度。

快速检查清单：

镜像布局容器与响应式类（
```
sm:
```
、
```
md:
```
等）。
用基于行高的高度设置
```
Skeleton
```
替换文本；对于使用
```
gap-1
```
的多行文本，每行减去2px以防止布局偏移。
移除按钮、链接、状态、副作用及数据请求逻辑。
在
```
bg-accent
```
、
```
bg-muted
```
或
```
bg-secondary
```
背景内的骨架使用
```
bg-border
```
样式。
若已有可复用的骨架子组件，请直接复用。

必填导入：

import { Skeleton } from '@/shared/components/ui/skeleton'

完整规则、尺寸设置、对比度及无障碍访问要求：skeleton-loading.md。模式与示例：skeleton-loading-examples.md。

References

参考文档

Full documentation:

achra-overview.md — Business and product context; main domains and where they live
architecture.md — Module layout, shared vs domain, promotion rules, placement decision tree, imports
conventions.md — Naming, component directories, exports
feature-flags-and-env.md — When and where to use feature flags; env behavior
data-and-graphql.md — GraphQL and services location; generated code
tech-stack.md — Framework, UI, data, forms, and tooling used in the project
skeleton-loading.md — Skeleton loaders: layout mirroring, sizing, contrast, cleanup, validation
skeleton-loading-examples.md — Skeleton patterns and code examples
achra-guidelines.md — Human-facing index with table of contents and links
rules/ — Granular rules (arch-, conv-, ff-, data-)

完整文档：

achra-overview.md — 业务与产品背景；主要领域及其存放位置
architecture.md — 模块布局、共享模块vs领域模块、晋升规则、放置决策树、导入规范
conventions.md — 命名、组件目录、导出规范
feature-flags-and-env.md — 功能标志的使用时机与位置；环境行为
data-and-graphql.md — GraphQL与服务的存放位置；生成代码
tech-stack.md — 项目使用的框架、UI、数据、表单及工具链
skeleton-loading.md — 骨架加载器：布局镜像、尺寸设置、对比度、清理、验证
skeleton-loading-examples.md — 骨架加载模式与代码示例
achra-guidelines.md — 面向开发者的索引，含目录与链接
rules/ — 细分规则（架构、约定、功能标志、数据相关）