2026-05-15-frontend-phase.md 8.8 KB

Edit Raw Blame History Permalink



module_id: frontend-phase
date: 2026-05-15


git_range: a6d4ac9c (docs/08 § 三 FE 清单 + 落入 prototype) ↔ 410ca8aa (test-gate evidence)


模块完成报告 — frontend-phase 前端阶段（整体）


① 模块信息


模块 ID: frontend-phase
模块名: 前端阶段（整体）
开发区间: 2026-05-15 单日，FE-01 → FE-02
分支: frontend-phase


② FE 完成清单


 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


 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 <div class="login-head"> 显示 "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


⑩ 已知问题


Playwright E2E 6 个 spec 全部 fixme: 浏览器 binary 未下载 + backend 9090 端口未连，无法端到端验收。手工验收步骤已写入 frontend-phase-test-gate.md。

App.tsx ConfigProvider hex 漂移风险: App.tsx 用 #1677ff 与 tokens.css --color-primary 双源；下一 FE 若改主色必须同步两处。建议未来引入 colorPrimary = getComputedStyle().getPropertyValue('--color-primary') 自动同步，或 build-time 注入。

UsersTable sortField/sortOrder UI ↔ query 回调未拉通: 视觉 sorter 已生效但点击列头不真正改变排序（FE-02 review 已记 nice-to-have）。

40004 banner vs field-level: 后端 ErrorResp.data 暂不含 field detail；约定后切。

employee / permissionCategory fixture: 硬编码 2-3 项；待后端补 API 后切。

AntD ConfigProvider 与 createBrowserRouter 在 jsdom 下不兼容: App.test.tsx 改为只验 store/router 静态导出，不实测 mount；路由真实流程由 LoginPage.test.tsx / UsersListPage.test.tsx 用 MemoryRouter 测试。

UserFormPage 编辑 PATCH 行为: 当前提交了所有字段（包括未修改）；后端 PATCH 缺省即不变能正确处理，但不是严格按 dirty fields 过滤。MVP 可接受。

i18n 推迟: 全部中文文案硬编码。

frontend lint 未配: scripts/test.sh stage 3/6 frontend lint 会 fail（npm run lint 命令存在但无 .eslintrc.cjs）。本 phase 内未引入 eslint 配置。


⑪ 下一模块预览

前端阶段全部 FE 完成。下一步：


审核 frontend-phase 分支：人工 review 整体 MR 的代码 + UI 体验

手工 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


GitLab 合并整体 MR 到 master

后续部署 / 上线：


后端打包：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 密码等


后续 FE 建议：


FE-03 用户作废 / 取消作废 / 重置密码 / 删除（含 prototype 工具栏完整按钮）
FE-04 操作日志 / 审计（如需要）
后端 REQ-USR-005+ 补 GET /api/v1/employees + GET /api/v1/permission-categories 接口，前端切动态加载


⑫ MR 链接


!2 http://git.xlyprint.cn/zhuzc/test5/-/merge_requests/2
标题: feat(frontend-phase): 前端阶段（整体）

目标分支: master
源分支: frontend-phase