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