zhixing-system/.trellis/spec/frontend/quality-guidelines.md

# 前端质量与测试

## 工具链与门禁

`zhixing-web/package.json` 定义以下命令：

- `pnpm format:check`：Prettier 格式检查。
- `pnpm lint`：ESLint，`--max-warnings=0`；React Hooks 规则启用。
- `pnpm typecheck`：`tsc -b --pretty false`。
- `pnpm test`：Vitest 单次运行。
- `pnpm build`：TypeScript project build 后执行 Vite build。
- `pnpm check`：按 format、lint、typecheck、test 的顺序执行。

提交前运行 `pnpm check`，需要验证产物时再运行 `pnpm build`。根目录 `./dev.sh check` 会把前端检查与后端检查串起来。

## 测试形状

- Vitest 使用 `jsdom`，公共初始化在 `src/test/setup.ts`，加载 `@testing-library/jest-dom/vitest`。
- React 页面使用 Testing Library 从用户可见行为断言，参照 `features/system/pages/system-status-page.test.tsx`。
- 页面测试通过 `vi.mock` 替换 feature query hook，并在 `beforeEach` 设置稳定的 query 返回值；测试渲染和文案，不测试 React Query 内部实现。
- 新增加载、错误或空数据分支时，至少为关键用户可见状态添加测试。

## 代码审查检查项

- API 请求是否仍经过 `shared/api/request-json.ts`，并使用同源 `/api/v1` 路径？
- 服务器状态是否留在 React Query，UI 偏好是否只放入必要的 Zustand store？
- 是否保持 strict TypeScript、无 unused、无 lint warning？
- 交互元素是否有语义标签、键盘可用性和必要的 aria 文本？
- feature/shared 边界是否清楚，是否复用了现有 `cn` 和 UI primitive？

## 禁止模式

- 不要提交格式化、lint、类型检查或测试失败的代码，也不要用 `eslint-disable`/`@ts-ignore` 隐藏问题而不说明原因。
- 不要用实现细节选择器（例如依赖 class 名）替代 Testing Library 的角色、文本或可访问名称。
- 不要在测试中复制被测逻辑或只断言组件成功挂载；断言真实用户可见结果。