朱子纯 / test6

2026-06-01-usr.md 14.6 KB

模块完成报告 — USR 用户管理（backend）

生成时间：2026-06-01 CST 模块 id：usr｜阶段：后端（backend）｜功能分支：module-usr（自默认分支 master 分叉） 本报告为标准化 12 节模块完成报告，供 milestone 标记前置。摘要级（不引入 diff 正文）。

① 模块概述

  • 模块名称：USR 用户管理（com.xly.erp.modules.usr）。
  • 业务范围：企业内部管理系统的用户账号全生命周期与登录认证，覆盖用户新增、修改、分页查询、登录认证 4 个后端 REQ。
  • 依赖：无（docs/08 § 二 标注「依赖: 无」），为整个 ERP 的基础模块。
  • 路径作用域：backend/src/main/java/com/xly/erp/modules/usr/** + 公共基础设施 com/xly/erp/common/**（统一响应 / 异常 / 安全 / JWT / BaseEntity，本模块首次落地，供后续模块复用）。
  • 本阶段产出范围：controller / service / repository(mapper) / DTO / VO / 校验 / REST 契约实现；不触 frontend/（UI 推迟到前端阶段）；本模块未新增 SQL migration（复用 A4 生成的 V1__initial_schema.sql）。

② 需求覆盖（REQ 清单 + spec 摘要）

本模块 4 个 REQ 全部完成并在 docs/08-模块任务管理.md § 二 勾选为 [x]：

REQ 标题 端点 spec 摘要
REQ-USR-001 增加用户 POST /api/usr/users 管理员新建用户：用户名 3-20 位唯一、密码 BCrypt（默认 666666）、用户类型 / 语言枚举约束、可选关联职员 + 权限组授权（多对多）；多表写入事务化；新建即生效（iIsVoid=0）。错误码 0/40001/40301/40901。
REQ-USR-002 修改用户 PUT /api/usr/users/{id} 管理员改用户基础信息（用户号 / 关联职员 / 用户类型 / 语言 / 单据修改权限 / 作废标志 / 权限组）；sUserName 与 sPassword 不可改；权限组全量覆盖语义；可选字段 null = 不更新（保守不清空）。错误码 0/40001/40301/40401。
REQ-USR-003 查询用户 GET /api/usr/users 任意已认证用户的只读单条件分页查询（8 个查询字段 × 3 种匹配方式）；跨表 LEFT JOIN usr_employee 取员工名 / 部门；文本模糊（LIKE 转义）/ 枚举 / 布尔 / 日期精确匹配；分页参数非法 → 42201，数据越界返回最后一页；密码绝不返回。错误码 0/40001/42201（+401 未认证）。
REQ-USR-004 登录用户 POST /api/usr/login（+ 配套 GET /api/usr/companies） 用户名 + 密码 + 版本(companyId) 认证：BCrypt 比对 → 签发带 exp 的无状态 JWT + 更新 tLastLoginDate；防账号枚举（不存在/密码错误同码同提示）；禁用账号 40302；进程内登录限流 42901（默认 5 次/300 秒）。配套补齐只读公司列表端点支撑登录页「版本」下拉。错误码 0/40001/40101/40302/42901（+401）。

spec 全文：docs/superpowers/specs/2026-06-01-REQ-USR-00{1,2,3,4}.md。各 spec § 8 已逐条登记自主决策（见本报告 § ⑩）。

③ 文件变更摘要（git diff --stat，master...HEAD）

  • 提交数：53 个 commit（git log master..HEAD --oneline）。
  • 变更规模：85 个文件，+8280 / -5 行。
  • 新增生产代码（backend/src/main/java/com/xly/erp/，A=新增）：
    • 公共基础设施 common/：base/BaseEntity、config/{MybatisPlusConfig,SecurityConfig}、exception/{BusinessException,GlobalExceptionHandler}、response/{Result,ResultCode,PageResult}、security/{JwtUtil,JwtAuthenticationFilter,SecurityUtil}、ErpApplication。
    • USR 模块 modules/usr/：controller（UsrUserController、UsrAuthController）、service（UsrUserService(+Impl)、UsrAuthService(+Impl)）、mapper（UsrUser/UsrCompany/UsrEmployee/UsrPermission/UsrUserPermission Mapper）、entity（UsrUser/UsrCompany/UsrEmployee/UsrPermission/UsrUserPermission）、dto（CreateUserDTO/UpdateUserDTO/UserQueryDTO/UserQueryCondition/LoginDTO）、vo（UserVO/LoginVO/CompanyOptionVO）。
    • 资源：application.yml、application-test.yml、mapper/usr/UsrUserMapper.xml（跨表分页查询）。
    • 构建：backend/pom.xml（Spring Boot + MyBatis-Plus + Flyway 10.10.0 + JWT，java.version=17）、backend/checkstyle.xml。
  • 新增测试代码（backend/src/test/java/）：25 个测试类（详见 § ⑤）。
  • 流程 / 文档：scripts/test.mjs（M，新增 ensureJava17()）、docs/08-模块任务管理.md（M，4 个 REQ 勾选）、docs/superpowers/{specs,plans,reviews}/2026-06-01-REQ-USR-00{1..4}*.md（A）、docs/superpowers/module-reports/usr-test-gate-r1.md（A）。
  • migration：无新增（见 § ⑥）。
  • 跨模块：无（见 § ⑦）。

④ 读写的数据表

本模块涉及 5 张表，全部由 sql/migrations/V1__initial_schema.sql 建好（A4 阶段从 docs/03 翻译），本模块未做 schema 变更：

表 操作 涉及 REQ 说明
usr_user 读 + 写 001(写) / 002(写) / 003(读) / 004(读+写 tLastLoginDate) 用户主表，主键 iIncrement，唯一索引 uk_usr_user_username。
usr_user_permission 写 001(批量插入) / 002(全量覆盖) 用户-权限多对多关联表，唯一索引 uk_usr_user_permission(iUserId,iPermissionId)。
usr_employee 读 001/002(存在性校验) / 003(LEFT JOIN 取员工名/部门) 职员表；与 usr_user 外键 fk_usr_user_employee ON DELETE SET NULL。
usr_permission 读 001/002(权限 id 存在性校验) 权限组表。
usr_company 读 004(版本下拉 + companyId 存在性校验) 公司/版本支撑表，与 usr_user 无外键（仅登录时选择）。

严格遵循 docs/04 § 3.4：仅经 Mapper 访问；查询不 SELECT sPassword；VO 不含密码列；SQL 参数化防注入，LIKE 通配符转义。

⑤ 测试与质量闸（test-gate）

flake 判定：无 flake。 test-gate attempt 序列仅 r1，且 r1 = GREEN（首跑即绿）。

说明：历史上曾在 JDK25 默认工具链下有 5 次 RED 记录（旧 r1–r5），其根因为 Mockito/Byte Buddy 不支持 JDK25 的 class file 版本（69），导致 UsrAuthServiceImplTest 对 JwtUtil 整片 Mockito cannot mock 报 error（终态 88 跑 / 9 error）。该批旧证据因属过期工具链问题已在 commit 282a524 移除，并非当前 attempt 序列的一部分；工具链修复在 dbc3454（scripts/test.mjs 新增 ensureJava17()，把后端测试 JVM 的 JAVA_HOME 固定到 Java 17）。本模块当前 attempt 序列从修复后重新起算，r1 首跑即绿，故不构成「red→green flake」。

本次 r1 证据（docs/superpowers/module-reports/usr-test-gate-r1.md）：

  • 执行命令：node scripts/test.mjs（内部 ensureJava17() → /opt/homebrew/Cellar/openjdk@17/17.0.19/.../Home）。
  • 工具链确认：Spring Boot 测试日志 Starting ErpApplicationTests using Java 17.0.19；Maven 3.9.15 / Java 17.0.19。
  • 5 级闸门：1/5 setup-db ✅、2/5 build(mvn -q -B -DskipTests package) ✅、3/5 lint(mvn -q -B checkstyle:check) ✅、4/5 unit+integration(mvn -q -B test) ✅、5/5 e2e（后端无 e2e，skip）✅。
  • 退出码 0，终态 [test.mjs] GREEN。
  • 测试统计（surefire-reports 汇总）：Tests run: 125, Failures: 0, Errors: 0, Skipped: 0（25 个测试类）。曾整片报错的 UsrAuthServiceImplTest（含 JwtUtil mock）本次 9/9 全绿，证明根因消除。

测试类清单（25）：

  • 公共：ErpApplicationTests、SecurityConfigTest、GlobalExceptionHandlerTest、ResultTest、ResultCodeLoginTest、PageResultTest、JwtUtilTest。
  • DTO 校验：CreateUserDTOValidationTest、UpdateUserDTOValidationTest、UserQueryDTOValidationTest、LoginDTOValidationTest。
  • VO 序列化：UserVOJsonTest、LoginVOJsonTest、CompanyOptionVOJsonTest。
  • Mapper：UsrUserMapperPageTest、UsrCompanyMapperTest。
  • Service 单测：UsrUserServiceImplTest(24)、UsrAuthServiceImplTest(9)。
  • Controller 单测：UsrUserControllerTest(11)、UsrAuthControllerTest(6)。
  • 端到端 IT：UsrUserCreateIT(5)、UsrUserUpdateIT(6)、UsrUserQueryIT(13)、UsrLoginIT(12)、AuthLoginConfigIT(1)。

⑥ 数据库 migration

本模块未新增 migration。

  • git diff --name-only --diff-filter=A master...HEAD -- 'sql/migrations/V*.sql' 结果为空。
  • 现有唯一 migration sql/migrations/V1__initial_schema.sql 由 A4 阶段 db-init 从 docs/03-数据库设计文档.md（schema SSoT）翻译生成，第一行：-- Flyway migration V1 — initial schema for 小羚羊。
  • 4 个 REQ 的 spec § 8 均明确决策「复用 V1，无 schema 变更」（4 张依赖表 usr_user/usr_employee/usr_permission/usr_user_permission/usr_company 结构与 docs/03 一致）。REQ-USR-004 仅对 usr_user.tLastLoginDate 做 UPDATE（DML 非 DDL）。
  • Flyway 依赖已在 pom.xml 声明（flyway-core + flyway-mysql 10.10.0），schema 由 Spring Boot / 测试启动时自动 apply（符合 CLAUDE.md Schema 演化规约）。

⑦ 跨模块改动

无跨模块改动。

  • docs/superpowers/module-reports/usr-cross-module.md 不存在（cross-module-log 未生成 = 本模块未触碰非当前模块的业务代码）。
  • 本模块新增的 common/** 公共基础设施（统一响应 / 异常 / 安全 / JWT / BaseEntity）属全局基础层首次落地，非「改动其他业务模块」，不计入跨模块改动。

⑧ 与规范 / 契约的偏离

实现层无偏离——4 个 REQ 的实现端点、请求/响应字段、错误码、分层、命名、统一响应、异常处理、事务、安全均与 docs/04 技术规范及 docs/05 API 契约一致（详见各 review 报告四维核对结论）。

仅记录 2 项对 docs/05 契约的反向同步建议（实现期已落地为代码，建议择机补入契约 SSoT，非阻塞、非违规）：

  1. 新增端点 GET /api/usr/companies（REQ-USR-004 spec § 8 D1）：docs/05 仅定义 POST /api/usr/login，未单列公司列表端点。为使登录链路自洽（前端需先取 companyId），后端补齐该只读放行端点。建议补入 docs/05 § REQ-USR-004。
  2. 新增限流错误码 42901（REQ-USR-004 spec § 8 D7）：docs/05 未列该码，系为落地卡片「连续失败锁定/限流」要求引入。建议补入 docs/05 错误码段。

以上两项均已在 spec § 8 显式登记为「建议反向同步（非本 stage 强制）」，review 亦标为非阻塞建议。其余无任何偏离。

⑨ 评审与验证记录

每个 REQ 均有 round-1 review（裁决 approve）+ verify（证据验证）报告，路径 docs/superpowers/reviews/2026-06-01-REQ-USR-00{1..4}{,-verify}.md：

REQ review 裁决 关键核对结论
REQ-USR-001 approve（issues=[]） 四维（plan-alignment / quality / architecture / docs）无 must-fix；用户名查重 + DuplicateKey 兜底并发安全；密码 BCrypt + @JsonIgnore 不外泄；多表写事务回滚验证；24/24 测试绿。
REQ-USR-002 approve 全量覆盖授权、null=不更新语义、sUserName/sPassword 不可改、审计字段只读均落地；权限差量覆盖与禁用实时生效端到端验证。
REQ-USR-003 approve 单条件 8 字段 × 3 匹配、跨表 LEFT JOIN、LIKE 转义防注入、参数非法 42201 / 数据越界返回最后一页、密码不返回均验证。
REQ-USR-004 approve 认证判定顺序（限流→查用户→验密码→判禁用→校 companyId→签发+更新时间）与 spec § 8 D3 一致；防账号枚举（同码同提示）；JWT 含 exp；进程内限流 42901；安全放行 /api/usr/companies。
  • 各 review 均附非阻塞口头建议（如限流计数与事务非原子、契约反向同步、冗余去重代码简化），无任何 must-fix。
  • verify 报告确认各 REQ 在通过工具链下测试全绿、验收标准（AC）逐条覆盖。
  • 模块级 test-gate（本报告 § ⑤）在锁定 JDK17 下 125/125 全绿，作为合并默认分支前的硬闸。

⑩ 自主决策汇总（decisions）

本报告渲染过程中的自主决策见文末 decisions[]（test-gate 重跑判定、flake 归类等）。各 REQ 实现期的自主决策已在对应 spec § 8 逐条登记，要点汇总：

  • 语言取值锁定：sLanguage ∈ {中文,英文,繁体}，不取 docs/03 带审阅占位的默认值（REQ-001 D1）。
  • 管理员判定口径：以 sUserType=超级管理员 视为有写权限（无独立角色表）（REQ-001 D2 / 002 D6）。
  • 修改语义：可选字段 null = 不更新（保守不清空）；权限组全量覆盖（REQ-002 D3/D4）。
  • 查询边界：单条件查询；参数非法 42201 vs 数据越界返回最后一页二分；LIKE 通配符转义（REQ-003 D1/D2/D3）。
  • 登录链路自洽：补 GET /api/usr/companies 端点；进程内限流 42901（5 次/300 秒）；先验密码再判禁用防枚举；JWT 默认 2 小时（REQ-004 D1/D3/D7/D10）。
  • migration：4 个 REQ 全部复用 V1，无新增（REQ-001~004 各 Dn）。

⑪ 已知限制 / 后续事项

  1. 登录限流为进程内 MVP：当前按 sUserName 在进程内存计数（默认 5 次失败 / 锁定 300 秒），分布式部署下不共享、不随 @Transactional 回滚（极小窗口）。技术栈虽列 Redis 但当前无连接配置，留待后续平滑替换为 Redis 原子计数（REQ-004 spec § 8 D7、review 非阻塞建议）。
  2. 契约反向同步待补：GET /api/usr/companies 端点与 42901 错误码建议补入 docs/05-API接口契约.md（见 § ⑧）。
  3. 多租户列兜底：sBrandsId/sSubsidiaryId 由 DB 默认值 1111111111 兜底，未引入运行时多租户上下文解析（按 spec 设计，当前阶段足够）。
  4. 冗余防御代码：UsrUserServiceImpl 权限去重存在一处可简化的二次去重（review 口头建议，无功能影响）。
  5. 前端未实现：FE-01~FE-04（登录页 / 主页框架 / 用户列表 / 用户单据）属前端阶段，docs/08 § 三 待办，不在本后端模块范围。

⑫ 结论

USR 用户管理后端模块 4 个 REQ（增 / 改 / 查 / 登录）全部实现并 approve，模块级硬测试闸在锁定 JDK17 工具链下 125/125 全绿（r1，无 flake），工作树干净，无新增 migration、无跨模块改动、实现层无偏离（仅 2 项非阻塞契约反向同步建议）。满足里程碑 milestone/usr 标记的全部前置条件。

证据：docs/superpowers/module-reports/usr-test-gate-r1.md（GREEN）。