---
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 链接

http://git.xlyprint.cn/zhuzc/test3/-/merge_requests/1