---
module_id: module_usr
date: 2026-05-15
git_range: 76218f3 (bootstrap spring boot 后端骨架) ↔ 4d58768 (test-gate evidence)
---

# 模块完成报告 — module_usr 用户管理

## ① 模块信息
- 模块 ID: module_usr
- 模块名: 用户管理
- 开发区间: 2026-05-15 单日（REQ-USR-001 → 002 → 003 → 004）
- 分支: module-module_usr

## ② REQ 完成清单

- [x] REQ-USR-001 — 用户登录
  - spec: docs/superpowers/specs/2026-05-15-REQ-USR-001.md
  - plan: docs/superpowers/plans/2026-05-15-REQ-USR-001.md
  - review: docs/superpowers/reviews/2026-05-15-REQ-USR-001.md
- [x] REQ-USR-002 — 新增用户
  - spec: docs/superpowers/specs/2026-05-15-REQ-USR-002.md
  - plan: docs/superpowers/plans/2026-05-15-REQ-USR-002.md
  - review: docs/superpowers/reviews/2026-05-15-REQ-USR-002.md
- [x] REQ-USR-003 — 修改用户（含 GET 详情）
  - spec: docs/superpowers/specs/2026-05-15-REQ-USR-003.md
  - plan: docs/superpowers/plans/2026-05-15-REQ-USR-003.md
  - review: docs/superpowers/reviews/2026-05-15-REQ-USR-003.md
- [x] REQ-USR-004 — 查询用户
  - spec: docs/superpowers/specs/2026-05-15-REQ-USR-004.md
  - plan: docs/superpowers/plans/2026-05-15-REQ-USR-004.md
  - review: docs/superpowers/reviews/2026-05-15-REQ-USR-004.md

## ③ 文件变更表

| 文件 | 操作 | 说明 |
|---|---|---|
| `backend/pom.xml` | Create | Spring Boot 3.3 + MyBatis-Plus + Flyway + JJWT + BCrypt 依赖 |
| `backend/src/main/java/com/xly/erp/Application.java` | Create | 启动类 + @MapperScan |
| `backend/src/main/resources/application.yml` / `application-test.yml` | Create | DB / JWT 配置 + Jackson 严格反序列化 + MyBatis mapper-locations |
| `backend/src/main/resources/logback-spring.xml` | Create | Logback 基础配置 |
| `backend/src/main/resources/mapper/usr/SysUserMapper.xml` | Create | REQ-004 动态 SQL JOIN + WHERE |
| `backend/src/main/java/com/xly/erp/common/response/{Result,ErrorCode,PageResult}.java` | Create | 统一响应包装 + 错误码（含 40001/40003/40004/40101/40103/40301/40302/40401/40901/40902/42301）+ 通用分页 VO |
| `backend/src/main/java/com/xly/erp/common/exception/{BizException,GlobalExceptionHandler}.java` | Create | 业务异常 + 全局 @RestControllerAdvice |
| `backend/src/main/java/com/xly/erp/common/security/{JwtUtil,LoginContext,RequireSuperAdmin,JwtHandlerInterceptor}.java` | Create | JWT 工具 + ThreadLocal + 角色守卫注解 + 鉴权拦截器 |
| `backend/src/main/java/com/xly/erp/common/config/{PasswordEncoderConfig,WebMvcConfig}.java` | Create | BCrypt Bean + interceptor 注册 |
| `backend/src/main/java/com/xly/erp/module/usr/entity/Sys*.java` | Create | SysUser / SysCompany / SysEmployee / SysPermissionCategory / SysUserPermissionCategory 5 张表实体 |
| `backend/src/main/java/com/xly/erp/module/usr/mapper/Sys*Mapper.java` + `UserQueryParams.java` | Create | 5 个 mapper + REQ-004 查询参数 DTO |
| `backend/src/main/java/com/xly/erp/module/usr/dto/{LoginReq,CreateUserReq,UpdateUserReq,UserQueryReq}.java` | Create | 4 个请求 DTO |
| `backend/src/main/java/com/xly/erp/module/usr/vo/{LoginVo,UserInfoVo,CreateUserVo,UserDetailVo,UserListItemVo}.java` | Create | 5 个响应 VO |
| `backend/src/main/java/com/xly/erp/module/usr/service/*Service.java` + `impl/*ServiceImpl.java` | Create | LoginService / UserCreateService / UserDetailService / UserUpdateService / UserListService |
| `backend/src/main/java/com/xly/erp/module/usr/controller/{AuthController,UserController}.java` | Create | 5 个 HTTP 端点（POST /auth/login，POST/GET/PUT /users，GET /users/{id}） |
| `backend/src/test/...` | Create | 14 个测试类，201 个测试方法 |
| `scripts/test.sh` | Modify | 把 `./mvnw` 改为系统 `mvn`（与 docs/07 § 一 Maven 3.9.x 依赖对齐；backend 未带 wrapper） |
| `docs/05-API接口契约.md` | Modify | REQ-002 去 password 字段 / 40002；REQ-003 补 GET 详情段；REQ-004 错误码列表补 sortField + 40101 |

> 文件总数：59 个新建（44 个 main + 14 个 test），1 个修改（scripts/test.sh + docs/05）；约 5118 行 backend/ 净增。

## ④ 数据库使用表

- 读: `sys_user`, `sys_company`, `sys_employee`, `sys_department`, `sys_permission_category`, `sys_user_permission_category`
- 写: `sys_user`（新增 / 部分字段更新 / 登录追踪字段 / 失败计数原子 UPDATE），`sys_user_permission_category`（增删差集）

> `sys_company` / `sys_employee` / `sys_department` 本模块全程只读使用；新增 / 编辑这三张表的接口推迟到后续运营 / HR 模块。

## ⑤ 测试结果

- `scripts/test.sh` 最终：GREEN（详见 `docs/superpowers/module-reports/module_usr-test-gate.md`）
- 通过: 201 / 失败: 0 / 跳过: 0
- 覆盖率: 未配置覆盖率插件；REQ 级 spec 验收覆盖：
  - REQ-USR-001：12/12（含 BizException 单测、JWT 单测、并发原子累加回归）
  - REQ-USR-002：15/15（spec § 15 唯一索引兜底未单测，依赖文本匹配；记入 ⑩）
  - REQ-USR-003：22/22（spec § 23 作废用户登录路径属 REQ-USR-001 既有，不重复）
  - REQ-USR-004：26/26（含 spec § 业务规则 3 isDeleted/lastLoginDate 强制 equals 回归）

## ⑥ 本模块新增 Migration

—（本模块无 schema 改动；V1__initial_schema.sql 已在 A 阶段建好 6 张表，本模块全程复用）

## ⑦ 跨模块改动清单（软规则 S2）

—（本模块未触碰其他模块代码；scripts/test.sh 改动属于项目级基础设施修复，不构成跨模块改动。docs/05 修订属于本模块自己的 API 契约同步。）

## ⑧ 偏离 spec 清单

- **REQ-USR-001**: docs/04 § 1.6 描述了 access + refresh token 双 token 模型，本 REQ 只签发 access token；refresh 推迟到后续 REQ。spec 已显式声明此偏离。
- **REQ-USR-001**: docs/04 § 1.6 提及"签发后写 Redis"，本 REQ 不实现 Redis 黑名单，JWT 自包含验证。spec 已声明。
- **REQ-USR-002**: REQ 卡片表 1 与 docs/05 在密码字段处理上原本冲突；spec 锁定为"系统生成初始密码 666666"（以 REQ 卡为准），docs/05 同步删除 password 字段与 40002 错误码。
- **跨 REQ 文档冲突**: docs/04 § 1.3 错误码段位（10xxx/20xxx/.../60xxx）与 docs/05 + 代码实际使用的 HTTP-aligned 段位（40001/40101/40301/40901/...）不一致。本模块沿用 docs/05 + HTTP-aligned 方案；建议后续单独 PR 修订 docs/04 § 1.3 表述以拉齐 SSoT。

## ⑨ AI reviewer 报告汇总

- REQ-USR-001: round 1 — request-changes（4 high + 7 medium，已落地 5 项修复）；round 2 — approve（4 nice-to-have）
- REQ-USR-002: round 1 — approve（13 nice-to-have，0 must-fix）
- REQ-USR-003: round 1 — approve（6 nice-to-have，0 must-fix；归档时顺手补 docs/05 PUT § 40101）
- REQ-USR-004: round 1 — request-changes（2 medium）；round 2 — approve（4 nice-to-have）

## ⑩ 已知问题

1. **spec § 15 唯一索引兜底（REQ-USR-002）未单测**: UserCreateServiceImpl 在 DataIntegrityViolationException 时通过 message 文本匹配 `uk_sys_user_username` / `uk_sys_user_code` 转 40901/40902；与 MySQL 驱动版本/locale 强耦合，缺 @SpyBean 模拟回归测试。建议后续用 `SQLState='23000' + 错误号 1062` 解析 + 单测覆盖。
2. **权限分类批量插入未走 batchInsert**: REQ-USR-002 / 003 用 for + 单条 insert（N 次 IO）。当前 N < 20 可接受，建议未来补 `insertBatch`。
3. **permissionCategoryIds 差集无乐观锁**: REQ-USR-003 并发 PUT 同一用户可能产生交叉写入。建议未来引入 `sys_user.iVersion` 做乐观锁。
4. **ErrorCode.COMPANY_NOT_FOUND 复用语义错位**: REQ-USR-002 / 003 用 40004 抛"权限分类不存在"，常量名 COMPANY_NOT_FOUND 与 message 字面冲突。建议重命名为 RELATED_ENTITY_NOT_FOUND 或拆专用 code。
5. **entity Lombok 字段沿用 SQL 列名匈牙利前缀**: 偏离 docs/04 § 1.2 Java 字段小驼峰约定。当前为了让 MyBatis-Plus 零配置映射；建议未来 refactor 用 @TableField 显式映射。
6. **跨文档错误码段位冲突**: docs/04 § 1.3 vs docs/05 + 代码（见 ⑧ 偏离）。
7. **mapper XML ORDER BY 硬编码 u.\* 前缀**: REQ-USR-004 sortField 白名单当前仅 sys_user 表列；未来扩展到 e.* / d.* 列需更新前缀逻辑。
8. **JwtHandlerInterceptor 每请求重查 DB**: 无缓存；后续容量评估后可加 Caffeine 短期缓存。
9. **scripts/test.sh 之前调用不存在的 ./mvnw**: 本模块期间发现并修复（改用系统 mvn）；首次 test-gate 失败已记录在 test-gate evidence。

## ⑪ 下一模块预览

后端阶段仅本一个模块（module_usr），全部 REQ 已完成。

**下一步**：本 MR 合并到 master 后，重跑 `/erp-workflow:coding-start`，会自动检测 `backend_done=true && frontend_done=false`，派发 `frontend-start` 进入前端阶段。前端阶段会以 `prototype/` 的 HTML mockup 为权威推导 FE 业务功能清单，按 FE 循环（fe-feature-brainstorm → plan → tdd → verify → review）完成。

**前端预期工作量**：基于已实现的 6 个端点（auth/login、users CRUD + 列表 + 详情），FE 至少需要：登录页、用户列表 + 筛选页、用户新增 / 编辑 Modal 表单。`prototype/` 目前为空，进入前端阶段时 `frontend-start` 会通过 AskUserQuestion 引导补齐 mockup。

## ⑫ MR 链接

- !1 http://git.xlyprint.cn/zhuzc/test5/-/merge_requests/1
- 标题: `feat(module_usr): 用户管理`
- 目标分支: master
- 源分支: module-module_usr