---
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 `<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

## ⑩ 已知问题

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 后回写此处）