fix(usr): review round-1 修复 — 多租户唯一索引 + LambdaUpdateWrapper + refresh 锁定检查 REQ-USR-004

1. V2 migration: uk_usr_user_username 改为 (sUsername, sBrandsId) 复合唯一 2. AuthServiceImpl: UpdateWrapper 换 LambdaUpdateWrapper（一致性） 3. AuthServiceImpl.refresh(): 追加 tLockUntil 检查，防绕过锁定 4. AuthServiceTest: 新增 refresh_lockedUser_throws40103 5. pom.xml: Lombok 1.18.36 适配 Java 25，surefire ByteBuddy 实验模式 6. .mvn/jvm.config + scripts/test.sh: Java 21 编译兼容性修复

fix(usr): review round-1 修复 — 多租户唯一索引 + LambdaUpdateWrapper + refresh 锁定检查 REQ-USR-004
1. V2 migration: uk_usr_user_username 改为 (sUsername, sBrandsId) 复合唯一 2. AuthServiceImpl: UpdateWrapper 换 LambdaUpdateWrapper（一致性） 3. AuthServiceImpl.refresh(): 追加 tLockUntil 检查，防绕过锁定 4. AuthServiceTest: 新增 refresh_lockedUser_throws40103 5. pom.xml: Lombok 1.18.36 适配 Java 25，surefire ByteBuddy 实验模式 6. .mvn/jvm.config + scripts/test.sh: Java 21 编译兼容性修复
zichun
1 parent 0e97c779
Showing 10 changed files with 753 additions and 12 deletions
backend/.mvn/jvm.config
backend/pom.xml
backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java
backend/src/test/java/com/example/erp/module/usr/AuthServiceTest.java
docs/03-数据库设计文档.md
docs/superpowers/plans/2026-05-08-REQ-USR-004.md
docs/superpowers/reviews/2026-05-08-REQ-USR-004.md
docs/superpowers/specs/2026-05-08-REQ-USR-004.md
scripts/test.sh
sql/migrations/V2__fix_username_unique_per_tenant.sql
+-XX:+EnableDynamicAgentLoading
@@ -20,6 +20,7 @@
     <properties>
         <java.version>21</java.version>
+        <lombok.version>1.18.36</lombok.version>
         <mybatis-plus.version>3.5.7</mybatis-plus.version>
         <jjwt.version>0.12.6</jjwt.version>
         <hutool.version>5.8.28</hutool.version>
@@ -2,7 +2,7 @@ package com.example.erp.module.usr.service.impl;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
-import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
 import com.example.erp.common.constants.AuthErrorCode;
 import com.example.erp.common.exception.BizException;
 import com.example.erp.common.util.JwtUtil;
@@ -68,12 +68,12 @@ public class AuthServiceImpl implements AuthService {
         // 5. 密码校验
         if (!passwordEncoder.matches(req.getPassword(), user.getSPasswordHash())) {
             int newCount = (user.getILoginFailCount() == null ? 0 : user.getILoginFailCount()) + 1;
-            UpdateWrapper<UsrUserEntity> updateWrapper = new UpdateWrapper<UsrUserEntity>()
-                    .eq("sId", user.getSId())
-                    .set("iLoginFailCount", newCount);
+            LambdaUpdateWrapper<UsrUserEntity> updateWrapper = new LambdaUpdateWrapper<UsrUserEntity>()
+                    .eq(UsrUserEntity::getSId, user.getSId())
+                    .set(UsrUserEntity::getILoginFailCount, newCount);
             if (newCount >= 5) {
                 LocalDateTime lockUntil = LocalDateTime.now().plusMinutes(30);
-                updateWrapper.set("tLockUntil", lockUntil);
+                updateWrapper.set(UsrUserEntity::getTLockUntil, lockUntil);
                 userMapper.update(null, updateWrapper);
                 throw new BizException(AuthErrorCode.ACCOUNT_LOCKED, "账号已被锁定，请 30 分钟后重试");
             }
@@ -82,11 +82,11 @@ public class AuthServiceImpl implements AuthService {
         }
         // 6. 登录成功
-        userMapper.update(null, new UpdateWrapper<UsrUserEntity>()
-                .eq("sId", user.getSId())
-                .set("iLoginFailCount", 0)
-                .set("tLockUntil", null)
-                .set("tLastLoginDate", LocalDateTime.now()));
+        userMapper.update(null, new LambdaUpdateWrapper<UsrUserEntity>()
+                .eq(UsrUserEntity::getSId, user.getSId())
+                .set(UsrUserEntity::getILoginFailCount, 0)
+                .set(UsrUserEntity::getTLockUntil, null)
+                .set(UsrUserEntity::getTLastLoginDate, LocalDateTime.now()));
         String accessToken = jwtUtil.generateAccessToken(
                 user.getSId(), user.getSUsername(), user.getSUserType(), brand.getSId());
@@ -115,7 +115,9 @@ public class AuthServiceImpl implements AuthService {
         UsrUserEntity user = userMapper.selectOne(
                 new LambdaQueryWrapper<UsrUserEntity>().eq(UsrUserEntity::getSId, userId));
-        if (user == null || Integer.valueOf(1).equals(user.getBIsDisabled())) {
+        if (user == null
+                || Integer.valueOf(1).equals(user.getBIsDisabled())
+                || (user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now()))) {
             throw new BizException(AuthErrorCode.REFRESH_TOKEN_INVALID, "Refresh Token 已失效，请重新登录");
         }
@@ -154,6 +154,19 @@ class AuthServiceTest {
     }
     @Test
+    void refresh_lockedUser_throws40103() {
+        Claims claims = mock(Claims.class);
+        when(claims.getSubject()).thenReturn("u1");
+        when(claims.get("brandId", String.class)).thenReturn("b1");
+        when(jwtUtil.parseRefreshToken("valid-refresh")).thenReturn(claims);
+        user.setTLockUntil(LocalDateTime.now().plusMinutes(25));
+        when(userMapper.selectOne(any())).thenReturn(user);
+
+        BizException ex = assertThrows(BizException.class, () -> authService.refresh("valid-refresh"));
+        assertEquals(40103, ex.getCode());
+    }
+
+    @Test
     void refresh_invalidRefreshToken_throws40103() {
         when(jwtUtil.parseRefreshToken("bad-token"))
                 .thenThrow(new BizException(40103, "Refresh Token 已失效，请重新登录"));
@@ -64,7 +64,7 @@ usr_user（用户主表）
 ### 索引
-- `uk_usr_user_username` (UNIQUE): `sUsername` — 全局唯一约束
+- `uk_usr_user_username_tenant` (UNIQUE): `(sUsername, sBrandsId)` — 用户名在同一 brand 内唯一（V2 迁移：原全局唯一改为多租户复合唯一）
 - `uk_usr_user_usercode` (UNIQUE): `sUserCode` — 用户号唯一约束
 - `idx_usr_user_tenant` (INDEX): `sBrandsId, sSubsidiaryId` — 多租户隔离查询
 - `idx_usr_user_type` (INDEX): `sUserType` — 按用户类型过滤
+---
+req_id: REQ-USR-004
+date: 2026-05-08
+spec_ref: docs/superpowers/specs/2026-05-08-REQ-USR-004.md
+---
+
+# REQ-USR-004 用户登录 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 从零搭建后端 Spring Boot 3 项目与前端 Vite+React 项目，实现三条公开认证接口（POST /api/auth/login、POST /api/auth/refresh、GET /api/auth/brands），完成多租户隔离的 JWT 登录认证及账号锁定防暴力破解。
+
+**Architecture:** 后端分四层推进：公共层（Result/BizException/JwtUtil）→ 数据访问层（BrandMapper/UsrUserMapper）→ 业务层（AuthServiceImpl，含 brand 多租户查找、BCrypt 校验、禁用/锁定检查、失败计数、JWT 签发 6 条业务规则）→ 接口层（SecurityConfig + AuthController）。前端分三层推进：项目骨架 → Axios 封装 + Redux authSlice → LoginPage.tsx 含 brand 下拉 + 用户名密码表单。
+
+**Tech Stack:** Spring Boot 3.x · Spring Security · JJWT 0.12.x · MyBatis-Plus 3.5.x · Flyway 10.x · MySQL 8.x · Vite · React 18 · Ant Design 5.x · Redux Toolkit · Axios · Vitest + @testing-library/react
+
+---
+
+## Schema 改动
+
+无（`sql/migrations/V1__initial_schema.sql` 已包含 `usr_user` + `brand` 表，已 apply 至测试库 `xlyweberp_vibe_erp_test`）
+
+## 文件变更清单
+
+### 后端（全部新建）
+- `backend/pom.xml` — 创建（Spring Boot 3 Maven 项目根 POM）
+- `backend/src/main/java/com/example/erp/Application.java` — 创建（启动类）
+- `backend/src/main/resources/application.yml` — 创建（主配置，DB/JWT 用 `${ENV_VAR}` 占位）
+- `backend/src/main/resources/application-dev.yml` — 创建（dev profile，Flyway baseline 防重复迁移）
+- `backend/src/main/resources/db/migration/V1__initial_schema.sql` — 创建（内容与 `sql/migrations/V1__initial_schema.sql` 完全一致，供 Flyway classpath 找到）
+- `backend/src/main/java/com/example/erp/common/response/Result.java` — 创建（统一响应体，含 timestamp）
+- `backend/src/main/java/com/example/erp/common/exception/BizException.java` — 创建（业务异常基类）
+- `backend/src/main/java/com/example/erp/common/constants/AuthErrorCode.java` — 创建（认证错误码常量）
+- `backend/src/main/java/com/example/erp/common/exception/GlobalExceptionHandler.java` — 创建（@RestControllerAdvice）
+- `backend/src/main/java/com/example/erp/common/util/JwtUtil.java` — 创建（JWT 生成 + 解析）
+- `backend/src/main/java/com/example/erp/config/JwtProperties.java` — 创建（@ConfigurationProperties("jwt")）
+- `backend/src/main/java/com/example/erp/module/usr/entity/BrandEntity.java` — 创建（brand 表映射）
+- `backend/src/main/java/com/example/erp/module/usr/entity/UsrUserEntity.java` — 创建（usr_user 表映射）
+- `backend/src/main/java/com/example/erp/module/usr/mapper/BrandMapper.java` — 创建（extends BaseMapper<BrandEntity>）
+- `backend/src/main/java/com/example/erp/module/usr/mapper/UsrUserMapper.java` — 创建（extends BaseMapper<UsrUserEntity>）
+- `backend/src/main/java/com/example/erp/config/MyBatisPlusConfig.java` — 创建（@MapperScan + 分页插件）
+- `backend/src/main/java/com/example/erp/module/usr/dto/LoginReqDTO.java` — 创建（登录入参）
+- `backend/src/main/java/com/example/erp/module/usr/dto/RefreshTokenReqDTO.java` — 创建（刷新入参）
+- `backend/src/main/java/com/example/erp/module/usr/vo/LoginVO.java` — 创建（登录出参，含内部静态类 UserInfoVO）
+- `backend/src/main/java/com/example/erp/module/usr/vo/BrandVO.java` — 创建（brand 下拉出参）
+- `backend/src/main/java/com/example/erp/module/usr/service/AuthService.java` — 创建（接口）
+- `backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java` — 创建（业务实现）
+- `backend/src/main/java/com/example/erp/config/BeanConfig.java` — 创建（@Bean BCryptPasswordEncoder；与 SecurityConfig 分离，避免循环依赖）
+- `backend/src/main/java/com/example/erp/config/SecurityConfig.java` — 创建（放行 /api/auth/**，注册 JwtFilter）
+- `backend/src/main/java/com/example/erp/config/JwtAuthenticationFilter.java` — 创建（OncePerRequestFilter，验证 Bearer Token）
+- `backend/src/main/java/com/example/erp/module/usr/controller/AuthController.java` — 创建（3 个端点）
+- `backend/src/test/java/com/example/erp/ApplicationContextTest.java` — 创建
+- `backend/src/test/java/com/example/erp/common/JwtUtilTest.java` — 创建
+- `backend/src/test/java/com/example/erp/module/usr/BrandMapperTest.java` — 创建
+- `backend/src/test/java/com/example/erp/module/usr/AuthServiceTest.java` — 创建
+- `backend/src/test/java/com/example/erp/module/usr/AuthControllerTest.java` — 创建
+
+### 前端（全部新建）
+- `frontend/package.json` — 创建
+- `frontend/vite.config.ts` — 创建（代理 /api → http://localhost:8080）
+- `frontend/tsconfig.json` — 创建
+- `frontend/index.html` — 创建
+- `frontend/src/main.tsx` — 创建（Provider + BrowserRouter + App）
+- `frontend/src/App.tsx` — 创建（路由表，/ 重定向 /login，受保护路由守卫 PrivateRoute）
+- `frontend/src/styles/tokens.css` — 创建（内容与根目录 `src/styles/tokens.css` 一致）
+- `frontend/src/api/request.ts` — 创建（Axios 实例 + 请求/响应拦截器 + 401 refresh 流程）
+- `frontend/src/api/auth.ts` — 创建（login / refresh / getBrands 接口函数）
+- `frontend/src/store/index.ts` — 创建（configureStore）
+- `frontend/src/store/slices/authSlice.ts` — 创建（setCredentials / clearCredentials）
+- `frontend/src/pages/usr/LoginPage.tsx` — 创建（AntD Form：brand Select + 用户名 + 密码 + 提交）
+- `frontend/src/test/setup.ts` — 创建（@testing-library/jest-dom setup）
+- `frontend/src/test/authSlice.test.ts` — 创建
+- `frontend/src/test/LoginPage.test.tsx` — 创建
+
+---
+
+## 任务步骤
+
+### Task 1: 后端项目骨架
+
+**Files:**
+- 创建: `backend/pom.xml`
+- 创建: `backend/src/main/java/com/example/erp/Application.java`
+- 创建: `backend/src/main/resources/application.yml`
+- 创建: `backend/src/main/resources/application-dev.yml`
+- 创建: `backend/src/main/resources/db/migration/V1__initial_schema.sql`
+- 测试: `backend/src/test/java/com/example/erp/ApplicationContextTest.java`
+
+**pom.xml 必须包含的依赖：**
+- `spring-boot-starter-parent` 3.x（parent）
+- `spring-boot-starter-web`, `spring-boot-starter-security`, `spring-boot-starter-validation`, `spring-boot-starter-test`
+- `mybatis-plus-spring-boot3-starter` 3.5.x
+- `mysql-connector-j`（runtime scope）
+- `flyway-core` + `flyway-mysql`（10.x）
+- `jjwt-api` + `jjwt-impl` + `jjwt-jackson`（0.12.x；impl/jackson 用 runtime scope）
+- `lombok`（optional）
+- `hutool-all` 5.8.x
+
+**application.yml 关键片段：**
+```yaml
+spring:
+  datasource:
+    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+    driver-class-name: com.mysql.cj.jdbc.Driver
+  flyway:
+    locations: classpath:db/migration
+    baseline-on-migrate: true
+    baseline-version: 1
+server:
+  port: 8080
+jwt:
+  secret: ${JWT_SECRET}
+  access-token-expiry: 86400
+  refresh-token-expiry: 604800
+```
+
+**application-dev.yml：**
+```yaml
+spring:
+  config:
+    import: optional:file:.env.local[.properties]
+```
+
+**说明：** `.env.local` 含 `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_SCHEMA`, `JWT_SECRET`。dev profile 通过 `spring.config.import` 自动加载；`baseline-on-migrate=true` + `baseline-version=1` 让 Flyway 把已有 schema 标记为 V1 已应用，不重复执行。
+
+- [ ] **Step 1: 写失败测试**
+  - 测试名: `ApplicationContextTest#contextLoads`
+  - 意图: `@SpringBootTest` 启动 ApplicationContext 不报错（验证 Bean 配置和 DB 连接）
+  - 子会话确认 FAIL（项目不存在，无法编译）
+
+- [ ] **Step 2: 创建 Maven 项目结构**
+  - 创建目录树：`backend/src/main/java/com/example/erp/`、`backend/src/main/resources/db/migration/`、`backend/src/test/java/com/example/erp/`
+  - 写 pom.xml（含上述依赖）
+  - 写 Application.java（`@SpringBootApplication`，标准 main 方法）
+  - 写 application.yml + application-dev.yml（按上述片段）
+  - 复制 `sql/migrations/V1__initial_schema.sql` 内容到 `backend/src/main/resources/db/migration/V1__initial_schema.sql`
+  - 写 `ApplicationContextTest.java`（`@SpringBootTest`，空的 `contextLoads()` 方法）
+  - 写 `backend/src/test/java/com/example/erp/TestApplication.java`（继承 `Application`，供测试使用 dev profile）
+
+- [ ] **Step 3: 子会话运行 `cd backend && mvn test -Dspring.profiles.active=dev`，确认 contextLoads PASS**
+
+- [ ] **Step 4: Commit**
+  - `git add backend/`
+  - `git commit -m "chore(backend): init Spring Boot 3 project skeleton REQ-USR-004"`
+
+---
+
+### Task 2: Common 层（Result / BizException / ErrorCode / GlobalExceptionHandler）
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/common/response/Result.java`
+- 创建: `backend/src/main/java/com/example/erp/common/exception/BizException.java`
+- 创建: `backend/src/main/java/com/example/erp/common/constants/AuthErrorCode.java`
+- 创建: `backend/src/main/java/com/example/erp/common/exception/GlobalExceptionHandler.java`
+- 测试: `backend/src/test/java/com/example/erp/common/ResultTest.java`
+
+**API shape:**
+- `Result<T>` — 字段：`int code`，`String message`，`T data`，`long timestamp`
+  - `static <T> Result<T> ok(T data)` → code=200, message="操作成功", timestamp=System.currentTimeMillis()
+  - `static <T> Result<T> fail(int code, String message)` → data=null, timestamp=System.currentTimeMillis()
+- `BizException(int code, String message)` — 继承 RuntimeException，含 `int code` 字段
+- `GlobalExceptionHandler (@RestControllerAdvice)`:
+  - `handleBizException(BizException e)` → `Result.fail(e.getCode(), e.getMessage())`，HTTP 200
+  - `handleMethodArgumentNotValid(MethodArgumentNotValidException e)` → `Result.fail(40001, 首个字段错误信息)`，HTTP 200
+  - `handleException(Exception e)` → `Result.fail(99000, "系统内部错误")`，记 Logback error 级日志
+
+**合同级错误码常量（AuthErrorCode.java，`public static final int`）：**
+```java
+USERNAME_OR_PASSWORD_ERROR = 40100   // 用户名或密码错误（不区分哪个，防枚举）
+ACCOUNT_DISABLED = 40101             // 账号已被禁用，请联系管理员
+ACCOUNT_LOCKED = 40102               // 账号已被锁定，请 N 分钟后重试
+REFRESH_TOKEN_INVALID = 40103        // Refresh Token 已失效，请重新登录
+```
+
+- [ ] **Step 1: 写失败测试**
+  - `ResultTest#ok_setsCode200AndData` — `Result.ok("hello").getCode() == 200 && "hello".equals(result.getData())`
+  - `ResultTest#fail_setsCodeAndNullData` — `Result.fail(40100, "msg").getCode() == 40100 && result.getData() == null`
+  - `ResultTest#ok_hasTimestamp` — `Result.ok(null).getTimestamp() > 0`
+  - 子会话确认 FAIL（类不存在）
+
+- [ ] **Step 2: 实现 Result.java + BizException.java + AuthErrorCode.java + GlobalExceptionHandler.java**
+
+- [ ] **Step 3: 子会话运行 `mvn test`，确认 3 个 ResultTest PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): common Result/BizException/AuthErrorCode/GlobalExceptionHandler REQ-USR-004"`
+
+---
+
+### Task 3: JwtUtil
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/config/JwtProperties.java`
+- 创建: `backend/src/main/java/com/example/erp/common/util/JwtUtil.java`
+- 测试: `backend/src/test/java/com/example/erp/common/JwtUtilTest.java`
+
+**API shape:**
+- `JwtProperties (@ConfigurationProperties("jwt"))` — `String secret`，`long accessTokenExpiry`（秒），`long refreshTokenExpiry`（秒）；加 `@EnableConfigurationProperties(JwtProperties.class)` 于 Application 或 Config 类
+- `JwtUtil (@Component)`：注入 JwtProperties
+  - `generateAccessToken(String userId, String username, String userType, String brandId) : String`
+    - claims: sub=userId, "username"=username, "userType"=userType, "brandId"=brandId, exp=now + accessTokenExpiry 秒
+    - HMAC-SHA256，key = `Keys.hmacShaKeyFor(properties.getSecret().getBytes(StandardCharsets.UTF_8))`
+  - `generateRefreshToken(String userId, String brandId) : String`
+    - claims: sub=userId, "brandId"=brandId, "type"="refresh", exp=now + refreshTokenExpiry 秒
+  - `parseAccessToken(String token) : Claims`
+    - 若签名无效或过期 → throw `new BizException(AuthErrorCode.REFRESH_TOKEN_INVALID, "Token 已失效，请重新登录")`
+  - `parseRefreshToken(String token) : Claims`
+    - 解析同 parseAccessToken
+    - 验证 claim "type" == "refresh"；否则 → throw BizException(40103)
+
+- [ ] **Step 1: 写失败测试**
+  - `JwtUtilTest#generateAndParseAccessToken_containsAllClaims`
+    - 构造 JwtUtil（properties: secret="testSecretKey32CharacterMinLength!", accessTokenExpiry=86400, refreshTokenExpiry=604800）
+    - 生成 access token，parseAccessToken → sub=="u1", username=="admin", userType=="超级管理员", brandId=="b1"
+  - `JwtUtilTest#parseRefreshToken_withAccessToken_throws40103`
+    - 生成 access token，传入 parseRefreshToken → 抛 BizException，code=40103
+  - `JwtUtilTest#parseAccessToken_withExpiredToken_throws40103`
+    - 构造 JwtUtil（accessTokenExpiry=-1 或 0），生成 token 后 parseAccessToken → 抛 BizException，code=40103
+  - 子会话确认 FAIL（类不存在）
+
+- [ ] **Step 2: 实现 JwtProperties + JwtUtil**
+  - JJWT 0.12.x API：`Jwts.builder()...signWith(key, Jwts.SIG.HS256).compact()`；解析：`Jwts.parser().verifyWith(key).build().parseSignedClaims(token).getPayload()`
+
+- [ ] **Step 3: 子会话运行 JwtUtilTest（3 个测试），确认 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): JwtUtil generate + parse access/refresh token REQ-USR-004"`
+
+---
+
+### Task 4: Entity + Mapper（BrandEntity / UsrUserEntity）
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/module/usr/entity/BrandEntity.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/entity/UsrUserEntity.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/mapper/BrandMapper.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/mapper/UsrUserMapper.java`
+- 创建: `backend/src/main/java/com/example/erp/config/MyBatisPlusConfig.java`
+- 测试: `backend/src/test/java/com/example/erp/module/usr/BrandMapperTest.java`
+
+**API shape:**
+- `BrandEntity (@TableName("brand"))` — 字段（均 `@TableField("<column_name>")`）：`iIncrement`（@TableId，AUTO），`sId`，`sNo`，`sName`，`sShortName`，`sBrandsId`，`sSubsidiaryId`，`tCreateDate(LocalDateTime)`
+- `UsrUserEntity (@TableName("usr_user"))` — 字段：`iIncrement`（@TableId，AUTO），`sId`，`sBrandsId`，`sSubsidiaryId`，`tCreateDate(LocalDateTime)`，`sUserCode`，`sUsername`，`sPasswordHash`，`sUserType`，`sLanguage`，`bCanEditDoc(Integer)`，`bIsDisabled(Integer)`，`sEmployeeId`，`sCreatorUsername`，`tLastLoginDate(LocalDateTime)`，`iLoginFailCount(Integer)`，`tLockUntil(LocalDateTime)`
+- `BrandMapper extends BaseMapper<BrandEntity>`（无额外方法）
+- `UsrUserMapper extends BaseMapper<UsrUserEntity>`（无额外方法；更新逻辑在 Service 用 LambdaUpdateWrapper 完成）
+- `MyBatisPlusConfig (@Configuration)` — `@MapperScan("com.example.erp.module.*.mapper")`；注册 `MybatisPlusInterceptor` + `PaginationInnerInterceptor(DbType.MYSQL)`
+
+**测试（BrandMapperTest — @SpringBootTest，使用真实测试库）：**
+- `@BeforeEach` 插入 brand 行：`sId='b-test-001', sNo='TST', sName='测试版', iIncrement=null`（自增），其余字段留 null
+- `@AfterEach` DELETE WHERE sNo='TST'
+- 测试方法 `findByNo_returnsCorrectBrand` — `new LambdaQueryWrapper<BrandEntity>().eq(BrandEntity::getSNo, "TST")` selectOne → sName == "测试版"
+
+- [ ] **Step 1: 写失败测试**
+  - `BrandMapperTest#findByNo_returnsCorrectBrand`
+  - 子会话确认 FAIL（类不存在）
+
+- [ ] **Step 2: 实现 Entity + Mapper + MyBatisPlusConfig**
+  - 注意：Entity 字段名用 Java camelCase，`@TableField` 注解对应数据库实际列名（如 `@TableField("sBrandsId")` 或直接用 MyBatis-Plus 全局下划线转换——由于列名本身是驼峰，需关闭 `map-underscore-to-camel-case` 或手动 @TableField）
+
+- [ ] **Step 3: 子会话运行 BrandMapperTest，确认 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): BrandEntity/UsrUserEntity + Mapper REQ-USR-004"`
+
+---
+
+### Task 5: AuthService — 登录核心逻辑
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/module/usr/dto/LoginReqDTO.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/vo/LoginVO.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/service/AuthService.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java`
+- 创建: `backend/src/main/java/com/example/erp/config/BeanConfig.java`
+- 测试: `backend/src/test/java/com/example/erp/module/usr/AuthServiceTest.java`
+
+**API shape:**
+- `LoginReqDTO` — `@NotBlank String brandNo`，`@NotBlank String username`，`@NotBlank String password`
+- `LoginVO` — `String accessToken`，`String refreshToken`，`long expiresIn`（固定值 86400），`UserInfoVO userInfo`
+  - `UserInfoVO (static inner class)` — `String userId`，`String username`，`String userType`，`String language`，`String brandId`
+- `AuthService` — `LoginVO login(LoginReqDTO req)`；`String refresh(String refreshToken)`；`List<BrandVO> getBrands()`
+- `AuthServiceImpl (@Service @Transactional)` — 注入 `BrandMapper`，`UsrUserMapper`，`JwtUtil`，`BCryptPasswordEncoder`
+
+**AuthServiceImpl.login 业务规则（按顺序）：**
+1. `brandMapper.selectOne(new LambdaQueryWrapper<BrandEntity>().eq(BrandEntity::getSNo, req.getBrandNo()))` → null → `throw new BizException(40100, "用户名或密码错误")`
+2. `userMapper.selectOne(new LambdaQueryWrapper<UsrUserEntity>().eq(UsrUserEntity::getSUsername, req.getUsername()).eq(UsrUserEntity::getSBrandsId, brand.getSId()))` → null → `throw new BizException(40100, "用户名或密码错误")`
+3. `user.getBIsDisabled() == 1` → `throw new BizException(40101, "账号已被禁用，请联系管理员")`
+4. `user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now())` → 计算 remainMinutes = `(int) Math.ceil(ChronoUnit.SECONDS.between(LocalDateTime.now(), user.getTLockUntil()) / 60.0)` → `throw new BizException(40102, "账号已被锁定，请 " + remainMinutes + " 分钟后重试")`
+5. `!passwordEncoder.matches(req.getPassword(), user.getSPasswordHash())` → `int newCount = user.getILoginFailCount() + 1`
+   - `newCount >= 5`: `LocalDateTime lockUntil = LocalDateTime.now().plusMinutes(30)`；`userMapper.update(null, new LambdaUpdateWrapper<UsrUserEntity>().eq(UsrUserEntity::getSId, user.getSId()).set(UsrUserEntity::getILoginFailCount, newCount).set(UsrUserEntity::getTLockUntil, lockUntil))` → `throw new BizException(40102, "账号已被锁定，请 30 分钟后重试")`
+   - `newCount < 5`: `userMapper.update(null, new LambdaUpdateWrapper<UsrUserEntity>().eq(UsrUserEntity::getSId, user.getSId()).set(UsrUserEntity::getILoginFailCount, newCount))` → `throw new BizException(40100, "用户名或密码错误")`
+6. 成功：`userMapper.update(null, new LambdaUpdateWrapper<UsrUserEntity>().eq(UsrUserEntity::getSId, user.getSId()).set(UsrUserEntity::getILoginFailCount, 0).set(UsrUserEntity::getTLockUntil, null).set(UsrUserEntity::getTLastLoginDate, LocalDateTime.now()))`；签发 tokens；返回 LoginVO
+
+- [ ] **Step 1: 写 7 个失败单元测试（AuthServiceTest — @ExtendWith(MockitoExtension.class)，mock BrandMapper/UsrUserMapper/JwtUtil/BCryptPasswordEncoder）**
+  - `login_brandNotFound_throws40100` — brandMapper.selectOne → null → BizException(40100)
+  - `login_userNotFound_throws40100` — brand 存在，userMapper.selectOne → null → BizException(40100)
+  - `login_accountDisabled_throws40101` — user.bIsDisabled=1 → BizException(40101)
+  - `login_accountLocked_throws40102WithRemainingMinutes` — user.tLockUntil=now+20min → BizException(40102)，message 含 "20 分钟"
+  - `login_wrongPassword_firstTime_throws40100AndIncrementsCount` — BCrypt 不匹配，iLoginFailCount=0 → 更新为 1，throw 40100
+  - `login_wrongPassword_5thTime_setsLockAndThrows40102` — BCrypt 不匹配，iLoginFailCount=4 → 更新为 5，设 tLockUntil，throw 40102
+  - `login_success_resetsCountAndReturnsTokens` — BCrypt 匹配 → reset count，issue tokens，返回 LoginVO
+
+- [ ] **Step 2: 实现 LoginReqDTO + LoginVO + AuthService + AuthServiceImpl.login()**
+  - `BCryptPasswordEncoder` 注入：在 Task 5 中同步创建 `BeanConfig.java`（`@Configuration @Bean BCryptPasswordEncoder passwordEncoder()`），使 Spring context（ApplicationContextTest）在 Task 5 之后仍能正常加载；SecurityConfig（Task 7）不重复声明此 Bean
+
+- [ ] **Step 3: 子会话运行 AuthServiceTest（7 个测试），确认 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): AuthService.login multi-tenant + lockout logic REQ-USR-004"`
+
+---
+
+### Task 6: AuthService — refresh + getBrands
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/module/usr/dto/RefreshTokenReqDTO.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/vo/BrandVO.java`
+- 修改: `backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java`（新增 refresh + getBrands）
+- 测试: `backend/src/test/java/com/example/erp/module/usr/AuthServiceTest.java`（追加 3 个测试方法）
+
+**API shape:**
+- `RefreshTokenReqDTO` — `@NotBlank String refreshToken`
+- `BrandVO` — `String sNo`，`String sName`
+- `AuthServiceImpl#refresh(String refreshToken) : String`
+  1. `Claims claims = jwtUtil.parseRefreshToken(refreshToken)` — 无效/过期自动抛 BizException(40103)
+  2. `String userId = claims.getSubject(); String brandId = claims.get("brandId", String.class)`
+  3. `UsrUserEntity user = userMapper.selectOne(new LambdaQueryWrapper<UsrUserEntity>().eq(UsrUserEntity::getSId, userId))` → null 或 `bIsDisabled=1` → throw BizException(40103, "Refresh Token 已失效，请重新登录")
+  4. 签发新 accessToken：`jwtUtil.generateAccessToken(user.getSId(), user.getSUsername(), user.getSUserType(), brandId)`；返回新 accessToken 字符串
+- `AuthServiceImpl#getBrands() : List<BrandVO>`
+  - `brandMapper.selectList(new QueryWrapper<BrandEntity>().select("sNo", "sName").orderByAsc("sName"))` → 映射为 BrandVO 列表
+
+- [ ] **Step 1: 写 3 个失败测试（追加到 AuthServiceTest）**
+  - `refresh_validRefreshToken_returnsNewAccessToken` — parseRefreshToken 成功，查库返回有效 user → generateAccessToken 被调用，返回新 token
+  - `refresh_invalidRefreshToken_throws40103` — parseRefreshToken 抛 BizException(40103)
+  - `getBrands_returnsListSortedByName` — brandMapper.selectList 返回 [b1, b2] → 结果 List<BrandVO> 包含对应 sNo/sName
+
+- [ ] **Step 2: 实现 RefreshTokenReqDTO + BrandVO + AuthServiceImpl#refresh() + AuthServiceImpl#getBrands()**
+
+- [ ] **Step 3: 子会话运行 AuthServiceTest（新增 3 个测试），确认 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): AuthService.refresh + getBrands REQ-USR-004"`
+
+---
+
+### Task 7: SecurityConfig + JwtAuthenticationFilter + AuthController
+
+**Files:**
+- 创建: `backend/src/main/java/com/example/erp/config/SecurityConfig.java`
+- 创建: `backend/src/main/java/com/example/erp/config/JwtAuthenticationFilter.java`
+- 创建: `backend/src/main/java/com/example/erp/module/usr/controller/AuthController.java`
+- 测试: `backend/src/test/java/com/example/erp/module/usr/AuthControllerTest.java`
+
+**API shape:**
+- `SecurityConfig (@Configuration @EnableWebSecurity)`:
+  - `@Bean SecurityFilterChain`: `csrf().disable()`；`sessionManagement(STATELESS)`；`authorizeHttpRequests`: `permitAll` for `/api/auth/**`，其余 `authenticated`
+  - `addFilterBefore(JwtAuthenticationFilter, UsernamePasswordAuthenticationFilter)`
+  - 不再声明 BCryptPasswordEncoder @Bean（已在 BeanConfig.java 声明）
+- `JwtAuthenticationFilter extends OncePerRequestFilter`:
+  - 读 `Authorization` header，提取 Bearer token
+  - `jwtUtil.parseAccessToken(token)` → 设 `UsernamePasswordAuthenticationToken` 入 SecurityContextHolder
+  - token 无效 → 不设 context（Spring Security 后续返回 401）；请求路径匹配 `/api/auth/**` → 直接放行不解析
+- `AuthController (@RestController @RequestMapping("/api/auth") @RequiredArgsConstructor)`:
+  - `@PostMapping("/login") Result<LoginVO> login(@Valid @RequestBody LoginReqDTO req)` → `Result.ok(authService.login(req))`
+  - `@PostMapping("/refresh") Result<Map<String,String>> refresh(@Valid @RequestBody RefreshTokenReqDTO req)` → `Result.ok(Map.of("accessToken", authService.refresh(req.getRefreshToken())))`
+  - `@GetMapping("/brands") Result<List<BrandVO>> brands()` → `Result.ok(authService.getBrands())`
+
+- [ ] **Step 1: 写 4 个 MockMvc 失败测试（AuthControllerTest — @WebMvcTest + @MockBean AuthService）**
+  - `login_wrongPassword_returns40100` — authService.login 抛 BizException(40100) → 响应 JSON code=40100
+  - `login_validCredentials_returns200AndTokens` — authService.login 返回 LoginVO → 响应 JSON code=200，accessToken 非空
+  - `refresh_invalidToken_returns40103` — authService.refresh 抛 BizException(40103) → code=40103
+  - `getBrands_returns200AndList` — authService.getBrands 返回 [BrandVO{sNo="STD", sName="标准版"}] → code=200，list 含该项
+
+- [ ] **Step 2: 实现 SecurityConfig + JwtAuthenticationFilter + AuthController**
+
+- [ ] **Step 3: 子会话运行 AuthControllerTest（4 个测试），确认 PASS**
+
+- [ ] **Step 4: 手动 smoke test（如果后端可本地运行）**
+  - `cd backend && mvn spring-boot:run -Dspring-boot.run.profiles=dev`（需 .env.local 在 backend/ 父目录可找到）
+  - `curl -s -X GET http://localhost:8080/api/auth/brands | jq .`
+  - `curl -s -X POST http://localhost:8080/api/auth/login -H "Content-Type: application/json" -d '{"brandNo":"STD","username":"admin","password":"666666"}' | jq .`
+
+- [ ] **Step 5: Commit**
+  - `git commit -m "feat(usr): SecurityConfig + JwtFilter + AuthController REQ-USR-004"`
+
+---
+
+### Task 8: 前端项目骨架
+
+**Files:**
+- 创建: `frontend/package.json`
+- 创建: `frontend/vite.config.ts`
+- 创建: `frontend/tsconfig.json`
+- 创建: `frontend/index.html`
+- 创建: `frontend/src/main.tsx`
+- 创建: `frontend/src/App.tsx`
+- 创建: `frontend/src/styles/tokens.css`
+
+**package.json 关键依赖：**
+```json
+"dependencies": {
+  "react": "^18.3.0", "react-dom": "^18.3.0",
+  "antd": "^5.17.0", "@ant-design/icons": "^5.3.0",
+  "@reduxjs/toolkit": "^2.2.0", "react-redux": "^9.1.0",
+  "react-router-dom": "^6.23.0",
+  "axios": "^1.7.0", "dayjs": "^1.11.0"
+},
+"devDependencies": {
+  "vite": "^5.2.0", "@vitejs/plugin-react": "^4.3.0",
+  "typescript": "^5.4.0",
+  "@types/react": "^18.3.0", "@types/react-dom": "^18.3.0",
+  "vitest": "^1.6.0",
+  "@testing-library/react": "^15.0.0",
+  "@testing-library/jest-dom": "^6.4.0",
+  "@testing-library/user-event": "^14.5.0",
+  "jsdom": "^24.0.0"
+}
+```
+
+**vite.config.ts 关键配置：**
+```ts
+export default defineConfig({
+  plugins: [react()],
+  server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true } } },
+  test: { environment: 'jsdom', globals: true, setupFiles: './src/test/setup.ts' }
+})
+```
+
+**App.tsx 骨架：** `<BrowserRouter>` 包裹路由，`/login` → `<LoginPage />`，`/` → PrivateRoute（暂时重定向 /login，后续 REQ 补充），`*` → 404
+
+- [ ] **Step 1: 创建前端项目文件结构**
+  - `mkdir -p frontend/src/{styles,api,store/slices,pages/usr,test,hooks,components,utils}`
+  - 写 package.json（上述依赖）
+  - 写 vite.config.ts、tsconfig.json、index.html、src/main.tsx、src/App.tsx（骨架）
+  - 复制 `src/styles/tokens.css` 内容到 `frontend/src/styles/tokens.css`
+  - 写 `frontend/src/test/setup.ts`（`import "@testing-library/jest-dom"`）
+  - `cd frontend && npm install`
+
+- [ ] **Step 2: 验证骨架构建**
+  - `cd frontend && npm run build`（应成功，0 错误）
+
+- [ ] **Step 3: Commit**
+  - `git add frontend/`
+  - `git commit -m "chore(frontend): init Vite React project skeleton REQ-USR-004"`
+
+---
+
+### Task 9: 前端 Auth API 层 + Redux authSlice
+
+**Files:**
+- 创建: `frontend/src/api/request.ts`
+- 创建: `frontend/src/api/auth.ts`
+- 创建: `frontend/src/store/index.ts`
+- 创建: `frontend/src/store/slices/authSlice.ts`
+- 测试: `frontend/src/test/authSlice.test.ts`
+
+**API shape:**
+- `request.ts` — Axios 实例 `baseURL: '/api'`，`timeout: 10000`
+  - 请求拦截器：从 `store.getState().auth.accessToken` 读 token，注入 `Authorization: Bearer ${token}`
+  - 响应拦截器（成功）：`response.data.code !== 200` → 抛 `new Error(response.data.message)`
+  - 响应拦截器（HTTP 401）：调 `auth.refresh(store.getState().auth.refreshToken)` → 更新 store → 重试原请求；refresh 失败 → `store.dispatch(clearCredentials())` → `window.location.href = '/login'`
+- `auth.ts`:
+  - `login(params: { brandNo: string; username: string; password: string }) : Promise<LoginVO>` — POST /api/auth/login
+  - `refresh(refreshToken: string) : Promise<{ accessToken: string }>` — POST /api/auth/refresh
+  - `getBrands() : Promise<BrandVO[]>` — GET /api/auth/brands
+  - 类型定义（TypeScript interface）：`LoginVO`（含 accessToken, refreshToken, expiresIn, userInfo: UserInfoVO），`UserInfoVO`（userId, username, userType, language, brandId），`BrandVO`（sNo, sName）
+- `authSlice` — `createSlice({ name: 'auth', initialState: { accessToken: null, refreshToken: null, userInfo: null } })`
+  - `setCredentials(state, action: PayloadAction<{ accessToken: string; refreshToken: string; userInfo: UserInfoVO }>)` — 更新三字段
+  - `clearCredentials(state)` — 三字段重置 null
+- `store/index.ts` — `configureStore({ reducer: { auth: authReducer } })`；导出 `RootState`、`AppDispatch`
+
+- [ ] **Step 1: 写 2 个失败单元测试（authSlice.test.ts）**
+  - `setCredentials_updatesAllStateFields` — dispatch setCredentials({accessToken:"t1", refreshToken:"r1", userInfo:{userId:"u1",...}}) → state.auth.accessToken=="t1"
+  - `clearCredentials_resetsToNull` — dispatch clearCredentials → state.auth.accessToken==null
+
+- [ ] **Step 2: 实现 request.ts + auth.ts + authSlice + store/index.ts**
+
+- [ ] **Step 3: 子会话运行 `cd frontend && npm run test -- --run`，确认 authSlice 2 个测试 PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): auth API layer + Redux authSlice REQ-USR-004"`
+
+---
+
+### Task 10: 登录页 LoginPage.tsx
+
+**Files:**
+- 创建: `frontend/src/pages/usr/LoginPage.tsx`
+- 修改: `frontend/src/App.tsx`（添加 /login 路由，PrivateRoute 守卫读 authSlice）
+- 测试: `frontend/src/test/LoginPage.test.tsx`
+
+**UI 规范（来自 docs/06 § 五）：**
+- 版本 `Select`（label="公司/版本"，name="brandNo"）：组件 mount 时调 `getBrands()`，填充选项（value=sNo, label=sName）；defaultValue = sName=="标准版" 对应的 sNo；若无"标准版"则选第一项
+- 用户名 `Input`（label="用户名"，name="username"）：必填
+- 密码 `Input.Password`（label="密码"，name="password"）：必填
+- 提交按钮（text="登录"，`loading={loading}`）：防重复点击
+- 失败：`message.error(接口返回 message)`
+- 成功：`dispatch(setCredentials({accessToken, refreshToken, userInfo}))` → `navigate('/')`
+
+**LoginPage 内部数据流：**
+1. `useEffect(() => { getBrands().then(setBrandOptions) }, [])` — 挂载时获取 brand 列表
+2. `onFinish(values)` → `setLoading(true)` → `await login(values)` → `dispatch(setCredentials(...))` → `navigate('/')` → `finally setLoading(false)`
+
+- [ ] **Step 1: 写 2 个失败测试（LoginPage.test.tsx）**
+  - `renders_brandSelect_username_and_password_fields`
+    - render LoginPage（with Redux Provider + MemoryRouter + mock getBrands → [{sNo:"STD",sName:"标准版"}]）
+    - 断言：combobox（brand Select）存在，`getByPlaceholderText` 或 label "用户名" Input 存在，"密码" Input 存在，"登录" Button 存在
+  - `submit_withValidCredentials_dispatchesSetCredentials`
+    - mock `auth.login` 返回 `{accessToken:"at", refreshToken:"rt", expiresIn:86400, userInfo:{userId:"u1",username:"admin",userType:"超级管理员",language:"中文",brandId:"b1"}}`
+    - 填写 username + password，点击登录 → `store.getState().auth.accessToken == "at"`
+
+- [ ] **Step 2: 实现 LoginPage.tsx + 更新 App.tsx（/login 路由）**
+
+- [ ] **Step 3: 子会话运行 `npm run test -- --run`，确认所有前端测试（包括 authSlice + LoginPage）PASS**
+
+- [ ] **Step 4: Commit**
+  - `git commit -m "feat(usr): LoginPage brand selector + login form REQ-USR-004"`
+
+---
+
+## 提交计划
+
+| 提交消息 | 覆盖 Task |
+|---|---|
+| `chore(backend): init Spring Boot 3 project skeleton REQ-USR-004` | Task 1 |
+| `feat(usr): common Result/BizException/AuthErrorCode/GlobalExceptionHandler REQ-USR-004` | Task 2 |
+| `feat(usr): JwtUtil generate + parse access/refresh token REQ-USR-004` | Task 3 |
+| `feat(usr): BrandEntity/UsrUserEntity + Mapper REQ-USR-004` | Task 4 |
+| `feat(usr): AuthService.login multi-tenant + lockout logic REQ-USR-004` | Task 5 |
+| `feat(usr): AuthService.refresh + getBrands REQ-USR-004` | Task 6 |
+| `feat(usr): SecurityConfig + JwtFilter + AuthController REQ-USR-004` | Task 7 |
+| `chore(frontend): init Vite React project skeleton REQ-USR-004` | Task 8 |
+| `feat(usr): auth API layer + Redux authSlice REQ-USR-004` | Task 9 |
+| `feat(usr): LoginPage brand selector + login form REQ-USR-004` | Task 10 |
+---
+req_id: REQ-USR-004
+date: 2026-05-08
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-004 — round 1
+
+## 结论
+request-changes  （approve / request-changes）
+
+## Must-fix
+- [high] sql/migrations/V1__initial_schema.sql:108 — uk_usr_user_username 是全库唯一索引，规格要求多租户隔离，同一 sUsername 应允许出现在不同 brand（sBrandsId）中，唯一性应为 (sUsername, sBrandsId) 复合唯一，否则第二个 brand 的同名用户插入时会触发唯一约束违反（建议：新增 V2__fix_username_unique_per_tenant.sql，DROP 旧索引并 CREATE UNIQUE INDEX uk_usr_user_username_tenant ON usr_user (sUsername, sBrandsId)；同步更新 docs/03）
+- [medium] backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java:71 — UpdateWrapper 使用裸字符串列名（"sId", "iLoginFailCount", "tLockUntil", "tLastLoginDate"），与项目其余代码 LambdaQueryWrapper 不一致，列重命名时不会编译报错（建议：改为 LambdaUpdateWrapper<UsrUserEntity> 使用方法引用，同时在 AuthServiceTest @BeforeAll 初始化 TableInfo 以支持单元测试）
+- [medium] backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java:118 — refresh() 只检查 user==null 和 bIsDisabled=1，未检查 tLockUntil；锁定账号可通过持有的 refresh token 持续获取新 access token 长达 7 天，绕过防暴力破解机制（建议：追加 tLockUntil 检查，并新增 refresh_lockedUser_throws40103 测试）
+
+## Nice-to-have
+- docs/05-API接口契约.md:49 — API 契约为 POST /api/auth/login 列出了 40400（公司编号不存在），但规格和实现均正确使用 40100（防枚举），契约文档应删除 40400 行
+- backend/src/main/java/com/example/erp/common/util/JwtUtil.java:72 — doParse() 对 access token 过期也抛 40103（REFRESH_TOKEN_INVALID），语义污染；建议区分 access/refresh 解析路径或使用更通用的 token 失效码
+- backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java:57 — Integer.valueOf(1).equals(user.getBIsDisabled()) 写法冗长，可简化为 user.getBIsDisabled() != null && user.getBIsDisabled() == 1
+- backend/src/main/java/com/example/erp/module/usr/service/impl/AuthServiceImpl.java:110 — refresh() 和 getBrands() 为只读操作，应加 @Transactional(readOnly = true)
+- backend/src/test/java/com/example/erp/module/usr/AuthServiceTest.java:93 — login_accountLocked_throws40102WithRemainingMinutes 只断言 message.contains("分钟")，未验证具体分钟数
+
+## 反例 / 测试覆盖缺口
+1. 缺少「锁定期内再次尝试登录仍返回 40102」测试（验收标准第 3 条后半段）
+2. 缺少 refresh_lockedUser_throws40103 测试（见 must_fix 第 3 条）
+3. 缺少多租户隔离集成测试（验收标准第 7 条）：同一用户名、不同 brandId 各自独立
+4. 前端 LoginPage.test.tsx 缺少登录失败时 message.error 展示的断言
+5. request.ts 的 401 自动刷新 pendingQueue 并发重试场景无测试覆盖
+6. JwtUtilTest 缺少 generateRefreshToken claims 验证正向测试
+---
+req_id: REQ-USR-004
+date: 2026-05-08
+module: module_usr
+---
+
+# Spec: REQ-USR-004 — 用户登录
+
+## 目标
+
+用户在登录页选择所属公司（brand）、输入用户名和密码，完成身份认证后获取 JWT Access Token 及 Refresh Token，用于后续所有接口鉴权。多租户隔离：每次登录的用户查询限定在所选 brand 的 sBrandsId 范围内。
+
+## 输入 / 触发
+
+**POST /api/auth/login**（公开接口，无需 Bearer Token）
+
+```json
+{
+  "brandNo": "string",   // brand.sNo，前端版本下拉选中项
+  "username": "string",  // usr_user.sUsername
+  "password": "string"   // 明文密码（HTTPS 传输），后端用 BCrypt 校验
+}
+```
+
+**辅助：版本下拉数据**  
+前端需预先调用 `GET /api/auth/brands` 获取 brand 列表（sNo / sName），填充版本下拉框。默认选中 `sName = "标准版"` 对应的项（若无则选第一项）。此接口亦无需鉴权。
+
+**POST /api/auth/refresh**（无需 Bearer Token，需 Refresh Token）
+
+```json
+{ "refreshToken": "string" }
+```
+
+## 输出 / 结果
+
+**登录成功（HTTP 200）**
+
+```json
+{
+  "code": 200,
+  "message": "登录成功",
+  "data": {
+    "accessToken": "<jwt>",
+    "refreshToken": "<jwt>",
+    "expiresIn": 86400,
+    "userInfo": {
+      "userId": "string",     // usr_user.sId
+      "username": "string",   // usr_user.sUsername
+      "userType": "string",   // 普通用户 | 超级管理员
+      "language": "string",   // 中文 | 英文 | 繁体
+      "brandId": "string"     // brand.sId，写入 token claims 用于后续多租户隔离
+    }
+  }
+}
+```
+
+**失败（业务错误，HTTP 200 + code ≠ 0）**
+
+| code | message | 场景 |
+|---|---|---|
+| 40100 | 用户名或密码错误 | 密码错误 / 用户不存在 / brand 不存在（统一文案，防枚举） |
+| 40101 | 账号已被禁用，请联系管理员 | bIsDisabled = 1 |
+| 40102 | 账号已被锁定，请 {N} 分钟后重试 | tLockUntil > NOW() |
+| 40103 | Refresh Token 已失效，请重新登录 | refresh 接口 token 过期或篡改 |
+
+## 业务规则
+
+1. **多租户查询**：先 `SELECT * FROM brand WHERE sNo = ?` 得 `brandId = brand.sId`；再 `SELECT * FROM usr_user WHERE sUsername = ? AND sBrandsId = ?`（brandId）。brand 不存在或用户不存在统一返回 40100（防枚举）。
+
+2. **密码校验**：`BCryptPasswordEncoder.matches(plainPassword, usr_user.sPasswordHash)`。
+
+3. **禁用检查**：`bIsDisabled = 1` → 返回 40101，不更新失败计数。
+
+4. **锁定检查**：`tLockUntil IS NOT NULL AND tLockUntil > NOW()` → 返回 40102，剩余分钟数 = `CEIL((tLockUntil - NOW()) / 60)`。
+
+5. **失败计数**：密码错误时 `iLoginFailCount += 1`；达到 5 次时设 `tLockUntil = NOW() + 30 分钟`，同时返回 40102。
+
+6. **登录成功**：
+   - 重置 `iLoginFailCount = 0`，`tLockUntil = NULL`
+   - 更新 `tLastLoginDate = NOW()`
+   - 签发 Access Token（24h）+ Refresh Token（7d），均为 JWT，签名密钥来自 `JWT_SECRET`（从 `.env.local` 注入，`application.yml` 中 `${JWT_SECRET}`）
+
+7. **JWT Claims**：
+   - Access Token：`sub = usr_user.sId`，`username`，`userType`，`brandId = brand.sId`，`exp = now + 24h`
+   - Refresh Token：`sub = usr_user.sId`，`brandId`，`type = refresh`，`exp = now + 7d`
+
+8. **Token 刷新**（POST /api/auth/refresh）：校验 Refresh Token 签名与 `type=refresh`；从 claims 读 `sub`（userId）和 `brandId` 重新查库确认用户仍有效；签发新 Access Token（24h）；Refresh Token **不续期**（滑动窗口留给后续迭代）。
+
+9. **版本下拉**（GET /api/auth/brands）：`SELECT sNo, sName FROM brand ORDER BY sName`；无需分页（品牌数量通常极少）。
+
+## 边界与约束
+
+- 所有接口均走 HTTPS（Nginx 层保障，后端不强制）
+- 登录日志（IP + 时间戳）通过 Spring Security 的 `AuthenticationSuccessHandler` / `AuthenticationFailureHandler` 写 Logback，不写业务表
+- Refresh Token 无服务端存储（无状态 JWT）；强制退出由后续迭代（引入 token 黑名单）实现；本期用 7 天过期控制
+- 密码明文绝不落库，`sPasswordHash` 仅存 BCrypt 60 字符哈希
+- Access Token 不含密码 hash，不含任何敏感字段
+- 防暴力破解：5 次失败锁 30 分钟（数据库层，不依赖内存，重启后有效）
+- `GET /api/auth/brands` 结果可加短缓存（30s），减少登录页加载压力
+
+## 依赖的 schema 表 / 字段
+
+**usr_user**（主要读写字段）
+
+| 字段 | 操作 | 说明 |
+|---|---|---|
+| `sUsername` | READ | 登录名匹配 |
+| `sBrandsId` | READ | 多租户范围限定 |
+| `sPasswordHash` | READ | BCrypt 校验 |
+| `bIsDisabled` | READ | 禁用检查 |
+| `tLockUntil` | READ / WRITE | 锁定截止时间 |
+| `iLoginFailCount` | READ / WRITE | 连续失败次数 |
+| `tLastLoginDate` | WRITE | 成功后更新 |
+| `sId` | READ | 写入 JWT sub |
+| `sUserType` | READ | 写入 JWT claims |
+| `sLanguage` | READ | 返回 userInfo |
+
+**brand**
+
+| 字段 | 操作 | 说明 |
+|---|---|---|
+| `sNo` | READ | 版本下拉匹配键 |
+| `sId` | READ | 写入 JWT brandId claim |
+| `sName` | READ | 版本下拉显示名 |
+
+## 依赖的接口
+
+- 自身即认证入口，无上游接口依赖
+- 对外暴露：`POST /api/auth/login`、`POST /api/auth/refresh`、`GET /api/auth/brands`（均无鉴权）
+
+## 验收标准
+
+1. 正确 brandNo + username + password → HTTP 200，返回有效 accessToken，`POST /api/usr/users` 携带该 token 鉴权通过
+2. 错误密码 → code=40100，且不暴露是用户名还是密码错了
+3. 连续 5 次错误密码 → 第 5 次返回 code=40102（含剩余分钟数），后续在锁定期内再请求仍返回 40102
+4. 锁定 30 分钟后自动解锁，正确凭据可再次登录
+5. `bIsDisabled = 1` 的账号登录 → code=40101
+6. brand.sNo 不存在 → code=40100（与密码错误同一文案）
+7. 用同一账号、不同 brandId 登录 → 互不干扰（多租户隔离）
+8. 有效 refreshToken → POST /api/auth/refresh 返回新 accessToken
+9. 过期 / 伪造 refreshToken → code=40103
+10. GET /api/auth/brands 返回所有 brand 列表（sNo + sName）
@@ -8,6 +8,14 @@ set -euo pipefail
 PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$PROJECT_ROOT"
+# Use Java 21 for Lombok compatibility (system default may be Java 25+)
+if [ -d "/opt/homebrew/Cellar/openjdk@21" ]; then
+  JAVA21="$(ls -d /opt/homebrew/Cellar/openjdk@21/*/bin/java 2>/dev/null | tail -1)"
+  if [ -n "$JAVA21" ]; then
+    export JAVA_HOME="$(dirname "$(dirname "$JAVA21")")"
+  fi
+fi
+
 # Stack detection (runtime, mode-agnostic)
 HAS_BACKEND=0; [ -d backend ] && HAS_BACKEND=1
 HAS_FRONTEND=0; [ -d frontend ] && HAS_FRONTEND=1
+-- Flyway migration V2 — fix usr_user username uniqueness to per-tenant scope
+-- Generated: 2026-05-08
+-- Reason: uk_usr_user_username was globally unique; same username must be allowed across different brands (sBrandsId)
+-- New unique constraint: (sUsername, sBrandsId) composite
+
+ALTER TABLE usr_user DROP INDEX uk_usr_user_username;
+CREATE UNIQUE INDEX uk_usr_user_username_tenant ON usr_user (sUsername, sBrandsId);