# 前端开发规格

前端是 `zhixing-web/` 下的 React 19 + TypeScript + Vite 应用，使用 TanStack Router、TanStack Query、Zustand、Tailwind CSS 4 和 Vitest。代码采用 feature 垂直切片；当前只有 `system` feature。

## 规格导航

| 规格 | 用途 |
| --- | --- |
| [目录与 feature 边界](./directory-structure.md) | `app`、`routes`、`features`、`shared` 的职责 |
| [组件与样式](./component-guidelines.md) | 函数组件、组合、Tailwind、可访问性 |
| [Hook 与数据请求](./hook-guidelines.md) | React Query API 适配和 hook 结构 |
| [状态管理](./state-management.md) | Query、Zustand 与局部状态的边界 |
| [类型安全](./type-safety.md) | 严格 TypeScript、API 类型和类型断言 |
| [质量与测试](./quality-guidelines.md) | Prettier、ESLint、Vitest、构建门禁 |

## 开发前检查

- 先判断代码属于某个 feature 还是跨 feature 的 shared 能力；不要把业务代码放进 `shared/`。
- API 字段变更时，同时检查后端 Pydantic 响应模型、`features/<name>/api/*.types.ts`、query hook 和页面测试。
- 通过 `/api/v1` 同源路径请求后端。开发代理见 `vite.config.ts`，生产代理见 `nginx/default.conf.template`。
- 先搜索已有的 `cn`、`requestJson`、query key 和 UI primitive，再创建新 helper。

## 质量检查

在 `zhixing-web/` 下运行：

```bash
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
```

根目录 `./dev.sh check` 和 `./dev.sh test` 会执行完整前后端检查。