朱子纯 / test3

2026-05-08-module_usr.md 7.19 KB

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 完成清单

  • 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

  • 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

  • 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

  • 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 步骤创建后填入）