zhixing-system/.trellis/spec/frontend/directory-structure.md

前端目录与 feature 边界

当前布局

zhixing-web/src/
├── app/                         # Provider、Router、QueryClient、应用壳
│   ├── app.tsx
│   ├── providers.tsx
│   ├── query-client.ts
│   └── router.tsx
├── routes/route-tree.tsx        # TanStack Router 路由树
├── features/system/             # system 垂直切片
│   ├── api/                     # request adapter、query、API 类型
│   └── pages/                   # 页面组件和同目录测试
├── shared/
│   ├── api/request-json.ts      # 同源 JSON transport 和 ApiError
│   ├── config/ui-store.ts       # 持久化 UI 偏好
│   └── ui/                      # 可复用的 Button、Card、Badge、cn
├── styles/globals.css           # Tailwind 主题和全局基础样式
└── test/setup.ts                # Vitest + Testing Library 初始化

@/* 映射到 src/*，在源码跨目录导入时使用该 alias；配置文件和同目录相对导入保持现有风格。

Feature 组织

每个业务 feature 将 API 适配、类型和页面放在自己的目录，例如 features/system/api/system.api.ts、system.query.ts、system.types.ts 和 pages/system-status-page.tsx。页面可以依赖本 feature 的 API 和 shared，但 shared 不能反向依赖 feature。

路由只负责把路径映射到页面。当前 routes/route-tree.tsx 将 / 映射到 SystemStatusPage；不要把请求逻辑或全局状态初始化塞进路由声明。

命名

• React 组件和页面使用 PascalCase 导出，文件使用 kebab-case，例如 system-status-page.tsx。
• feature API 文件按职责使用 *.api.ts、*.query.ts、*.types.ts。
• shared UI primitive 使用小写文件名并导出 PascalCase 组件，例如 button.tsx 导出 Button。
• 测试与被测模块同目录，使用 .test.tsx 或 .test.ts。

反模式

• 不要创建一个全局 components/、hooks/ 或 services/ 目录来掩盖 feature 所有权。
• 不要让页面直接 import 远端 URL、调用 fetch 或保存 React Query 数据到 Zustand。
• 不要通过 ../../.. 穿透 feature 边界；优先使用 @/features/... 或 @/shared/...。