朱子纯 / test5

Commit 47bde60f7d51e3b7d2f8ccdf04b7ca49859176aa

Authored by zichun
1 parent 4d58768c

docs(module_usr): add completion report

Inline Side-by-side
Showing 1 changed file with 120 additions and 0 deletions
docs/superpowers/module-reports/2026-05-15-module_usr.md 0 → 100644
  View file @47bde60
  1 +---
  2 +module_id: module_usr
  3 +date: 2026-05-15
  4 +git_range: 76218f3 (bootstrap spring boot 后端骨架) ↔ 4d58768 (test-gate evidence)
  5 +---
  6 +
  7 +# 模块完成报告 — module_usr 用户管理
  8 +
  9 +## ① 模块信息
  10 +- 模块 ID: module_usr
  11 +- 模块名: 用户管理
  12 +- 开发区间: 2026-05-15 单日（REQ-USR-001 → 002 → 003 → 004）
  13 +- 分支: module-module_usr
  14 +
  15 +## ② REQ 完成清单
  16 +
  17 +- [x] REQ-USR-001 — 用户登录
  18 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-001.md
  19 + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-001.md
  20 + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-001.md
  21 +- [x] REQ-USR-002 — 新增用户
  22 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-002.md
  23 + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-002.md
  24 + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-002.md
  25 +- [x] REQ-USR-003 — 修改用户（含 GET 详情）
  26 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-003.md
  27 + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-003.md
  28 + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-003.md
  29 +- [x] REQ-USR-004 — 查询用户
  30 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-004.md
  31 + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-004.md
  32 + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-004.md
  33 +
  34 +## ③ 文件变更表
  35 +
  36 +| 文件 | 操作 | 说明 |
  37 +|---|---|---|
  38 +| `backend/pom.xml` | Create | Spring Boot 3.3 + MyBatis-Plus + Flyway + JJWT + BCrypt 依赖 |
  39 +| `backend/src/main/java/com/xly/erp/Application.java` | Create | 启动类 + @MapperScan |
  40 +| `backend/src/main/resources/application.yml` / `application-test.yml` | Create | DB / JWT 配置 + Jackson 严格反序列化 + MyBatis mapper-locations |
  41 +| `backend/src/main/resources/logback-spring.xml` | Create | Logback 基础配置 |
  42 +| `backend/src/main/resources/mapper/usr/SysUserMapper.xml` | Create | REQ-004 动态 SQL JOIN + WHERE |
  43 +| `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 |
  44 +| `backend/src/main/java/com/xly/erp/common/exception/{BizException,GlobalExceptionHandler}.java` | Create | 业务异常 + 全局 @RestControllerAdvice |
  45 +| `backend/src/main/java/com/xly/erp/common/security/{JwtUtil,LoginContext,RequireSuperAdmin,JwtHandlerInterceptor}.java` | Create | JWT 工具 + ThreadLocal + 角色守卫注解 + 鉴权拦截器 |
  46 +| `backend/src/main/java/com/xly/erp/common/config/{PasswordEncoderConfig,WebMvcConfig}.java` | Create | BCrypt Bean + interceptor 注册 |
  47 +| `backend/src/main/java/com/xly/erp/module/usr/entity/Sys*.java` | Create | SysUser / SysCompany / SysEmployee / SysPermissionCategory / SysUserPermissionCategory 5 张表实体 |
  48 +| `backend/src/main/java/com/xly/erp/module/usr/mapper/Sys*Mapper.java` + `UserQueryParams.java` | Create | 5 个 mapper + REQ-004 查询参数 DTO |
  49 +| `backend/src/main/java/com/xly/erp/module/usr/dto/{LoginReq,CreateUserReq,UpdateUserReq,UserQueryReq}.java` | Create | 4 个请求 DTO |
  50 +| `backend/src/main/java/com/xly/erp/module/usr/vo/{LoginVo,UserInfoVo,CreateUserVo,UserDetailVo,UserListItemVo}.java` | Create | 5 个响应 VO |
  51 +| `backend/src/main/java/com/xly/erp/module/usr/service/*Service.java` + `impl/*ServiceImpl.java` | Create | LoginService / UserCreateService / UserDetailService / UserUpdateService / UserListService |
  52 +| `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}） |
  53 +| `backend/src/test/...` | Create | 14 个测试类，201 个测试方法 |
  54 +| `scripts/test.sh` | Modify | 把 `./mvnw` 改为系统 `mvn`（与 docs/07 § 一 Maven 3.9.x 依赖对齐；backend 未带 wrapper） |
  55 +| `docs/05-API接口契约.md` | Modify | REQ-002 去 password 字段 / 40002；REQ-003 补 GET 详情段；REQ-004 错误码列表补 sortField + 40101 |
  56 +
  57 +> 文件总数：59 个新建（44 个 main + 14 个 test），1 个修改（scripts/test.sh + docs/05）；约 5118 行 backend/ 净增。
  58 +
  59 +## ④ 数据库使用表
  60 +
  61 +- 读: `sys_user`, `sys_company`, `sys_employee`, `sys_department`, `sys_permission_category`, `sys_user_permission_category`
  62 +- 写: `sys_user`（新增 / 部分字段更新 / 登录追踪字段 / 失败计数原子 UPDATE），`sys_user_permission_category`（增删差集）
  63 +
  64 +> `sys_company` / `sys_employee` / `sys_department` 本模块全程只读使用；新增 / 编辑这三张表的接口推迟到后续运营 / HR 模块。
  65 +
  66 +## ⑤ 测试结果
  67 +
  68 +- `scripts/test.sh` 最终：GREEN（详见 `docs/superpowers/module-reports/module_usr-test-gate.md`）
  69 +- 通过: 201 / 失败: 0 / 跳过: 0
  70 +- 覆盖率: 未配置覆盖率插件；REQ 级 spec 验收覆盖：
  71 + - REQ-USR-001：12/12（含 BizException 单测、JWT 单测、并发原子累加回归）
  72 + - REQ-USR-002：15/15（spec § 15 唯一索引兜底未单测，依赖文本匹配；记入 ⑩）
  73 + - REQ-USR-003：22/22（spec § 23 作废用户登录路径属 REQ-USR-001 既有，不重复）
  74 + - REQ-USR-004：26/26（含 spec § 业务规则 3 isDeleted/lastLoginDate 强制 equals 回归）
  75 +
  76 +## ⑥ 本模块新增 Migration
  77 +
  78 +—（本模块无 schema 改动；V1__initial_schema.sql 已在 A 阶段建好 6 张表，本模块全程复用）
  79 +
  80 +## ⑦ 跨模块改动清单（软规则 S2）
  81 +
  82 +—（本模块未触碰其他模块代码；scripts/test.sh 改动属于项目级基础设施修复，不构成跨模块改动。docs/05 修订属于本模块自己的 API 契约同步。）
  83 +
  84 +## ⑧ 偏离 spec 清单
  85 +
  86 +- **REQ-USR-001**: docs/04 § 1.6 描述了 access + refresh token 双 token 模型，本 REQ 只签发 access token；refresh 推迟到后续 REQ。spec 已显式声明此偏离。
  87 +- **REQ-USR-001**: docs/04 § 1.6 提及"签发后写 Redis"，本 REQ 不实现 Redis 黑名单，JWT 自包含验证。spec 已声明。
  88 +- **REQ-USR-002**: REQ 卡片表 1 与 docs/05 在密码字段处理上原本冲突；spec 锁定为"系统生成初始密码 666666"（以 REQ 卡为准），docs/05 同步删除 password 字段与 40002 错误码。
  89 +- **跨 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。
  90 +
  91 +## ⑨ AI reviewer 报告汇总
  92 +
  93 +- REQ-USR-001: round 1 — request-changes（4 high + 7 medium，已落地 5 项修复）；round 2 — approve（4 nice-to-have）
  94 +- REQ-USR-002: round 1 — approve（13 nice-to-have，0 must-fix）
  95 +- REQ-USR-003: round 1 — approve（6 nice-to-have，0 must-fix；归档时顺手补 docs/05 PUT § 40101）
  96 +- REQ-USR-004: round 1 — request-changes（2 medium）；round 2 — approve（4 nice-to-have）
  97 +
  98 +## ⑩ 已知问题
  99 +
  100 +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` 解析 + 单测覆盖。
  101 +2. **权限分类批量插入未走 batchInsert**: REQ-USR-002 / 003 用 for + 单条 insert（N 次 IO）。当前 N < 20 可接受，建议未来补 `insertBatch`。
  102 +3. **permissionCategoryIds 差集无乐观锁**: REQ-USR-003 并发 PUT 同一用户可能产生交叉写入。建议未来引入 `sys_user.iVersion` 做乐观锁。
  103 +4. **ErrorCode.COMPANY_NOT_FOUND 复用语义错位**: REQ-USR-002 / 003 用 40004 抛"权限分类不存在"，常量名 COMPANY_NOT_FOUND 与 message 字面冲突。建议重命名为 RELATED_ENTITY_NOT_FOUND 或拆专用 code。
  104 +5. **entity Lombok 字段沿用 SQL 列名匈牙利前缀**: 偏离 docs/04 § 1.2 Java 字段小驼峰约定。当前为了让 MyBatis-Plus 零配置映射；建议未来 refactor 用 @TableField 显式映射。
  105 +6. **跨文档错误码段位冲突**: docs/04 § 1.3 vs docs/05 + 代码（见 ⑧ 偏离）。
  106 +7. **mapper XML ORDER BY 硬编码 u.\* 前缀**: REQ-USR-004 sortField 白名单当前仅 sys_user 表列；未来扩展到 e.* / d.* 列需更新前缀逻辑。
  107 +8. **JwtHandlerInterceptor 每请求重查 DB**: 无缓存；后续容量评估后可加 Caffeine 短期缓存。
  108 +9. **scripts/test.sh 之前调用不存在的 ./mvnw**: 本模块期间发现并修复（改用系统 mvn）；首次 test-gate 失败已记录在 test-gate evidence。
  109 +
  110 +## ⑪ 下一模块预览
  111 +
  112 +后端阶段仅本一个模块（module_usr），全部 REQ 已完成。
  113 +
  114 +**下一步**：本 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）完成。
  115 +
  116 +**前端预期工作量**：基于已实现的 6 个端点（auth/login、users CRUD + 列表 + 详情），FE 至少需要：登录页、用户列表 + 筛选页、用户新增 / 编辑 Modal 表单。`prototype/` 目前为空，进入前端阶段时 `frontend-start` 会通过 AskUserQuestion 引导补齐 mockup。
  117 +
  118 +## ⑫ MR 链接
  119 +
  120 +—（由 `mr-create` 在推送 + 创建 MR 后回写此处）
... ...