Simplify system implementation

2026-08-04 18:59:21 +08:00
parent bf8da90433
commit ee0064135c
19 changed files with 418 additions and 1169 deletions
@@ -1,51 +1,35 @@
-# Quality Guidelines
+# 前端质量与测试

-> Code quality standards for frontend development.
+## 工具链与门禁

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

-## Overview
+- `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 的顺序执行。

-<!--
-Document your project's quality standards here.
+提交前运行 `pnpm check`，需要验证产物时再运行 `pnpm build`。根目录 `./dev.sh check` 会把前端检查与后端检查串起来。

-Questions to answer:
- What patterns are forbidden?
- What linting rules do you enforce?
- What are your testing requirements?
- What code review standards apply?
-->
+## 测试形状

-(To be filled by the team)
+- 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 内部实现。
+- 新增加载、错误或空数据分支时，至少为关键用户可见状态添加测试。

---
+## 代码审查检查项

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

-<!-- Patterns that should never be used and why -->
+## 禁止模式

-(To be filled by the team)
-
---
-
-## Required Patterns
-
-<!-- Patterns that must always be used -->
-
-(To be filled by the team)
-
---
-
-## Testing Requirements
-
-<!-- What level of testing is expected -->
-
-(To be filled by the team)
-
---
-
-## Code Review Checklist
-
-<!-- What reviewers should check -->
-
-(To be filled by the team)
+- 不要提交格式化、lint、类型检查或测试失败的代码，也不要用 `eslint-disable`/`@ts-ignore` 隐藏问题而不说明原因。
+- 不要用实现细节选择器（例如依赖 class 名）替代 Testing Library 的角色、文本或可访问名称。
+- 不要在测试中复制被测逻辑或只断言组件成功挂载；断言真实用户可见结果。