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

# 前端目录与 feature 边界

## 当前布局

```text
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/...`。