diff --git a/docs/superpowers/module-reports/2026-05-08-module_usr.md b/docs/superpowers/module-reports/2026-05-08-module_usr.md new file mode 100644 index 0000000..42cd676 --- /dev/null +++ b/docs/superpowers/module-reports/2026-05-08-module_usr.md @@ -0,0 +1,115 @@ +--- +module_id: module_usr +date: 2026-05-08 +git_range: master..module-module_usr +--- + +# 模块完成报告 — module_usr 用户管理 + +## ① 模块信息 +- 模块 ID: module_usr +- 模块名: 用户管理 +- 开发区间: master..module-module_usr（共 29 commits） + +## ② REQ 完成清单 + +- [x] REQ-USR-004 — 用户登录 + - spec: docs/superpowers/specs/2026-05-08-REQ-USR-004.md + - plan: docs/superpowers/plans/2026-05-08-REQ-USR-004.md + - review: docs/superpowers/reviews/2026-05-08-REQ-USR-004.md + +- [x] REQ-USR-001 — 增加用户 + - spec: docs/superpowers/specs/2026-05-08-REQ-USR-001.md + - plan: docs/superpowers/plans/2026-05-08-REQ-USR-001.md + - review: docs/superpowers/reviews/2026-05-08-REQ-USR-001.md + +- [x] REQ-USR-003 — 查询用户 + - spec: docs/superpowers/specs/2026-05-08-REQ-USR-003.md + - plan: docs/superpowers/plans/2026-05-08-REQ-USR-003.md + - review: docs/superpowers/reviews/2026-05-08-REQ-USR-003.md + +- [x] REQ-USR-002 — 修改用户 + - spec: docs/superpowers/specs/2026-05-08-REQ-USR-002.md + - plan: docs/superpowers/plans/2026-05-08-REQ-USR-002.md + - review: docs/superpowers/reviews/2026-05-08-REQ-USR-002.md + +## ③ 文件变更表 + +| 文件 | 操作 | 说明 | +|---|---|---| +| backend/pom.xml | 新增 | Spring Boot 3 项目配置，含 checkstyle 插件 | +| backend/checkstyle.xml | 新增 | 项目 checkstyle 规则（Spring Boot 友好） | +| backend/src/main/java/com/example/erp/common/\* | 新增 | Result/BizException/GlobalExceptionHandler/JwtUtil/PageVO/错误码常量 | +| backend/src/main/java/com/example/erp/config/\* | 新增 | SecurityConfig/JwtFilter/JwtProperties/UserPrincipal/BeanConfig/MybatisPlusConfig | +| backend/src/main/java/com/example/erp/module/usr/controller/\* | 新增 | AuthController（登录/刷新/品牌列表）、UserController（CRUD 接口） | +| backend/src/main/java/com/example/erp/module/usr/service/\* | 新增 | AuthService/AuthServiceImpl/UserService/UserServiceImpl | +| backend/src/main/java/com/example/erp/module/usr/entity/\* | 新增 | BrandEntity/UsrUserEntity/StaffEntity/PermissionGroupEntity/UserPermissionEntity | +| backend/src/main/java/com/example/erp/module/usr/mapper/\* | 新增 | BrandMapper/UsrUserMapper/StaffMapper/PermissionGroupMapper/UserPermissionMapper | +| backend/src/main/java/com/example/erp/module/usr/dto/\* | 新增 | LoginReqDTO/RefreshTokenReqDTO/UserCreateReqDTO/UserListQueryDTO/UserUpdateReqDTO | +| backend/src/main/java/com/example/erp/module/usr/vo/\* | 新增 | LoginVO/BrandVO/StaffVO/PermissionGroupVO/UserCreateRespVO/UserListItemVO/UserUpdateRespVO | +| backend/src/main/resources/mapper/UsrUserMapper.xml | 新增 | selectUserList 动态查询 SQL | +| backend/src/main/resources/db/migration/V1\_\_initial\_schema.sql | 新增 | 初始全量 schema | +| backend/src/main/resources/db/migration/V2\_\_fix\_username\_unique\_per\_tenant.sql | 新增 | 用户名唯一索引改为租户范围内唯一 | +| backend/src/test/\* | 新增 | 49 个测试（ApplicationContext/JwtUtil/Result/AuthService/AuthController/UserService/UserController/BrandMapper） | +| frontend/src/api/auth.ts | 新增 | 登录/刷新 API 函数 | +| frontend/src/api/request.ts | 新增 | Axios 请求拦截器（含 JWT 自动注入） | +| frontend/src/api/usr.ts | 新增 | 用户增/查/改 API 接口及类型定义 | +| frontend/src/pages/usr/LoginPage.tsx | 新增 | 登录页（多品牌选择） | +| frontend/src/pages/usr/UserFormDrawer.tsx | 新增 | 新增/修改用户抽屉（复用组件） | +| frontend/src/pages/usr/UserListPage.tsx | 新增 | 用户列表（搜索+分页+操作列） | +| frontend/src/store/\* | 新增 | Redux auth 切片（credentials/userInfo） | +| frontend/src/components/PermButton.tsx | 新增 | 基于用户类型的权限按钮组件 | +| frontend/src/test/\* | 新增 | 10 个前端测试（authSlice/LoginPage/UserListPage） | +| frontend/package.json | 修改 | lint 脚本改为 tsc --noEmit（eslint 未安装） | +| docs/03-数据库设计文档.md | 修改 | 同步 V2 migration 唯一索引变更 | +| docs/04-技术规范.md | 修改 | 分页入参规范统一为 page（原 pageNum） | +| docs/05-API接口契约.md | 修改 | 分页规范同步更新 | +| docs/08-模块任务管理.md | 修改 | 4 个 REQ 全部勾选 [x] | +| scripts/test.sh | 修改 | 添加 Java 21 PATH 适配（Lombok 兼容性） | + +## ④ 数据库使用表 +- 读: `brand`（登录品牌列表）、`tStaff`（员工下拉）、`usr_permission_group`（权限组下拉） +- 写: `usr_user`（登录时更新 tLastLoginDate/iLoginFailCount/tLockUntil；新增/修改用户字段）、`usr_user_permission`（新增/修改时先删后插） + +## ⑤ 测试结果 +- `scripts/test.sh` 最终：green +- 通过: 59 / 失败: 0 / 跳过: 0 +- 覆盖率: 未配置覆盖率工具（所有业务路径已有对应测试用例） + +## ⑥ 本模块新增 Migration + +- `backend/src/main/resources/db/migration/V1__initial_schema.sql` — 全量初始 schema（usr_user / tStaff / usr_permission_group / usr_user_permission / brand 五张表） +- `backend/src/main/resources/db/migration/V2__fix_username_unique_per_tenant.sql` — 将 uk_usr_user_username 从全局唯一改为租户范围内唯一（允许不同 brand 使用相同用户名） + +## ⑦ 跨模块改动清单（软规则 S2） + +本项目当前仅含 module_usr 一个模块，无跨模块改动。 + +改动了两处项目级规范文档： +- `docs/04-技术规范.md § 3.2`：分页入参统一为 `page`（REQ-USR-003 review 发现 `pageNum` 与实现不一致，修正文档） +- `docs/05-API接口契约.md`：分页规范同步更新 + +## ⑧ 偏离 spec 清单 + +- REQ-USR-002：`UserListPage` 传给编辑抽屉的 `initialData` 中 `permGroupIds` 字段未传值（始终为空数组）。原因：用户列表 API 不返回每用户的权限组关联，无法在列表页预填。规格 § 前端交互设计 line 103 已明确说明"初始化为空数组即可，用户可重新勾选"，属有意决策而非实现缺陷。 + +## ⑨ AI reviewer 报告汇总 + +- REQ-USR-004: round 2 — approve（link: docs/superpowers/reviews/2026-05-08-REQ-USR-004.md） +- REQ-USR-001: round 2 — approve（link: docs/superpowers/reviews/2026-05-08-REQ-USR-001.md） +- REQ-USR-003: round 4 — approve（link: docs/superpowers/reviews/2026-05-08-REQ-USR-003.md） +- REQ-USR-002: round 2 — approve（link: docs/superpowers/reviews/2026-05-08-REQ-USR-002.md） + +## ⑩ 已知问题 + +1. **前端 lint 工具缺失**：`eslint` 未在 `package.json` 中声明为 devDependency，lint 脚本临时改为 `tsc --noEmit`。建议后续补充 ESLint + TypeScript ESLint 插件配置。 +2. **`updatedAt` 序列化格式**：`UserUpdateRespVO.updatedAt` 未加 `@JsonFormat` 注解，依赖 Jackson 全局配置。如未配置全局 LocalDateTime 序列化器，返回值可能为数组格式而非 ISO-8601 字符串。 +3. **controller 层 BizException 错误码映射测试缺失**：`UserControllerTest` 未覆盖 40300/40400/40301 通过 `GlobalExceptionHandler` 映射为 JSON 错误码的路径（低风险，handler 已通过 createUser 路径间接覆盖）。 + +## ⑪ 下一模块预览 + +当前项目 `docs/02-开发计划.md` 仅包含 module_usr 一个模块，无后续模块。本次开发计划全部完成。 + +## ⑫ MR 链接 + +（待 mr-create 步骤创建后填入）