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 的角色、文本或可访问名称。
• 不要在测试中复制被测逻辑或只断言组件成功挂载；断言真实用户可见结果。