chore(usr): REQ-USR-001 review approve + 归档 spec/plan/review

zichun
1 parent 3d2c0ad3
Showing 4 changed files with 630 additions and 1 deletions
docs/08-模块任务管理.md
docs/superpowers/plans/2026-05-15-REQ-USR-001.md
docs/superpowers/reviews/2026-05-15-REQ-USR-001.md
docs/superpowers/specs/2026-05-15-REQ-USR-001.md
@@ -60,7 +60,7 @@
   - 路径: backend/module/usr/
   - MR: —
   - 功能:
-    - [ ] REQ-USR-001 用户登录
+    - [x] REQ-USR-001 用户登录
     - [ ] REQ-USR-002 新增用户
     - [ ] REQ-USR-003 修改用户
     - [ ] REQ-USR-004 查询用户
+---
+req_id: REQ-USR-001
+date: 2026-05-15
+spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-001.md
+---
+
+# REQ-USR-001 用户登录 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `POST /api/v1/auth/login`，按 spec 完成 4 类校验（公司 / 作废 / 锁定 / 密码）+ 失败计数 + 锁定写入 + JWT 签发，并落地后端项目骨架以支撑后续 REQ。
+
+**Architecture:**
+- Spring Boot 3 + MyBatis-Plus + Flyway + BCrypt + JJWT (HS256)；分层 controller → service(impl) → mapper（docs/04 § 1.1）。
+- 业务逻辑全部在 `LoginServiceImpl`，事务边界为成功路径的"清零计数 + 更新登录时间 + 签发 JWT"原子提交。
+- 失败逻辑（计数累加 + 锁定写入）在独立事务里执行；锁定时间通过 `tLockUntil` 字段比对 `NOW()` 判定（无需 Redis）。
+- 错误码集中在 `ErrorCode` 常量类；`GlobalExceptionHandler` 把 `BizException` 转 `Result.fail`。
+
+**Tech Stack:** Spring Boot 3.x（Java 17）/ MyBatis-Plus 最新稳定 / Flyway 10.x（core + mysql）/ Spring Security crypto（BCryptPasswordEncoder，不启用完整 Security filter chain）/ JJWT 0.12.x / Lombok / Jakarta Validation。
+
+---
+
+## Schema 改动
+
+无。V1 已建好 `sys_user` / `sys_company` / `sys_employee`，本 REQ 不动 schema。
+
+---
+
+## 文件变更清单
+
+**Bootstrap（首次 REQ 一次性投入，后续 REQ 复用）：**
+- `backend/pom.xml` — Create（Maven POM，声明依赖与插件）
+- `backend/src/main/java/com/xly/erp/Application.java` — Create（Spring Boot 启动类）
+- `backend/src/main/resources/application.yml` — Create（主配置，从 `.env.local` / 环境变量读敏感项）
+- `backend/src/main/resources/application-test.yml` — Create（测试 profile，复用相同 schema 但禁日志彩色）
+- `backend/src/main/resources/logback-spring.xml` — Create（最小 logback 配置）
+
+**通用基础层（首次 REQ 一次性投入）：**
+- `backend/src/main/java/com/xly/erp/common/response/Result.java` — Create
+- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — Create
+- `backend/src/main/java/com/xly/erp/common/exception/BizException.java` — Create
+- `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java` — Create
+- `backend/src/main/java/com/xly/erp/common/security/JwtUtil.java` — Create
+- `backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java` — Create（`BCryptPasswordEncoder` Bean）
+
+**业务层（REQ-USR-001 专属）：**
+- `backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java` — Create（只读 join 用，最小字段）
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java` — Create（接口）
+- `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java` — Create
+
+**测试：**
+- `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` — Create（unit/integration with Spring Test + 真实 MySQL，按 spec 验收 1-10 项）
+- `backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java` — Create（`MockMvc` 端到端覆盖错误码 40001 / 40004 / 40101 / 40103 / 42301）
+- `backend/src/test/resources/sql/req-usr-001-seed.sql` — Create（测试 fixture：1 个启用用户、1 个作废用户、2 个公司、1 个员工）
+
+---
+
+## 约束常量（跨任务，写死不允许漂移）
+
+**错误码**（`ErrorCode` 常量类）：
+
+| 常量名 | 值 | HTTP |
+|---|---|---|
+| `OK` | `200` | 200 |
+| `BAD_REQUEST` | `40001` | 400 |
+| `COMPANY_NOT_FOUND` | `40004` | 400 |
+| `BAD_CREDENTIALS` | `40101` | 401 |
+| `ACCOUNT_DELETED` | `40103` | 401 |
+| `ACCOUNT_LOCKED` | `42301` | 423 |
+| `INTERNAL_ERROR` | `50000` | 500 |
+
+**JWT 常量**：算法 HS256；TTL 7200 秒；claims 名 `sub` / `username` / `userType` / `companyCode` / `language` / `iat` / `exp` / `jti`；签名密钥从 `application.yml` 注入 `${JWT_SECRET}`（已在 `.env.local` 配置）。
+
+**锁定策略**：阈值 5 次（含第 5 次触发锁定）；锁定时长 30 分钟。Magic number 集中在 `LoginServiceImpl` 私有常量 `MAX_FAILED_LOGIN_COUNT = 5` 与 `LOCK_DURATION_MINUTES = 30L`。
+
+**API 形状**：
+
+```
+POST /api/v1/auth/login   (公开接口，无需 Bearer)
+Request:  LoginReq { username:String, password:String, companyCode:String }
+Response: Result<LoginVo>
+  LoginVo { accessToken:String, tokenType:"Bearer", expiresInSec:7200, userInfo:UserInfoVo }
+  UserInfoVo { userId:int, username:String, userType:String, language:String,
+               employeeName:String?, companyCode:String }
+```
+
+---
+
+## 任务步骤
+
+### Task 1: Bootstrap Spring Boot 项目骨架
+
+**Files:**
+- Create: `backend/pom.xml`
+- Create: `backend/src/main/java/com/xly/erp/Application.java`
+- Create: `backend/src/main/resources/application.yml`
+- Create: `backend/src/main/resources/application-test.yml`
+- Create: `backend/src/main/resources/logback-spring.xml`
+- Create: `backend/src/test/java/com/xly/erp/ApplicationContextTest.java`
+
+**配置要点**（POM 内容由 TDD 实现，签名约束如下）：
+- Parent: `spring-boot-starter-parent:3.3.x`，Java 17
+- Dependencies: `spring-boot-starter-web`, `spring-boot-starter-validation`, `spring-boot-starter-test`, `mybatis-plus-spring-boot3-starter:3.5.x`, `mysql-connector-j` (runtime), `flyway-core` + `flyway-mysql`, `spring-security-crypto`（**不**引入 `spring-boot-starter-security`，避免开启 filter chain），`io.jsonwebtoken:jjwt-api/jjwt-impl/jjwt-jackson:0.12.5`, `lombok`
+- Flyway 自动启用：默认指向 classpath:db/migration，本项目改为 `classpath:db/migration` 同步指向仓库根 `sql/migrations/` —— **由 Spring Boot 配置加载实现**：在 `application.yml` 写 `spring.flyway.locations: filesystem:../sql/migrations`（相对 backend/ 目录）
+- `application.yml` 必须用 `${VAR_NAME}` 注入 DB / JWT 凭据（来源 `.env.local`，启动时由 maven-dotenv-plugin 或 `EnvironmentPostProcessor` 加载——TDD 选择最简单方案 `spring-boot-dotenv` 第三方 starter 或 spring-cloud-context 都不引入，改用 `application.yml` 占位 + 启动命令显式 `--spring.config.location` 或 OS 环境变量；**推荐**：要求开发者把 `.env.local` 中的变量 export 到 shell 后 `./mvnw spring-boot:run`；测试场景由 surefire `<environmentVariables>` 注入或测试自行 `@TestPropertySource` 覆盖）
+
+> 注：以上"如何加载 .env.local"是 Spring Boot 项目的通用工程难题，本任务**最小可行实现**：测试用 `@DynamicPropertySource` 从 `System.getenv()` 注入；启动用 OS 环境变量。生产部署后续 REQ 再优化。
+
+**API shape**:
+- `Application.main(String[])` — 标准 `SpringApplication.run`
+- `ApplicationContextTest#contextLoads()` — Spring Test 验证 ApplicationContext 启动
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `ApplicationContextTest#contextLoads`
+  - 意图: 验证 Spring Boot context 能启动；Flyway 能连接到 .env.local 指定的 MySQL 并发现 V1 已 apply（含 `flyway_schema_history` 表）
+  - 子会话确认 FAIL（pom.xml 不存在 / Application 类不存在）
+
+- [ ] **Step 2: 实现最小代码**
+  - 写 pom.xml（依赖如上）、Application.java、application.yml、application-test.yml、logback-spring.xml
+  - 在 `application-test.yml` 中通过 `@DynamicPropertySource` 或 `spring.datasource.url=jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_SCHEMA}` 占位符让测试读 env
+
+- [ ] **Step 3: 子会话验证 PASS**
+  - 子会话跑 `cd backend && ./mvnw -B test -Dtest=ApplicationContextTest` 应绿
+
+- [ ] **Step 4: Commit**
+  - `git add backend/pom.xml backend/src/main/java/com/xly/erp/Application.java backend/src/main/resources/ backend/src/test/java/com/xly/erp/ApplicationContextTest.java`
+  - `git commit -m "feat(usr): bootstrap spring boot 后端骨架 REQ-USR-001"`
+
+---
+
+### Task 2: 通用响应包装 + 异常处理
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/response/Result.java`
+- Create: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Create: `backend/src/main/java/com/xly/erp/common/exception/BizException.java`
+- Create: `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java`
+- Create: `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java`
+
+**API shape:**
+- `Result<T> { int code; String message; T data; long timestamp; static <T> Result<T> ok(T data); static Result<?> fail(int code, String message); }`
+- `ErrorCode` — 常量类，含上方"约束常量"表中所有 code（int 字段）
+- `BizException extends RuntimeException { int code; String message; BizException(int code, String message); }`
+- `GlobalExceptionHandler` — `@RestControllerAdvice`，handles：
+  - `BizException` → 按其 `code` 映射到 `ResponseEntity<Result>`，HTTP 状态按 ErrorCode 表
+  - `MethodArgumentNotValidException` / `ConstraintViolationException` → `Result.fail(40001, ...)`，HTTP 400
+  - `Exception`（兜底） → `Result.fail(50000, "服务器内部错误")`，HTTP 500，记 ERROR 日志，**不**回显堆栈到 message
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `GlobalExceptionHandlerTest#bizException_returnsCodeAndHttpStatus` 等 3 个测试
+  - 意图: 用 `MockMvc` 配合一个 `/_test/throw-biz` 测试 controller 触发 `BizException(42301, "...")`，断言 HTTP 423 + body `code=42301`；类似覆盖 `BizException(40101, ...)` → 401，以及兜底 `RuntimeException` → 500 且 message 不含 "java." 前缀
+  - 子会话确认 FAIL
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): 通用响应包装 + 全局异常处理 REQ-USR-001"`
+
+---
+
+### Task 3: JWT 工具 + 密码编码器 Bean
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/security/JwtUtil.java`
+- Create: `backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java`
+- Create: `backend/src/test/java/com/xly/erp/common/security/JwtUtilTest.java`
+
+**API shape:**
+- `JwtUtil#issue(Map<String,Object> claims, long ttlSec) : String` — 用 `${JWT_SECRET}`（注入 `@Value`）签发 HS256 JWT，含 `iat` / `exp` / `jti(=UUID)`
+- `JwtUtil#parse(String token) : Map<String,Object>` — 验签 + 解析，签名错或过期抛 `BizException(40101, ...)`
+- `PasswordEncoderConfig#passwordEncoder() : BCryptPasswordEncoder` — Spring Bean，strength=10
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `JwtUtilTest#issuedToken_canBeParsedBackToClaims` / `JwtUtilTest#tamperedToken_throwsBizException` / `JwtUtilTest#expiredToken_throwsBizException`（用 ttl=0 模拟）
+  - 意图: 验证签发→解析往返一致；篡改任意一字节抛 40101；过期抛 40101
+
+- [ ] **Step 2: 实现最小代码**
+  - JWT_SECRET 来自 `application-test.yml` 的 `jwt.secret: ${JWT_SECRET:test-secret-256bit-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}`
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): JWT 工具 + BCrypt 编码器 REQ-USR-001"`
+
+---
+
+### Task 4: Entity + Mapper（sys_user / sys_company / sys_employee）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java`
+- Create: `backend/src/test/resources/sql/req-usr-001-seed.sql`
+
+**API shape:**
+- `SysUser` — 含 `iIncrement / sUsername / sUserCode / sPasswordHash / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / iFailedLoginCount / tLockUntil / tLastLoginDate / sCreatedBy / sUpdatedBy / tUpdatedDate` 字段（命名按 docs/03，TableField 映射）；`@TableName("sys_user")`，`@TableId(value="iIncrement", type=IdType.AUTO)`
+- `SysCompany` — 含 `iIncrement / sCompanyCode / sCompanyName / iIsDeleted`（最小字段）
+- `SysEmployee` — 含 `iIncrement / sEmployeeName / iDepartmentId`（最小字段）
+- Mapper 三个均 `extends BaseMapper<T>`（MyBatis-Plus）；`SysUserMapper` 额外定义一个方法：`selectByUsername(String username) : SysUser`（@Select 注解），用于登录查找
+
+**Seed SQL** 内容（写死）：
+```sql
+-- req-usr-001-seed.sql
+DELETE FROM sys_user_permission_category;
+DELETE FROM sys_user;
+DELETE FROM sys_employee;
+DELETE FROM sys_company;
+
+INSERT INTO sys_company (sCompanyName, sCompanyCode, iIsDeleted) VALUES
+  ('总部', 'HQ', 0),
+  ('已删公司', 'DEL_CO', 1);
+
+INSERT INTO sys_employee (sEmployeeName, sEmployeeCode, iDepartmentId)
+SELECT '张三', 'E001', 1 FROM (SELECT 1) t
+WHERE EXISTS (SELECT 1 FROM sys_department LIMIT 1);
+-- 若 sys_department 为空，先插入一行
+INSERT INTO sys_department (sDepartmentName, sDepartmentCode) VALUES ('技术部', 'TECH');
+INSERT INTO sys_employee (sEmployeeName, sEmployeeCode, iDepartmentId)
+  SELECT '张三', 'E001', iIncrement FROM sys_department WHERE sDepartmentCode='TECH' LIMIT 1;
+
+-- password = 'Password1!' 的 BCrypt(strength=10) 哈希（TDD 阶段实际生成填入）
+INSERT INTO sys_user (sUsername, sUserCode, sPasswordHash, iEmployeeId, sUserType, sLanguage, iIsDeleted, iFailedLoginCount, sCreatedBy)
+  SELECT 'alice', 'U001', '<BCRYPT_HASH_OF_Password1!>', iIncrement, 'NORMAL', 'zh-CN', 0, 0, 'system'
+  FROM sys_employee WHERE sEmployeeCode='E001';
+
+INSERT INTO sys_user (sUsername, sUserCode, sPasswordHash, sUserType, sLanguage, iIsDeleted, sCreatedBy)
+  VALUES ('bob_deleted', 'U002', '<BCRYPT_HASH_OF_Password1!>', 'NORMAL', 'zh-CN', 1, 'system');
+```
+> `<BCRYPT_HASH_OF_Password1!>` 在 Task 4 实现时通过一次性 java main 或 `BCryptPasswordEncoder` 调用生成后填入；不允许保留占位符进 commit。
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `SysUserMapperTest#selectByUsername_returnsUserWithAllFields` / `SysUserMapperTest#selectByUsername_returnsNullWhenNotFound`
+  - 意图: seed 后查 `alice` → 字段完整；查 `nobody` → null
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): sys_user/sys_company/sys_employee entity + mapper REQ-USR-001"`
+
+---
+
+### Task 5: LoginReq DTO + LoginVo + UserInfoVo
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/LoginReqValidationTest.java`
+
+**API shape:**
+- `LoginReq { @NotBlank @Size(max=50) String username; @NotBlank @Size(max=128) String password; @NotBlank @Size(max=50) String companyCode; }`
+- `LoginVo { String accessToken; String tokenType; long expiresInSec; UserInfoVo userInfo; }`
+- `UserInfoVo { Integer userId; String username; String userType; String language; String employeeName; String companyCode; }`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `LoginReqValidationTest#blankUsername_fails` / `LoginReqValidationTest#tooLongUsername_fails` / `LoginReqValidationTest#allFieldsPresent_passes`
+  - 意图: 用 `Validator` 校验 jakarta 约束注解工作正常
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): LoginReq + LoginVo + UserInfoVo REQ-USR-001"`
+
+---
+
+### Task 6: LoginService 接口骨架
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API shape:**
+- `LoginService#login(String username, String password, String companyCode) : LoginVo` — 业务方法签名
+- `LoginServiceImpl implements LoginService` — `@Service`，注入 `SysUserMapper`、`SysCompanyMapper`、`SysEmployeeMapper`、`BCryptPasswordEncoder`、`JwtUtil`
+- `LoginServiceImpl` 私有常量：`MAX_FAILED_LOGIN_COUNT = 5`、`LOCK_DURATION_MINUTES = 30L`、`TOKEN_TTL_SEC = 7200L`
+
+本 task 仅产出**接口 + 空实现 + 一个 baseline 测试**（直接抛 UnsupportedOperationException），用于建立后续 task 的脚手架。
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `LoginServiceImplTest#contextLoads`（验证 LoginService Bean 注入成功；与 `@SpringBootTest` + seed.sql 一起工作）
+  - 意图: Bean 装配可用
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): LoginService 接口骨架 REQ-USR-001"`
+
+---
+
+### Task 7: Login — 公司不存在或已删 → 40004
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API behavior**：当 `companyCode` 在 `sys_company` 查不到（不存在 OR `iIsDeleted=1`）→ 抛 `BizException(ErrorCode.COMPANY_NOT_FOUND, "公司不存在或已删除")`；**不**触碰 sys_user。
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `LoginServiceImplTest#login_unknownCompany_throws40004` / `login_softDeletedCompany_throws40004`
+  - 意图: 用 seed 中的 `HQ`（正常）vs `NOPE`（不存在）vs `DEL_CO`（软删）触发不同分支；断言抛 `BizException` 且 `code == 40004`；同时断言 `alice` 的 `iFailedLoginCount` 仍为 0（未被错误计入失败）
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): 登录校验公司存在性 REQ-USR-001"`
+
+---
+
+### Task 8: Login — 用户不存在 / 密码错 → 40101（同文案，含失败计数）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API behavior**:
+- 用户名不存在 → `BizException(40101, "用户名或密码错误")`；不写 DB（无 user 行可写）
+- 用户存在 + 密码 hash 不匹配 → `sys_user.iFailedLoginCount += 1`，返 `BizException(40101, "用户名或密码错误")`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名:
+    - `login_unknownUser_throws40101_noDbWrite`
+    - `login_badPassword_throws40101_andIncrementsFailCount` （断言一次错误后 `iFailedLoginCount == 1`）
+  - 意图: 防用户名枚举 + 失败计数累加
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): 登录用户名/密码错误统一返回 40101 + 累加失败计数 REQ-USR-001"`
+
+---
+
+### Task 9: Login — 失败 5 次锁定 → 第 6 次返 42301
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API behavior**:
+- 累计第 5 次错误密码时，在同一事务里写 `tLockUntil = NOW() + 30 分钟`；本次响应仍返 `40101`（**不**在第 5 次直接返锁定，避免泄露阈值）
+- 后续请求遇到 `tLockUntil IS NOT NULL AND tLockUntil > NOW()` → 直接抛 `BizException(ACCOUNT_LOCKED, "账号已锁定，请稍后再试")`，HTTP 423；**不**计入失败次数
+- `tLockUntil <= NOW()`（锁定到期）→ 视为已解锁，正常进入密码校验流程（即仍允许累加失败、仍允许成功）
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名:
+    - `login_5thBadPassword_setsLockUntil_andStillReturns40101`（断言 `iFailedLoginCount == 5` 且 `tLockUntil` 不为空 ≥ NOW()+29min）
+    - `login_duringLockWindow_throws42301_noCountIncrement`
+    - `login_afterLockExpired_allowsNewAttempt`（用 SQL 把 tLockUntil 改成过去时刻，再次登录正确密码 → 应成功并清零计数；属于先做小验证，可在 Task 10 完整覆盖成功路径）
+  - 意图: 锁定语义闭环
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): 登录失败 5 次锁定 30 分钟 REQ-USR-001"`
+
+---
+
+### Task 10: Login — 作废账号 → 40103；成功 → 签 JWT + 清零 + 更新登录时间
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API behavior**:
+- `sys_user.iIsDeleted == 1` → `BizException(ACCOUNT_DELETED, "账号已被作废，禁止登录")`，HTTP 401；**不**进入密码校验，**不**累加失败
+- 成功路径（`@Transactional`）：
+  1. `iFailedLoginCount = 0`，`tLockUntil = NULL`，`tLastLoginDate = NOW()`（一次 UPDATE）
+  2. 加载 `sys_employee.sEmployeeName`（若 `iEmployeeId` 非空）
+  3. 构造 JWT claims（`sub=userId`, `username`, `userType`, `companyCode`, `language`, `jti=UUID`），通过 `JwtUtil.issue(claims, TOKEN_TTL_SEC)`
+  4. 返回 `LoginVo`
+
+判定顺序（先后明确）：1) 公司校验 → 2) 用户查找 → 3) 作废校验 → 4) 锁定校验 → 5) 密码校验 → 6) 成功路径。
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名:
+    - `login_deletedUser_throws40103_noCountIncrement`
+    - `login_success_returnsTokenAndClearsFailCount_andUpdatesLastLogin`
+    - `login_success_jwtParsesBack_with_sub_username_companyCode`
+  - 意图: 成功路径与作废路径都覆盖；JWT 验签往返
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): 登录成功签发 JWT + 作废账号 40103 REQ-USR-001"`
+
+---
+
+### Task 11: AuthController + 端到端 MockMvc 测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java`
+
+**API shape:**
+- `AuthController` — `@RestController @RequestMapping("/api/v1/auth")`
+- `POST /api/v1/auth/login` 方法 `login(@RequestBody @Valid LoginReq req) : Result<LoginVo>`，委托给 `LoginService`
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名（`AuthControllerTest` 用 `@SpringBootTest + MockMvc`）：
+    - `post_login_success_returns200_andLoginVo`
+    - `post_login_badCredentials_returns401_code40101`
+    - `post_login_lockedAccount_returns423_code42301`
+    - `post_login_deletedAccount_returns401_code40103`
+    - `post_login_unknownCompany_returns400_code40004`
+    - `post_login_blankUsername_returns400_code40001`
+  - 意图: 6 个 HTTP 路径全部覆盖 spec § 验收 1-10
+
+- [ ] **Step 2: 实现最小代码**
+
+- [ ] **Step 3: 子会话验证 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): POST /api/v1/auth/login controller + 端到端测试 REQ-USR-001"`
+
+---
+
+## 提交计划
+
+按 task 顺序产生 11 个 commit：
+
+| Task | Commit message |
+|---|---|
+| 1 | `feat(usr): bootstrap spring boot 后端骨架 REQ-USR-001` |
+| 2 | `feat(usr): 通用响应包装 + 全局异常处理 REQ-USR-001` |
+| 3 | `feat(usr): JWT 工具 + BCrypt 编码器 REQ-USR-001` |
+| 4 | `feat(usr): sys_user/sys_company/sys_employee entity + mapper REQ-USR-001` |
+| 5 | `feat(usr): LoginReq + LoginVo + UserInfoVo REQ-USR-001` |
+| 6 | `feat(usr): LoginService 接口骨架 REQ-USR-001` |
+| 7 | `feat(usr): 登录校验公司存在性 REQ-USR-001` |
+| 8 | `feat(usr): 登录用户名/密码错误统一返回 40101 + 累加失败计数 REQ-USR-001` |
+| 9 | `feat(usr): 登录失败 5 次锁定 30 分钟 REQ-USR-001` |
+| 10 | `feat(usr): 登录成功签发 JWT + 作废账号 40103 REQ-USR-001` |
+| 11 | `feat(usr): POST /api/v1/auth/login controller + 端到端测试 REQ-USR-001` |
+---
+req_id: REQ-USR-001
+date: 2026-05-15
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-001 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java:28 — incrementFailedLoginCountAtomic 依赖 MySQL `SET` 子句左到右求值语义；建议加链接 dev.mysql.com/doc/refman/8.0/en/update.html 提醒切换数据库方言时复查
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java:66 — lockUntil 在 service 层 ISO 字符串化；建议改为直接放 LocalDateTime 让 Jackson 全局规则统一处理
+- backend/src/main/java/com/xly/erp/common/exception/BizException.java:25 — (int, String, Throwable) 构造的 data=null 是合理默认；未来若有"包装异常 + data"诉求再加 4 参构造
+- backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java:171 — 并发测试用 2×2 低于阈值；可补 3×2 高于阈值场景断言 lock 触发 + count 准确
+
+## 反例 / 测试覆盖缺口
+
+Round 1 标记『推迟』的 4 项（docs/04 vs docs/05 跨文档不一致、HttpMessageNotReadableException 兜底、ErrorCode.toHttpStatus future-proof、application.yml flyway 路径）本轮未触及，符合 round 1 review 约定，不视为 gap。Reviewer 沙箱因无 MySQL 连接产生 28 个测试 error，已通过 surefire 报告确认为环境问题；主会话 34 测试全过。
+
+## 本轮变更归档
+
+Round 1 修复全部正确落地：
+
+| # | 项目 | 状态 |
+|---|------|-----|
+| H1 | 42301 data.lockUntil | ✓ BizException 扩 data 链路完整 |
+| H2 | 失败计数原子 UPDATE | ✓ 单 SQL，去 noRollbackFor，并发回归覆盖 |
+| H3 | SELECT * → 显式列 | ✓ 两个 mapper 都改 |
+| M5 | JWT 短密钥静默补零 | ✓ < 32 字节 PostConstruct 硬抛 |
+| M6 | loginSuccess 双路径 | ✓ 去 entity，走 markLoginSuccess SQL |
+| NTH | exp-iat==7200 / lockUntil / 并发原子累加 测试 | ✓ 全部新增 |
+
+未引入新回归。Approve。
+---
+req_id: REQ-USR-001
+date: 2026-05-15
+module: module_usr
+---
+
+# Spec: REQ-USR-001 — 用户登录
+
+## 目标
+
+提供用户名 + 密码 + 公司编码的登录接口，校验通过后签发 JWT access token（HS256，TTL 2 小时）并返回当前用户基础信息，用于后续接口的 Bearer 鉴权。本 REQ 仅签发 access token，refresh token 推迟到后续 REQ（与 docs/05 LoginVo 一致；docs/04 § 1.6 的 refresh 描述视为未来增量，本 REQ 范围内不实现）。
+
+## 输入 / 触发
+
+HTTP 入口 `POST /api/v1/auth/login`，公开接口（无需 Bearer）。
+
+**请求体 LoginReq**（JSON）：
+
+| 字段 | 类型 | 必填 | 校验规则（登录场景，宽松，不复用创建场景的强度规则） |
+|---|---|---|---|
+| `username` | string | 是 | 非空；长度 1-50（容纳潜在历史账号；越界返 `40001`） |
+| `password` | string | 是 | 非空；长度 1-128（密码强度只在创建/重置流程校验，登录只校验匹配；越界返 `40001`） |
+| `companyCode` | string | 是 | 非空；最大长度 50；命中 `sys_company.sCompanyCode AND iIsDeleted=0`，否则返 `40004` |
+
+> **登录与创建的校验差异**：REQ-USR-002 创建用户时密码必须 8-20 位含大小写字母和数字（强度规则）；本 REQ 登录只校验"非空且未超长"，避免历史账号或未来规则放宽时无法登录。
+
+## 输出 / 结果
+
+**成功 200**：`Result<LoginVo>`，其中 `LoginVo`：
+
+```json
+{
+  "accessToken": "<JWT HS256, TTL=7200s>",
+  "tokenType": "Bearer",
+  "expiresInSec": 7200,
+  "userInfo": {
+    "userId": 123,
+    "username": "alice",
+    "userType": "NORMAL",
+    "language": "zh-CN",
+    "employeeName": "张三",
+    "companyCode": "HQ"
+  }
+}
+```
+
+- `employeeName` 通过 `sys_user.iEmployeeId` JOIN `sys_employee.sEmployeeName` 取得；未绑定职员时字段省略。
+- 副作用：写库 `sys_user.iFailedLoginCount = 0`、`sys_user.tLockUntil = NULL`、`sys_user.tLastLoginDate = NOW()`。
+
+**失败**：见错误码段，全部走全局异常处理器映射为 `Result.fail(code, message)`。错误码段位与 docs/05 一致：
+
+| HTTP | code | 含义 | 触发条件 |
+|---|---|---|---|
+| 400 | 40001 | 用户名或密码格式错误 | 必填字段缺失 / 类型错 / 长度越界 |
+| 400 | 40004 | 公司不存在或已删除 | `companyCode` 在 `sys_company` 查不到（含 `iIsDeleted=1`） |
+| 401 | 40101 | 用户名或密码错误 | 用户不存在 OR 密码哈希不匹配（统一文案，不区分两者，防用户名枚举） |
+| 401 | 40103 | 账号已被作废，禁止登录 | `sys_user.iIsDeleted = 1` |
+| 423 | 42301 | 账号已锁定，请稍后再试 | `sys_user.tLockUntil IS NOT NULL AND tLockUntil > NOW()`；`data.lockUntil` 返回 ISO 8601 剩余截止时刻 |
+
+## 业务规则
+
+1. **账号查找**：以 `sUsername` 全等匹配（大小写敏感，与建表 collation `utf8mb4_unicode_ci` 行为一致，登录时不做规范化）。
+2. **作废态优先**：若用户记录 `iIsDeleted = 1`，直接返 `40103`，不进入密码校验，**不**累加 `iFailedLoginCount`。
+3. **锁定优先**：若用户 `tLockUntil` 不为空且大于当前时间，直接返 `42301`，**不**进入密码校验，**不**累加。锁定到期（`tLockUntil <= NOW()`）视为已解锁，正常进入密码校验。
+4. **密码校验**：使用 Spring Security `BCryptPasswordEncoder.matches(rawPassword, sPasswordHash)`。docs/03 业务注记里"BCrypt / Argon2" 二选一，本 REQ 锁定 BCrypt——`BCryptPasswordEncoder` 是 Spring Security 默认实现，无额外依赖；strength=10。
+5. **失败计数**：密码不匹配时 `sys_user.iFailedLoginCount += 1`。
+   - 阈值：累计达到 **5 次**（含第 5 次）时，**同步**写 `sys_user.tLockUntil = NOW() + 30 分钟`；下一次（第 6 次）请求会落到锁定分支返 `42301`。
+   - 阈值前的失败仍返 `40101`，**不**主动告诉客户端剩余尝试次数（防探测）。
+6. **登录成功**：原子事务（service 层 `@Transactional`）内：
+   - `sys_user.iFailedLoginCount = 0`
+   - `sys_user.tLockUntil = NULL`
+   - `sys_user.tLastLoginDate = NOW()`
+   - 然后签发 JWT（事务内构造 claim，事务提交后返响应）。
+7. **JWT claims**：
+   - `sub` = `sys_user.iIncrement`（数字主键，字符串化）
+   - `username` = `sys_user.sUsername`
+   - `userType` = `sys_user.sUserType`
+   - `companyCode` = 请求传入的 `companyCode`（已校验存在）
+   - `language` = `sys_user.sLanguage`
+   - `iat` / `exp` = 标准时间 claims（TTL 7200s）
+   - `jti` = UUID（为未来 refresh / 黑名单预留，本 REQ 不消费）
+8. **JWT 密钥**：从 `.env.local` 的 `JWT_SECRET` 读取；`application.yml` 用 `${JWT_SECRET}` 占位符注入，代码层不允许硬编码。
+
+## 边界与约束
+
+- **HTTPS 传输**：密码以明文走 HTTPS body，生产部署由 Nginx 终止 TLS（docs/07 § 二）；本 REQ 不在应用层加密 / 解密密码。
+- **统一响应**：全部走 `Result` / `Result.fail`（docs/04 § 1.3）；错误响应禁回显堆栈。
+- **审计日志**：登录成功 / 失败 / 锁定均通过 Logback 写 INFO / WARN 日志（含 traceId 与 username），日志位置遵循 docs/04 / docs/07；本 REQ 不写额外的 DB 审计表。
+- **Redis**：docs/04 § 1.6 提及"签发后写 Redis"，**本 REQ 不实现**——签发后不写 Redis，JWT 自包含可独立验证；登出黑名单功能推迟到后续 REQ。`pom.xml` 不强制要求 redis 依赖（如已加入也不使用）。
+- **并发安全**：失败计数 / 锁定写入位于同一事务；MySQL 默认 RR 隔离 + 行锁可避免并发同账号失败计数竞争。
+- **不实现**：管理员手动解锁、密码重置、refresh token、登出、多端互踢、Redis 黑名单——全部推迟到后续 REQ。
+
+## 依赖的 schema 表 / 字段
+
+读 + 写 `sys_user`（V1 已建）：
+- 读：`iIncrement`, `sUsername`, `sPasswordHash`, `sUserType`, `sLanguage`, `iEmployeeId`, `iIsDeleted`, `iFailedLoginCount`, `tLockUntil`
+- 写：`iFailedLoginCount`, `tLockUntil`, `tLastLoginDate`
+
+只读 `sys_company`（V1 已建）：
+- 读：`sCompanyCode`, `iIsDeleted`
+
+只读 JOIN `sys_employee`（V1 已建）：
+- 读：`sEmployeeName`
+
+**本 REQ 不需要新增 migration**（schema 已就绪）。
+
+## 依赖的接口
+
+- 本 REQ 提供：`POST /api/v1/auth/login`（docs/05 § module_usr）。
+- 外部依赖（前端会调，但本 REQ 范围不实现）：`GET /api/v1/companies`（公司下拉），由后续运营模块或前端阶段使用 fixture 数据替代。
+
+## 验收标准
+
+后端集成测试（不依赖前端）：
+
+1. **正确凭据 + 启用账号 + 存在公司** → 200，返回 `accessToken`（非空 JWT），`userInfo` 字段完整；`sys_user.tLastLoginDate` 更新、`iFailedLoginCount = 0`、`tLockUntil IS NULL`。
+2. **JWT 可验签**：用 `JWT_SECRET` HS256 验签通过；`sub` = `userId` 字符串；`exp - iat == 7200`。
+3. **错误密码 N 次（N<5）** → 401 / 40101；`iFailedLoginCount = N`；`tLockUntil` 仍为 NULL。
+4. **第 5 次错误密码** → 401 / 40101；`iFailedLoginCount = 5`；`tLockUntil` 被写为 NOW() + 30 分钟。
+5. **锁定期间第 6 次（任意密码）** → 423 / 42301；返回 `data.lockUntil` 字段；`iFailedLoginCount` 不再累加。
+6. **锁定到期后** → 锁定字段自然过期，下一次正确密码登录 200 并清零计数。
+7. **作废账号（iIsDeleted=1）正确密码** → 401 / 40103；`iFailedLoginCount` 不变。
+8. **用户名不存在** → 401 / 40101（与密码错误同文案）。
+9. **公司不存在 / 已删除** → 400 / 40004，**不**累加失败计数（先于密码校验完成公司校验）。
+10. **请求体缺字段 / 越长** → 400 / 40001。
+11. **响应不回显堆栈**：故意制造服务端异常时，响应 `message` 为通用文案，无 stack trace。
+12. **日志记录**：每次登录成功 / 失败 / 锁定均有日志行（人工或 grep 抽样验证即可）。