From 3f341aeaebc0f0c1103ed48d8061952b57f274ac Mon Sep 17 00:00:00 2001 From: zichun Date: Fri, 15 May 2026 18:23:45 +0800 Subject: [PATCH] docs(frontend-phase): add completion report --- docs/superpowers/module-reports/2026-05-15-frontend-phase.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+), 0 deletions(-) create mode 100644 docs/superpowers/module-reports/2026-05-15-frontend-phase.md diff --git a/docs/superpowers/module-reports/2026-05-15-frontend-phase.md b/docs/superpowers/module-reports/2026-05-15-frontend-phase.md new file mode 100644 index 0000000..fd8def2 --- /dev/null +++ b/docs/superpowers/module-reports/2026-05-15-frontend-phase.md @@ -0,0 +1,123 @@ +--- +module_id: frontend-phase +date: 2026-05-15 +git_range: a6d4ac9 (docs/08 § 三 FE 清单 + 落入 prototype) ↔ 410ca8a (test-gate evidence) +--- + +# 模块完成报告 — frontend-phase 前端阶段（整体） + +## ① 模块信息 +- 模块 ID: frontend-phase +- 模块名: 前端阶段（整体） +- 开发区间: 2026-05-15 单日，FE-01 → FE-02 +- 分支: frontend-phase + +## ② FE 完成清单 + +- [x] FE-01 — 用户登录 + - spec: docs/superpowers/specs/2026-05-15-FE-01.md + - plan: docs/superpowers/plans/2026-05-15-FE-01.md + - review: docs/superpowers/reviews/2026-05-15-FE-01.md +- [x] FE-02 — 用户管理（列表 + 新增 / 编辑） + - spec: docs/superpowers/specs/2026-05-15-FE-02.md + - plan: docs/superpowers/plans/2026-05-15-FE-02.md + - review: docs/superpowers/reviews/2026-05-15-FE-02.md + +## ③ 文件变更表 + +| 文件 | 操作 | 说明 | +|---|---|---| +| `frontend/package.json` / `tsconfig.json` / `vite.config.ts` / `vitest.config.ts` / `playwright.config.ts` / `index.html` / `.gitignore` | Create | Vite 5 + React 18 + TS 5 + Vitest 2 + Playwright 1.x 项目骨架（FE-01 引入） | +| `frontend/src/main.tsx` / `App.tsx` | Create | 入口；Redux Provider + AntD ConfigProvider + RouterProvider | +| `frontend/src/styles/{tokens.css, global.css}` | Create | tokens.css 与 docs/06 § 二 SSoT 全量对齐（含 16 个 canonical token） | +| `frontend/src/api/{client.ts, errors.ts, auth.ts, users.ts}` | Create | Axios 统一实例 + BizError 拦截器 + authApi + usersApi 4 个函数 | +| `frontend/src/store/{index.ts, hooks.ts, slices/authSlice.ts}` | Create | Redux Toolkit + typed hooks + auth slice（accessToken + userInfo + status） | +| `frontend/src/router/{index.tsx, RequireAuth.tsx, RequireSuperAdmin.tsx}` | Create | createBrowserRouter + 两级守卫；/login + /users(\*) 路由表 | +| `frontend/src/pages/login/{LoginPage,LoginForm,LoginHero,LoginFooter,loginConstants}.tsx` | Create | FE-01 登录页 + 表单 + hero + footer | +| `frontend/src/pages/users/{UsersListPage,UsersToolbar,UsersFilterBar,UsersTable,UserFormPage,UserFormFields,UserPermissionPanel,usersConstants}.{ts,tsx}` | Create | FE-02 列表 / 新增 / 编辑全套组件 + 常量 | +| `frontend/src/test-utils/{setup.ts, msw-handlers.ts}` | Create | Vitest setup（jest-dom + jsdom polyfills + MSW server）；MSW 拦截 6 个后端端点 | +| `frontend/src/App.test.tsx` 等 9 个 `*.test.tsx/ts` | Create | 44 个 vitest 单测覆盖 API / Redux / 路由守卫 / 页面集成 | +| `frontend/tests/e2e/{login,users}.spec.ts` | Create | 6 个 Playwright spec，`test.fixme()` 标记延后手工验收 | +| `docs/08-模块任务管理.md` | Modify | § 三 FE 清单写入（FE-01 + FE-02）+ 后续 review 勾选 | +| `prototype/erp.html` | Add | 850 行 HTML mockup（之前未入库，本阶段开始时落入 frontend-phase 分支） | + +> 文件总数：48 个新建 + 1 个修改；约 7475 行净增（含 prototype）。 + +## ④ 数据库使用表 + +N/A（前端阶段） + +## ⑤ 测试结果 + +- `npm test` (vitest) 最终: GREEN（详见 `docs/superpowers/module-reports/frontend-phase-test-gate.md`） +- 通过: 44 / 失败: 0 / 跳过: 0（vitest） +- Playwright E2E: 6 个 spec 全部 `test.fixme()` 跳过，留作手工验收（需 `npx playwright install` + 启 backend 9090） +- 覆盖率: 未配置；spec 验收覆盖： + - FE-01: 8 个 LoginPage 测试 + a11y + 锁定 disabled + 空字段必填 + JwtUtil/auth API 单测 + - FE-02: 7 个 UserFormPage 测试（create + edit + canEditDocument prefill + 40401 / 40901 等错误码）+ 4 个 UsersListPage 测试 + 7 个 usersApi + 3 个 RequireSuperAdmin 守卫 + +## ⑥ 本模块新增 Migration + +N/A（前端阶段） + +## ⑦ 跨模块改动清单（软规则 S2） + +N/A（前端阶段不涉及跨模块代码改动；token 漂移见 § ⑧） + +## ⑧ 偏离 spec 清单 + +**docs vs 实际渲染**： + +- **FE-01 LoginPage**: spec § 二组件树有 `LoginHeader { Logo SVG, BrandName, SubTitle }`，实际实现 inline `
` 显示 "Antler ERP" + 副标题，logo SVG 未引入（标 nice-to-have 推后；review 已记录）。 +- **FE-01 LoginForm**: spec 提到 username/password 字段含 prefix 图标（UserOutlined / LockOutlined），实际未引入 `@ant-design/icons` 减小依赖（用 AntD 默认无图标 Input）。 +- **FE-01 公司下拉**: spec § 一 explicit 标记硬编码 `{HQ: 总部}`；后续运营模块 / FE 提供 `GET /api/v1/companies` 后改动态加载。 +- **FE-02 工具栏**: prototype #screen-userdetail line 427-436 渲染 9 个按钮（新增/修改/删除/保存/取消/功能/作废/重置密码/取消作废），实际 UserFormPage 仅渲染 Save/Cancel。其他能力（作废 / 删除 / 重置密码）已在 spec § 一 明确推后到后续 FE。 +- **FE-02 sortField/sortOrder UI**: UsersTable 列头加了 sorter 视觉指示，但 onChange 回调未连到 UsersListPage.setQuery，点击列头不会真正改变排序。默认排序（tCreateDate desc）正常发后端。记 nice-to-have（review 已记录）。 +- **FE-02 40004 field-level**: spec § 五 #13 要求"员工/权限分类不存在 → field-level"，实际实现为顶部 banner（后端 ErrorResp.data 暂未携带 field 信息）。等后端协议扩展后切。 +- **FE-02 employee / permissionCategory 下拉**: spec 已声明硬编码 fixture；待后端补 `GET /api/v1/employees` + `GET /api/v1/permission-categories` 后改 API 拉取。 + +**tokens.css 与 SSoT 关系**： +- FE-01 round 1 修复后，frontend/src/styles/tokens.css 与 docs/06 § 二 1:1 对齐（16 个 canonical token，无自定义键）。 +- AntD ConfigProvider.token.colorPrimary 在 App.tsx 使用 hex 字面量 `#1677ff`（与 `--color-primary` 同源），不是 CSS 变量字符串；这是 spec § 一 #5 已声明的约束（AntD ConfigProvider 不接受 CSS var）。 + +## ⑨ AI reviewer 报告汇总 + +- FE-01: round 1 — request-changes（9 项 must-fix，包括 App.tsx 没挂 Provider 这个 critical bug）；round 2 — approve +- FE-02: round 1 — request-changes（1 high + 4 medium + 3 low，包括 canEditDocument 静默覆盖 bug）；round 2 — approve + +## ⑩ 已知问题 + +1. **Playwright E2E 6 个 spec 全部 fixme**: 浏览器 binary 未下载 + backend 9090 端口未连，无法端到端验收。手工验收步骤已写入 frontend-phase-test-gate.md。 +2. **App.tsx ConfigProvider hex 漂移风险**: App.tsx 用 `#1677ff` 与 tokens.css `--color-primary` 双源；下一 FE 若改主色必须同步两处。建议未来引入 `colorPrimary = getComputedStyle().getPropertyValue('--color-primary')` 自动同步，或 build-time 注入。 +3. **UsersTable sortField/sortOrder UI ↔ query 回调未拉通**: 视觉 sorter 已生效但点击列头不真正改变排序（FE-02 review 已记 nice-to-have）。 +4. **40004 banner vs field-level**: 后端 ErrorResp.data 暂不含 field detail；约定后切。 +5. **employee / permissionCategory fixture**: 硬编码 2-3 项；待后端补 API 后切。 +6. **AntD ConfigProvider 与 createBrowserRouter 在 jsdom 下不兼容**: App.test.tsx 改为只验 store/router 静态导出，不实测 mount；路由真实流程由 LoginPage.test.tsx / UsersListPage.test.tsx 用 MemoryRouter 测试。 +7. **UserFormPage 编辑 PATCH 行为**: 当前提交了所有字段（包括未修改）；后端 PATCH 缺省即不变能正确处理，但不是严格按 dirty fields 过滤。MVP 可接受。 +8. **i18n 推迟**: 全部中文文案硬编码。 +9. **frontend lint 未配**: scripts/test.sh stage 3/6 frontend lint 会 fail（`npm run lint` 命令存在但无 .eslintrc.cjs）。本 phase 内未引入 eslint 配置。 + +## ⑪ 下一模块预览 + +**前端阶段全部 FE 完成。下一步**： + +1. **审核 frontend-phase 分支**：人工 review 整体 MR 的代码 + UI 体验 +2. **手工 E2E 验收**（推荐在 MR 合并前完成）： + - `cd frontend && npx playwright install chromium` + - 另一终端：`cd backend && DB_HOST=... mvn spring-boot:run` + - `cd frontend && grep -rl 'test.fixme' tests/e2e | xargs sed -i '' 's/test.fixme/test/g'` + - `cd frontend && npm run e2e` +3. **GitLab 合并整体 MR 到 master** +4. **后续部署 / 上线**： + - 后端打包：`cd backend && mvn clean package` → `target/*.jar` + - 前端打包：`cd frontend && npm run build` → `dist/` + - Nginx 配置：dist/ 静态托管 + `/api/v1` 反代到 backend:9090（docs/07 § 二） + - .env.local 生产凭据填写：JWT_SECRET / DB 密码等 +5. **后续 FE 建议**： + - FE-03 用户作废 / 取消作废 / 重置密码 / 删除（含 prototype 工具栏完整按钮） + - FE-04 操作日志 / 审计（如需要） + - 后端 REQ-USR-005+ 补 `GET /api/v1/employees` + `GET /api/v1/permission-categories` 接口，前端切动态加载 + +## ⑫ MR 链接 + +—（由 `mr-create` 在推送 + 创建 MR 后回写此处） -- libgit2 0.22.2