Merge branch 'module-module_usr'

zichun
2 parents 2bc3429d d170f319
Showing 103 changed files with 8198 additions and 632 deletions
CLAUDE.md
backend/pom.xml
backend/src/main/java/com/xly/erp/Application.java
backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java
backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java
backend/src/main/java/com/xly/erp/common/exception/BizException.java
backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java
backend/src/main/java/com/xly/erp/common/response/ErrorCode.java
backend/src/main/java/com/xly/erp/common/response/PageResult.java
backend/src/main/java/com/xly/erp/common/response/Result.java
backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java
backend/src/main/java/com/xly/erp/common/security/JwtUtil.java
backend/src/main/java/com/xly/erp/common/security/LoginContext.java
backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java
backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java
backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java
backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java
backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java
backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java
backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java
@@ -132,7 +132,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding-
  
 ### 你禁止做的 🚫
  
-1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约
+1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试 / A4 `db-init` 首次 apply V1 验证除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约。**A4 例外**：`db-init` 在 A 阶段 setup-test-db 后会一次性手工 `mysql < V1__initial_schema.sql` 把 V1 灌入测试库，并校验 `SHOW TABLES` 行数 = docs/03 表数量，用于 DDL 自检；B 阶段（Spring Boot 启动后）Flyway 会重建 schema 并 apply 全部 migration（包括 V1），手工 apply 不会污染 Flyway 历史。
 2. **手动 Edit `docs/08 § 二/§ 三` 的 `MR:` / `整体 MR:` 字段**，必须要由 `mr-create` 自动回写
  
 ### Schema 演化规约（Flyway migration）
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-parent</artifactId>
+        <version>3.3.4</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.xly.erp</groupId>
+    <artifactId>xly-erp-backend</artifactId>
+    <version>0.0.1-SNAPSHOT</version>
+    <packaging>jar</packaging>
+    <name>xly-erp-backend</name>
+    <description>小羚羊 ERP 后端</description>
+
+    <properties>
+        <java.version>17</java.version>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <mybatis-plus.version>3.5.7</mybatis-plus.version>
+        <jjwt.version>0.12.5</jjwt.version>
+        <lombok.version>1.18.40</lombok.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-validation</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-crypto</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>com.baomidou</groupId>
+            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
+            <version>${mybatis-plus.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-mysql</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-api</artifactId>
+            <version>${jjwt.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-impl</artifactId>
+            <version>${jjwt.version}</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-jackson</artifactId>
+            <version>${jjwt.version}</version>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>${lombok.version}</version>
+            <optional>true</optional>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                            <version>${lombok.version}</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.springframework.boot</groupId>
+                <artifactId>spring-boot-maven-plugin</artifactId>
+                <configuration>
+                    <excludes>
+                        <exclude>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                        </exclude>
+                    </excludes>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <environmentVariables>
+                        <DB_HOST>${env.DB_HOST}</DB_HOST>
+                        <DB_PORT>${env.DB_PORT}</DB_PORT>
+                        <DB_USER>${env.DB_USER}</DB_USER>
+                        <DB_PASSWORD>${env.DB_PASSWORD}</DB_PASSWORD>
+                        <DB_SCHEMA>${env.DB_SCHEMA}</DB_SCHEMA>
+                        <JWT_SECRET>${env.JWT_SECRET}</JWT_SECRET>
+                    </environmentVariables>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
+package com.xly.erp;
+
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+@MapperScan("com.xly.erp.module.*.mapper")
+public class Application {
+    public static void main(String[] args) {
+        SpringApplication.run(Application.class, args);
+    }
+}
+package com.xly.erp.common.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+
+/**
+ * BCrypt 密码编码器 Bean。strength=10（Spring Security 默认）。
+ * docs/03 sys_user.sPasswordHash + docs/04 § 1.6。
+ */
+@Configuration
+public class PasswordEncoderConfig {
+
+    @Bean
+    public BCryptPasswordEncoder passwordEncoder() {
+        return new BCryptPasswordEncoder(10);
+    }
+}
+package com.xly.erp.common.config;
+
+import com.xly.erp.common.security.JwtHandlerInterceptor;
+import lombok.RequiredArgsConstructor;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+@RequiredArgsConstructor
+public class WebMvcConfig implements WebMvcConfigurer {
+
+    private final JwtHandlerInterceptor jwtInterceptor;
+
+    @Override
+    public void addInterceptors(InterceptorRegistry registry) {
+        registry.addInterceptor(jwtInterceptor)
+                .addPathPatterns("/api/v1/**")
+                .excludePathPatterns("/api/v1/auth/login");
+    }
+}
+package com.xly.erp.common.exception;
+
+import lombok.Getter;
+
+/**
+ * 业务异常 — 由 service 层抛出，由 GlobalExceptionHandler 统一转 Result.fail。
+ * docs/04 § 1.4。
+ */
+@Getter
+public class BizException extends RuntimeException {
+    private final int code;
+    /** 可选附带的响应数据（例如 42301 锁定返 lockUntil）。null 表示无 data 字段。 */
+    private final Object data;
+
+    public BizException(int code, String message) {
+        this(code, message, (Object) null);
+    }
+
+    public BizException(int code, String message, Object data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+    }
+
+    public BizException(int code, String message, Throwable cause) {
+        super(message, cause);
+        this.code = code;
+        this.data = null;
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.response.Result;
+import jakarta.validation.ConstraintViolationException;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.ResponseEntity;
+import org.springframework.http.converter.HttpMessageNotReadableException;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+/**
+ * 全局异常处理器。
+ * 把 BizException / 参数校验异常 / 兜底异常转 Result.fail 统一响应。
+ * docs/04 § 1.4。
+ */
+@RestControllerAdvice
+@Slf4j
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(BizException.class)
+    public ResponseEntity<Result<Object>> handleBiz(BizException e) {
+        log.warn("[BizException] code={} message={} hasData={}", e.getCode(), e.getMessage(), e.getData() != null);
+        Result<Object> body = e.getData() != null
+                ? Result.fail(e.getCode(), e.getMessage(), e.getData())
+                : Result.fail(e.getCode(), e.getMessage());
+        return ResponseEntity
+                .status(ErrorCode.toHttpStatus(e.getCode()))
+                .body(body);
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<Result<Void>> handleValidation(MethodArgumentNotValidException e) {
+        String msg = e.getBindingResult().getFieldErrors().stream()
+                .findFirst()
+                .map(fe -> fe.getField() + " " + fe.getDefaultMessage())
+                .orElse("参数校验失败");
+        return ResponseEntity
+                .status(400)
+                .body(Result.fail(ErrorCode.BAD_REQUEST, msg));
+    }
+
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<Result<Void>> handleConstraint(ConstraintViolationException e) {
+        return ResponseEntity
+                .status(400)
+                .body(Result.fail(ErrorCode.BAD_REQUEST, e.getMessage()));
+    }
+
+    @ExceptionHandler(HttpMessageNotReadableException.class)
+    public ResponseEntity<Result<Void>> handleNotReadable(HttpMessageNotReadableException e) {
+        log.warn("[HttpMessageNotReadable] {}", e.getMessage());
+        return ResponseEntity
+                .status(400)
+                .body(Result.fail(ErrorCode.BAD_REQUEST, "请求体格式不合法或包含未知字段"));
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<Result<Void>> handleFallback(Exception e) {
+        log.error("[Unhandled] {}", e.getMessage(), e);
+        return ResponseEntity
+                .status(500)
+                .body(Result.fail(ErrorCode.INTERNAL_ERROR, "服务器内部错误"));
+    }
+}
+package com.xly.erp.common.response;
+
+/**
+ * 全局错误码定义。
+ * 段位约定见 docs/04 § 1.3。
+ */
+public final class ErrorCode {
+
+    private ErrorCode() {}
+
+    public static final int OK                  = 200;
+
+    public static final int BAD_REQUEST         = 40001;
+    public static final int INVALID_ENUM_PARAM  = 40003;
+    public static final int COMPANY_NOT_FOUND   = 40004;
+
+    public static final int BAD_CREDENTIALS     = 40101;
+    public static final int ACCOUNT_DELETED     = 40103;
+
+    public static final int FORBIDDEN           = 40301;
+    public static final int USER_FORBIDDEN_SELF_DEACTIVATE = 40302;
+
+    public static final int USER_NOT_FOUND      = 40401;
+
+    public static final int ACCOUNT_LOCKED      = 42301;
+
+    public static final int CONFLICT_USERNAME   = 40901;
+    public static final int CONFLICT_USERCODE   = 40902;
+
+    public static final int INTERNAL_ERROR      = 50000;
+
+    /**
+     * 业务 code → HTTP 状态码映射。
+     */
+    public static int toHttpStatus(int code) {
+        if (code == OK) return 200;
+        if (code == ACCOUNT_LOCKED) return 423;
+        int hundreds = code / 100;
+        if (hundreds == 400) return 400;
+        if (hundreds == 401) return 401;
+        if (hundreds == 403) return 403;
+        if (hundreds == 404) return 404;
+        if (hundreds == 409) return 409;
+        if (hundreds == 423) return 423;
+        if (hundreds == 500) return 500;
+        return 500;
+    }
+}
+package com.xly.erp.common.response;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 通用分页响应包装。docs/04 § 3.2。
+ */
+@Data
+@Builder
+public class PageResult<T> {
+    private List<T> records;
+    private long total;
+    private int page;
+    private int size;
+}
+package com.xly.erp.common.response;
+
+import lombok.Getter;
+
+/**
+ * 统一响应包装。
+ * docs/04 § 1.3。
+ */
+@Getter
+public class Result<T> {
+    private final int code;
+    private final String message;
+    private final T data;
+    private final long timestamp;
+
+    private Result(int code, String message, T data) {
+        this.code = code;
+        this.message = message;
+        this.data = data;
+        this.timestamp = System.currentTimeMillis();
+    }
+
+    public static <T> Result<T> ok(T data) {
+        return new Result<>(ErrorCode.OK, "操作成功", data);
+    }
+
+    public static Result<Void> ok() {
+        return new Result<>(ErrorCode.OK, "操作成功", null);
+    }
+
+    public static <T> Result<T> fail(int code, String message) {
+        return new Result<>(code, message, null);
+    }
+
+    @SuppressWarnings("unchecked")
+    public static <T> Result<T> fail(int code, String message, T data) {
+        return new Result<>(code, message, data);
+    }
+}
+package com.xly.erp.common.security;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+import org.springframework.web.method.HandlerMethod;
+import org.springframework.web.servlet.HandlerInterceptor;
+
+import java.time.LocalDateTime;
+import java.util.Map;
+
+/**
+ * REQ-USR-002 鉴权与角色守卫拦截器。
+ * - 解析 Authorization Bearer → 校验 user 状态 → set LoginContext
+ * - 若 handler 标注 @RequireSuperAdmin，强制 userType == SUPER_ADMIN
+ * - afterCompletion 清理 ThreadLocal
+ */
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class JwtHandlerInterceptor implements HandlerInterceptor {
+
+    private static final String BEARER_PREFIX = "Bearer ";
+
+    private final JwtUtil jwtUtil;
+    private final SysUserMapper userMapper;
+
+    @Override
+    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
+        String authHeader = request.getHeader("Authorization");
+        if (authHeader == null || !authHeader.startsWith(BEARER_PREFIX)) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "未携带 token");
+        }
+        String token = authHeader.substring(BEARER_PREFIX.length());
+
+        Map<String, Object> claims = jwtUtil.parse(token);
+        String username = (String) claims.get("username");
+        if (username == null || username.isBlank()) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 缺 username claim");
+        }
+
+        SysUser user = userMapper.selectByUsername(username);
+        if (user == null) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户不存在");
+        }
+        if (Integer.valueOf(1).equals(user.getIIsDeleted())) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户已作废");
+        }
+        if (user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now())) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户已锁定");
+        }
+
+        String companyCode = (String) claims.get("companyCode");
+        LoginContext.set(new LoginContext.LoginUser(
+                user.getIIncrement(),
+                user.getSUsername(),
+                user.getSUserType(),
+                companyCode));
+
+        if (handler instanceof HandlerMethod hm) {
+            if (hm.getMethodAnnotation(RequireSuperAdmin.class) != null
+                    && !"SUPER_ADMIN".equals(user.getSUserType())) {
+                throw new BizException(ErrorCode.FORBIDDEN, "权限不足，仅超级管理员可调用");
+            }
+        }
+        return true;
+    }
+
+    @Override
+    public void afterCompletion(HttpServletRequest request, HttpServletResponse response,
+                                Object handler, Exception ex) {
+        LoginContext.clear();
+    }
+}
+package com.xly.erp.common.security;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.JwtException;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.security.Keys;
+import jakarta.annotation.PostConstruct;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import javax.crypto.SecretKey;
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * JWT 签发与验证工具。HS256，密钥来自 ${JWT_SECRET}。
+ * docs/04 § 1.6。
+ */
+@Component
+public class JwtUtil {
+
+    @Value("${jwt.secret}")
+    private String secret;
+
+    private SecretKey key;
+
+    @PostConstruct
+    void init() {
+        byte[] bytes = secret.getBytes(StandardCharsets.UTF_8);
+        if (bytes.length < 32) {
+            throw new IllegalStateException(
+                    "JWT_SECRET 长度不足 32 字节（HS256 要求），实际 " + bytes.length
+                            + " 字节。请在 .env.local 配置至少 256 位的随机字符串。");
+        }
+        this.key = Keys.hmacShaKeyFor(bytes);
+    }
+
+    public String issue(Map<String, Object> claims, long ttlSec) {
+        long now = System.currentTimeMillis();
+        Map<String, Object> all = new HashMap<>(claims);
+        String sub = String.valueOf(all.remove("sub"));
+        String jti = UUID.randomUUID().toString();
+        return Jwts.builder()
+                .subject(sub)
+                .claims(all)
+                .id(jti)
+                .issuedAt(new Date(now))
+                .expiration(new Date(now + ttlSec * 1000L))
+                .signWith(key)
+                .compact();
+    }
+
+    public Map<String, Object> parse(String token) {
+        try {
+            Claims claims = Jwts.parser()
+                    .verifyWith(key)
+                    .build()
+                    .parseSignedClaims(token)
+                    .getPayload();
+            Map<String, Object> out = new HashMap<>(claims);
+            out.put("sub", claims.getSubject());
+            out.put("jti", claims.getId());
+            out.put("iat", claims.getIssuedAt() != null ? claims.getIssuedAt().getTime() / 1000 : null);
+            out.put("exp", claims.getExpiration() != null ? claims.getExpiration().getTime() / 1000 : null);
+            return out;
+        } catch (JwtException e) {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 无效或已过期");
+        }
+    }
+}
+package com.xly.erp.common.security;
+
+/**
+ * 请求级登录上下文 — JwtHandlerInterceptor 在 preHandle 时 set，afterCompletion 时 clear。
+ * 用普通 ThreadLocal（不用 InheritableThreadLocal）避免子线程意外继承。
+ */
+public final class LoginContext {
+
+    private static final ThreadLocal<LoginUser> HOLDER = new ThreadLocal<>();
+
+    private LoginContext() {}
+
+    public static void set(LoginUser user) {
+        HOLDER.set(user);
+    }
+
+    public static LoginUser current() {
+        return HOLDER.get();
+    }
+
+    public static void clear() {
+        HOLDER.remove();
+    }
+
+    /** 当前登录用户上下文。userType 取值 NORMAL / SUPER_ADMIN。 */
+    public record LoginUser(Integer userId, String username, String userType, String companyCode) {}
+}
+package com.xly.erp.common.security;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * 标注在 controller 方法上，要求当前登录用户 userType == SUPER_ADMIN。
+ * 由 JwtHandlerInterceptor 在 preHandle 时校验。
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface RequireSuperAdmin {
+}
+package com.xly.erp.module.usr.controller;
+
+import com.xly.erp.common.response.Result;
+import com.xly.erp.module.usr.dto.LoginReq;
+import com.xly.erp.module.usr.service.LoginService;
+import com.xly.erp.module.usr.vo.LoginVo;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 认证入口。REQ-USR-001：POST /api/v1/auth/login。
+ */
+@RestController
+@RequestMapping("/api/v1/auth")
+@RequiredArgsConstructor
+public class AuthController {
+
+    private final LoginService loginService;
+
+    @PostMapping("/login")
+    public Result<LoginVo> login(@RequestBody @Valid LoginReq req) {
+        LoginVo vo = loginService.login(req.getUsername(), req.getPassword(), req.getCompanyCode());
+        return Result.ok(vo);
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.common.response.Result;
+import com.xly.erp.common.security.LoginContext;
+import com.xly.erp.common.security.RequireSuperAdmin;
+import com.xly.erp.module.usr.dto.CreateUserReq;
+import com.xly.erp.module.usr.dto.UpdateUserReq;
+import com.xly.erp.module.usr.dto.UserQueryReq;
+import com.xly.erp.module.usr.service.UserCreateService;
+import com.xly.erp.module.usr.service.UserDetailService;
+import com.xly.erp.module.usr.service.UserListService;
+import com.xly.erp.module.usr.service.UserUpdateService;
+import com.xly.erp.module.usr.vo.CreateUserVo;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/v1/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserCreateService userCreateService;
+    private final UserDetailService userDetailService;
+    private final UserUpdateService userUpdateService;
+    private final UserListService userListService;
+
+    @PostMapping
+    @RequireSuperAdmin
+    public ResponseEntity<Result<CreateUserVo>> create(@RequestBody @Valid CreateUserReq req) {
+        String operator = LoginContext.current().username();
+        CreateUserVo vo = userCreateService.create(req, operator);
+        return ResponseEntity.status(HttpStatus.CREATED).body(Result.ok(vo));
+    }
+
+    @GetMapping
+    @RequireSuperAdmin
+    public Result<PageResult<UserListItemVo>> list(@Valid UserQueryReq req) {
+        return Result.ok(userListService.list(req));
+    }
+
+    @GetMapping("/{userId}")
+    @RequireSuperAdmin
+    public Result<UserDetailVo> getById(@PathVariable Integer userId) {
+        return Result.ok(userDetailService.getById(userId));
+    }
+
+    @PutMapping("/{userId}")
+    @RequireSuperAdmin
+    public Result<UserDetailVo> update(@PathVariable Integer userId,
+                                       @RequestBody @Valid UpdateUserReq req) {
+        LoginContext.LoginUser cur = LoginContext.current();
+        UserDetailVo vo = userUpdateService.update(userId, req, cur.userId(), cur.username());
+        return Result.ok(vo);
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+public class CreateUserReq {
+
+    @NotBlank
+    @Pattern(regexp = "^[A-Za-z0-9_]{3,20}$",
+            message = "用户名必须为 3-20 位字母数字下划线")
+    private String username;
+
+    @NotBlank
+    @Size(max = 50)
+    private String userCode;
+
+    @NotBlank
+    @Pattern(regexp = "NORMAL|SUPER_ADMIN",
+            message = "userType 必须为 NORMAL 或 SUPER_ADMIN")
+    private String userType;
+
+    @NotBlank
+    @Pattern(regexp = "zh-CN|en-US|zh-TW",
+            message = "language 必须为 zh-CN / en-US / zh-TW")
+    private String language;
+
+    @NotNull
+    private Boolean canEditDocument;
+
+    /** 可选；非空则必须命中 sys_employee.iIncrement 且 iIsDeleted=0 */
+    private Integer employeeId;
+
+    /** 可选；空数组 / null 都允许；非空时每个 ID 必须命中 sys_permission_category */
+    private List<Integer> permissionCategoryIds;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+@Data
+public class LoginReq {
+
+    @NotBlank
+    @Size(max = 50)
+    private String username;
+
+    @NotBlank
+    @Size(max = 128)
+    private String password;
+
+    @NotBlank
+    @Size(max = 50)
+    private String companyCode;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * PATCH 语义：所有字段都可选；缺省 / 显式 null 视为不变。
+ * 特例：employeeId == 0 视为解除关联（DB 写 NULL）。
+ */
+@Data
+public class UpdateUserReq {
+
+    @Size(max = 50)
+    @Pattern(regexp = "^\\S+$", message = "userCode 不可为空白")
+    private String userCode;
+
+    @Pattern(regexp = "NORMAL|SUPER_ADMIN",
+            message = "userType 必须为 NORMAL 或 SUPER_ADMIN")
+    private String userType;
+
+    @Pattern(regexp = "zh-CN|en-US|zh-TW",
+            message = "language 必须为 zh-CN / en-US / zh-TW")
+    private String language;
+
+    private Boolean canEditDocument;
+
+    @Min(value = 0, message = "employeeId 必须 >= 0；0 表示解除关联")
+    private Integer employeeId;
+
+    private Boolean isDeleted;
+
+    private List<Integer> permissionCategoryIds;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import lombok.Data;
+
+/**
+ * 用户列表查询请求。所有字段可选；枚举值白名单由 service 层校验。
+ * REQ-USR-004。
+ */
+@Data
+public class UserQueryReq {
+
+    @Min(value = 1, message = "page 必须 >= 1")
+    private Integer page;
+
+    @Min(value = 1, message = "size 必须 >= 1")
+    @Max(value = 100, message = "size 不能超过 100")
+    private Integer size;
+
+    private String sortField;
+    private String sortOrder;
+    private String queryField;
+    private String matchMode;
+    private String queryValue;
+    private String userType;
+    private Boolean isDeleted;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 公司表实体（只需登录用到的字段）。docs/03 § sys_company。
+ */
+@Data
+@TableName("sys_company")
+public class SysCompany {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    private String sId;
+    private String sBrandsId;
+    private String sSubsidiaryId;
+    private LocalDateTime tCreateDate;
+
+    private String sCompanyName;
+    private String sCompanyCode;
+    private Integer iSortOrder;
+    private Integer iIsDeleted;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 职员表实体（只读 join，含登录返回 employeeName 所需的最小字段）。
+ * docs/03 § sys_employee。
+ */
+@Data
+@TableName("sys_employee")
+public class SysEmployee {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    private String sId;
+    private String sBrandsId;
+    private String sSubsidiaryId;
+    private LocalDateTime tCreateDate;
+
+    private String sEmployeeName;
+    private String sEmployeeCode;
+    private Integer iDepartmentId;
+    private String sPhone;
+    private String sEmail;
+    private Integer iIsDeleted;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@TableName("sys_permission_category")
+public class SysPermissionCategory {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    private String sId;
+    private String sBrandsId;
+    private String sSubsidiaryId;
+    private LocalDateTime tCreateDate;
+
+    private String sCategoryName;
+    private String sCategoryCode;
+    private String sCategoryDesc;
+    private Integer iSortOrder;
+    private Integer iIsDeleted;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 用户表实体。docs/03 § sys_user。
+ */
+@Data
+@TableName("sys_user")
+public class SysUser {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    private String sId;
+    private String sBrandsId;
+    private String sSubsidiaryId;
+    private LocalDateTime tCreateDate;
+
+    private String sUsername;
+    private String sUserCode;
+    private String sPasswordHash;
+
+    private Integer iEmployeeId;
+    private String sUserType;
+    private String sLanguage;
+    private Integer iCanEditDocument;
+    private Integer iIsDeleted;
+    private Integer iFailedLoginCount;
+    private LocalDateTime tLockUntil;
+    private LocalDateTime tLastLoginDate;
+    private String sCreatedBy;
+    private String sUpdatedBy;
+    private LocalDateTime tUpdatedDate;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@TableName("sys_user_permission_category")
+public class SysUserPermissionCategory {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    private String sId;
+    private String sBrandsId;
+    private String sSubsidiaryId;
+    private LocalDateTime tCreateDate;
+
+    private Integer iUserId;
+    private Integer iPermissionCategoryId;
+    private String sGrantedBy;
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.SysCompany;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface SysCompanyMapper extends BaseMapper<SysCompany> {
+
+    @Select("SELECT iIncrement, sCompanyCode, sCompanyName, iIsDeleted " +
+            "FROM sys_company WHERE sCompanyCode = #{code} LIMIT 1")
+    SysCompany selectByCode(String code);
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface SysEmployeeMapper extends BaseMapper<SysEmployee> {
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.SysPermissionCategory;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface SysPermissionCategoryMapper extends BaseMapper<SysPermissionCategory> {
+
+    /**
+     * 计算给定 ID 集合中有多少行未删除（iIsDeleted=0）。
+     * 用于 REQ-USR-002 批量校验 permissionCategoryIds 是否全部存在。
+     */
+    @Select({
+            "<script>",
+            "SELECT COUNT(*) FROM sys_permission_category ",
+            "WHERE iIsDeleted = 0 AND iIncrement IN ",
+            "<foreach item='id' collection='ids' open='(' separator=',' close=')'>#{id}</foreach>",
+            "</script>"
+    })
+    int countActiveByIds(@Param("ids") List<Integer> ids);
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.annotations.Update;
+
+import java.util.List;
+
+@Mapper
+public interface SysUserMapper extends BaseMapper<SysUser> {
+
+    String LOGIN_COLUMNS = "iIncrement, sUsername, sUserCode, sPasswordHash, iEmployeeId, " +
+            "sUserType, sLanguage, iCanEditDocument, iIsDeleted, iFailedLoginCount, " +
+            "tLockUntil, tLastLoginDate";
+
+    @Select("SELECT " + LOGIN_COLUMNS + " FROM sys_user WHERE sUsername = #{username} LIMIT 1")
+    SysUser selectByUsername(String username);
+
+    /**
+     * 原子累加失败登录次数；达到阈值 maxCount 时同步写 tLockUntil = NOW() + lockMinutes 分钟。
+     * 单 SQL，DB 层保证并发安全。返回受影响行数（应为 1）。
+     * MySQL 按 SET 子句从左到右求值，所以放在 +1 之后的引用看到的是新值。
+     */
+    @Update("UPDATE sys_user " +
+            "SET iFailedLoginCount = iFailedLoginCount + 1, " +
+            "    tLockUntil = IF(iFailedLoginCount >= #{maxCount}, " +
+            "                    DATE_ADD(NOW(), INTERVAL #{lockMinutes} MINUTE), " +
+            "                    tLockUntil) " +
+            "WHERE iIncrement = #{userId}")
+    int incrementFailedLoginCountAtomic(@Param("userId") Integer userId,
+                                        @Param("maxCount") int maxCount,
+                                        @Param("lockMinutes") long lockMinutes);
+
+    /**
+     * 成功登录写入：清零计数 + 清空锁定 + 更新登录时间。一次 UPDATE。
+     */
+    @Update("UPDATE sys_user " +
+            "SET iFailedLoginCount = 0, tLockUntil = NULL, tLastLoginDate = NOW() " +
+            "WHERE iIncrement = #{userId}")
+    int markLoginSuccess(@Param("userId") Integer userId);
+
+    @Select("SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUsername = #{username})")
+    boolean existsByUsername(@Param("username") String username);
+
+    @Select("SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUserCode = #{userCode})")
+    boolean existsByUserCode(@Param("userCode") String userCode);
+
+    @Select("SELECT EXISTS(SELECT 1 FROM sys_user " +
+            "WHERE sUserCode = #{userCode} AND iIncrement <> #{excludedUserId})")
+    boolean existsByUserCodeExcludingId(@Param("userCode") String userCode,
+                                        @Param("excludedUserId") Integer excludedUserId);
+
+    /**
+     * REQ-USR-004 动态查询。SQL 在 SysUserMapper.xml 定义。
+     * QueryParams 必须已通过 service 层白名单校验。
+     */
+    List<UserListItemVo> selectByQuery(@Param("p") UserQueryParams p);
+
+    long countByQuery(@Param("p") UserQueryParams p);
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import org.apache.ibatis.annotations.Delete;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface SysUserPermissionCategoryMapper extends BaseMapper<SysUserPermissionCategory> {
+
+    @Select("SELECT iPermissionCategoryId FROM sys_user_permission_category WHERE iUserId = #{userId}")
+    List<Integer> selectPermissionCategoryIdsByUserId(@Param("userId") Integer userId);
+
+    @Delete({
+            "<script>",
+            "DELETE FROM sys_user_permission_category WHERE iUserId = #{userId} AND iPermissionCategoryId IN ",
+            "<foreach item='id' collection='ids' open='(' separator=',' close=')'>#{id}</foreach>",
+            "</script>"
+    })
+    int deleteByUserAndCategoryIds(@Param("userId") Integer userId,
+                                   @Param("ids") List<Integer> categoryIds);
+}
+package com.xly.erp.module.usr.mapper;
+
+/**
+ * SysUserMapper.selectByQuery / countByQuery 入参（service 层规范化白名单后填入）。
+ * sqlSortField / sqlSortOrder / sqlQueryColumn 必须已通过白名单校验；
+ * mapper XML 直接用 ${} 拼接到 SQL。
+ */
+public class UserQueryParams {
+    public String sqlSortField;
+    public String sqlSortOrder;
+    public String sqlQueryColumn;  // null 表示无 queryField 条件
+    public String matchMode;       // contains / notContains / equals
+    public String queryValue;      // null/"" 表示跳过该条件
+    public String userType;        // null 表示不过滤
+    public Integer isDeleted;      // null 不过滤；0 / 1 过滤
+    public Integer offset;
+    public Integer limit;
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.module.usr.vo.LoginVo;
+
+public interface LoginService {
+    /**
+     * 校验用户名 + 密码 + 公司编码并签发 access token。
+     * REQ-USR-001。
+     *
+     * @throws com.xly.erp.common.exception.BizException
+     *   40004 公司不存在 / 40101 凭据错误 / 40103 账号作废 / 42301 账号锁定
+     */
+    LoginVo login(String username, String password, String companyCode);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.module.usr.dto.CreateUserReq;
+import com.xly.erp.module.usr.vo.CreateUserVo;
+
+public interface UserCreateService {
+    /**
+     * 新建用户 + 权限分类授权。
+     * REQ-USR-002。
+     *
+     * @param req 已通过 jakarta 校验的请求体
+     * @param operatorUsername 当前登录用户（写入 sCreatedBy / sGrantedBy）
+     * @throws com.xly.erp.common.exception.BizException
+     *   40004 employee / permissionCategory 不存在 / 40901 用户名重复 / 40902 用户号重复
+     */
+    CreateUserVo create(CreateUserReq req, String operatorUsername);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.module.usr.vo.UserDetailVo;
+
+public interface UserDetailService {
+    /**
+     * REQ-USR-003 GET /api/v1/users/{userId} 详情。
+     * 包含作废用户（不过滤 iIsDeleted）。
+     *
+     * @throws com.xly.erp.common.exception.BizException 40401 用户不存在
+     */
+    UserDetailVo getById(Integer userId);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.module.usr.dto.UserQueryReq;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+
+public interface UserListService {
+    /**
+     * REQ-USR-004 GET /api/v1/users — 分页 + 多字段筛选 + 排序。
+     * 白名单校验、越界矫正均由实现层完成。
+     */
+    PageResult<UserListItemVo> list(UserQueryReq req);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.module.usr.dto.UpdateUserReq;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+
+public interface UserUpdateService {
+    /**
+     * REQ-USR-003 PUT /api/v1/users/{userId}：部分字段更新 + 权限分类增量差集。
+     *
+     * @throws com.xly.erp.common.exception.BizException
+     *   40004 employee/permissionCategory 不存在 / 40302 自我停用 / 40401 用户不存在 / 40902 用户号冲突
+     */
+    UserDetailVo update(Integer userId, UpdateUserReq req,
+                        Integer operatorUserId, String operatorUsername);
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.security.JwtUtil;
+import com.xly.erp.module.usr.entity.SysCompany;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.mapper.SysCompanyMapper;
+import com.xly.erp.module.usr.mapper.SysEmployeeMapper;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.service.LoginService;
+import com.xly.erp.module.usr.vo.LoginVo;
+import com.xly.erp.module.usr.vo.UserInfoVo;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.HashMap;
+import java.util.Map;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class LoginServiceImpl implements LoginService {
+
+    static final int MAX_FAILED_LOGIN_COUNT = 5;
+    static final long LOCK_DURATION_MINUTES = 30L;
+    static final long TOKEN_TTL_SEC = 7200L;
+
+    private final SysUserMapper userMapper;
+    private final SysCompanyMapper companyMapper;
+    private final SysEmployeeMapper employeeMapper;
+    private final BCryptPasswordEncoder passwordEncoder;
+    private final JwtUtil jwtUtil;
+
+    @Override
+    public LoginVo login(String username, String password, String companyCode) {
+        // 1. 公司校验（只读，不需事务）
+        SysCompany company = companyMapper.selectByCode(companyCode);
+        if (company == null || Integer.valueOf(1).equals(company.getIIsDeleted())) {
+            log.warn("[login] companyCode={} 不存在或已删除", companyCode);
+            throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "公司不存在或已删除");
+        }
+
+        // 2. 用户查找
+        SysUser user = userMapper.selectByUsername(username);
+        if (user == null) {
+            log.warn("[login] username={} 不存在（统一返 40101）", username);
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误");
+        }
+
+        // 3. 作废校验（不计入失败次数）
+        if (Integer.valueOf(1).equals(user.getIIsDeleted())) {
+            log.warn("[login] username={} 已作废", username);
+            throw new BizException(ErrorCode.ACCOUNT_DELETED, "账号已被作废，禁止登录");
+        }
+
+        // 4. 锁定校验（不计入失败次数；过期锁定视为已解锁）
+        if (user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now())) {
+            log.warn("[login] username={} 锁定中，lockUntil={}", username, user.getTLockUntil());
+            Map<String, Object> data = new HashMap<>();
+            data.put("lockUntil", user.getTLockUntil()
+                    .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
+            throw new BizException(ErrorCode.ACCOUNT_LOCKED, "账号已锁定，请稍后再试", data);
+        }
+
+        // 5. 密码校验
+        if (!passwordEncoder.matches(password, user.getSPasswordHash())) {
+            int rows = userMapper.incrementFailedLoginCountAtomic(
+                    user.getIIncrement(), MAX_FAILED_LOGIN_COUNT, LOCK_DURATION_MINUTES);
+            log.warn("[login] username={} 密码错误，原子累加失败次数 rows={}", username, rows);
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误");
+        }
+
+        // 6. 成功路径
+        return loginSuccess(user, companyCode);
+    }
+
+    private LoginVo loginSuccess(SysUser user, String companyCode) {
+        userMapper.markLoginSuccess(user.getIIncrement());
+
+        String employeeName = null;
+        if (user.getIEmployeeId() != null) {
+            SysEmployee emp = employeeMapper.selectById(user.getIEmployeeId());
+            if (emp != null) {
+                employeeName = emp.getSEmployeeName();
+            }
+        }
+
+        Map<String, Object> claims = new HashMap<>();
+        claims.put("sub", user.getIIncrement());
+        claims.put("username", user.getSUsername());
+        claims.put("userType", user.getSUserType());
+        claims.put("companyCode", companyCode);
+        claims.put("language", user.getSLanguage());
+
+        String token = jwtUtil.issue(claims, TOKEN_TTL_SEC);
+
+        log.info("[login] username={} 登录成功", user.getSUsername());
+
+        return LoginVo.builder()
+                .accessToken(token)
+                .tokenType("Bearer")
+                .expiresInSec(TOKEN_TTL_SEC)
+                .userInfo(UserInfoVo.builder()
+                        .userId(user.getIIncrement())
+                        .username(user.getSUsername())
+                        .userType(user.getSUserType())
+                        .language(user.getSLanguage())
+                        .companyCode(companyCode)
+                        .employeeName(employeeName)
+                        .build())
+                .build();
+    }
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.CreateUserReq;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysEmployeeMapper;
+import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.service.UserCreateService;
+import com.xly.erp.module.usr.vo.CreateUserVo;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.dao.DataIntegrityViolationException;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class UserCreateServiceImpl implements UserCreateService {
+
+    static final String INITIAL_PASSWORD = "666666";
+
+    private final SysUserMapper userMapper;
+    private final SysEmployeeMapper employeeMapper;
+    private final SysPermissionCategoryMapper permissionCategoryMapper;
+    private final SysUserPermissionCategoryMapper userPermissionCategoryMapper;
+    private final BCryptPasswordEncoder passwordEncoder;
+
+    @Override
+    @Transactional
+    public CreateUserVo create(CreateUserReq req, String operatorUsername) {
+        // 1. 唯一性预检（返友好错误码；DB 唯一索引兜底并发场景）
+        if (userMapper.existsByUsername(req.getUsername())) {
+            throw new BizException(ErrorCode.CONFLICT_USERNAME, "用户名已存在");
+        }
+        if (userMapper.existsByUserCode(req.getUserCode())) {
+            throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已存在");
+        }
+
+        // 2. employee 外键校验
+        if (req.getEmployeeId() != null) {
+            SysEmployee emp = employeeMapper.selectById(req.getEmployeeId());
+            if (emp == null || Integer.valueOf(1).equals(emp.getIIsDeleted())) {
+                throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "指定的员工不存在或已删除");
+            }
+        }
+
+        // 3. permissionCategory 外键校验（批量）
+        List<Integer> pcIds = req.getPermissionCategoryIds();
+        if (pcIds != null && !pcIds.isEmpty()) {
+            int active = permissionCategoryMapper.countActiveByIds(pcIds);
+            if (active != pcIds.size()) {
+                throw new BizException(ErrorCode.COMPANY_NOT_FOUND,
+                        "指定的权限分类含不存在或已删除项");
+            }
+        }
+
+        // 4. 写入 sys_user
+        SysUser user = new SysUser();
+        user.setSUsername(req.getUsername());
+        user.setSUserCode(req.getUserCode());
+        user.setSPasswordHash(passwordEncoder.encode(INITIAL_PASSWORD));
+        user.setIEmployeeId(req.getEmployeeId());
+        user.setSUserType(req.getUserType());
+        user.setSLanguage(req.getLanguage());
+        user.setICanEditDocument(Boolean.TRUE.equals(req.getCanEditDocument()) ? 1 : 0);
+        user.setIIsDeleted(0);
+        user.setIFailedLoginCount(0);
+        user.setSCreatedBy(operatorUsername);
+        try {
+            userMapper.insert(user);
+        } catch (DataIntegrityViolationException e) {
+            String msg = e.getMessage() == null ? "" : e.getMessage();
+            if (msg.contains("uk_sys_user_username")) {
+                throw new BizException(ErrorCode.CONFLICT_USERNAME, "用户名已存在");
+            }
+            if (msg.contains("uk_sys_user_code")) {
+                throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已存在");
+            }
+            throw e;
+        }
+
+        // 5. 写入 sys_user_permission_category（如有）
+        if (pcIds != null && !pcIds.isEmpty()) {
+            for (Integer pcId : pcIds) {
+                SysUserPermissionCategory link = new SysUserPermissionCategory();
+                link.setIUserId(user.getIIncrement());
+                link.setIPermissionCategoryId(pcId);
+                link.setSGrantedBy(operatorUsername);
+                userPermissionCategoryMapper.insert(link);
+            }
+        }
+
+        log.info("[user-create] username={} userCode={} byOperator={} permissionCount={}",
+                user.getSUsername(), user.getSUserCode(), operatorUsername,
+                pcIds == null ? 0 : pcIds.size());
+
+        return CreateUserVo.builder()
+                .userId(user.getIIncrement())
+                .username(user.getSUsername())
+                .userCode(user.getSUserCode())
+                .build();
+    }
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.mapper.SysEmployeeMapper;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.service.UserDetailService;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+public class UserDetailServiceImpl implements UserDetailService {
+
+    private final SysUserMapper userMapper;
+    private final SysEmployeeMapper employeeMapper;
+    private final SysUserPermissionCategoryMapper upcMapper;
+
+    @Override
+    public UserDetailVo getById(Integer userId) {
+        SysUser user = userMapper.selectById(userId);
+        if (user == null) {
+            throw new BizException(ErrorCode.USER_NOT_FOUND, "用户不存在");
+        }
+
+        String employeeName = null;
+        if (user.getIEmployeeId() != null) {
+            SysEmployee emp = employeeMapper.selectById(user.getIEmployeeId());
+            if (emp != null) {
+                employeeName = emp.getSEmployeeName();
+            }
+        }
+
+        List<Integer> pcIds = upcMapper.selectPermissionCategoryIdsByUserId(userId);
+
+        return UserDetailVo.builder()
+                .userId(user.getIIncrement())
+                .username(user.getSUsername())
+                .userCode(user.getSUserCode())
+                .userType(user.getSUserType())
+                .language(user.getSLanguage())
+                .canEditDocument(Integer.valueOf(1).equals(user.getICanEditDocument()))
+                .isDeleted(Integer.valueOf(1).equals(user.getIIsDeleted()))
+                .employeeId(user.getIEmployeeId())
+                .employeeName(employeeName)
+                .permissionCategoryIds(pcIds)
+                .updatedBy(user.getSUpdatedBy())
+                .updatedDate(user.getTUpdatedDate())
+                .build();
+    }
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.module.usr.dto.UserQueryReq;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.UserQueryParams;
+import com.xly.erp.module.usr.service.UserListService;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+@Service
+@RequiredArgsConstructor
+public class UserListServiceImpl implements UserListService {
+
+    static final int DEFAULT_PAGE = 1;
+    static final int DEFAULT_SIZE = 20;
+    static final String DEFAULT_SORT_FIELD = "tCreateDate";
+    static final String DEFAULT_SORT_ORDER = "desc";
+    static final String DEFAULT_MATCH_MODE = "contains";
+
+    static final Set<String> SORT_FIELDS = Set.of(
+            "tCreateDate", "tLastLoginDate", "sUsername", "sUserCode");
+
+    static final Set<String> SORT_ORDERS = Set.of("asc", "desc");
+
+    static final Set<String> MATCH_MODES = Set.of("contains", "notContains", "equals");
+
+    /** spec § 业务规则 3：非字符串列（int/datetime）一律按 equals 处理。 */
+    static final Set<String> EQUALS_ONLY_FIELDS = Set.of("isDeleted", "lastLoginDate");
+
+    static final Set<String> USER_TYPES = Set.of("NORMAL", "SUPER_ADMIN");
+
+    static final Map<String, String> QUERY_FIELD_TO_SQL = Map.ofEntries(
+            Map.entry("username",       "u.sUsername"),
+            Map.entry("employeeName",   "e.sEmployeeName"),
+            Map.entry("userCode",       "u.sUserCode"),
+            Map.entry("departmentName", "d.sDepartmentName"),
+            Map.entry("userType",       "u.sUserType"),
+            Map.entry("isDeleted",      "u.iIsDeleted"),
+            Map.entry("lastLoginDate",  "u.tLastLoginDate"),
+            Map.entry("createdBy",      "u.sCreatedBy"));
+
+    private final SysUserMapper userMapper;
+
+    @Override
+    public PageResult<UserListItemVo> list(UserQueryReq req) {
+        // 应用默认值
+        int page = req.getPage() == null ? DEFAULT_PAGE : req.getPage();
+        int size = req.getSize() == null ? DEFAULT_SIZE : req.getSize();
+        String sortField = req.getSortField() == null ? DEFAULT_SORT_FIELD : req.getSortField();
+        String sortOrder = req.getSortOrder() == null ? DEFAULT_SORT_ORDER : req.getSortOrder();
+        String matchMode = req.getMatchMode() == null ? DEFAULT_MATCH_MODE : req.getMatchMode();
+
+        // 白名单校验
+        if (!SORT_FIELDS.contains(sortField)) {
+            throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "sortField 不在白名单");
+        }
+        if (!SORT_ORDERS.contains(sortOrder)) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "sortOrder 必须为 asc 或 desc");
+        }
+        if (!MATCH_MODES.contains(matchMode)) {
+            throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "matchMode 不在白名单");
+        }
+
+        String sqlQueryColumn = null;
+        String normalizedQueryValue = null;
+        if (req.getQueryField() != null && !req.getQueryField().isBlank()) {
+            sqlQueryColumn = QUERY_FIELD_TO_SQL.get(req.getQueryField());
+            if (sqlQueryColumn == null) {
+                throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "queryField 不在白名单");
+            }
+            // 只有 queryField + queryValue 都提供且非空才应用条件
+            if (req.getQueryValue() != null && !req.getQueryValue().isBlank()) {
+                normalizedQueryValue = normalizeQueryValue(req.getQueryField(), req.getQueryValue());
+                // spec § 业务规则 3：非字符串列一律强制 equals
+                if (EQUALS_ONLY_FIELDS.contains(req.getQueryField())) {
+                    matchMode = "equals";
+                }
+            } else {
+                sqlQueryColumn = null;  // 缺 queryValue 跳过条件
+            }
+        }
+
+        if (req.getUserType() != null && !USER_TYPES.contains(req.getUserType())) {
+            throw new BizException(ErrorCode.BAD_REQUEST, "userType 必须为 NORMAL 或 SUPER_ADMIN");
+        }
+
+        UserQueryParams p = new UserQueryParams();
+        p.sqlSortField = sortField;
+        p.sqlSortOrder = sortOrder;
+        p.sqlQueryColumn = sqlQueryColumn;
+        p.matchMode = matchMode;
+        p.queryValue = normalizedQueryValue;
+        p.userType = req.getUserType();
+        p.isDeleted = req.getIsDeleted() == null ? null : (req.getIsDeleted() ? 1 : 0);
+        p.limit = size;
+        p.offset = (page - 1) * size;
+
+        long total = userMapper.countByQuery(p);
+        List<UserListItemVo> records = userMapper.selectByQuery(p);
+
+        // 越界矫正：当前页空但 total>0 → 重算最后一页
+        int actualPage = page;
+        if (records.isEmpty() && total > 0) {
+            int lastPage = (int) ((total + size - 1) / size);
+            p.offset = (lastPage - 1) * size;
+            records = userMapper.selectByQuery(p);
+            actualPage = lastPage;
+        }
+
+        return PageResult.<UserListItemVo>builder()
+                .records(records)
+                .total(total)
+                .page(actualPage)
+                .size(size)
+                .build();
+    }
+
+    /**
+     * 对非字符串列做规范化（spec § 业务规则 3）：
+     * - isDeleted: true/1 → "1"；false/0 → "0"；其他抛 40001
+     * - lastLoginDate: 解析 ISO LOCAL_DATE_TIME 或 ISO LOCAL_DATE，统一格式为 'yyyy-MM-dd HH:mm:ss'；非法抛 40001
+     * - 其他列返回原值
+     */
+    private String normalizeQueryValue(String queryField, String raw) {
+        if ("isDeleted".equals(queryField)) {
+            if ("true".equalsIgnoreCase(raw) || "1".equals(raw)) return "1";
+            if ("false".equalsIgnoreCase(raw) || "0".equals(raw)) return "0";
+            throw new BizException(ErrorCode.BAD_REQUEST,
+                    "queryField=isDeleted 时 queryValue 必须为 true / false / 0 / 1");
+        }
+        if ("lastLoginDate".equals(queryField)) {
+            try {
+                LocalDateTime dt;
+                if (raw.contains("T") || raw.contains(" ")) {
+                    dt = LocalDateTime.parse(raw.replace(' ', 'T'));
+                } else {
+                    dt = java.time.LocalDate.parse(raw).atStartOfDay();
+                }
+                return dt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
+            } catch (DateTimeParseException e) {
+                throw new BizException(ErrorCode.BAD_REQUEST,
+                        "queryField=lastLoginDate 时 queryValue 必须为 ISO 日期或日期时间");
+            }
+        }
+        return raw;
+    }
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper;
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.UpdateUserReq;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysEmployeeMapper;
+import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.service.UserDetailService;
+import com.xly.erp.module.usr.service.UserUpdateService;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Set;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class UserUpdateServiceImpl implements UserUpdateService {
+
+    private final SysUserMapper userMapper;
+    private final SysEmployeeMapper employeeMapper;
+    private final SysPermissionCategoryMapper permissionCategoryMapper;
+    private final SysUserPermissionCategoryMapper upcMapper;
+    private final UserDetailService userDetailService;
+
+    @Override
+    @Transactional
+    public UserDetailVo update(Integer userId, UpdateUserReq req,
+                               Integer operatorUserId, String operatorUsername) {
+        // 1. 存在性
+        SysUser existing = userMapper.selectById(userId);
+        if (existing == null) {
+            throw new BizException(ErrorCode.USER_NOT_FOUND, "用户不存在");
+        }
+
+        // 2. 自我停用守卫
+        if (Boolean.TRUE.equals(req.getIsDeleted()) && userId.equals(operatorUserId)) {
+            throw new BizException(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE,
+                    "不允许停用当前登录用户自己");
+        }
+
+        // 3. userCode 唯一（排除自身）
+        if (req.getUserCode() != null
+                && !req.getUserCode().equals(existing.getSUserCode())
+                && userMapper.existsByUserCodeExcludingId(req.getUserCode(), userId)) {
+            throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已被占用");
+        }
+
+        // 4. employeeId 外键（仅正整数才查）
+        if (req.getEmployeeId() != null && req.getEmployeeId() > 0) {
+            SysEmployee emp = employeeMapper.selectById(req.getEmployeeId());
+            if (emp == null || Integer.valueOf(1).equals(emp.getIIsDeleted())) {
+                throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "指定的员工不存在或已删除");
+            }
+        }
+
+        // 5. permissionCategoryIds 外键（dedup 后校验）
+        Set<Integer> targetPcSet = null;
+        if (req.getPermissionCategoryIds() != null) {
+            targetPcSet = new LinkedHashSet<>(req.getPermissionCategoryIds());
+            if (!targetPcSet.isEmpty()) {
+                int active = permissionCategoryMapper.countActiveByIds(
+                        new java.util.ArrayList<>(targetPcSet));
+                if (active != targetPcSet.size()) {
+                    throw new BizException(ErrorCode.COMPANY_NOT_FOUND,
+                            "指定的权限分类含不存在或已删除项");
+                }
+            }
+        }
+
+        // 6. 写 sys_user 字段
+        UpdateWrapper<SysUser> uw = new UpdateWrapper<>();
+        uw.eq("iIncrement", userId);
+
+        if (req.getUserCode() != null) uw.set("sUserCode", req.getUserCode());
+        if (req.getUserType() != null) uw.set("sUserType", req.getUserType());
+        if (req.getLanguage() != null) uw.set("sLanguage", req.getLanguage());
+        if (req.getCanEditDocument() != null)
+            uw.set("iCanEditDocument", req.getCanEditDocument() ? 1 : 0);
+        if (req.getIsDeleted() != null)
+            uw.set("iIsDeleted", req.getIsDeleted() ? 1 : 0);
+        if (req.getEmployeeId() != null) {
+            if (req.getEmployeeId() == 0) {
+                uw.set("iEmployeeId", null);  // 解除关联
+            } else {
+                uw.set("iEmployeeId", req.getEmployeeId());
+            }
+        }
+        uw.set("sUpdatedBy", operatorUsername);
+        uw.set("tUpdatedDate", LocalDateTime.now());
+
+        userMapper.update(null, uw);
+
+        // 7. 权限分类增量差集
+        if (targetPcSet != null) {
+            List<Integer> currentList = upcMapper.selectPermissionCategoryIdsByUserId(userId);
+            Set<Integer> currentSet = new HashSet<>(currentList);
+
+            Set<Integer> toRemove = new HashSet<>(currentSet);
+            toRemove.removeAll(targetPcSet);
+
+            Set<Integer> toAdd = new LinkedHashSet<>(targetPcSet);
+            toAdd.removeAll(currentSet);
+
+            if (!toRemove.isEmpty()) {
+                upcMapper.deleteByUserAndCategoryIds(userId, new java.util.ArrayList<>(toRemove));
+            }
+            for (Integer pcId : toAdd) {
+                SysUserPermissionCategory link = new SysUserPermissionCategory();
+                link.setIUserId(userId);
+                link.setIPermissionCategoryId(pcId);
+                link.setSGrantedBy(operatorUsername);
+                upcMapper.insert(link);
+            }
+            log.info("[user-update] userId={} pc.toRemove={} pc.toAdd={}",
+                    userId, toRemove.size(), toAdd.size());
+        }
+
+        log.info("[user-update] userId={} byOperator={} 完成", userId, operatorUsername);
+        return userDetailService.getById(userId);
+    }
+}
+package com.xly.erp.module.usr.vo;
+
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class CreateUserVo {
+    private Integer userId;
+    private String username;
+    private String userCode;
+}
+package com.xly.erp.module.usr.vo;
+
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+public class LoginVo {
+    private String accessToken;
+    private String tokenType;
+    private long expiresInSec;
+    private UserInfoVo userInfo;
+}
+package com.xly.erp.module.usr.vo;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Builder;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+@Data
+@Builder
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class UserDetailVo {
+    private Integer userId;
+    private String username;
+    private String userCode;
+    private String userType;
+    private String language;
+    private Boolean canEditDocument;
+    private Boolean isDeleted;
+    private Integer employeeId;
+    private String employeeName;
+    private List<Integer> permissionCategoryIds;
+    private String updatedBy;
+    private LocalDateTime updatedDate;
+}
+package com.xly.erp.module.usr.vo;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Builder;
+import lombok.Data;
+
+@Data
+@Builder
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class UserInfoVo {
+    private Integer userId;
+    private String username;
+    private String userType;
+    private String language;
+    private String employeeName;
+    private String companyCode;
+}
+package com.xly.erp.module.usr.vo;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import lombok.AllArgsConstructor;
+
+import java.time.LocalDateTime;
+
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+@JsonInclude(JsonInclude.Include.ALWAYS)
+public class UserListItemVo {
+    private Integer userId;
+    private String username;
+    private String employeeName;
+    private String userCode;
+    private String departmentName;
+    private String userType;
+    private String language;
+    private Boolean isDeleted;
+    private LocalDateTime lastLoginDate;
+    private String createdBy;
+    private LocalDateTime createdDate;
+}
+spring:
+  jackson:
+    deserialization:
+      fail-on-unknown-properties: true
+  datasource:
+    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+  flyway:
+    enabled: true
+    locations: filesystem:../sql/migrations
+
+jwt:
+  secret: ${JWT_SECRET:test-secret-please-replace-with-256bit-random-string-xxxxxxx}
+  ttl-sec: 7200
+
+logging:
+  level:
+    root: WARN
+    com.xly.erp: DEBUG
+    com.zaxxer.hikari: WARN
+server:
+  port: 9090
+
+spring:
+  application:
+    name: xly-erp-backend
+  jackson:
+    deserialization:
+      fail-on-unknown-properties: true
+  datasource:
+    driver-class-name: com.mysql.cj.jdbc.Driver
+    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+  flyway:
+    enabled: true
+    locations: filesystem:../sql/migrations
+    baseline-on-migrate: true
+    baseline-version: 0
+    validate-on-migrate: true
+
+mybatis-plus:
+  mapper-locations: classpath*:/mapper/**/*.xml
+  configuration:
+    map-underscore-to-camel-case: false
+    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl
+  global-config:
+    db-config:
+      id-type: auto
+
+jwt:
+  secret: ${JWT_SECRET}
+  ttl-sec: 7200
+
+logging:
+  level:
+    root: INFO
+    com.xly.erp: DEBUG
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="CONSOLE"/>
+    </root>
+
+    <logger name="com.xly.erp" level="DEBUG"/>
+</configuration>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="com.xly.erp.module.usr.mapper.SysUserMapper">
+
+    <sql id="baseFrom">
+        FROM sys_user u
+        LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId
+        LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId
+    </sql>
+
+    <sql id="whereClause">
+        <where>
+            <if test="p.sqlQueryColumn != null and p.queryValue != null and p.queryValue != ''">
+                <choose>
+                    <when test="'contains'.equals(p.matchMode)">
+                        AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%')
+                    </when>
+                    <when test="'notContains'.equals(p.matchMode)">
+                        AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%')
+                             OR ${p.sqlQueryColumn} IS NULL)
+                    </when>
+                    <otherwise>
+                        AND ${p.sqlQueryColumn} = #{p.queryValue}
+                    </otherwise>
+                </choose>
+            </if>
+            <if test="p.userType != null">
+                AND u.sUserType = #{p.userType}
+            </if>
+            <if test="p.isDeleted != null">
+                AND u.iIsDeleted = #{p.isDeleted}
+            </if>
+        </where>
+    </sql>
+
+    <resultMap id="UserListItemVoMap" type="com.xly.erp.module.usr.vo.UserListItemVo">
+        <id     property="userId"          column="userId"/>
+        <result property="username"        column="username"/>
+        <result property="employeeName"    column="employeeName"/>
+        <result property="userCode"        column="userCode"/>
+        <result property="departmentName"  column="departmentName"/>
+        <result property="userType"        column="userType"/>
+        <result property="language"        column="language"/>
+        <result property="isDeleted"       column="isDeleted" javaType="java.lang.Boolean"/>
+        <result property="lastLoginDate"   column="lastLoginDate"/>
+        <result property="createdBy"       column="createdBy"/>
+        <result property="createdDate"     column="createdDate"/>
+    </resultMap>
+
+    <select id="selectByQuery" resultMap="UserListItemVoMap">
+        SELECT u.iIncrement      AS userId,
+               u.sUsername       AS username,
+               e.sEmployeeName   AS employeeName,
+               u.sUserCode       AS userCode,
+               d.sDepartmentName AS departmentName,
+               u.sUserType       AS userType,
+               u.sLanguage       AS language,
+               u.iIsDeleted      AS isDeleted,
+               u.tLastLoginDate  AS lastLoginDate,
+               u.sCreatedBy      AS createdBy,
+               u.tCreateDate     AS createdDate
+        <include refid="baseFrom"/>
+        <include refid="whereClause"/>
+        ORDER BY u.${p.sqlSortField} ${p.sqlSortOrder}
+        LIMIT #{p.offset}, #{p.limit}
+    </select>
+
+    <select id="countByQuery" resultType="long">
+        SELECT COUNT(*)
+        <include refid="baseFrom"/>
+        <include refid="whereClause"/>
+    </select>
+
+</mapper>
+package com.xly.erp;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.ApplicationContext;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+/**
+ * REQ-USR-001 — Boot smoke test:
+ * verifies Spring Boot context starts and Flyway has applied V1 against the
+ * MySQL schema configured via .env.local (DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_SCHEMA).
+ */
+@SpringBootTest
+@org.springframework.test.context.ActiveProfiles("test")
+class ApplicationContextTest {
+
+    @Autowired
+    private ApplicationContext ctx;
+
+    @Test
+    void contextLoads() {
+        assertNotNull(ctx, "Spring ApplicationContext should be initialised");
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ErrorCode;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.not;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@org.springframework.context.annotation.Import(GlobalExceptionHandlerTest.ThrowingTestController.class)
+class GlobalExceptionHandlerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    void bizException_locked_returns423_withCode42301() throws Exception {
+        mockMvc.perform(get("/_test/throw/locked"))
+                .andExpect(status().isLocked())
+                .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_LOCKED))
+                .andExpect(jsonPath("$.data").doesNotExist());
+    }
+
+    @Test
+    void bizException_badCredentials_returns401_withCode40101() throws Exception {
+        mockMvc.perform(get("/_test/throw/bad-credentials"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void unexpectedException_returns500_doesNotLeakStackTrace() throws Exception {
+        mockMvc.perform(get("/_test/throw/runtime"))
+                .andExpect(status().isInternalServerError())
+                .andExpect(jsonPath("$.code").value(ErrorCode.INTERNAL_ERROR))
+                .andExpect(jsonPath("$.message").value(not(containsString("java."))))
+                .andExpect(jsonPath("$.message").value(not(containsString("Exception"))));
+    }
+
+    @RestController
+    static class ThrowingTestController {
+        @GetMapping("/_test/throw/locked")
+        public void locked() {
+            throw new BizException(ErrorCode.ACCOUNT_LOCKED, "账号已锁定，请稍后再试");
+        }
+
+        @GetMapping("/_test/throw/bad-credentials")
+        public void badCredentials() {
+            throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误");
+        }
+
+        @GetMapping("/_test/throw/runtime")
+        public void runtime() {
+            throw new RuntimeException("internal boom java.lang.NullPointerException");
+        }
+    }
+}
+package com.xly.erp.common.response;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class ErrorCodeTest {
+
+    @Test
+    void httpMappings_coverNewCodes() {
+        assertEquals(403, ErrorCode.toHttpStatus(ErrorCode.FORBIDDEN));
+        assertEquals(409, ErrorCode.toHttpStatus(ErrorCode.CONFLICT_USERNAME));
+        assertEquals(409, ErrorCode.toHttpStatus(ErrorCode.CONFLICT_USERCODE));
+        assertEquals(40301, ErrorCode.FORBIDDEN);
+        assertEquals(40901, ErrorCode.CONFLICT_USERNAME);
+        assertEquals(40902, ErrorCode.CONFLICT_USERCODE);
+    }
+
+    @Test
+    void httpMappings_coverNewCodes_v004() {
+        assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.INVALID_ENUM_PARAM));
+        assertEquals(40003, ErrorCode.INVALID_ENUM_PARAM);
+    }
+
+    @Test
+    void httpMappings_coverNewCodes_v003() {
+        assertEquals(403, ErrorCode.toHttpStatus(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE));
+        assertEquals(404, ErrorCode.toHttpStatus(ErrorCode.USER_NOT_FOUND));
+        assertEquals(40302, ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE);
+        assertEquals(40401, ErrorCode.USER_NOT_FOUND);
+    }
+
+    @Test
+    void httpMappings_existingCodes_unchanged() {
+        assertEquals(200, ErrorCode.toHttpStatus(ErrorCode.OK));
+        assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.BAD_REQUEST));
+        assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.COMPANY_NOT_FOUND));
+        assertEquals(401, ErrorCode.toHttpStatus(ErrorCode.BAD_CREDENTIALS));
+        assertEquals(401, ErrorCode.toHttpStatus(ErrorCode.ACCOUNT_DELETED));
+        assertEquals(423, ErrorCode.toHttpStatus(ErrorCode.ACCOUNT_LOCKED));
+        assertEquals(500, ErrorCode.toHttpStatus(ErrorCode.INTERNAL_ERROR));
+    }
+}
+package com.xly.erp.common.security;
+
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@org.springframework.context.annotation.Import(JwtHandlerInterceptorTest.GuardedTestController.class)
+class JwtHandlerInterceptorTest {
+
+    @Autowired private MockMvc mvc;
+    @Autowired private JwtUtil jwtUtil;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private org.springframework.jdbc.core.JdbcTemplate jdbc;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    private String issueToken(String username, String userType, String companyCode) {
+        Map<String, Object> claims = new HashMap<>();
+        claims.put("sub", 1);
+        claims.put("username", username);
+        claims.put("userType", userType);
+        claims.put("companyCode", companyCode);
+        claims.put("language", "zh-CN");
+        return jwtUtil.issue(claims, 7200);
+    }
+
+    // ===== 鉴权基础 =====
+
+    @Test
+    void noAuthHeader_returns401_40101() throws Exception {
+        mvc.perform(get("/api/v1/_test/any-auth"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void invalidToken_returns401_40101() throws Exception {
+        mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer bogus.jwt.token"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void tokenForUnknownUser_returns401_40101() throws Exception {
+        String token = issueToken("nobody", "NORMAL", "HQ");
+        mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void tokenForDeletedUser_returns401_40101() throws Exception {
+        String token = issueToken(LoginTestSeeder.USER_DELETED, "NORMAL", "HQ");
+        mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void tokenForLockedUser_returns401_40101() throws Exception {
+        jdbc.update("UPDATE sys_user SET tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?",
+                LoginTestSeeder.USER_OK);
+        String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ");
+        mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void validToken_normalUser_canAccessAnyAuthEndpoint() throws Exception {
+        String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ");
+        mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data").value("ok-" + LoginTestSeeder.USER_OK));
+    }
+
+    // ===== @RequireSuperAdmin =====
+
+    @Test
+    void validToken_normalUser_cannotAccessAdminOnly_returns403_40301() throws Exception {
+        String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ");
+        mvc.perform(get("/api/v1/_test/admin-only").header("Authorization", "Bearer " + token))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN));
+    }
+
+    @Test
+    void validToken_superAdmin_canAccessAdminOnly() throws Exception {
+        // 把 alice 升级为 SUPER_ADMIN
+        jdbc.update("UPDATE sys_user SET sUserType='SUPER_ADMIN' WHERE sUsername=?", LoginTestSeeder.USER_OK);
+        String token = issueToken(LoginTestSeeder.USER_OK, "SUPER_ADMIN", "HQ");
+        mvc.perform(get("/api/v1/_test/admin-only").header("Authorization", "Bearer " + token))
+                .andExpect(status().isOk());
+    }
+
+    // ===== 放行 /api/v1/auth/login =====
+
+    @Test
+    void loginEndpointPath_skipsInterceptor() throws Exception {
+        // 不带 auth 头调登录接口；应进入 controller 并返参数校验错（不是 40101）
+        mvc.perform(post("/api/v1/auth/login").contentType("application/json").content("{}"))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @RestController
+    @RequestMapping("/api/v1/_test")
+    static class GuardedTestController {
+
+        @GetMapping("/any-auth")
+        public com.xly.erp.common.response.Result<String> anyAuth() {
+            LoginContext.LoginUser u = LoginContext.current();
+            return com.xly.erp.common.response.Result.ok("ok-" + (u == null ? "null" : u.username()));
+        }
+
+        @GetMapping("/admin-only")
+        @RequireSuperAdmin
+        public com.xly.erp.common.response.Result<String> adminOnly() {
+            return com.xly.erp.common.response.Result.ok("admin");
+        }
+    }
+}
+package com.xly.erp.common.security;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class JwtUtilTest {
+
+    @Autowired
+    private JwtUtil jwtUtil;
+
+    private Map<String, Object> sampleClaims() {
+        Map<String, Object> claims = new HashMap<>();
+        claims.put("sub", "42");
+        claims.put("username", "alice");
+        claims.put("userType", "NORMAL");
+        claims.put("companyCode", "HQ");
+        claims.put("language", "zh-CN");
+        return claims;
+    }
+
+    @Test
+    void issuedToken_canBeParsedBackToClaims() {
+        String token = jwtUtil.issue(sampleClaims(), 7200);
+        assertNotNull(token);
+        assertFalse(token.isEmpty());
+
+        Map<String, Object> parsed = jwtUtil.parse(token);
+        assertEquals("42", parsed.get("sub"));
+        assertEquals("alice", parsed.get("username"));
+        assertEquals("NORMAL", parsed.get("userType"));
+        assertEquals("HQ", parsed.get("companyCode"));
+        assertEquals("zh-CN", parsed.get("language"));
+        assertNotNull(parsed.get("jti"));
+        assertNotNull(parsed.get("iat"));
+        assertNotNull(parsed.get("exp"));
+
+        long iat = ((Number) parsed.get("iat")).longValue();
+        long exp = ((Number) parsed.get("exp")).longValue();
+        assertEquals(7200L, exp - iat, "exp - iat 必须严格等于 ttlSec（spec § 验收 § 2）");
+    }
+
+    @Test
+    void tamperedToken_throwsBizException() {
+        String token = jwtUtil.issue(sampleClaims(), 7200);
+        String tampered = token.substring(0, token.length() - 4) + "XXXX";
+        BizException e = assertThrows(BizException.class, () -> jwtUtil.parse(tampered));
+        assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode());
+    }
+
+    @Test
+    void expiredToken_throwsBizException() {
+        String token = jwtUtil.issue(sampleClaims(), 0L);
+        try { Thread.sleep(1100); } catch (InterruptedException ignored) {}
+        BizException e = assertThrows(BizException.class, () -> jwtUtil.parse(token));
+        assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode());
+    }
+}
+package com.xly.erp.common.security;
+
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.Test;
+
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.atomic.AtomicReference;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class LoginContextTest {
+
+    @AfterEach
+    void tearDown() {
+        LoginContext.clear();
+    }
+
+    @Test
+    void setAndCurrent_returnsSameUser() {
+        LoginContext.LoginUser u = new LoginContext.LoginUser(42, "alice", "NORMAL", "HQ");
+        LoginContext.set(u);
+        assertSame(u, LoginContext.current());
+    }
+
+    @Test
+    void clear_returnsNullForCurrent() {
+        LoginContext.set(new LoginContext.LoginUser(1, "x", "NORMAL", "HQ"));
+        LoginContext.clear();
+        assertNull(LoginContext.current());
+    }
+
+    @Test
+    void setAndCurrent_isolatedPerThread() throws InterruptedException {
+        LoginContext.set(new LoginContext.LoginUser(1, "main", "NORMAL", "HQ"));
+
+        AtomicReference<LoginContext.LoginUser> seen = new AtomicReference<>();
+        CountDownLatch latch = new CountDownLatch(1);
+        Thread t = new Thread(() -> {
+            seen.set(LoginContext.current());
+            LoginContext.set(new LoginContext.LoginUser(2, "child", "SUPER_ADMIN", "HQ"));
+            latch.countDown();
+        });
+        t.start();
+        latch.await();
+        t.join();
+
+        assertNull(seen.get(), "子线程不应继承父线程 ThreadLocal");
+        assertEquals("main", LoginContext.current().username(),
+                "父线程上下文不应被子线程改动影响");
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.LoginReq;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.MediaType;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class AuthControllerTest {
+
+    @Autowired private MockMvc mvc;
+    @Autowired private ObjectMapper json;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private JdbcTemplate jdbc;
+
+    @BeforeEach
+    void setUp() {
+        seeder.reset();
+    }
+
+    private String body(String username, String password, String companyCode) throws Exception {
+        LoginReq r = new LoginReq();
+        r.setUsername(username);
+        r.setPassword(password);
+        r.setCompanyCode(companyCode);
+        return json.writeValueAsString(r);
+    }
+
+    @Test
+    void post_login_success_returns200_andLoginVo() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                                LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data.accessToken").isNotEmpty())
+                .andExpect(jsonPath("$.data.tokenType").value("Bearer"))
+                .andExpect(jsonPath("$.data.expiresInSec").value(7200))
+                .andExpect(jsonPath("$.data.userInfo.username").value(LoginTestSeeder.USER_OK))
+                .andExpect(jsonPath("$.data.userInfo.companyCode").value(LoginTestSeeder.COMPANY_OK));
+    }
+
+    @Test
+    void post_login_badCredentials_returns401_code40101() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void post_login_unknownUser_returns401_code40101() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body("nobody", "any", LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void post_login_lockedAccount_returns423_code42301_withLockUntil() throws Exception {
+        jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?",
+                LoginTestSeeder.USER_OK);
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                                LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isLocked())
+                .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_LOCKED))
+                .andExpect(jsonPath("$.data.lockUntil").isNotEmpty());
+    }
+
+    @Test
+    void post_login_deletedAccount_returns401_code40103() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(LoginTestSeeder.USER_DELETED, LoginTestSeeder.DEFAULT_PASSWORD,
+                                LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_DELETED));
+    }
+
+    @Test
+    void post_login_unknownCompany_returns400_code40004() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, "NOPE")))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND));
+    }
+
+    @Test
+    void post_login_blankUsername_returns400_code40001() throws Exception {
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body("", LoginTestSeeder.DEFAULT_PASSWORD, LoginTestSeeder.COMPANY_OK)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.security.JwtUtil;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class UserControllerListTest {
+
+    @Autowired private MockMvc mvc;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private JwtUtil jwtUtil;
+    @Autowired private JdbcTemplate jdbc;
+
+    private LoginTestSeeder.Fixture fx;
+    private String adminToken;
+    private String normalToken;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+        adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN", fx.adminId());
+        normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL", fx.aliceId());
+    }
+
+    private String issue(String username, String userType, Integer userId) {
+        Map<String, Object> c = new HashMap<>();
+        c.put("sub", userId);
+        c.put("username", username);
+        c.put("userType", userType);
+        c.put("companyCode", LoginTestSeeder.COMPANY_OK);
+        c.put("language", "zh-CN");
+        return jwtUtil.issue(c, 7200);
+    }
+
+    @Test
+    void list_default_returnsAllUsers() throws Exception {
+        mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data.total").value(3))
+                .andExpect(jsonPath("$.data.records.length()").value(3))
+                .andExpect(jsonPath("$.data.page").value(1))
+                .andExpect(jsonPath("$.data.size").value(20));
+    }
+
+    @Test
+    void list_sizeOver100_returns400_40001() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("size", "200")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void list_pageZero_returns400_40001() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("page", "0")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void list_sortByUsernameAsc() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("sortField", "sUsername")
+                        .param("sortOrder", "asc")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_ADMIN));
+    }
+
+    @Test
+    void list_sortFieldInvalid_returns400_40003() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("sortField", "badField")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM));
+    }
+
+    @Test
+    void list_sortOrderInvalid_returns400_40001() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("sortOrder", "foo")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void list_queryByUsernameContains() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("queryField", "username")
+                        .param("matchMode", "contains")
+                        .param("queryValue", "ali")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_OK));
+    }
+
+    @Test
+    void list_queryByDepartmentName_multiJoin() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("queryField", "departmentName")
+                        .param("matchMode", "equals")
+                        .param("queryValue", "技术部")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.records[0].departmentName").value("技术部"));
+    }
+
+    @Test
+    void list_queryByIsDeletedTrue() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("queryField", "isDeleted")
+                        .param("matchMode", "equals")
+                        .param("queryValue", "true")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_DELETED));
+    }
+
+    @Test
+    void list_queryFieldInvalid_returns400_40003() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("queryField", "badField")
+                        .param("queryValue", "x")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM));
+    }
+
+    @Test
+    void list_matchModeInvalid_returns400_40003() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("matchMode", "startsWith")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM));
+    }
+
+    @Test
+    void list_explicitUserTypeFilter() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("userType", "NORMAL")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(2));  // alice + bob_deleted
+    }
+
+    @Test
+    void list_explicitUserTypeInvalid_returns400_40001() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("userType", "HACKER")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void list_explicitIsDeletedFalse_filtersActive() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("isDeleted", "false")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(2));  // alice + admin
+    }
+
+    @Test
+    void list_composedFilters_andSemantics() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("queryField", "username")
+                        .param("queryValue", "a")
+                        .param("userType", "NORMAL")
+                        .param("isDeleted", "false")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_OK));
+    }
+
+    @Test
+    void list_pageBeyondTotal_returnsLastPage() throws Exception {
+        mvc.perform(get("/api/v1/users")
+                        .param("page", "999")
+                        .param("size", "10")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(3))
+                .andExpect(jsonPath("$.data.page").value(1))
+                .andExpect(jsonPath("$.data.records.length()").value(3));
+    }
+
+    @Test
+    void list_normalUserToken_returns403_40301() throws Exception {
+        mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + normalToken))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN));
+    }
+
+    @Test
+    void list_noAuthHeader_returns401_40101() throws Exception {
+        mvc.perform(get("/api/v1/users"))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void list_responseRecordDoesNotIncludePasswordField() throws Exception {
+        mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.records[0].password").doesNotExist())
+                .andExpect(jsonPath("$.data.records[0].passwordHash").doesNotExist())
+                .andExpect(jsonPath("$.data.records[0].sPasswordHash").doesNotExist());
+    }
+
+    @Test
+    void list_emptyTable_returnsZeroTotal() throws Exception {
+        jdbc.update("DELETE FROM sys_user_permission_category");
+        jdbc.update("DELETE FROM sys_user");
+        // 但鉴权需要 token 关联用户存在，所以保留 admin 用户即可
+        // 重做：只删 alice / bob
+        // 重置后用一个独立 seed
+        seeder.reset();
+        jdbc.update("DELETE FROM sys_user WHERE sUsername IN (?, ?)",
+                LoginTestSeeder.USER_OK, LoginTestSeeder.USER_DELETED);
+
+        mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1));  // 只剩 admin
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.security.JwtUtil;
+import com.xly.erp.module.usr.dto.CreateUserReq;
+import com.xly.erp.module.usr.dto.LoginReq;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class UserControllerTest {
+
+    @Autowired private MockMvc mvc;
+    @Autowired private ObjectMapper json;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private JwtUtil jwtUtil;
+
+    private LoginTestSeeder.Fixture fx;
+    private String adminToken;
+    private String normalToken;
+    private String deletedToken;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+        adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN");
+        normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL");
+        deletedToken = issue(LoginTestSeeder.USER_DELETED, "NORMAL");
+    }
+
+    private String issue(String username, String userType) {
+        Map<String, Object> claims = new HashMap<>();
+        claims.put("sub", 1);
+        claims.put("username", username);
+        claims.put("userType", userType);
+        claims.put("companyCode", LoginTestSeeder.COMPANY_OK);
+        claims.put("language", "zh-CN");
+        return jwtUtil.issue(claims, 7200);
+    }
+
+    private CreateUserReq buildReq() {
+        CreateUserReq r = new CreateUserReq();
+        r.setUsername("newbie");
+        r.setUserCode("U010");
+        r.setUserType("NORMAL");
+        r.setLanguage("zh-CN");
+        r.setCanEditDocument(false);
+        return r;
+    }
+
+    private String body(Object o) throws Exception {
+        return json.writeValueAsString(o);
+    }
+
+    @Test
+    void post_users_success_returns201_andCreatedVo() throws Exception {
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(buildReq())))
+                .andExpect(status().isCreated())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data.userId").isNumber())
+                .andExpect(jsonPath("$.data.username").value("newbie"))
+                .andExpect(jsonPath("$.data.userCode").value("U010"));
+    }
+
+    @Test
+    void post_users_blankUsername_returns400_40001() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setUsername("");
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void post_users_invalidUserType_returns400_40001() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setUserType("ROOT");
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void post_users_unknownPropertyPassword_returns400_40001() throws Exception {
+        ObjectNode body = json.valueToTree(buildReq());
+        body.put("password", "Password1!");
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body.toString()))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void post_users_noAuthHeader_returns401_40101() throws Exception {
+        mvc.perform(post("/api/v1/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(buildReq())))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void post_users_normalUserToken_returns403_40301() throws Exception {
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + normalToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(buildReq())))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN));
+    }
+
+    @Test
+    void post_users_deletedUserToken_returns401_40101() throws Exception {
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + deletedToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(buildReq())))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void post_users_duplicateUsername_returns409_40901() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setUsername(LoginTestSeeder.USER_OK);
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isConflict())
+                .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERNAME));
+    }
+
+    @Test
+    void post_users_duplicateUserCode_returns409_40902() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setUserCode("U001");
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isConflict())
+                .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERCODE));
+    }
+
+    @Test
+    void post_users_unknownEmployee_returns400_40004() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setEmployeeId(99999);
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND));
+    }
+
+    @Test
+    void post_users_unknownPermissionCategory_returns400_40004() throws Exception {
+        CreateUserReq r = buildReq();
+        r.setPermissionCategoryIds(List.of(99999));
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND));
+    }
+
+    @Test
+    void post_users_success_canLoginWithInitialPassword() throws Exception {
+        // 1) admin 创建用户
+        mvc.perform(post("/api/v1/users")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(buildReq())))
+                .andExpect(status().isCreated());
+
+        // 2) 新用户用初始密码 666666 登录应成功
+        LoginReq login = new LoginReq();
+        login.setUsername("newbie");
+        login.setPassword("666666");
+        login.setCompanyCode(LoginTestSeeder.COMPANY_OK);
+        mvc.perform(post("/api/v1/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(login)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data.accessToken").isNotEmpty());
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.security.JwtUtil;
+import com.xly.erp.module.usr.dto.UpdateUserReq;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.http.MediaType;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class UserControllerUpdateTest {
+
+    @Autowired private MockMvc mvc;
+    @Autowired private ObjectMapper json;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private JwtUtil jwtUtil;
+    @Autowired private SysUserPermissionCategoryMapper upcMapper;
+    @Autowired private com.xly.erp.module.usr.mapper.SysUserMapper userMapper;
+
+    private LoginTestSeeder.Fixture fx;
+    private String adminToken;
+    private String normalToken;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+        adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN", fx.adminId());
+        normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL", fx.aliceId());
+    }
+
+    private String issue(String username, String userType, Integer userId) {
+        Map<String, Object> c = new HashMap<>();
+        c.put("sub", userId);
+        c.put("username", username);
+        c.put("userType", userType);
+        c.put("companyCode", LoginTestSeeder.COMPANY_OK);
+        c.put("language", "zh-CN");
+        return jwtUtil.issue(c, 7200);
+    }
+
+    // ===== GET =====
+
+    @Test
+    void get_existingUser_returns200_andFullVo() throws Exception {
+        mvc.perform(get("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(ErrorCode.OK))
+                .andExpect(jsonPath("$.data.userId").value(fx.aliceId()))
+                .andExpect(jsonPath("$.data.username").value(LoginTestSeeder.USER_OK))
+                .andExpect(jsonPath("$.data.employeeName").value("张三"));
+    }
+
+    @Test
+    void get_unknownUser_returns404_40401() throws Exception {
+        mvc.perform(get("/api/v1/users/99999")
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.code").value(ErrorCode.USER_NOT_FOUND));
+    }
+
+    @Test
+    void get_normalUser_returns403_40301() throws Exception {
+        mvc.perform(get("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + normalToken))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN));
+    }
+
+    @Test
+    void get_noAuthHeader_returns401_40101() throws Exception {
+        mvc.perform(get("/api/v1/users/" + fx.aliceId()))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void get_deletedUser_stillReturns200() throws Exception {
+        mvc.perform(get("/api/v1/users/" + fx.bobDeletedId())
+                        .header("Authorization", "Bearer " + adminToken))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.isDeleted").value(true));
+    }
+
+    // ===== PUT =====
+
+    private String body(Object o) throws Exception {
+        return json.writeValueAsString(o);
+    }
+
+    private UpdateUserReq req() {
+        return new UpdateUserReq();
+    }
+
+    @Test
+    void put_updateUserCodeAndType_returns200() throws Exception {
+        UpdateUserReq r = req();
+        r.setUserCode("U_NEW");
+        r.setUserType("SUPER_ADMIN");
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.userCode").value("U_NEW"))
+                .andExpect(jsonPath("$.data.userType").value("SUPER_ADMIN"));
+    }
+
+    @Test
+    void put_updateEmployeeId_toAnotherEmployee_setsValue() throws Exception {
+        UpdateUserReq r = req();
+        r.setEmployeeId(fx.employeeId());
+        mvc.perform(put("/api/v1/users/" + fx.adminId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.employeeId").value(fx.employeeId()));
+    }
+
+    @Test
+    void put_updateEmployeeId_zero_clearsRelation() throws Exception {
+        UpdateUserReq r = req();
+        r.setEmployeeId(0);
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.employeeId").doesNotExist());
+    }
+
+    @Test
+    void put_updateEmployeeId_unknown_returns400_40004() throws Exception {
+        UpdateUserReq r = req();
+        r.setEmployeeId(99999);
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND));
+    }
+
+    @Test
+    void put_isDeletedTrue_marksAndOriginalTokenRejectedNextCall() throws Exception {
+        // 把 alice 设为作废
+        UpdateUserReq r = req();
+        r.setIsDeleted(true);
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk());
+
+        // 用 alice 的 token 调任何 /api/v1/** 接口应 40101
+        // 但 alice 是 NORMAL，连 admin 路径都会先 401（用户已作废），不是 403
+        mvc.perform(get("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + normalToken))
+                .andExpect(status().isUnauthorized())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS));
+    }
+
+    @Test
+    void put_permissionCategories_subsetDelta() throws Exception {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        Integer sal = fx.activePermissionCategoryIds().get(1);
+        // 预置 alice 有 {pur, sal}
+        for (Integer pcId : List.of(pur, sal)) {
+            SysUserPermissionCategory l = new SysUserPermissionCategory();
+            l.setIUserId(fx.aliceId());
+            l.setIPermissionCategoryId(pcId);
+            l.setSGrantedBy("system");
+            upcMapper.insert(l);
+        }
+
+        UpdateUserReq r = req();
+        r.setPermissionCategoryIds(List.of(sal));  // 只保留 sal
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.permissionCategoryIds.length()").value(1))
+                .andExpect(jsonPath("$.data.permissionCategoryIds[0]").value(sal));
+    }
+
+    @Test
+    void put_permissionCategories_emptyArray_clearsAll() throws Exception {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        SysUserPermissionCategory l = new SysUserPermissionCategory();
+        l.setIUserId(fx.aliceId());
+        l.setIPermissionCategoryId(pur);
+        l.setSGrantedBy("system");
+        upcMapper.insert(l);
+
+        UpdateUserReq r = req();
+        r.setPermissionCategoryIds(List.of());
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.permissionCategoryIds.length()").value(0));
+    }
+
+    @Test
+    void put_permissionCategories_unknownId_returns400_40004_andRollsBack() throws Exception {
+        UpdateUserReq r = req();
+        r.setUserCode("U_NEW");
+        r.setPermissionCategoryIds(List.of(99999));
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND));
+
+        // 验证回滚：alice 的 userCode 仍是 U001
+        com.xly.erp.module.usr.entity.SysUser db = userMapper.selectById(fx.aliceId());
+        org.junit.jupiter.api.Assertions.assertEquals("U001", db.getSUserCode());
+    }
+
+    @Test
+    void put_duplicateUserCode_returns409_40902() throws Exception {
+        UpdateUserReq r = req();
+        r.setUserCode("U001"); // alice 的 userCode
+        mvc.perform(put("/api/v1/users/" + fx.adminId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isConflict())
+                .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERCODE));
+    }
+
+    @Test
+    void put_userCodeUnchangedSameAsSelf_returns200() throws Exception {
+        UpdateUserReq r = req();
+        r.setUserCode("U001"); // alice 的当前 userCode
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isOk());
+    }
+
+    @Test
+    void put_selfDeactivate_returns403_40302() throws Exception {
+        UpdateUserReq r = req();
+        r.setIsDeleted(true);
+        mvc.perform(put("/api/v1/users/" + fx.adminId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(r)))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE));
+    }
+
+    @Test
+    void put_unknownProperty_username_returns400_40001() throws Exception {
+        ObjectNode b = json.createObjectNode();
+        b.put("username", "hacker");
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(b.toString()))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void put_unknownProperty_password_returns400_40001() throws Exception {
+        ObjectNode b = json.createObjectNode();
+        b.put("password", "newpass");
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(b.toString()))
+                .andExpect(status().isBadRequest())
+                .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST));
+    }
+
+    @Test
+    void put_unknownUserId_returns404_40401() throws Exception {
+        mvc.perform(put("/api/v1/users/99999")
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(req())))
+                .andExpect(status().isNotFound())
+                .andExpect(jsonPath("$.code").value(ErrorCode.USER_NOT_FOUND));
+    }
+
+    @Test
+    void put_normalUser_returns403_40301() throws Exception {
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + normalToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body(req())))
+                .andExpect(status().isForbidden())
+                .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN));
+    }
+
+    @Test
+    void put_emptyBody_only_updates_audit_fields() throws Exception {
+        mvc.perform(put("/api/v1/users/" + fx.aliceId())
+                        .header("Authorization", "Bearer " + adminToken)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.updatedBy").value(LoginTestSeeder.USER_ADMIN));
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validation;
+import jakarta.validation.Validator;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class CreateUserReqValidationTest {
+
+    private static final Validator VALIDATOR =
+            Validation.buildDefaultValidatorFactory().getValidator();
+
+    private CreateUserReq build() {
+        CreateUserReq r = new CreateUserReq();
+        r.setUsername("alice2");
+        r.setUserCode("U010");
+        r.setUserType("NORMAL");
+        r.setLanguage("zh-CN");
+        r.setCanEditDocument(false);
+        return r;
+    }
+
+    @Test
+    void allRequired_passes() {
+        Set<ConstraintViolation<CreateUserReq>> v = VALIDATOR.validate(build());
+        assertTrue(v.isEmpty());
+    }
+
+    @Test
+    void blankUsername_fails() {
+        CreateUserReq r = build();
+        r.setUsername("");
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void usernameTooShort_fails() {
+        CreateUserReq r = build();
+        r.setUsername("ab");
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void usernameWithIllegalChar_fails() {
+        CreateUserReq r = build();
+        r.setUsername("al ice");
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void userCodeTooLong_fails() {
+        CreateUserReq r = build();
+        r.setUserCode("X".repeat(51));
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void userTypeNotEnum_fails() {
+        CreateUserReq r = build();
+        r.setUserType("ROOT");
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void languageNotEnum_fails() {
+        CreateUserReq r = build();
+        r.setLanguage("ja-JP");
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void canEditDocumentMissing_fails() {
+        CreateUserReq r = build();
+        r.setCanEditDocument(null);
+        assertFalse(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void employeeIdNull_isAllowed() {
+        CreateUserReq r = build();
+        r.setEmployeeId(null);
+        assertTrue(VALIDATOR.validate(r).isEmpty());
+    }
+
+    @Test
+    void permissionCategoryIdsEmpty_isAllowed() {
+        CreateUserReq r = build();
+        r.setPermissionCategoryIds(List.of());
+        assertTrue(VALIDATOR.validate(r).isEmpty());
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validation;
+import jakarta.validation.Validator;
+import jakarta.validation.ValidatorFactory;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class LoginReqValidationTest {
+
+    private static final Validator VALIDATOR =
+            Validation.buildDefaultValidatorFactory().getValidator();
+
+    private LoginReq build(String u, String p, String c) {
+        LoginReq r = new LoginReq();
+        r.setUsername(u);
+        r.setPassword(p);
+        r.setCompanyCode(c);
+        return r;
+    }
+
+    @Test
+    void blankUsername_fails() {
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build("", "Password1!", "HQ"));
+        assertFalse(v.isEmpty());
+        assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("username")));
+    }
+
+    @Test
+    void blankPassword_fails() {
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build("alice", "", "HQ"));
+        assertFalse(v.isEmpty());
+        assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("password")));
+    }
+
+    @Test
+    void blankCompanyCode_fails() {
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build("alice", "Password1!", ""));
+        assertFalse(v.isEmpty());
+        assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("companyCode")));
+    }
+
+    @Test
+    void tooLongUsername_fails() {
+        String tooLong = "a".repeat(51);
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build(tooLong, "Password1!", "HQ"));
+        assertFalse(v.isEmpty());
+    }
+
+    @Test
+    void tooLongPassword_fails() {
+        String tooLong = "a".repeat(129);
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build("alice", tooLong, "HQ"));
+        assertFalse(v.isEmpty());
+    }
+
+    @Test
+    void allFieldsPresent_passes() {
+        Set<ConstraintViolation<LoginReq>> v = VALIDATOR.validate(build("alice", "Password1!", "HQ"));
+        assertTrue(v.isEmpty());
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.Validation;
+import jakarta.validation.Validator;
+import org.junit.jupiter.api.Test;
+
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class UpdateUserReqValidationTest {
+
+    private static final Validator V =
+            Validation.buildDefaultValidatorFactory().getValidator();
+
+    @Test
+    void emptyBody_isValid() {
+        assertTrue(V.validate(new UpdateUserReq()).isEmpty());
+    }
+
+    @Test
+    void invalidUserType_fails() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setUserType("ROOT");
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void invalidLanguage_fails() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setLanguage("ja-JP");
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void userCodeTooLong_fails() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setUserCode("X".repeat(51));
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void userCodeBlank_fails() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setUserCode("   ");
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void employeeIdNegative_fails() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setEmployeeId(-1);
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void employeeIdZero_isValid_meansUnsetRelation() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setEmployeeId(0);
+        assertTrue(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void allValidFields_passes() {
+        UpdateUserReq r = new UpdateUserReq();
+        r.setUserCode("U999");
+        r.setUserType("NORMAL");
+        r.setLanguage("zh-CN");
+        r.setCanEditDocument(true);
+        r.setEmployeeId(7);
+        r.setIsDeleted(false);
+        r.setPermissionCategoryIds(java.util.List.of(1, 2));
+        Set<ConstraintViolation<UpdateUserReq>> v = V.validate(r);
+        assertTrue(v.isEmpty(), () -> "should be empty but got: " + v);
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.Validation;
+import jakarta.validation.Validator;
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class UserQueryReqValidationTest {
+
+    private static final Validator V =
+            Validation.buildDefaultValidatorFactory().getValidator();
+
+    @Test
+    void emptyReq_isValid() {
+        assertTrue(V.validate(new UserQueryReq()).isEmpty());
+    }
+
+    @Test
+    void pageZero_fails() {
+        UserQueryReq r = new UserQueryReq();
+        r.setPage(0);
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void sizeOver100_fails() {
+        UserQueryReq r = new UserQueryReq();
+        r.setSize(101);
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void sizeZero_fails() {
+        UserQueryReq r = new UserQueryReq();
+        r.setSize(0);
+        assertFalse(V.validate(r).isEmpty());
+    }
+
+    @Test
+    void allValidFields_passes() {
+        UserQueryReq r = new UserQueryReq();
+        r.setPage(2);
+        r.setSize(50);
+        r.setSortField("tCreateDate");
+        r.setSortOrder("asc");
+        r.setQueryField("username");
+        r.setMatchMode("contains");
+        r.setQueryValue("ali");
+        r.setUserType("NORMAL");
+        r.setIsDeleted(false);
+        assertTrue(V.validate(r).isEmpty());
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class SysPermissionCategoryMapperTest {
+
+    @Autowired private SysPermissionCategoryMapper mapper;
+    @Autowired private LoginTestSeeder seeder;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    @Test
+    void countActiveByIds_returnsAllActive() {
+        int n = mapper.countActiveByIds(fx.activePermissionCategoryIds());
+        assertEquals(fx.activePermissionCategoryIds().size(), n);
+    }
+
+    @Test
+    void countActiveByIds_excludesDeleted() {
+        List<Integer> mixed = new ArrayList<>(fx.activePermissionCategoryIds());
+        mixed.add(fx.deletedPermissionCategoryId());
+        int n = mapper.countActiveByIds(mixed);
+        assertEquals(fx.activePermissionCategoryIds().size(), n,
+                "已软删的分类不应计入");
+    }
+
+    @Test
+    void countActiveByIds_excludesUnknown() {
+        List<Integer> mixed = new ArrayList<>(fx.activePermissionCategoryIds());
+        mixed.add(99999);
+        int n = mapper.countActiveByIds(mixed);
+        assertEquals(fx.activePermissionCategoryIds().size(), n);
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class SysUserMapperQueryTest {
+
+    @Autowired private SysUserMapper mapper;
+    @Autowired private LoginTestSeeder seeder;
+
+    @BeforeEach
+    void setUp() {
+        seeder.reset();
+    }
+
+    private UserQueryParams baseParams() {
+        UserQueryParams p = new UserQueryParams();
+        p.sqlSortField = "tCreateDate";
+        p.sqlSortOrder = "desc";
+        p.matchMode = "contains";
+        p.offset = 0;
+        p.limit = 100;
+        return p;
+    }
+
+    @Test
+    void count_noFilters_returnsAllRows() {
+        long total = mapper.countByQuery(baseParams());
+        // seeder 插入 alice + admin + bob_deleted = 3 行
+        assertEquals(3, total);
+    }
+
+    @Test
+    void select_withSortByUsername_ascending() {
+        UserQueryParams p = baseParams();
+        p.sqlSortField = "sUsername";
+        p.sqlSortOrder = "asc";
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(3, rows.size());
+        // 期望升序：admin / alice / bob_deleted
+        assertEquals(LoginTestSeeder.USER_ADMIN, rows.get(0).getUsername());
+        assertEquals(LoginTestSeeder.USER_OK, rows.get(1).getUsername());
+        assertEquals(LoginTestSeeder.USER_DELETED, rows.get(2).getUsername());
+    }
+
+    @Test
+    void select_withQueryFieldUsername_contains() {
+        UserQueryParams p = baseParams();
+        p.sqlQueryColumn = "u.sUsername";
+        p.matchMode = "contains";
+        p.queryValue = "ali";
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(1, rows.size());
+        assertEquals(LoginTestSeeder.USER_OK, rows.get(0).getUsername());
+    }
+
+    @Test
+    void select_joinsEmployeeAndDepartment_returnsBothNames() {
+        UserQueryParams p = baseParams();
+        p.sqlQueryColumn = "u.sUsername";
+        p.matchMode = "equals";
+        p.queryValue = LoginTestSeeder.USER_OK;
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(1, rows.size());
+        assertEquals("张三", rows.get(0).getEmployeeName());
+        assertEquals("技术部", rows.get(0).getDepartmentName());
+    }
+
+    @Test
+    void select_withIsDeletedFilter_returnsOnlyMatching() {
+        UserQueryParams p = baseParams();
+        p.isDeleted = 1;
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(1, rows.size());
+        assertEquals(LoginTestSeeder.USER_DELETED, rows.get(0).getUsername());
+    }
+
+    @Test
+    void select_withUserTypeFilter_returnsOnlyAdmin() {
+        UserQueryParams p = baseParams();
+        p.userType = "SUPER_ADMIN";
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(1, rows.size());
+        assertEquals(LoginTestSeeder.USER_ADMIN, rows.get(0).getUsername());
+    }
+
+    @Test
+    void select_pagination_limitsResults() {
+        UserQueryParams p = baseParams();
+        p.limit = 2;
+        List<UserListItemVo> rows = mapper.selectByQuery(p);
+        assertEquals(2, rows.size());
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class SysUserMapperTest {
+
+    @Autowired
+    private SysUserMapper userMapper;
+
+    @Autowired
+    private LoginTestSeeder seeder;
+
+    @BeforeEach
+    void setUp() {
+        seeder.reset();
+    }
+
+    @Test
+    void selectByUsername_returnsUserWithAllFields() {
+        SysUser user = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertNotNull(user);
+        assertEquals(LoginTestSeeder.USER_OK, user.getSUsername());
+        assertEquals("U001", user.getSUserCode());
+        assertNotNull(user.getSPasswordHash());
+        assertEquals("NORMAL", user.getSUserType());
+        assertEquals("zh-CN", user.getSLanguage());
+        assertEquals(0, user.getIIsDeleted());
+        assertEquals(0, user.getIFailedLoginCount());
+    }
+
+    @Test
+    void selectByUsername_returnsNullWhenNotFound() {
+        SysUser user = userMapper.selectByUsername("nobody");
+        assertNull(user);
+    }
+
+    @Test
+    void existsByUsername_trueForExisting() {
+        assertTrue(userMapper.existsByUsername(LoginTestSeeder.USER_OK));
+    }
+
+    @Test
+    void existsByUsername_falseForUnknown() {
+        assertFalse(userMapper.existsByUsername("nobody"));
+    }
+
+    @Test
+    void existsByUserCode_trueForExisting() {
+        assertTrue(userMapper.existsByUserCode("U001"));
+    }
+
+    @Test
+    void existsByUserCode_falseForUnknown() {
+        assertFalse(userMapper.existsByUserCode("UXXX"));
+    }
+
+    @Test
+    void existsByUserCodeExcludingId_otherUserHasCode_returnsTrue() {
+        // alice has U001 / admin has U000；查 U001 排除 admin → 找到 alice → true
+        assertTrue(userMapper.existsByUserCodeExcludingId("U001",
+                seeder.reset().adminId()));
+    }
+
+    @Test
+    void existsByUserCodeExcludingId_selfHasCode_returnsFalse() {
+        LoginTestSeeder.Fixture f = seeder.reset();
+        // 查 alice 的 userCode 排除 alice 本身 → false
+        assertFalse(userMapper.existsByUserCodeExcludingId("U001", f.aliceId()));
+    }
+
+    @Test
+    void existsByUserCodeExcludingId_unknownCode_returnsFalse() {
+        assertFalse(userMapper.existsByUserCodeExcludingId("UXXX", 1));
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class SysUserPermissionCategoryMapperTest {
+
+    @Autowired private SysUserPermissionCategoryMapper mapper;
+    @Autowired private LoginTestSeeder seeder;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+        // 给 alice 授权两个活跃分类
+        for (Integer pcId : fx.activePermissionCategoryIds()) {
+            SysUserPermissionCategory link = new SysUserPermissionCategory();
+            link.setIUserId(fx.aliceId());
+            link.setIPermissionCategoryId(pcId);
+            link.setSGrantedBy("system");
+            mapper.insert(link);
+        }
+    }
+
+    @Test
+    void selectPermissionCategoryIdsByUserId_returnsAllCurrent() {
+        List<Integer> ids = mapper.selectPermissionCategoryIdsByUserId(fx.aliceId());
+        assertEquals(fx.activePermissionCategoryIds().size(), ids.size());
+        assertTrue(ids.containsAll(fx.activePermissionCategoryIds()));
+    }
+
+    @Test
+    void selectPermissionCategoryIdsByUserId_emptyForNoGrants() {
+        List<Integer> ids = mapper.selectPermissionCategoryIdsByUserId(fx.adminId());
+        assertTrue(ids.isEmpty());
+    }
+
+    @Test
+    void deleteByUserAndCategoryIds_onlyDeletesGivenSubset() {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        int rows = mapper.deleteByUserAndCategoryIds(fx.aliceId(), List.of(pur));
+        assertEquals(1, rows);
+
+        List<Integer> remaining = mapper.selectPermissionCategoryIdsByUserId(fx.aliceId());
+        assertEquals(fx.activePermissionCategoryIds().size() - 1, remaining.size());
+        assertFalse(remaining.contains(pur));
+    }
+
+    @Test
+    void deleteByUserAndCategoryIds_nonMatchingIds_returns0() {
+        int rows = mapper.deleteByUserAndCategoryIds(fx.aliceId(), List.of(99999));
+        assertEquals(0, rows);
+    }
+
+    @Test
+    void deleteByUserAndCategoryIds_doesNotAffectOtherUser() {
+        // 给 admin 也授权一条
+        SysUserPermissionCategory link = new SysUserPermissionCategory();
+        link.setIUserId(fx.adminId());
+        link.setIPermissionCategoryId(fx.activePermissionCategoryIds().get(0));
+        link.setSGrantedBy("system");
+        mapper.insert(link);
+
+        // 删 alice 的某个分类不应影响 admin
+        mapper.deleteByUserAndCategoryIds(fx.aliceId(),
+                List.of(fx.activePermissionCategoryIds().get(0)));
+
+        assertEquals(1, mapper.selectPermissionCategoryIdsByUserId(fx.adminId()).size());
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.security.JwtUtil;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.LoginVo;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.time.LocalDateTime;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class LoginServiceImplTest {
+
+    @Autowired private LoginService loginService;
+    @Autowired private SysUserMapper userMapper;
+    @Autowired private JdbcTemplate jdbc;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private JwtUtil jwtUtil;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    @Test
+    void contextLoads_loginServiceBean() {
+        assertNotNull(loginService);
+    }
+
+    // ===== Task 7: company validation =====
+
+    @Test
+    void login_unknownCompany_throws40004() {
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, "NOPE"));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(0, u.getIFailedLoginCount(), "公司校验失败不应累加用户失败次数");
+    }
+
+    @Test
+    void login_softDeletedCompany_throws40004() {
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                        LoginTestSeeder.COMPANY_DELETED));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+    }
+
+    // ===== Task 8: bad credentials =====
+
+    @Test
+    void login_unknownUser_throws40101_noDbWrite() {
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login("nobody", "any", LoginTestSeeder.COMPANY_OK));
+        assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode());
+    }
+
+    @Test
+    void login_badPassword_throws40101_andIncrementsFailCount() {
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK));
+        assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode());
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(1, u.getIFailedLoginCount());
+    }
+
+    // ===== Task 9: locking =====
+
+    @Test
+    void login_5thBadPassword_setsLockUntil_andStillReturns40101() {
+        for (int i = 0; i < 4; i++) {
+            assertThrows(BizException.class,
+                    () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK));
+        }
+        SysUser before5 = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(4, before5.getIFailedLoginCount());
+        assertNull(before5.getTLockUntil());
+
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK));
+        assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode(),
+                "第 5 次错误仍返 40101（不暴露阈值）");
+
+        SysUser after5 = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(5, after5.getIFailedLoginCount());
+        assertNotNull(after5.getTLockUntil(), "第 5 次错误应设置锁定截止");
+        assertTrue(after5.getTLockUntil().isAfter(LocalDateTime.now().plusMinutes(29)),
+                "锁定时长应 ~30 分钟");
+    }
+
+    @Test
+    void login_duringLockWindow_throws42301_noCountIncrement() {
+        jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?",
+                LoginTestSeeder.USER_OK);
+
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                        LoginTestSeeder.COMPANY_OK));
+        assertEquals(ErrorCode.ACCOUNT_LOCKED, e.getCode());
+
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(5, u.getIFailedLoginCount(), "锁定期间任何登录尝试不应改变计数");
+    }
+
+    @Test
+    void login_afterLockExpired_allowsNewAttempt() {
+        jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_SUB(NOW(), INTERVAL 1 MINUTE) WHERE sUsername=?",
+                LoginTestSeeder.USER_OK);
+
+        LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                LoginTestSeeder.COMPANY_OK);
+        assertNotNull(vo.getAccessToken());
+
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(0, u.getIFailedLoginCount(), "锁定过期 + 成功登录应清零");
+        assertNull(u.getTLockUntil(), "成功登录应清空 tLockUntil");
+    }
+
+    // ===== Task 10: deleted + success =====
+
+    @Test
+    void login_deletedUser_throws40103_noCountIncrement() {
+        BizException e = assertThrows(BizException.class,
+                () -> loginService.login(LoginTestSeeder.USER_DELETED, LoginTestSeeder.DEFAULT_PASSWORD,
+                        LoginTestSeeder.COMPANY_OK));
+        assertEquals(ErrorCode.ACCOUNT_DELETED, e.getCode());
+
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_DELETED);
+        assertEquals(0, u.getIFailedLoginCount());
+    }
+
+    @Test
+    void login_success_returnsTokenAndClearsFailCount_andUpdatesLastLogin() {
+        jdbc.update("UPDATE sys_user SET iFailedLoginCount=2 WHERE sUsername=?", LoginTestSeeder.USER_OK);
+
+        LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                LoginTestSeeder.COMPANY_OK);
+
+        assertNotNull(vo);
+        assertNotNull(vo.getAccessToken());
+        assertEquals("Bearer", vo.getTokenType());
+        assertEquals(7200L, vo.getExpiresInSec());
+        assertNotNull(vo.getUserInfo());
+        assertEquals(LoginTestSeeder.USER_OK, vo.getUserInfo().getUsername());
+        assertEquals("NORMAL", vo.getUserInfo().getUserType());
+        assertEquals("zh-CN", vo.getUserInfo().getLanguage());
+        assertEquals(LoginTestSeeder.COMPANY_OK, vo.getUserInfo().getCompanyCode());
+        assertEquals("张三", vo.getUserInfo().getEmployeeName());
+
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(0, u.getIFailedLoginCount());
+        assertNull(u.getTLockUntil());
+        assertNotNull(u.getTLastLoginDate());
+    }
+
+    @Test
+    void login_concurrentBadPassword_atomicallyIncrementsCount() throws Exception {
+        // 2 线程并发各跑 2 次错误密码 → 计数累加必须 == 4（低于 5 不触发锁定，
+        // 专注验证原子性。锁定路径在 login_5thBadPassword_* 单线程测试中验证）
+        int perThread = 2;
+        int threadCount = 2;
+        Thread t1 = new Thread(() -> {
+            for (int i = 0; i < perThread; i++) {
+                try {
+                    loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK);
+                } catch (BizException ignored) {}
+            }
+        });
+        Thread t2 = new Thread(() -> {
+            for (int i = 0; i < perThread; i++) {
+                try {
+                    loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK);
+                } catch (BizException ignored) {}
+            }
+        });
+        t1.start(); t2.start();
+        t1.join(); t2.join();
+
+        SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK);
+        assertEquals(perThread * threadCount, u.getIFailedLoginCount(),
+                "并发失败累加必须 == 总次数（原子 UPDATE 保证；非原子实现会丢失累加）");
+        assertNull(u.getTLockUntil(), "总次数低于阈值不应触发锁定");
+    }
+
+    @Test
+    void login_success_jwtParsesBack_with_sub_username_companyCode() {
+        LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD,
+                LoginTestSeeder.COMPANY_OK);
+        Map<String, Object> claims = jwtUtil.parse(vo.getAccessToken());
+        assertEquals(String.valueOf(fx.aliceId()), claims.get("sub"));
+        assertEquals(LoginTestSeeder.USER_OK, claims.get("username"));
+        assertEquals(LoginTestSeeder.COMPANY_OK, claims.get("companyCode"));
+        assertEquals("NORMAL", claims.get("userType"));
+        assertEquals("zh-CN", claims.get("language"));
+        assertNotNull(claims.get("jti"));
+        long iat = ((Number) claims.get("iat")).longValue();
+        long exp = ((Number) claims.get("exp")).longValue();
+        assertEquals(7200L, exp - iat, "exp - iat 必须 == TOKEN_TTL_SEC");
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.CreateUserReq;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.CreateUserVo;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class UserCreateServiceImplTest {
+
+    @Autowired private UserCreateService service;
+    @Autowired private SysUserMapper userMapper;
+    @Autowired private SysUserPermissionCategoryMapper upcMapper;
+    @Autowired private BCryptPasswordEncoder encoder;
+    @Autowired private LoginTestSeeder seeder;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    private CreateUserReq buildReq(String username, String userCode) {
+        CreateUserReq r = new CreateUserReq();
+        r.setUsername(username);
+        r.setUserCode(userCode);
+        r.setUserType("NORMAL");
+        r.setLanguage("zh-CN");
+        r.setCanEditDocument(false);
+        return r;
+    }
+
+    // ===== 唯一性 / 外键校验（Task 7） =====
+
+    @Test
+    void create_usernameExists_throws40901() {
+        CreateUserReq r = buildReq(LoginTestSeeder.USER_OK, "U999");
+        BizException e = assertThrows(BizException.class, () -> service.create(r, "admin"));
+        assertEquals(ErrorCode.CONFLICT_USERNAME, e.getCode());
+    }
+
+    @Test
+    void create_userCodeExists_throws40902() {
+        CreateUserReq r = buildReq("brandnew", "U001");
+        BizException e = assertThrows(BizException.class, () -> service.create(r, "admin"));
+        assertEquals(ErrorCode.CONFLICT_USERCODE, e.getCode());
+    }
+
+    @Test
+    void create_employeeIdNotFound_throws40004() {
+        CreateUserReq r = buildReq("brandnew", "U999");
+        r.setEmployeeId(99999);
+        BizException e = assertThrows(BizException.class, () -> service.create(r, "admin"));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+    }
+
+    @Test
+    void create_permissionCategoryNotFound_throws40004() {
+        CreateUserReq r = buildReq("brandnew", "U999");
+        List<Integer> bad = new java.util.ArrayList<>(fx.activePermissionCategoryIds());
+        bad.add(99999);
+        r.setPermissionCategoryIds(bad);
+        BizException e = assertThrows(BizException.class, () -> service.create(r, "admin"));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+    }
+
+    @Test
+    void create_permissionCategorySoftDeleted_throws40004() {
+        CreateUserReq r = buildReq("brandnew", "U999");
+        r.setPermissionCategoryIds(List.of(fx.deletedPermissionCategoryId()));
+        BizException e = assertThrows(BizException.class, () -> service.create(r, "admin"));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+    }
+
+    // ===== 写入路径（Task 8） =====
+
+    @Test
+    void create_minimalFields_persistsUserWithInitialPassword() {
+        CreateUserReq r = buildReq("newbie", "U010");
+        CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN);
+
+        assertNotNull(vo.getUserId());
+        assertEquals("newbie", vo.getUsername());
+        assertEquals("U010", vo.getUserCode());
+
+        SysUser db = userMapper.selectByUsername("newbie");
+        assertNotNull(db);
+        assertEquals("NORMAL", db.getSUserType());
+        assertEquals("zh-CN", db.getSLanguage());
+        assertEquals(0, db.getICanEditDocument());
+        assertEquals(0, db.getIIsDeleted());
+        assertEquals(0, db.getIFailedLoginCount());
+        assertTrue(encoder.matches("666666", db.getSPasswordHash()),
+                "初始密码必须 BCrypt 哈希为 666666");
+    }
+
+    @Test
+    void create_fullFields_persistsUserAndPermissionMappings() {
+        CreateUserReq r = buildReq("manager", "U020");
+        r.setUserType("SUPER_ADMIN");
+        r.setLanguage("en-US");
+        r.setCanEditDocument(true);
+        r.setEmployeeId(fx.employeeId());
+        r.setPermissionCategoryIds(fx.activePermissionCategoryIds());
+
+        CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN);
+
+        SysUser db = userMapper.selectByUsername("manager");
+        assertNotNull(db);
+        assertEquals("SUPER_ADMIN", db.getSUserType());
+        assertEquals("en-US", db.getSLanguage());
+        assertEquals(1, db.getICanEditDocument());
+        assertEquals(fx.employeeId(), db.getIEmployeeId());
+
+        List<SysUserPermissionCategory> links = upcMapper.selectList(
+                new LambdaQueryWrapper<SysUserPermissionCategory>()
+                        .eq(SysUserPermissionCategory::getIUserId, vo.getUserId()));
+        assertEquals(fx.activePermissionCategoryIds().size(), links.size());
+        for (SysUserPermissionCategory link : links) {
+            assertEquals(LoginTestSeeder.USER_ADMIN, link.getSGrantedBy());
+        }
+    }
+
+    @Test
+    void create_emptyPermissionCategories_persistsUserOnly() {
+        CreateUserReq r = buildReq("solo", "U030");
+        r.setPermissionCategoryIds(List.of());
+        CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN);
+
+        SysUser db = userMapper.selectByUsername("solo");
+        assertNotNull(db);
+
+        List<SysUserPermissionCategory> links = upcMapper.selectList(
+                new LambdaQueryWrapper<SysUserPermissionCategory>()
+                        .eq(SysUserPermissionCategory::getIUserId, vo.getUserId()));
+        assertTrue(links.isEmpty());
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class UserDetailServiceImplTest {
+
+    @Autowired private UserDetailService service;
+    @Autowired private LoginTestSeeder seeder;
+    @Autowired private SysUserPermissionCategoryMapper upcMapper;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    @Test
+    void getById_existingActiveUser_returnsFullVo() {
+        // 给 alice 加 2 个权限分类授权
+        for (Integer pcId : fx.activePermissionCategoryIds()) {
+            SysUserPermissionCategory link = new SysUserPermissionCategory();
+            link.setIUserId(fx.aliceId());
+            link.setIPermissionCategoryId(pcId);
+            link.setSGrantedBy("system");
+            upcMapper.insert(link);
+        }
+
+        UserDetailVo vo = service.getById(fx.aliceId());
+        assertEquals(fx.aliceId(), vo.getUserId());
+        assertEquals(LoginTestSeeder.USER_OK, vo.getUsername());
+        assertEquals("U001", vo.getUserCode());
+        assertEquals("NORMAL", vo.getUserType());
+        assertEquals("zh-CN", vo.getLanguage());
+        assertEquals(false, vo.getCanEditDocument());
+        assertEquals(false, vo.getIsDeleted());
+        assertEquals(fx.employeeId(), vo.getEmployeeId());
+        assertEquals("张三", vo.getEmployeeName());
+        assertEquals(2, vo.getPermissionCategoryIds().size());
+    }
+
+    @Test
+    void getById_userWithoutEmployee_employeeNameIsNull() {
+        UserDetailVo vo = service.getById(fx.adminId());
+        assertNull(vo.getEmployeeId());
+        assertNull(vo.getEmployeeName());
+    }
+
+    @Test
+    void getById_userWithoutPermissions_emptyList() {
+        UserDetailVo vo = service.getById(fx.aliceId());
+        assertNotNull(vo.getPermissionCategoryIds());
+        assertTrue(vo.getPermissionCategoryIds().isEmpty());
+    }
+
+    @Test
+    void getById_deletedUser_stillReturned() {
+        UserDetailVo vo = service.getById(fx.bobDeletedId());
+        assertEquals(LoginTestSeeder.USER_DELETED, vo.getUsername());
+        assertEquals(true, vo.getIsDeleted());
+    }
+
+    @Test
+    void getById_unknownId_throws40401() {
+        BizException e = assertThrows(BizException.class, () -> service.getById(99999));
+        assertEquals(ErrorCode.USER_NOT_FOUND, e.getCode());
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.module.usr.dto.UserQueryReq;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.UserListItemVo;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class UserListServiceImplTest {
+
+    @Autowired private UserListService service;
+    @Autowired private LoginTestSeeder seeder;
+
+    @BeforeEach
+    void setUp() {
+        seeder.reset();
+    }
+
+    private UserQueryReq req() {
+        return new UserQueryReq();
+    }
+
+    @Test
+    void list_default_returnsAllUsers() {
+        PageResult<UserListItemVo> result = service.list(req());
+        assertEquals(3, result.getTotal());
+        assertEquals(3, result.getRecords().size());
+        assertEquals(1, result.getPage());
+        assertEquals(20, result.getSize());
+    }
+
+    @Test
+    void list_sortByUsernameAsc() {
+        UserQueryReq r = req();
+        r.setSortField("sUsername");
+        r.setSortOrder("asc");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(LoginTestSeeder.USER_ADMIN, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_sortFieldInvalid_throws40003() {
+        UserQueryReq r = req();
+        r.setSortField("badField");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode());
+    }
+
+    @Test
+    void list_sortOrderInvalid_throws40001() {
+        UserQueryReq r = req();
+        r.setSortOrder("foo");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.BAD_REQUEST, e.getCode());
+    }
+
+    @Test
+    void list_queryFieldInvalid_throws40003() {
+        UserQueryReq r = req();
+        r.setQueryField("badField");
+        r.setQueryValue("x");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode());
+    }
+
+    @Test
+    void list_matchModeInvalid_throws40003() {
+        UserQueryReq r = req();
+        r.setMatchMode("startsWith");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode());
+    }
+
+    @Test
+    void list_queryByUsernameContains() {
+        UserQueryReq r = req();
+        r.setQueryField("username");
+        r.setMatchMode("contains");
+        r.setQueryValue("ali");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(1, result.getTotal());
+        assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_queryByEmployeeName_joinsCorrectly() {
+        UserQueryReq r = req();
+        r.setQueryField("employeeName");
+        r.setMatchMode("contains");
+        r.setQueryValue("张");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(1, result.getTotal());
+        assertEquals("张三", result.getRecords().get(0).getEmployeeName());
+    }
+
+    @Test
+    void list_queryByDepartmentName_multiLevelJoin() {
+        UserQueryReq r = req();
+        r.setQueryField("departmentName");
+        r.setMatchMode("equals");
+        r.setQueryValue("技术部");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(1, result.getTotal());
+        assertEquals("技术部", result.getRecords().get(0).getDepartmentName());
+    }
+
+    @Test
+    void list_queryByIsDeleted_true_returnsDeleted() {
+        UserQueryReq r = req();
+        r.setQueryField("isDeleted");
+        r.setMatchMode("equals");
+        r.setQueryValue("true");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(1, result.getTotal());
+        assertEquals(LoginTestSeeder.USER_DELETED, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_queryByIsDeleted_invalidValue_throws40001() {
+        UserQueryReq r = req();
+        r.setQueryField("isDeleted");
+        r.setQueryValue("maybe");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.BAD_REQUEST, e.getCode());
+    }
+
+    @Test
+    void list_queryFieldWithoutValue_skipsCondition() {
+        UserQueryReq r = req();
+        r.setQueryField("username");
+        // no queryValue
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(3, result.getTotal());
+    }
+
+    @Test
+    void list_explicitUserTypeFilter() {
+        UserQueryReq r = req();
+        r.setUserType("NORMAL");
+        PageResult<UserListItemVo> result = service.list(r);
+        // alice (NORMAL active) + bob_deleted (NORMAL deleted) = 2
+        assertEquals(2, result.getTotal());
+    }
+
+    @Test
+    void list_explicitUserTypeInvalid_throws40001() {
+        UserQueryReq r = req();
+        r.setUserType("HACKER");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.BAD_REQUEST, e.getCode());
+    }
+
+    @Test
+    void list_explicitIsDeletedFalse_filtersActive() {
+        UserQueryReq r = req();
+        r.setIsDeleted(false);
+        PageResult<UserListItemVo> result = service.list(r);
+        // alice + admin
+        assertEquals(2, result.getTotal());
+    }
+
+    @Test
+    void list_composedFilters_andSemantics() {
+        UserQueryReq r = req();
+        r.setQueryField("username");
+        r.setQueryValue("a");
+        r.setUserType("NORMAL");
+        r.setIsDeleted(false);
+        PageResult<UserListItemVo> result = service.list(r);
+        // alice 是唯一 NORMAL + 启用 + 名字含 a 的
+        assertEquals(1, result.getTotal());
+        assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_pageBeyondTotal_returnsLastPage() {
+        UserQueryReq r = req();
+        r.setPage(999);
+        r.setSize(10);
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(3, result.getTotal());
+        assertFalse(result.getRecords().isEmpty(), "越界应返回最后一页数据");
+        assertEquals(1, result.getPage(), "actualPage 应矫正为最后一页 (3/10 → 1)");
+    }
+
+    @Test
+    void list_queryByIsDeleted_matchModeContains_isForcedToEquals() {
+        // spec § 业务规则 3：isDeleted matchMode 强制 equals
+        UserQueryReq r = req();
+        r.setQueryField("isDeleted");
+        r.setMatchMode("contains");
+        r.setQueryValue("true");
+        PageResult<UserListItemVo> result = service.list(r);
+        // 应该等同于 equals true → 仅 bob_deleted
+        assertEquals(1, result.getTotal());
+        assertEquals(LoginTestSeeder.USER_DELETED, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_queryByLastLoginDate_matchModeContains_isForcedToEquals_andDateNormalized() {
+        // 给 alice 写一个明确的 lastLoginDate
+        jdbc.update("UPDATE sys_user SET tLastLoginDate='2026-05-15 10:00:00' WHERE sUsername=?",
+                LoginTestSeeder.USER_OK);
+
+        UserQueryReq r = req();
+        r.setQueryField("lastLoginDate");
+        r.setMatchMode("contains");
+        r.setQueryValue("2026-05-15 10:00:00");
+        PageResult<UserListItemVo> result = service.list(r);
+        assertEquals(1, result.getTotal());
+        assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername());
+    }
+
+    @Test
+    void list_queryByLastLoginDate_invalidValue_throws40001() {
+        UserQueryReq r = req();
+        r.setQueryField("lastLoginDate");
+        r.setQueryValue("not-a-date");
+        BizException e = assertThrows(BizException.class, () -> service.list(r));
+        assertEquals(ErrorCode.BAD_REQUEST, e.getCode());
+    }
+
+    @org.springframework.beans.factory.annotation.Autowired
+    private org.springframework.jdbc.core.JdbcTemplate jdbc;
+
+    @Test
+    void list_responseDoesNotIncludePasswordField() {
+        PageResult<UserListItemVo> result = service.list(req());
+        UserListItemVo vo = result.getRecords().get(0);
+        // UserListItemVo 不应有 password 相关字段——通过反射验证
+        for (java.lang.reflect.Field f : vo.getClass().getDeclaredFields()) {
+            assertFalse(f.getName().toLowerCase().contains("password"),
+                    "VO 字段不应含 password: " + f.getName());
+        }
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.UpdateUserReq;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.entity.SysUserPermissionCategory;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper;
+import com.xly.erp.module.usr.support.LoginTestSeeder;
+import com.xly.erp.module.usr.vo.UserDetailVo;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class UserUpdateServiceImplTest {
+
+    @Autowired private UserUpdateService service;
+    @Autowired private SysUserMapper userMapper;
+    @Autowired private SysUserPermissionCategoryMapper upcMapper;
+    @Autowired private LoginTestSeeder seeder;
+
+    private LoginTestSeeder.Fixture fx;
+
+    @BeforeEach
+    void setUp() {
+        fx = seeder.reset();
+    }
+
+    private UpdateUserReq req() {
+        return new UpdateUserReq();
+    }
+
+    // ===== 校验路径（Task 6） =====
+
+    @Test
+    void update_unknownUserId_throws40401() {
+        BizException e = assertThrows(BizException.class,
+                () -> service.update(99999, req(), fx.adminId(), LoginTestSeeder.USER_ADMIN));
+        assertEquals(ErrorCode.USER_NOT_FOUND, e.getCode());
+    }
+
+    @Test
+    void update_selfDeactivate_throws40302() {
+        UpdateUserReq r = req();
+        r.setIsDeleted(true);
+        BizException e = assertThrows(BizException.class,
+                () -> service.update(fx.adminId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN));
+        assertEquals(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE, e.getCode());
+    }
+
+    @Test
+    void update_userCodeConflict_throws40902() {
+        UpdateUserReq r = req();
+        r.setUserCode("U001"); // alice's code
+        BizException e = assertThrows(BizException.class,
+                () -> service.update(fx.adminId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN));
+        assertEquals(ErrorCode.CONFLICT_USERCODE, e.getCode());
+    }
+
+    @Test
+    void update_employeeIdNotFound_throws40004() {
+        UpdateUserReq r = req();
+        r.setEmployeeId(99999);
+        BizException e = assertThrows(BizException.class,
+                () -> service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+    }
+
+    @Test
+    void update_permissionCategoryNotFound_throws40004_rollsBack() {
+        UpdateUserReq r = req();
+        r.setUserCode("U_NEW");
+        r.setPermissionCategoryIds(List.of(99999));
+        BizException e = assertThrows(BizException.class,
+                () -> service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN));
+        assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode());
+        // 回滚：sys_user.sUserCode 不应被改
+        SysUser after = userMapper.selectById(fx.aliceId());
+        assertEquals("U001", after.getSUserCode());
+    }
+
+    // ===== 字段写入（Task 7） =====
+
+    @Test
+    void update_userCode_only_persisted_otherFieldsUnchanged() {
+        UpdateUserReq r = req();
+        r.setUserCode("U_NEW");
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertEquals("U_NEW", db.getSUserCode());
+        assertEquals(LoginTestSeeder.USER_OK, db.getSUsername(), "用户名不变");
+        assertEquals(LoginTestSeeder.USER_ADMIN, db.getSUpdatedBy());
+        assertNotNull(db.getTUpdatedDate());
+    }
+
+    @Test
+    void update_userType_language_canEditDocument() {
+        UpdateUserReq r = req();
+        r.setUserType("SUPER_ADMIN");
+        r.setLanguage("en-US");
+        r.setCanEditDocument(true);
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertEquals("SUPER_ADMIN", db.getSUserType());
+        assertEquals("en-US", db.getSLanguage());
+        assertEquals(1, db.getICanEditDocument());
+    }
+
+    @Test
+    void update_employeeId_positiveInteger_setsToValue() {
+        UpdateUserReq r = req();
+        r.setEmployeeId(fx.employeeId());
+        service.update(fx.adminId(), r, fx.adminId() + 1000, LoginTestSeeder.USER_ADMIN);
+        // operatorUserId 不等于 adminId 才能避开自我停用守卫（本测试未触发，但保持参数有效）
+        SysUser db = userMapper.selectById(fx.adminId());
+        assertEquals(fx.employeeId(), db.getIEmployeeId());
+    }
+
+    @Test
+    void update_employeeId_zero_setsToNull() {
+        UpdateUserReq r = req();
+        r.setEmployeeId(0);
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertNull(db.getIEmployeeId());
+    }
+
+    @Test
+    void update_employeeId_unchanged_preservesOriginalValue() {
+        UpdateUserReq r = req();
+        // 不设 employeeId
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertEquals(fx.employeeId(), db.getIEmployeeId());
+    }
+
+    @Test
+    void update_isDeleted_true_marksUserDeleted() {
+        UpdateUserReq r = req();
+        r.setIsDeleted(true);
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertEquals(1, db.getIIsDeleted());
+    }
+
+    @Test
+    void update_isDeleted_false_revivesUser() {
+        UpdateUserReq r = req();
+        r.setIsDeleted(false);
+        service.update(fx.bobDeletedId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        SysUser db = userMapper.selectById(fx.bobDeletedId());
+        assertEquals(0, db.getIIsDeleted());
+    }
+
+    @Test
+    void update_emptyRequest_onlyUpdatesAuditFields() {
+        service.update(fx.aliceId(), req(), fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        SysUser db = userMapper.selectById(fx.aliceId());
+        assertEquals(LoginTestSeeder.USER_ADMIN, db.getSUpdatedBy());
+        assertNotNull(db.getTUpdatedDate());
+        // 其他字段不变
+        assertEquals("U001", db.getSUserCode());
+        assertEquals("NORMAL", db.getSUserType());
+    }
+
+    @Test
+    void update_userCodeUnchangedSameAsSelf_returns200() {
+        UpdateUserReq r = req();
+        r.setUserCode("U001"); // alice 自己当前的 userCode
+        UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        assertEquals("U001", vo.getUserCode());
+    }
+
+    // ===== 权限分类增量差集（Task 8） =====
+
+    @Test
+    void update_permissionCategories_emptyList_clearsAll() {
+        // 先给 alice 加 2 个
+        for (Integer pcId : fx.activePermissionCategoryIds()) {
+            SysUserPermissionCategory l = new SysUserPermissionCategory();
+            l.setIUserId(fx.aliceId());
+            l.setIPermissionCategoryId(pcId);
+            l.setSGrantedBy("system");
+            upcMapper.insert(l);
+        }
+        UpdateUserReq r = req();
+        r.setPermissionCategoryIds(List.of());
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        assertTrue(upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()).isEmpty());
+    }
+
+    @org.springframework.beans.factory.annotation.Autowired
+    private com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper permissionCategoryMapper;
+
+    @Test
+    void update_permissionCategories_subsetDelta_addsAndRemoves() {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        Integer sal = fx.activePermissionCategoryIds().get(1);
+        // 初始：alice = {PUR, SAL}
+        for (Integer pcId : List.of(pur, sal)) {
+            SysUserPermissionCategory l = new SysUserPermissionCategory();
+            l.setIUserId(fx.aliceId());
+            l.setIPermissionCategoryId(pcId);
+            l.setSGrantedBy("system");
+            upcMapper.insert(l);
+        }
+        Integer salRowId = upcMapper.selectList(
+                new com.baomidou.mybatisplus.core.conditions.query.QueryWrapper<SysUserPermissionCategory>()
+                        .eq("iUserId", fx.aliceId())
+                        .eq("iPermissionCategoryId", sal))
+                .get(0).getIIncrement();
+
+        // 新增分类 X（活跃）
+        com.xly.erp.module.usr.entity.SysPermissionCategory x =
+                new com.xly.erp.module.usr.entity.SysPermissionCategory();
+        x.setSCategoryName("X");
+        x.setSCategoryCode("X");
+        x.setISortOrder(99);
+        x.setIIsDeleted(0);
+        permissionCategoryMapper.insert(x);
+
+        UpdateUserReq r = req();
+        r.setPermissionCategoryIds(List.of(sal, x.getIIncrement()));
+        UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        // 最终 alice 应有 {SAL, X}
+        Set<Integer> finalSet = new HashSet<>(
+                upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()));
+        assertEquals(Set.of(sal, x.getIIncrement()), finalSet);
+
+        // SAL 行 iIncrement 不变（差集而非全量替换）
+        Integer salRowIdAfter = upcMapper.selectList(
+                new com.baomidou.mybatisplus.core.conditions.query.QueryWrapper<SysUserPermissionCategory>()
+                        .eq("iUserId", fx.aliceId())
+                        .eq("iPermissionCategoryId", sal))
+                .get(0).getIIncrement();
+        assertEquals(salRowId, salRowIdAfter, "保留项的 iIncrement 应不变");
+    }
+
+    @Test
+    void update_permissionCategories_omitted_preservesExisting() {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        SysUserPermissionCategory l = new SysUserPermissionCategory();
+        l.setIUserId(fx.aliceId());
+        l.setIPermissionCategoryId(pur);
+        l.setSGrantedBy("system");
+        upcMapper.insert(l);
+
+        // 请求不含 permissionCategoryIds
+        UpdateUserReq r = req();
+        r.setUserCode("U_NEW");
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        assertEquals(1, upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()).size());
+    }
+
+    @Test
+    void update_permissionCategories_duplicateInRequest_deduped() {
+        Integer pur = fx.activePermissionCategoryIds().get(0);
+        Integer sal = fx.activePermissionCategoryIds().get(1);
+        UpdateUserReq r = req();
+        r.setPermissionCategoryIds(new ArrayList<>(List.of(pur, pur, sal)));
+        service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+
+        Set<Integer> finalSet = new HashSet<>(
+                upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()));
+        assertEquals(Set.of(pur, sal), finalSet);
+    }
+
+    @Test
+    void update_returnsUserDetailVoReflectingFinalState() {
+        UpdateUserReq r = req();
+        r.setUserType("SUPER_ADMIN");
+        r.setLanguage("en-US");
+        UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN);
+        assertEquals("SUPER_ADMIN", vo.getUserType());
+        assertEquals("en-US", vo.getLanguage());
+        assertEquals(LoginTestSeeder.USER_ADMIN, vo.getUpdatedBy());
+        assertNotNull(vo.getUpdatedDate());
+    }
+}
+package com.xly.erp.module.usr.support;
+
+import com.xly.erp.module.usr.entity.SysCompany;
+import com.xly.erp.module.usr.entity.SysEmployee;
+import com.xly.erp.module.usr.entity.SysPermissionCategory;
+import com.xly.erp.module.usr.entity.SysUser;
+import com.xly.erp.module.usr.mapper.SysCompanyMapper;
+import com.xly.erp.module.usr.mapper.SysEmployeeMapper;
+import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.SysUserMapper;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+/**
+ * 测试数据种子。在每个集成测试 @BeforeEach 调用 reset()。
+ *
+ * 默认账号：
+ *   - alice  / Password1! / 启用 / NORMAL / 关联员工"张三"
+ *   - admin  / Password1! / 启用 / SUPER_ADMIN
+ *   - bob_deleted / Password1! / 作废（iIsDeleted=1）
+ *
+ * 默认公司：HQ（启用）/ DEL_CO（软删）。
+ * 默认权限分类：PUR-采购管理 / SAL-销售管理（启用）/ HR-人事（软删）。
+ */
+@Component
+public class LoginTestSeeder {
+
+    public static final String DEFAULT_PASSWORD = "Password1!";
+    public static final String COMPANY_OK = "HQ";
+    public static final String COMPANY_DELETED = "DEL_CO";
+    public static final String USER_OK = "alice";
+    public static final String USER_ADMIN = "admin";
+    public static final String USER_DELETED = "bob_deleted";
+    public static final String PERMISSION_CATEGORY_PUR = "PUR";
+    public static final String PERMISSION_CATEGORY_SAL = "SAL";
+    public static final String PERMISSION_CATEGORY_HR_DELETED = "HR";
+
+    private final JdbcTemplate jdbc;
+    private final SysCompanyMapper companyMapper;
+    private final SysEmployeeMapper employeeMapper;
+    private final SysUserMapper userMapper;
+    private final SysPermissionCategoryMapper permissionCategoryMapper;
+    private final BCryptPasswordEncoder encoder;
+
+    @Autowired
+    public LoginTestSeeder(JdbcTemplate jdbc,
+                           SysCompanyMapper companyMapper,
+                           SysEmployeeMapper employeeMapper,
+                           SysUserMapper userMapper,
+                           SysPermissionCategoryMapper permissionCategoryMapper,
+                           BCryptPasswordEncoder encoder) {
+        this.jdbc = jdbc;
+        this.companyMapper = companyMapper;
+        this.employeeMapper = employeeMapper;
+        this.userMapper = userMapper;
+        this.permissionCategoryMapper = permissionCategoryMapper;
+        this.encoder = encoder;
+    }
+
+    @Transactional
+    public Fixture reset() {
+        jdbc.update("DELETE FROM sys_user_permission_category");
+        jdbc.update("DELETE FROM sys_user");
+        jdbc.update("DELETE FROM sys_permission_category");
+        jdbc.update("DELETE FROM sys_employee");
+        jdbc.update("DELETE FROM sys_department");
+        jdbc.update("DELETE FROM sys_company");
+
+        SysCompany hq = new SysCompany();
+        hq.setSCompanyCode(COMPANY_OK);
+        hq.setSCompanyName("总部");
+        hq.setIIsDeleted(0);
+        companyMapper.insert(hq);
+
+        SysCompany del = new SysCompany();
+        del.setSCompanyCode(COMPANY_DELETED);
+        del.setSCompanyName("已删公司");
+        del.setIIsDeleted(1);
+        companyMapper.insert(del);
+
+        jdbc.update("INSERT INTO sys_department (sDepartmentName, sDepartmentCode, iIsDeleted) VALUES (?,?,0)",
+                "技术部", "TECH");
+        Integer deptId = jdbc.queryForObject(
+                "SELECT iIncrement FROM sys_department WHERE sDepartmentCode='TECH'",
+                Integer.class);
+
+        SysEmployee emp = new SysEmployee();
+        emp.setSEmployeeName("张三");
+        emp.setSEmployeeCode("E001");
+        emp.setIDepartmentId(deptId);
+        emp.setIIsDeleted(0);
+        employeeMapper.insert(emp);
+
+        String hash = encoder.encode(DEFAULT_PASSWORD);
+
+        SysUser alice = new SysUser();
+        alice.setSUsername(USER_OK);
+        alice.setSUserCode("U001");
+        alice.setSPasswordHash(hash);
+        alice.setIEmployeeId(emp.getIIncrement());
+        alice.setSUserType("NORMAL");
+        alice.setSLanguage("zh-CN");
+        alice.setICanEditDocument(0);
+        alice.setIIsDeleted(0);
+        alice.setIFailedLoginCount(0);
+        alice.setSCreatedBy("system");
+        userMapper.insert(alice);
+
+        SysUser admin = new SysUser();
+        admin.setSUsername(USER_ADMIN);
+        admin.setSUserCode("U000");
+        admin.setSPasswordHash(hash);
+        admin.setSUserType("SUPER_ADMIN");
+        admin.setSLanguage("zh-CN");
+        admin.setICanEditDocument(1);
+        admin.setIIsDeleted(0);
+        admin.setIFailedLoginCount(0);
+        admin.setSCreatedBy("system");
+        userMapper.insert(admin);
+
+        SysUser bob = new SysUser();
+        bob.setSUsername(USER_DELETED);
+        bob.setSUserCode("U002");
+        bob.setSPasswordHash(hash);
+        bob.setSUserType("NORMAL");
+        bob.setSLanguage("zh-CN");
+        bob.setICanEditDocument(0);
+        bob.setIIsDeleted(1);
+        bob.setIFailedLoginCount(0);
+        bob.setSCreatedBy("system");
+        userMapper.insert(bob);
+
+        SysPermissionCategory pur = new SysPermissionCategory();
+        pur.setSCategoryCode(PERMISSION_CATEGORY_PUR);
+        pur.setSCategoryName("采购管理");
+        pur.setISortOrder(1);
+        pur.setIIsDeleted(0);
+        permissionCategoryMapper.insert(pur);
+
+        SysPermissionCategory sal = new SysPermissionCategory();
+        sal.setSCategoryCode(PERMISSION_CATEGORY_SAL);
+        sal.setSCategoryName("销售管理");
+        sal.setISortOrder(2);
+        sal.setIIsDeleted(0);
+        permissionCategoryMapper.insert(sal);
+
+        SysPermissionCategory hrDel = new SysPermissionCategory();
+        hrDel.setSCategoryCode(PERMISSION_CATEGORY_HR_DELETED);
+        hrDel.setSCategoryName("人事（已删）");
+        hrDel.setISortOrder(3);
+        hrDel.setIIsDeleted(1);
+        permissionCategoryMapper.insert(hrDel);
+
+        return new Fixture(
+                alice.getIIncrement(),
+                admin.getIIncrement(),
+                bob.getIIncrement(),
+                emp.getIIncrement(),
+                List.of(pur.getIIncrement(), sal.getIIncrement()),
+                hrDel.getIIncrement());
+    }
+
+    public record Fixture(
+            Integer aliceId,
+            Integer adminId,
+            Integer bobDeletedId,
+            Integer employeeId,
+            List<Integer> activePermissionCategoryIds,
+            Integer deletedPermissionCategoryId) {}
+}
 ### REQ-USR-001 用户登录
  
-
 **目标**: 用户通过用户名+密码完成身份认证，获取 JWT Token 用于后续接口鉴权
  
 - **输入**: 
@@ -11,12 +10,12 @@
    | --- | ---- | --- | ---- | ------- | ----- | --- | ----------- |
    | 用户名 | 文本 | 是   | 手工输入 | —       | —     | —   | —          |
    | 密码  | 文本 | 是   | 手工输入 | —       | —     | —   | 输入显示星号      |
-   | 版本  | 文本 | 是   | 下拉单选 | `公司表`   | 页面加载时 | 标准版 |             |
+   | 版本  | 文本 | 是   | 下拉单选 | `公司表`   | 页面加载时 | — |             |
  
 - **输出**: 成功/失败
  
 - **跨字段规则**: 校验用户名 + 密码哈希；连续失败达到阈值临时锁定账号；登录成功签发限时 token 并返回基本用户信息
 - **边界**: token 设置合理过期时间；接口需具备防暴力破解保护
 - **验收**: 正确凭据返回 Token 且可通过鉴权接口验证；错误密码返回通用错误消息（不区分用户名或密码错误）；锁定账号返回锁定提示
-- **依赖表**: `t_user`（认证主体 + 失败计数 + 锁定时间 + 登录时间）/ `t_company`（「版本」下拉数据源）
-- **依赖接口**: `POST /api/usr/auth/login`（本 REQ 提供）；后续配套 `POST /api/usr/auth/refresh`、`POST /api/usr/auth/logout` 由同模块衍生接口（不另立 REQ）
+- **依赖表**: `sys_user`(读: 校验账号 / 写: 更新 `iFailedLoginCount`、`tLockUntil`、`tLastLoginDate`), `sys_company`(读: 登录页"版本"下拉)
+- **依赖接口**: `POST /api/v1/auth/login`（本 REQ 提供）；`GET /api/v1/companies`（登录页公司下拉，后续运营模块提供）
@@ -37,5 +37,5 @@
 - **跨字段规则**: 用户名在系统内全局唯一；角色取值受系统配置约束
 - **边界**: 密码以哈希形式存储
 - **验收**: 提交合法数据后用户记录出现在列表；重复用户名返回错误提示；普通账号无权访问此功能
-- **依赖表**: `t_user`（新建主记录）/ `t_employee`（员工名下拉 + 关联）/ `t_permission`（权限分类下拉）/ `t_user_permission`（写入权限组关联）
-- **依赖接口**: `POST /api/usr/users`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001）获取 JWT
+- **依赖表**: `sys_user`(写: 新增账号), `sys_employee`(读: 关联职员下拉), `sys_permission_category`(读: 权限分类列表), `sys_user_permission_category`(写: 写入勾选授权)
+- **依赖接口**: `POST /api/v1/users`（本 REQ 提供）；下游调用：`GET /api/v1/employees`（员工下拉，后续 HR 模块提供）；`GET /api/v1/permission-categories`（权限分类下拉，后续运营模块提供）
@@ -36,5 +36,5 @@
 - **跨字段规则**: 密码不在该接口修改；角色变更需具备相应权限
 - **边界**: 必须传入有效用户 id；字段格式与新增一致
 - **验收**: 修改角色或状态后立即反映在用户列表；被禁用账号无法登录并收到明确提示
-- **依赖表**: `t_user`（更新主记录）/ `t_employee`（员工名下拉 + 关联）/ `t_permission`（权限分类下拉）/ `t_user_permission`（删旧 + 写新权限组关联）
-- **依赖接口**: `PUT /api/usr/users/{iIncrement}`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001）+ 数据来源 `POST /api/usr/users`（REQ-USR-002）
+- **依赖表**: `sys_user`(读 + 写: 更新非密码字段), `sys_employee`(读: 关联职员下拉), `sys_permission_category`(读: 权限分类列表), `sys_user_permission_category`(读 + 写: 增量增删授权差集)
+- **依赖接口**: `PUT /api/v1/users/{userId}`（本 REQ 提供）；`GET /api/v1/users/{userId}`（详情回显，可在本 REQ 实现或复用 REQ-USR-004 列表点击进入）；下游调用：`GET /api/v1/employees`、`GET /api/v1/permission-categories`（同 REQ-USR-002）
@@ -33,5 +33,5 @@
 - **跨字段规则**: -
 - **边界**: 单页最大条数受限（默认 100）；密码与敏感字段不返回；查询为只读，不产生写副作用
 - **验收**: 按条件筛选返回正确结果集；无匹配时返回空列表而非报错；分页参数越界时返回最后一页
-- **依赖表**: `t_user`（列表主表 + 类型 / 作废 / 登录日期 / 制单人）/ `t_employee`（员工名）/ `t_department`（部门）
-- **依赖接口**: `GET /api/usr/users`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001）
+- **依赖表**: `sys_user`(读: 分页 + 筛选), `sys_employee`(读: JOIN 取员工名), `sys_department`(读: JOIN 经 employee 取部门名)
+- **依赖接口**: `GET /api/v1/users`（本 REQ 提供）
 # USR-用户管理
  
-- **模块简述**: 提供用户全生命周期管理，含登录认证、新增、修改、查询等业务操作
-- **依赖模块**: —（基础模块）
-- **涉及表**: `t_user` / `t_employee` / `t_department` / `t_permission` / `t_user_permission` / `t_company`
+- **模块简述**: 用户管理模块负责用户账号的全生命周期管理，包括登录认证、新增 / 修改 / 查询用户、角色分配与账号启停
+- **依赖模块**: —（无）
+- **涉及表**: `sys_user`, `sys_employee`, `sys_department`, `sys_company`, `sys_permission_category`, `sys_user_permission_category`
@@ -4,7 +4,7 @@
  
 | 模块 ID | 模块名 | 依赖模块 | 依赖表 |
 |---|---|---|---|
-| module_usr | USR-用户管理 | — | `t_user` / `t_employee` / `t_department` / `t_permission` / `t_user_permission` / `t_company` |
+| module_usr | 用户管理 | — | `sys_user`, `sys_employee`, `sys_department`, `sys_company`, `sys_permission_category`, `sys_user_permission_category` |
  
 ## 二、开发顺序清单（CC 分发权威）
  
@@ -14,15 +14,16 @@
  
 | # | REQ | 所属模块 | 选中理由 | 备注 |
 |---|-----|---------|---------|------|
-| 1 | **REQ-USR-001** | module_usr | 所属模块无依赖，认证接口为基础设施（其余 REQ 接口需 JWT 鉴权） | — |
-| 2 | **REQ-USR-002** | module_usr | 依赖 REQ-USR-001 已在前；新增用户为后续修改 / 查询提供数据 | — |
-| 3 | **REQ-USR-003** | module_usr | 依赖 REQ-USR-002 已在前（先有用户才能修改） | — |
-| 4 | **REQ-USR-004** | module_usr | 依赖 REQ-USR-002 已在前（先有用户才能查询） | — |
+| 1 | **REQ-USR-001** | module_usr | 所属模块无依赖，登录是后续接口鉴权的基础 | — |
+| 2 | **REQ-USR-002** | module_usr | 同模块，无前置 REQ 依赖；用户创建是 003/004 的数据源 | — |
+| 3 | **REQ-USR-003** | module_usr | 同模块，逻辑上依赖 REQ-USR-002 已在前（修改基于已存在用户） | — |
+| 4 | **REQ-USR-004** | module_usr | 同模块，无前置 REQ 依赖；列表查询用 002/003 产生的数据更易自测 | — |
  
 > **后端模块全部 merged 后**：用户重跑 `/erp-workflow:coding-start` → coding-start 检测到 `backend_done=true && frontend_done=false` → 派发 `frontend-start`。`frontend-start` 步骤 1 自带 prototype/ 门禁（≥ 1 个 `*.html` mockup，缺失则 AskUserQuestion 提示用户补齐）。前端阶段以业务功能（不是 HTML 文件数）为粒度拆分 FE，每个 FE 跑一次 feature 循环（fe-feature-*），最后整个阶段合 1 个 MR（分支 `frontend-phase`，记录在 `docs/08 § 三 整体 MR`）。
  
 ## 三、关键说明
  
-- 本期需求只覆盖 USR 用户管理一个模块；后续若新增 PUR / SAL / FIN 等模块，需重新跑 `/erp-workflow:plan-start` 让 A5 重算依赖与顺序。
-- REQ-USR-001 排第一是「基础设施先行」策略：JWT 鉴权机制建好后，其余 REQ 才能复用 `@PreAuthorize` 与统一异常处理；初始管理员账号由 V1 后续的种子 migration 注入（或人工 SQL 直插）。
-- `t_employee` / `t_department` / `t_permission` / `t_company` 四张维表在 module_usr 内部按需访问，不另起模块；后续如演化出独立的 HR / 组织架构模块，再单独拆分。
+- 当前仅有 1 个业务模块 `module_usr`，无跨模块依赖，模块级 DAG 退化为单节点，无环。
+- REQ 内部依赖只有 003 → 002 一条边，按数字序天然满足，无需破环。
+- `sys_employee` / `sys_department` / `sys_company` / `sys_permission_category` 4 张参考字典已由 V1 建好但本模块**只读使用**，初始化数据由 B 阶段开发时通过 V2/V3 seed migration 或测试 fixture 补全（不在当前 4 个 REQ 范围内）。
+- 后端阶段所有任务限定在 `backend/module/usr/` 路径下；前端实现推迟到 `frontend-start` 派发的前端阶段，按 `prototype/*.html` 拆 FE。
@@ -12,7 +12,7 @@
 |---|---|---|---|---|
 | `iIncrement` | int | 否 | 是 | 整数主键 ID（自增方式由实现决定：DB `AUTO_INCREMENT` 或应用 / 触发器分配） |
 | `sId` | varchar(100) | 是 | — | 业务 ID（对外暴露的字符串标识，如 UUID / 人类可读编号） |
-| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离） |
+| `sBrandsId` | varchar(100) | 是 | — | 母公司 ID（多租户隔离） |
 | `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离） |
 | `tCreateDate` | datetime | 否 | — | 记录创建时间 |
  
@@ -20,24 +20,37 @@
  
 ## ER 关系概览
  
-USR 用户管理模块共 6 张表，围绕「用户」为核心：
+```
+sys_department  ◄──┐                                   sys_company（独立，登录页"版本"下拉）
+                   │
+                   │ N:1
+sys_employee  ─────┘
+     ▲
+     │ N:1 (可选, ON DELETE SET NULL)
+     │
+sys_user  ────────►  sys_user_permission_category  ◄──── sys_permission_category
+                            (用户 × 权限分类多对多, ON DELETE CASCADE)
+```
+
+- `sys_company`：登录页"版本"下拉来源；目前独立存在，不与 user 直接 FK，登录上下文记录公司选择即可。
+- `sys_department`：部门字典；被 `sys_employee` 引用。
+- `sys_employee`：职员档案；被 `sys_user` 通过 `iEmployeeId` 可选引用（员工先存在，用户后绑定）。
+- `sys_user`：用户账号（登录、权限、状态、登录追踪一体）。
+- `sys_permission_category`：权限分类字典（USR-002/003 表 2 "权限组"的来源）。
+- `sys_user_permission_category`：用户 × 权限分类多对多授权表，记录每个用户被授予哪些权限分类。
  
-- `t_user`（用户主表）通过 `iEmployeeId` 关联 `t_employee`（职员），实现「用户号 / 员工名」一对一联动。
-- `t_employee`（职员表）通过 `iDepartmentId` 关联 `t_department`（部门表），支撑 REQ-USR-004 按部门筛选。
-- `t_user` 与 `t_permission`（权限分类字典）通过 `t_user_permission`（用户-权限关联表）建立多对多关系，实现 REQ-USR-002 / 003 的「权限组」分配。
-- `t_company`（公司版本字典）独立于 `t_user`，仅为 REQ-USR-001 登录入参「版本」下拉提供可选项，不与用户产生强引用。
+## 表清单
  
-依赖方向：`t_user → t_employee → t_department`、`t_user ↔ t_permission`（多对多）、`t_company` 独立。
+- `sys_company` — 公司 / 版本字典，登录页下拉选择来源
+- `sys_department` — 部门字典，职员归属
+- `sys_employee` — 职员档案，员工基础信息
+- `sys_user` — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪）
+- `sys_permission_category` — 权限分类字典
+- `sys_user_permission_category` — 用户 × 权限分类授权关系
  
-## 表清单
-- `t_user` — 系统用户主表，承载登录认证、用户类型、语言偏好、单据权限等基础属性
-- `t_employee` — 公司职员主档，与用户表通过 `iEmployeeId` 关联，提供姓名 / 工号 / 部门归属
-- `t_department` — 部门组织树，支撑职员归属与按部门筛选
-- `t_permission` — 权限分类字典，定义系统可分配的权限项
-- `t_user_permission` — 用户-权限分类多对多关联表
-- `t_company` — 公司 / 版本字典（标准版 / 专业版 / 旗舰版），登录时「版本」下拉数据源
+---
  
-## `t_user` — 系统用户主表，承载登录认证与基础属性
+## `sys_company` — 公司 / 版本字典，登录页下拉选择来源
  
 ### 字段
  
@@ -48,38 +61,28 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `sUserNo` | varchar(50) | 否 | — | 用户号；关联职员后自动同步员工号；系统内唯一 |
-| `sUserName` | varchar(50) | 否 | — | 登录用户名；系统内唯一；3-50 位 |
-| `iEmployeeId` | int | 是 | NULL | 关联职员 `t_employee.iIncrement`；可空（非员工账号如系统管理员） |
-| `sPasswordHash` | varchar(255) | 否 | — | 密码哈希（BCrypt / Argon2）；禁止明文；初始密码 `666666` 哈希后存入 |
-| `sUserType` | varchar(20) | 否 | `NORMAL` | 用户类型枚举：`NORMAL`（普通用户）/ `SUPER_ADMIN`（超级管理员） |
-| `sLanguage` | varchar(10) | 否 | `zh-CN` | 语言枚举：`zh-CN`（中文）/ `en-US`（英文）/ `zh-TW`（繁体） |
-| `bModifyDoc` | tinyint(1) | 否 | 0 | 单据修改权限：0 否 / 1 是 |
-| `bVoid` | tinyint(1) | 否 | 0 | 作废标记（软删除）：0 启用 / 1 已作废 |
-| `iLoginFailCount` | int | 否 | 0 | 连续登录失败次数；达到阈值触发临时锁定；登录成功后清零 |
-| `tLockUntil` | datetime | 是 | NULL | 锁定截止时间；NULL 表示未锁定 |
-| `tLastLoginDate` | datetime | 是 | NULL | 最近一次登录时间 |
-| `sCreator` | varchar(100) | 是 | NULL | 制单人（创建该账号的操作员用户名） |
+| `sCompanyName` | varchar(100) | 否 | — | 公司 / 版本名称（登录页下拉显示文本） |
+| `sCompanyCode` | varchar(50) | 否 | — | 公司编码（前端唯一识别） |
+| `iSortOrder` | int | 否 | 0 | 下拉列表排序权重，升序 |
+| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记，0=正常 1=已删 |
  
 ### 索引
  
-- `uk_user_username` (UNIQUE): `sUserName`
-- `uk_user_userno` (UNIQUE): `sUserNo`
-- `idx_user_employee` (BTREE): `iEmployeeId`
-- `idx_user_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId`
-- `idx_user_void` (BTREE): `bVoid`
+- `pk_sys_company` (PRIMARY): `iIncrement`
+- `uk_sys_company_code` (UNIQUE): `sCompanyCode`
+- `idx_sys_company_is_deleted` (BTREE): `iIsDeleted, iSortOrder`
  
 ### 外键
  
-- `fk_user_employee`: `iEmployeeId` → `t_employee.iIncrement` (ON DELETE SET NULL / ON UPDATE RESTRICT)
+（无）
  
 ### 业务注记
  
-- 登录认证主体表；密码以哈希形式存储，登录失败计数与锁定时间均落库以保证服务重启不丢；亦可由 Redis 镜像加速，但 DB 字段为权威。
-- `bVoid = 1` 视为已作废账号，不可登录、不出现在默认查询结果中（REQ-USR-004 列表默认隐藏作废）。
-- 用户名 / 用户号唯一性由 `uk_user_username` / `uk_user_userno` 保证；新增 / 修改时若冲突由 DB 抛唯一约束错误，Service 转译为 `40001 用户名已存在`。
+REQ-USR-001 登录页 "版本" 字段下拉来源。当前与 `sys_user` 不直接 FK，登录会话记录用户选择的公司即可（避免单用户跨公司绑定的复杂度）。新增公司由后续运营模块管理；本模块阶段只读使用。
+
+---
  
-## `t_employee` — 公司职员主档
+## `sys_department` — 部门字典，职员归属
  
 ### 字段
  
@@ -90,30 +93,26 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `sEmployeeNo` | varchar(50) | 否 | — | 员工号；系统内唯一 |
-| `sName` | varchar(100) | 否 | — | 姓名 |
-| `iDepartmentId` | int | 是 | NULL | 部门 ID，关联 `t_department.iIncrement` |
-| `sPhone` | varchar(20) | 是 | NULL | 手机号 |
-| `sEmail` | varchar(100) | 是 | NULL | 邮箱 |
-| `bDisabled` | tinyint(1) | 否 | 0 | 是否离职：0 在职 / 1 离职 |
+| `sDepartmentName` | varchar(100) | 否 | — | 部门名称 |
+| `sDepartmentCode` | varchar(50) | 否 | — | 部门编码 |
+| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 |
  
 ### 索引
  
-- `uk_employee_no` (UNIQUE): `sEmployeeNo`
-- `idx_employee_dept` (BTREE): `iDepartmentId`
-- `idx_employee_name` (BTREE): `sName`
-- `idx_employee_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId`
+- `pk_sys_department` (PRIMARY): `iIncrement`
+- `uk_sys_department_code` (UNIQUE): `sDepartmentCode`
  
 ### 外键
  
-- `fk_employee_department`: `iDepartmentId` → `t_department.iIncrement` (ON DELETE SET NULL / ON UPDATE RESTRICT)
+（无）
  
 ### 业务注记
  
-- 用户表通过 `iEmployeeId` 关联本表；REQ-USR-002 / 003 选择员工时下拉数据源；REQ-USR-004 查询字段「员工名 / 部门」均联表本表。
-- 离职员工保留记录（`bDisabled = 1`），其关联用户应被自动作废（应用层逻辑，未做 DB 触发器）。
+REQ-USR-004 查询输出 "部门" 字段来源（经 `sys_employee` 关联）。本阶段是扁平字典，未来 HR 模块扩展时可加 `iParentId` 形成树状结构。
+
+---
  
-## `t_department` — 部门组织树
+## `sys_employee` — 职员档案，员工基础信息
  
 ### 字段
  
@@ -124,27 +123,31 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `sName` | varchar(100) | 否 | — | 部门名称 |
-| `sCode` | varchar(50) | 否 | — | 部门编码；系统内唯一 |
-| `iParentId` | int | 是 | NULL | 上级部门 ID，NULL 表示根部门 |
-| `iSortOrder` | int | 否 | 0 | 排序值，小者靠前 |
+| `sEmployeeName` | varchar(50) | 否 | — | 员工姓名（2-50 字符） |
+| `sEmployeeCode` | varchar(50) | 否 | — | 员工工号（系统内唯一） |
+| `iDepartmentId` | int | 否 | — | 所属部门 ID（FK → sys_department.iIncrement） |
+| `sPhone` | varchar(20) | 是 | NULL | 手机号 |
+| `sEmail` | varchar(100) | 是 | NULL | 邮箱 |
+| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 |
  
 ### 索引
  
-- `uk_department_code` (UNIQUE): `sCode`
-- `idx_department_parent` (BTREE): `iParentId`
-- `idx_department_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId`
+- `pk_sys_employee` (PRIMARY): `iIncrement`
+- `uk_sys_employee_code` (UNIQUE): `sEmployeeCode`
+- `idx_sys_employee_department` (BTREE): `iDepartmentId`
+- `idx_sys_employee_name` (BTREE): `sEmployeeName`
  
 ### 外键
  
-- `fk_department_parent`: `iParentId` → `t_department.iIncrement` (ON DELETE RESTRICT / ON UPDATE RESTRICT)
+- `fk_sys_employee_department`: `iDepartmentId` → `sys_department.iIncrement` (ON DELETE RESTRICT, ON UPDATE CASCADE)
  
 ### 业务注记
  
-- 自引用形成部门树，根部门 `iParentId IS NULL`。
-- 部门删除采用「拒绝删除有下级 / 有员工的部门」策略（应用层校验）；DB 外键 RESTRICT 兜底。
+REQ-USR-002 / 003 "员工名" 下拉来源；REQ-USR-004 "员工名" / "部门" 输出来源。`iDepartmentId` 用 RESTRICT 防止删除还有员工的部门。员工先于用户存在；同一员工可对应 0 或 1 个用户账号。
+
+---
  
-## `t_permission` — 权限分类字典
+## `sys_user` — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪）
  
 ### 字段
  
@@ -155,24 +158,46 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `sCode` | varchar(50) | 否 | — | 权限码，例如 `USR:ADD` / `USR:EDIT`；系统内唯一 |
-| `sName` | varchar(100) | 否 | — | 权限分类名称（展示用） |
-| `iSortOrder` | int | 否 | 0 | 同分类内排序 |
+| `sUsername` | varchar(50) | 否 | — | 用户名（登录凭据，系统内全局唯一，3-20 位字母数字下划线） |
+| `sUserCode` | varchar(50) | 否 | — | 用户号（业务展示用编码，系统内唯一） |
+| `sPasswordHash` | varchar(255) | 否 | — | 密码哈希（BCrypt / Argon2，禁明文） |
+| `iEmployeeId` | int | 是 | NULL | 关联职员 ID（可选；FK → sys_employee.iIncrement） |
+| `sUserType` | varchar(20) | 否 | `NORMAL` | 用户类型枚举：`NORMAL`=普通用户 / `SUPER_ADMIN`=超级管理员 |
+| `sLanguage` | varchar(10) | 否 | `zh-CN` | 语言：`zh-CN`=中文 / `en-US`=英文 / `zh-TW`=繁体 |
+| `iCanEditDocument` | tinyint(1) | 否 | 0 | 单据修改权限：0=否 1=是 |
+| `iIsDeleted` | tinyint(1) | 否 | 0 | 是否作废：0=启用 1=作废（停用） |
+| `iFailedLoginCount` | int | 否 | 0 | 累计登录失败次数，达阈值锁定，登录成功清零 |
+| `tLockUntil` | datetime | 是 | NULL | 锁定截止时间，NULL=未锁定，过期自动解锁 |
+| `tLastLoginDate` | datetime | 是 | NULL | 最后一次成功登录时间，REQ-USR-004 "登录日期" 来源 |
+| `sCreatedBy` | varchar(50) | 是 | NULL | 制单人（创建该用户的用户名），REQ-USR-002 "制单人" |
+| `sUpdatedBy` | varchar(50) | 是 | NULL | 最后修改人用户名 |
+| `tUpdatedDate` | datetime | 是 | NULL | 最后修改时间 |
  
 ### 索引
  
-- `uk_permission_code` (UNIQUE): `sCode`
+- `pk_sys_user` (PRIMARY): `iIncrement`
+- `uk_sys_user_username` (UNIQUE): `sUsername`
+- `uk_sys_user_code` (UNIQUE): `sUserCode`
+- `idx_sys_user_employee` (BTREE): `iEmployeeId`
+- `idx_sys_user_type` (BTREE): `sUserType`
+- `idx_sys_user_is_deleted` (BTREE): `iIsDeleted`
+- `idx_sys_user_created_by` (BTREE): `sCreatedBy`
  
 ### 外键
  
-- 无
+- `fk_sys_user_employee`: `iEmployeeId` → `sys_employee.iIncrement` (ON DELETE SET NULL, ON UPDATE CASCADE)
  
 ### 业务注记
  
-- 字典表，启动时由初始化脚本灌入；不允许业务删除，禁用通过软标记（暂未引入 `bVoid`，由 docs/01 补充时再加）。
-- 权限码格式 `<模块代码>:<动作>`，与后端 `@PreAuthorize('hasAuthority(...)')` 一一对应（docs/06 § 1.3）。
+USR 模块核心表。
+- **登录认证**（REQ-USR-001）：`sUsername` + `sPasswordHash` 验证；连续失败累加 `iFailedLoginCount`，达 5 次写 `tLockUntil = now() + 30 分钟`；登录成功清零 + 更新 `tLastLoginDate`。
+- **作废**（`iIsDeleted = 1`）：等价业务"停用"，登录直接拒绝。删除用户不物理删，避免 FK 联动；`uk_sys_user_username` 与作废态共存的可能由应用层处理（作废后用户名释放或保留按运营决定，本阶段保留唯一）。
+- **职员关联**（`iEmployeeId`）：可选；删除职员时此字段置 NULL（`ON DELETE SET NULL`），用户记录不丢。
+- **密码不在本接口修改**（REQ-USR-003 边界）：修改用户走非密码字段；密码重置走独立流程（后续 REQ 扩展）。
  
-## `t_user_permission` — 用户-权限分类关联表
+---
+
+## `sys_permission_category` — 权限分类字典
  
 ### 字段
  
@@ -183,26 +208,29 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `iUserId` | int | 否 | — | 用户 ID，关联 `t_user.iIncrement` |
-| `iPermissionId` | int | 否 | — | 权限分类 ID，关联 `t_permission.iIncrement` |
+| `sCategoryName` | varchar(100) | 否 | — | 权限分类名称（如 "采购管理" / "销售管理"） |
+| `sCategoryCode` | varchar(50) | 否 | — | 权限分类编码（系统内唯一，代码层引用） |
+| `sCategoryDesc` | varchar(255) | 是 | NULL | 分类说明 |
+| `iSortOrder` | int | 否 | 0 | 列表展示顺序 |
+| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 |
  
 ### 索引
  
-- `uk_user_perm` (UNIQUE): `iUserId`, `iPermissionId`
-- `idx_user_perm_perm` (BTREE): `iPermissionId`
+- `pk_sys_permission_category` (PRIMARY): `iIncrement`
+- `uk_sys_permission_category_code` (UNIQUE): `sCategoryCode`
+- `idx_sys_permission_category_sort` (BTREE): `iIsDeleted, iSortOrder`
  
 ### 外键
  
-- `fk_userperm_user`: `iUserId` → `t_user.iIncrement` (ON DELETE CASCADE / ON UPDATE RESTRICT)
-- `fk_userperm_perm`: `iPermissionId` → `t_permission.iIncrement` (ON DELETE RESTRICT / ON UPDATE RESTRICT)
+（无）
  
 ### 业务注记
  
-- 关联表豁免 `sBrandsId` / `sSubsidiaryId` 的业务语义但保留列以遵守项目标准；写入时复用 `t_user` 的对应租户标识。
-- 删除用户时级联清理本表行（`ON DELETE CASCADE`）；删除字典项保护已分配数据（`ON DELETE RESTRICT`）。
-- 唯一约束 `(iUserId, iPermissionId)` 确保同一用户对同一权限分类不重复授权。
+REQ-USR-002 / 003 表 2 "权限组" 的"权限分类"来源。本表是字典，分类条目由系统初始化或运营维护，**用户管理模块只读使用**。
+
+---
  
-## `t_company` — 公司 / 版本字典
+## `sys_user_permission_category` — 用户 × 权限分类授权关系
  
 ### 字段
  
@@ -213,18 +241,25 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心：
 | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） |
 | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） |
 | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） |
-| `sCode` | varchar(50) | 否 | — | 公司 / 版本编码；系统内唯一 |
-| `sName` | varchar(100) | 否 | — | 显示名称 |
+| `iUserId` | int | 否 | — | 用户 ID（FK → sys_user.iIncrement） |
+| `iPermissionCategoryId` | int | 否 | — | 权限分类 ID（FK → sys_permission_category.iIncrement） |
+| `sGrantedBy` | varchar(50) | 是 | NULL | 授予人用户名 |
  
 ### 索引
  
-- `uk_company_code` (UNIQUE): `sCode`
+- `pk_sys_user_permission_category` (PRIMARY): `iIncrement`
+- `uk_sys_user_permission_category` (UNIQUE): `iUserId, iPermissionCategoryId`
+- `idx_sys_user_permission_category_category` (BTREE): `iPermissionCategoryId`
  
 ### 外键
  
-- 无
+- `fk_sys_upc_user`: `iUserId` → `sys_user.iIncrement` (ON DELETE CASCADE, ON UPDATE CASCADE)
+- `fk_sys_upc_permission_category`: `iPermissionCategoryId` → `sys_permission_category.iIncrement` (ON DELETE CASCADE, ON UPDATE CASCADE)
  
 ### 业务注记
  
-- REQ-USR-001 登录入参「版本」下拉数据源；启动时由初始化脚本插入至少一行默认公司数据；具体「版本」字段语义待后续业务确认后再补列。
-- 当前 REQ 描述不足以确认与 `t_user` 是否需要强关联，故先做独立字典；后续如需「用户绑定公司 / 版本」再于 `t_user` 增列。
+记录每个用户被授予的权限分类清单。
+- REQ-USR-002 新增用户时，根据表 2 勾选生成本表对应行。
+- REQ-USR-003 修改用户时，重新计算差集做增量增删。
+- `ON DELETE CASCADE`：用户被物理删除时联动清理（注意：业务上用户作废不会物理删除，所以联动主要面向极端场景）；权限分类被物理删除时联动清理用户授权关系，避免悬挂。
+- 复合唯一键 `(iUserId, iPermissionCategoryId)` 保证同一用户同一分类只授权一次。
@@ -35,117 +35,138 @@
  
 ### 1.1 分层结构
  
+按 Spring Boot 3 + MyBatis-Plus 惯例分四层，每层职责单一：
+
 | 层 | 职责 |
 |---|---|
-| `controller/` | 接收 HTTP 请求、参数校验（`@Valid`）、调用 Service、组装响应；不写业务逻辑 |
-| `service/` | 业务编排、事务边界、跨 Mapper 调用；接口 + `impl/` 实现 |
-| `mapper/` | MyBatis-Plus 数据访问（Java 接口 + XML），仅做单表 CRUD 与简单关联查询 |
-| `entity/` | 与数据库表 1:1 的实体类，字段名/类型严格对齐 docs/03 |
-| `dto/` | 入参对象（前端 → 后端），含 `@NotNull` / `@Pattern` 等校验注解 |
-| `vo/` | 出参对象（后端 → 前端），由 MapStruct 从 Entity 转换 |
-| `config/` | Spring 配置类（Security / Redis / MyBatis-Plus / Swagger / Activiti） |
-| `common/` | 全局响应包装、统一异常处理器、拦截器、工具类 |
-| `security/` | JWT 生成 / 验证、`UserDetailsService` 实现、权限注解 |
+| `controller` | HTTP 入口；参数校验（`@Valid`）；调用 service；返回统一响应；**不写业务逻辑** |
+| `service` + `service/impl` | 业务编排；事务边界；调用一个或多个 mapper；DTO ↔ Entity 转换走 converter |
+| `mapper` + `resources/mapper/*.xml` | 单表 CRUD 走 MyBatis-Plus；复杂 SQL 写 XML；**不写业务逻辑** |
+| `entity` / `dto` / `vo` / `converter` | 数据传输层；converter 用 MapStruct 自动生成实现 |
  
 ### 1.2 命名约定
  
-- **包名**：全小写，单数。根包 `com.example.erp`。业务模块包 `<ROOT>.module.<模块代码小写>`（示例：`com.example.erp.module.usr`）。
-- **类名**：大驼峰；按层级加后缀（`UserController` / `UserServiceImpl` / `UserMapper` / `UserCreateDTO` / `UserListVO`）。
-- **方法名**：小驼峰；动词开头（`createUser` / `listUsers` / `disableUser`），与 REST 动作语义对齐。
-- **常量**：全大写下划线（`MAX_LOGIN_FAILS = 5`），放对应业务模块的 `constant/` 子包或公共 `common/constant/`。
-- **示例 1**：`com.example.erp.module.usr.controller.UserController#listUsers(UserQueryDTO)` 返回 `PageVO<UserListVO>`。
-- **示例 2**：`com.example.erp.module.usr.service.impl.UserServiceImpl#disableUser(Long id)` 写入 `t_user_audit_log` 审计。
+- **Java 包**：全小写。根包：`com.xly.erp`。业务模块：`module.<module_code_lower>`（与 docs/01 模块代码对齐）。
+- **类名**：大驼峰；后缀清晰标识层（`UserController` / `UserServiceImpl` / `UserMapper` / `UserEntity` / `CreateUserReq` / `UserVo` / `UserConverter`）。
+- **方法 / 字段**：小驼峰（`createUser` / `userName`）。
+- **常量**：全大写下划线（`MAX_LOGIN_ATTEMPTS`）。
+- **数据库表名**：小写下划线（`sys_user`）；字段名同样小写下划线（`created_at`）。
+
+**示例**：
+```java
+package com.xly.erp.module.usr.controller;
+
+@RestController
+@RequestMapping("/api/v1/users")
+public class UserController {
+    public Result<UserVo> createUser(@RequestBody @Valid CreateUserReq req) { ... }
+}
+```
  
 ### 1.3 统一响应格式
  
-后端所有 HTTP 接口返回 `Result<T>` 包装：
+所有 HTTP 接口返回 `Result<T>` / `PageResult<T>`：
  
 ```json
 // 成功
 { "code": 0, "message": "ok", "data": { ... } }
+
 // 失败
 { "code": 40001, "message": "用户名已存在", "data": null }
 ```
  
 错误码段位：
-
-| 段位 | 含义 |
-|---|---|
-| `0` | 成功 |
-| `1xxxx` | 系统级（参数校验、未授权、未登录） |
-| `2xxxx` | 通用业务错误（资源不存在、状态非法） |
-| `4xxxx` | 模块业务错误（按模块再分子段：USR=`40xxx`，PUR=`41xxx`...） |
-| `5xxxx` | 第三方 / 基础设施错误（DB / Redis / 外部服务） |
+- `0`：成功
+- `10xxx`：参数 / 校验类错误
+- `20xxx`：业务规则错误
+- `30xxx`：权限类错误
+- `40xxx`：资源类错误（找不到、冲突）
+- `50xxx`：服务器内部错误
+- `60xxx`：第三方依赖错误
  
 ### 1.4 异常处理
  
-- **全局异常处理器**：`@RestControllerAdvice` 统一捕获，转换为 `Result` 失败结构。
-- **必须 catch**：`MethodArgumentNotValidException`（参数校验）/ `BindException` / 业务自定义 `BizException` / `AccessDeniedException`。
-- **禁止 catch**：泛 `Exception` 在业务代码中吞掉；必须让全局处理器接管。
-- **接口响应禁止回显后端异常堆栈**：返回用户友好错误码 + 文案；堆栈仅写入 logback。
+- 全局异常处理器 `GlobalExceptionHandler`（`@RestControllerAdvice`）统一捕获并转 `Result.fail(...)`。
+- 业务异常用 `BizException(int code, String message)`，service 层抛出，全局处理器捕获后转响应。
+- **禁止**在 controller / service 里 `catch (Exception e) { e.printStackTrace(); }` 后吞掉。
+- **接口响应禁止回显后端异常堆栈**：仅返回 `code` + 用户友好 `message`；堆栈写日志（含 traceId）。
  
 ### 1.5 事务
  
-- **事务边界**：放在 Service 层方法上（`@Transactional`），Controller / Mapper 禁止开事务。
-- **传播策略**：默认 `REQUIRED`；只读查询用 `@Transactional(readOnly = true)`。
-- **跨服务调用禁止开新事务嵌套**：跨进程 / 跨服务的一致性走「最终一致 + 补偿」或 Activiti 工作流，不要用分布式事务。
+- 事务边界统一在 **service 实现层**，使用 `@Transactional(rollbackFor = Exception.class)`。
+- controller / mapper 层**禁止**写 `@Transactional`。
+- 跨服务（跨进程）调用**禁止**使用本地事务跨边界；改用最终一致性（消息队列 / 补偿任务），本项目当前无跨服务场景。
  
 ### 1.6 认证
  
-- **协议**：JWT（HS256），头 `Authorization: Bearer <token>`。
-- **生命周期**：access token 8 小时，refresh token 7 天；登录返回两枚 token；access 过期前端凭 refresh 刷新一次。
-- **刷新机制**：refresh token 只能用于换 access，不能直接调业务接口；服务端可吊销（Redis 存吊销名单）。
-- **密钥管理**：JWT 签名密钥放 `.env.local` 的 `JWT_SECRET`，至少 32 字节；生产环境必须更换默认值。
-- **登录失败锁定**：连续 5 次失败锁账户 30 分钟，Redis 计数器 key `login:fail:<username>`。
+- 使用 Spring Security + JWT。
+- **Access Token**：HS256，TTL 2 小时；签发后写 Redis（key=`auth:token:<userId>:<jti>`，value=用户摘要）。
+- **Refresh Token**：TTL 7 天，单独签发；刷新时旋转 token 并使旧 token 失效。
+- 密钥（HMAC secret）放 `.env.local` 的 `JWT_SECRET`，**禁止**写入 application.yml 或代码。
+- 登出 / 改密 / 停用：把对应 `jti` 加入 Redis 黑名单直至原 TTL 过期。
  
 ## 二、前端规范
  
 ### 2.1 目录约定
  
+按 Vite + React 18 + Redux Toolkit 惯例分层（详见 docs/09 § 三）：
+
 | 目录 | 职责 |
 |---|---|
-| `src/api/` | Axios 实例 + 每模块一个 API 文件；**所有 HTTP 调用唯一入口** |
-| `src/components/` | 跨页面通用组件（`AuthButton` / `AppTable` / `PageHeader`） |
-| `src/pages/` | 业务页面，按模块组织子目录 |
-| `src/store/` | Redux Toolkit slice，仅放真正的全局状态 |
-| `src/hooks/` | 自定义 hook（`useAuth` / `usePagination` / `useDebounce`） |
-| `src/utils/` | 纯函数工具（格式化、校验、正则） |
-| `src/styles/` | `tokens.css` + 全局样式 |
-| `src/router/` | 路由表 + 路由守卫 |
-
-> **前端禁止直接写 SQL / 操作 DB**，所有数据访问走 `api/` 层统一封装。
+| `src/api/` | Axios 实例 + 各模块接口调用函数；**所有数据访问唯一入口** |
+| `src/store/` | Redux Toolkit slices；全局态（认证 / 用户信息 / 字典） |
+| `src/router/` | React Router 配置 + 路由守卫 |
+| `src/pages/<module>/` | 业务页面（按模块分目录） |
+| `src/components/` | 跨页面通用组件（含 `Permission` 等） |
+| `src/layouts/` | 框架布局 |
+| `src/hooks/` | 自定义 hook |
+| `src/utils/` | 工具方法（日期 / 金额 / 校验等） |
+| `src/styles/` | 全局样式 + Design Tokens |
+| `src/types/` | 全局 TypeScript 类型 |
+
+**前端禁止直接写 SQL / 操作 DB**；所有数据访问走 `api/` 层封装的 HTTP 调用。
  
 ### 2.2 状态管理
  
-- **Redux 存什么**：全局共享 + 跨页面持久（当前用户信息、权限码列表、菜单树、字典）。
-- **Redux 不存什么**：单个页面的表单值、Modal 开关、表格分页参数 → 放组件 `useState` / `useReducer`。
-- **服务端数据**：业务数据（列表、明细）不要塞 Redux，每次进入页面走 `api/` 取最新；只有字典 / 全局枚举做内存缓存（`store/slices/dictSlice`）。
+- **全局态**（用户身份 / 权限 / 全局字典 / 主题）：Redux Toolkit。
+- **页面级态**（表单值 / 列表参数）：组件本地 `useState` / `useReducer`。
+- **服务端数据**（列表 / 详情）：直接调 `api/` 函数，配合 `useEffect` + 本地 state；**不放**全局 store，避免缓存一致性问题。
+- 跨页面共享但**非全局**的态用 React Context（如 Modal Provider）。
  
 ### 2.3 请求封装
  
-- **Axios 实例**：`src/api/http.ts` 统一创建，`baseURL` 取 `import.meta.env.VITE_API_BASE`。
-- **请求拦截器**：自动注入 `Authorization: Bearer <accessToken>`；token 临期则先刷新再发起原请求。
-- **响应拦截器**：剥 `Result.data` 给业务；`code !== 0` 时 `message.error(message)` 并 reject。
-- **超时**：默认 15s；上传 / 导出接口单独 60s。
-- **错误重试**：仅对幂等 GET 重试 1 次，POST / PUT / DELETE 禁止重试。
+`src/api/client.ts` 统一 Axios 实例：
+
+- baseURL 从 `import.meta.env.VITE_API_BASE_URL` 读取。
+- **请求拦截**：自动注入 `Authorization: Bearer <accessToken>`；附带 `X-Request-Id` 用于链路追踪。
+- **响应拦截**：
+  - HTTP 200 + `code === 0` → 返回 `data`。
+  - HTTP 200 + `code !== 0` → 抛业务错误（含 message 和 code）。
+  - HTTP 401 → 触发 refresh token；refresh 失败 → 清登录态 + 跳登录页。
+  - HTTP 5xx → 抛网络错误。
+- 超时：默认 10s；上传 / 导出接口 60s。
+- 不做自动重试（重试由业务调用处显式控制）。
  
 ### 2.4 错误处理
  
-- **网络错误**：Axios `error.code === 'ERR_NETWORK'` → 全局 `message.error('网络异常，请检查连接')`。
-- **业务错误**：`code !== 0` 在响应拦截器统一弹 message；页面只需处理 `try/catch` 中的 reject。
-- **页面级错误**：路由级 `ErrorBoundary` 包顶层，组件 throw 时显示统一错误页（docs/06 § 1.2）。
+| 错误类型 | 处理方式 |
+|---|---|
+| 网络错误（断网 / 5xx） | 顶层 `message.error('网络异常，请重试')`，业务调用处可自定义重试按钮 |
+| 业务错误（code !== 0） | 默认 `message.error(err.message)`，业务调用处可拦截做特殊提示 |
+| 表单校验失败 | 字段下方红字（Ant Design `Form` 自带） |
+| 路由级未授权 | `RequireAuth` 守卫重定向到 `/login` |
+| 页面级崩溃 | 顶层 `ErrorBoundary` 显示 `Result status="500"` + 重新加载按钮 |
  
 ### 2.5 样式与主题
  
 - **CSS 变量命名**：`--color-<scope>-<role>-<state>`
-  - `scope` = `form` / `table-row` / `btn` / `link` / ...
-  - `role` = `bg` / `fg` / `border`
-  - `state` = `edit` / `readonly` / `hover` / `selected`
-- **文件位置**：`src/styles/tokens.css`，由 skeleton-gen 生成空骨架，色值由 docs/06 § 二锁定后填入。
-- **组件样式**：只用 `var(--color-xxx)`，禁止硬编码 hex / rgba。
-- **Ant Design 主题对接**：`<ConfigProvider theme={{ token: { colorPrimary: 'var(--color-primary)', ... } }}>` 把 tokens 注入 antd 主题。
-
-具体 token 表见 docs/06 § 二。
+  - `scope`：`form` / `table-row` / `tag` / `btn` 等；通用全局色无 scope（如 `--color-primary`）
+  - `role`：`bg` / `fg` / `border`
+  - `state`：`edit` / `readonly` / `hover` / `selected` / `disabled`；常态省略
+- **文件位置**：`frontend/src/styles/tokens.css`（由 skeleton-gen 生成骨架，色值由 docs/06 § 二锁定）。
+- **组件样式中只用 `var(--color-xxx)`**，禁止硬编码 hex / rgba。
+- **与 Ant Design 主题对接**：`App.tsx` 顶层包 `<ConfigProvider theme={{ token: { colorPrimary: 'var(--color-primary)', ... } }}>`；Ant Design 5 接受 token 对象映射，确保组件库色值与 tokens.css 单一来源。
+- 具体 token 表见 `docs/06 § 二`。
  
 ## 三、共同约定
  
@@ -153,35 +174,40 @@
  
 `<type>(<scope>): <subject> REQ-XXX-NNN`
  
-- `type` ∈ `feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `style`
-- `scope` 为模块代码小写（`usr` / `pur` / `sal`）或 `infra`
-- `subject` 50 字以内动词开头
-- 末尾必须挂 `REQ-XXX-NNN`（如 `REQ-USR-001`），CI 用此挂关联
+- type：见 CLAUDE.md § 🗂️ Git 提交规范。
+- scope：模块代码小写（`usr` / `pur` / `sal`）或 `infra` / `docs`。
+- subject：祈使句，中文，<= 50 字。
+- REQ tag：业务类提交（feat / fix / test）必带。
+
+**示例**：`feat(usr): 实现用户登录接口 REQ-USR-001`
  
 ### 3.2 分页查询
  
-- **后端入参**：`PageQuery { pageNum: int = 1, pageSize: int = 20 }`（`pageSize` 上限 100）+ 业务过滤字段；继承基类避免重复声明。
-- **后端出参**：`PageVO<T> { records: List<T>, total: long, pageNum: int, pageSize: int }`。
-- **前端组件**：统一封装 `<AppTable />` 内置 antd `Table` + `Pagination`，受控 `current` / `pageSize` / `total`。
-- **默认排序**：按创建时间倒序；可按列点击切换。
+- **后端**：请求入参 `PageReq { page=1, size=20 }`（兜底默认值；size 上限 100）；返回 `PageResult<T> { records: List<T>, total: long, page: int, size: int }`。
+- **前端**：使用 Ant Design `Table` + `Pagination`；统一组件包装在 `components/PagedTable`，对接 `PageResult`。
+- 排序参数走 `sortField` / `sortOrder`，白名单字段，禁止任意字段排序。
  
 ### 3.3 日期与金额
  
-- **后端类型**：日期 `LocalDate`，时间 `LocalDateTime`，金额 `BigDecimal`（scale=2，HALF_UP）。
-- **序列化**：Jackson 全局配置 `LocalDateTime` ↔ `yyyy-MM-dd HH:mm:ss`；`BigDecimal` 序列化为字符串避免精度丢失。
-- **前端展示**：`utils/format.ts` 提供 `formatDate(d)` / `formatMoney(n)`；金额展示固定 2 位小数 + 千分位（`￥1,234.56`）。
+- **后端类型**：日期用 `LocalDateTime` / `LocalDate`；金额用 `BigDecimal`（精度 2 位）。
+- **后端 → 前端**：日期统一序列化为 `YYYY-MM-DD HH:mm:ss` 字符串；金额序列化为 `string`（避免精度丢失）。
+- **前端展示**：日期使用 `dayjs` 格式化（`YYYY-MM-DD HH:mm`）；金额使用 `utils/money.ts` 格式化为千分位。
+- **金额精度**：内部全部 `BigDecimal`，4 舍 6 入 5 成双（`HALF_EVEN`）；展示截断到 2 位。
  
 ### 3.4 数据访问规约
  
-- **SELECT 字段显式列举**，禁止 `SELECT *`；Mapper XML 用 `<sql id="Base_Column_List">` 集中维护。
-- **禁止 N+1**：循环中不得执行 DB 查询；改用批量查（`IN (?,?,?)`）/ JOIN / `<foreach>`。
-- **表名 / 字段名**：Mapper XML 中通过 `<sql>` 片段或常量引用，禁止字符串拼接（防 SQL 注入 + 利于改名）。
-- **分页**：统一用 MyBatis-Plus `Page<T>` + `selectPage(...)`，禁止 LIMIT 字符串拼接。
+- **SELECT 字段显式列举**：禁止 `SELECT *`；MyBatis-Plus 用 `select(User::getId, User::getUsername)` 或 XML 显式列名。
+- **禁止 N+1 反模式**：循环中不得执行 DB 查询；改用 `selectBatchIds` / `IN` 子句 / `JOIN`。
+- **Mapper XML**：表名 / 字段名用常量或引用，禁止字符串拼接 SQL（防注入）。
+- **复杂查询走 XML**，简单 CRUD 走 LambdaQueryWrapper。
+- **写操作**：单表批量写用 `saveBatch` / `updateBatchById`；超大批量（>1000）分批 commit。
  
 ### 3.5 配置与安全
  
-- **配置**：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`，代码里**禁止硬编码**；`application.yml` 用 `${VAR_NAME:default}` 引用环境变量。
+- **后端配置**：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`。代码中**禁止硬编码**（用 `@Value` / `@ConfigurationProperties` 注入）。
+- **多环境**：`application-dev.yml` / `application-test.yml` / `application-prod.yml`，通过 `SPRING_PROFILES_ACTIVE` 切换。
 - **前端安全**：
-  - `localStorage` **不存敏感信息**（token / 身份 / 个人数据）；推荐 HttpOnly Cookie 或 「内存 access token + HttpOnly refresh cookie」组合。
-  - 接口响应禁止回显后端异常堆栈（与 § 1.4 一致）。
-  - XSS：所有用户输入展示走 React JSX 自动转义；`dangerouslySetInnerHTML` 禁用，除非内容来源已白名单化。
+  - `localStorage` **禁止**存敏感信息（token / 身份 / 个人数据）。
+  - Token 推荐**内存 + HttpOnly Cookie**（refresh）或纯内存（access），Redux store 持有 access；刷新页面通过 refresh cookie 重新换取。
+  - **接口响应禁止回显后端异常堆栈**（与 § 1.4 一致）。
+- **密钥来源**：所有密钥（JWT / DB 密码 / 第三方 API key）从 `.env.local` 加载；`.env.local` 在 `.gitignore`，永不入库。
 # 05-API接口契约
  
-BasePath: `/api`
-端口: `8080`
+BasePath: `/api/v1`
+端口: `9090`
  
 ## 全局约定
  
@@ -22,186 +22,109 @@ BasePath: `/api`
  
 ### 鉴权
  
-所有业务接口走 JWT Bearer。客户端在 `Authorization: Bearer <accessToken>` 头中携带访问令牌。
-
-- 登录 `POST /api/usr/auth/login` 返回 `accessToken`（8 小时）+ `refreshToken`（7 天）
-- 临期前端用 refresh token 换新 access token：`POST /api/usr/auth/refresh`
-- 注销 `POST /api/usr/auth/logout` 服务端把 token 加入 Redis 吊销名单
-- 未携带 / 过期 / 已吊销 → 401，对应错误码 `40101 未登录` / `40102 Token 已过期` / `40103 Token 已吊销`
+除 `POST /api/v1/auth/login` 和 `GET /api/v1/companies`（登录页"版本"下拉）之外的全部接口需在请求头携带 `Authorization: Bearer <accessToken>`。Token 由 `/auth/login` 签发，TTL 2 小时，HS256 签名（密钥 `JWT_SECRET` 来自 `.env.local`）。鉴权失败统一返回 `40101 token 无效或已过期` / `40102 用户已被作废或锁定`。详见 docs/04 § 1.6。
  
 ### 分页参数
  
-统一查询入参：
+请求入参：
  
-| 字段 | 类型 | 必填 | 默认 | 说明 |
+| 参数 | 类型 | 必填 | 默认 | 说明 |
 |---|---|---|---|---|
-| `pageNum` | int | 否 | 1 | 当前页码，从 1 开始 |
-| `pageSize` | int | 否 | 20 | 每页条数；上限 100 |
-| `orderBy` | string | 否 | `tCreateDate DESC` | 排序表达式，列名 + 方向 |
+| `page` | int | 否 | 1 | 页码，从 1 开始 |
+| `size` | int | 否 | 20 | 每页条数，上限 100 |
+| `sortField` | string | 否 | — | 排序字段，白名单内 |
+| `sortOrder` | string | 否 | `desc` | `asc` / `desc` |
  
-响应包装：
+响应 `data` 结构 `PageResult<T>`：
  
 ```json
 {
-  "code": 200, "message": "ok",
-  "data": {
-    "records": [ ... ],
-    "total": 1234,
-    "pageNum": 1,
-    "pageSize": 20
-  },
-  "timestamp": 1700000000000
+  "records": [],
+  "total": 0,
+  "page": 1,
+  "size": 20
 }
 ```
  
 ## 接口清单
 （各模块接口段落见下方，由 `downstream-gen` 按 REQ 填入）
  
-## module_usr — USR 用户管理
+## module_usr 用户管理
  
 ### REQ-USR-001 用户登录
  
 - **Method**: POST
-- **Path**: `/api/usr/auth/login`
-- **Auth**: 公开（无需 JWT）
-- **请求**:
-  ```json
-  {
-    "userName": "admin",
-    "password": "P@ssw0rd",
-    "companyVersion": "STANDARD"
-  }
-  ```
-  - `userName` (string, 必填, 3-50 位)
-  - `password` (string, 必填, 明文传输，由 TLS 保证机密性；后端用 BCrypt/Argon2 比对哈希)
-  - `companyVersion` (string, 必填, 枚举 `STANDARD` / `PRO` / `FLAGSHIP`)
-- **响应**:
-  ```json
-  {
-    "code": 200, "message": "ok",
-    "data": {
-      "accessToken": "eyJ...",
-      "refreshToken": "eyJ...",
-      "expiresIn": 28800,
-      "user": {
-        "iIncrement": 1,
-        "sUserName": "admin",
-        "sUserType": "SUPER_ADMIN",
-        "sLanguage": "zh-CN",
-        "permissionCodes": ["USR:ADD", "USR:EDIT", "USR:DELETE", "USR:VIEW"]
-      }
-    },
-    "timestamp": 1700000000000
-  }
-  ```
+- **Path**: `/api/v1/auth/login`
+- **Auth**: 无需（公开接口）
+- **请求**: JSON body `LoginReq { username: string (3-20), password: string (8-20, 明文，HTTPS 传输), companyCode: string (sys_company.sCompanyCode) }`
+- **响应**: JSON `LoginVo { accessToken: string (JWT), tokenType: "Bearer", expiresInSec: 7200, userInfo: { userId: int, username: string, userType: "NORMAL"|"SUPER_ADMIN", language: string, employeeName?: string, companyCode: string } }`
  
 #### 错误码
-- `40001` — 用户名或密码错误（不区分两者，防爆破）
-- `40301` — 账号已锁定，请稍后再试
-- `40302` — 账号已作废
-- `40010` — 参数校验失败（用户名 / 密码 / 版本字段为空或格式不合法）
-
----
+- `40001` — 用户名或密码格式错误
+- `40101` — 用户名或密码错误（统一文案，不区分两者）
+- `40103` — 账号已被作废，禁止登录
+- `42301` — 账号已锁定，请稍后再试（HTTP 423；锁定剩余时间见 `data.lockUntil`）
+- `40004` — 公司不存在或已删除
  
 ### REQ-USR-002 新增用户
  
 - **Method**: POST
-- **Path**: `/api/usr/users`
-- **Auth**: JWT；要求权限码 `USR:ADD`
-- **请求**:
-  ```json
-  {
-    "userNo": "U10001",
-    "userName": "zhangsan",
-    "employeeId": 12,
-    "userType": "NORMAL",
-    "language": "zh-CN",
-    "modifyDoc": false,
-    "permissionIds": [3, 5, 8]
-  }
-  ```
-  - `userNo` / `userName` 必填且系统内唯一
-  - `employeeId` 可空（非员工账号）
-  - `userType` 枚举 `NORMAL` / `SUPER_ADMIN`（仅超级管理员可创建超级管理员）
-  - `language` 枚举 `zh-CN` / `en-US` / `zh-TW`
-  - `permissionIds` 权限分类 ID 数组，可为空
-  - 初始密码后端固定生成（`666666`），不在请求体中
-- **响应**:
-  ```json
-  { "code": 200, "message": "ok", "data": { "userNo": "U10001", "iIncrement": 42 }, "timestamp": 1700000000000 }
-  ```
+- **Path**: `/api/v1/users`
+- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
+- **请求**: JSON body `CreateUserReq { username: string (3-20，正则 ^[A-Za-z0-9_]{3,20}$), userCode: string (max 50), userType: "NORMAL"|"SUPER_ADMIN", language: "zh-CN"|"en-US"|"zh-TW", canEditDocument: boolean, employeeId?: int, permissionCategoryIds?: int[] }`。**初始密码由系统统一设为 `"666666"`（BCrypt 哈希后入库），请求体不接受 `password` 字段（出现即返 40001）。**
+- **响应**: JSON `CreateUserVo { userId: int, username: string, userCode: string }`（HTTP 201）
  
 #### 错误码
-- `40001` — 用户名 / 用户号已存在
-- `40010` — 参数校验失败
-- `40310` — 普通用户无权创建超级管理员
-- `40411` — 关联职员不存在
-- `40412` — 关联权限分类不存在
+- `40001` — 必填字段缺失或格式错误（含携带未知字段如 `password`）
+- `40004` — 指定的员工 / 权限分类不存在
+- `40101` — 未携带或无效 Token
+- `40301` — 当前用户非超级管理员，无权调用
+- `40901` — 用户名已存在
+- `40902` — 用户号已存在
  
----
+### REQ-USR-003 GET 用户详情
+
+- **Method**: GET
+- **Path**: `/api/v1/users/{userId}`
+- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
+- **请求**: Path `userId: int`
+- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds: int[], updatedBy, updatedDate }`
+
+#### 错误码
+- `40101` — 未携带或无效 Token
+- `40301` — 当前用户非超级管理员，无权调用
+- `40401` — 用户不存在
  
 ### REQ-USR-003 修改用户
  
 - **Method**: PUT
-- **Path**: `/api/usr/users/{iIncrement}`
-- **Auth**: JWT；要求权限码 `USR:EDIT`
-- **请求**:
-  ```json
-  {
-    "employeeId": 12,
-    "userType": "NORMAL",
-    "language": "en-US",
-    "modifyDoc": true,
-    "void": false,
-    "permissionIds": [3, 5]
-  }
-  ```
-  - `userName` 不可修改，故请求体不包含
-  - `void = true` 等价于禁用（软删除）
-  - `permissionIds` 全量覆盖（先 DELETE 后 INSERT，事务内）
-- **响应**:
-  ```json
-  { "code": 200, "message": "ok", "data": { "iIncrement": 42 }, "timestamp": 1700000000000 }
-  ```
+- **Path**: `/api/v1/users/{userId}`
+- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
+- **请求**: Path `userId: int`；JSON body `UpdateUserReq { userCode?: string, userType?: "NORMAL"|"SUPER_ADMIN", language?: "zh-CN"|"en-US"|"zh-TW", canEditDocument?: boolean, employeeId?: int|null, isDeleted?: boolean, permissionCategoryIds?: int[] }`（username 与 password 字段不接受）
+- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds, updatedBy, updatedDate }`
  
 #### 错误码
-- `40404` — 目标用户不存在
-- `40310` — 不可修改超级管理员（非超级管理员调用）
-- `40311` — 不可禁用 / 修改自己
-- `40411` — 关联职员不存在
-- `40412` — 关联权限分类不存在
-- `40010` — 参数校验失败
-
----
+- `40001` — 字段格式错误或试图修改 username / password
+- `40004` — 指定的员工 / 权限分类不存在
+- `40101` — 未携带或无效 Token
+- `40301` — 当前用户非超级管理员，无权调用
+- `40302` — 试图停用当前登录用户自己
+- `40401` — 用户不存在
+- `40902` — 用户号已被占用
  
 ### REQ-USR-004 查询用户
  
 - **Method**: GET
-- **Path**: `/api/usr/users`
-- **Auth**: JWT；要求权限码 `USR:VIEW`
-- **请求**: query string
-  - `searchField` 枚举 `userName` / `employeeName` / `userNo` / `departmentName` / `userType` / `void` / `lastLoginDate` / `creator`
-  - `matchMode` 枚举 `CONTAINS` / `NOT_CONTAINS` / `EQUALS`
-  - `searchValue` 字符串，空则不过滤
-  - `includeVoid` 布尔，默认 false（不返回已作废用户）
-  - `pageNum` / `pageSize` / `orderBy` 通用分页参数
-- **响应**: 分页结构，`records[]` 元素：
-  ```json
-  {
-    "iIncrement": 42,
-    "sUserName": "zhangsan",
-    "employeeName": "张三",
-    "sUserNo": "U10001",
-    "departmentName": "技术部",
-    "sUserType": "NORMAL",
-    "sLanguage": "zh-CN",
-    "bVoid": false,
-    "tLastLoginDate": "2026-05-13 09:12:33",
-    "sCreator": "admin",
-    "tCreateDate": "2025-12-01 10:00:00"
-  }
-  ```
-  - 不返回 `sPasswordHash` / `iLoginFailCount` / `tLockUntil`
+- **Path**: `/api/v1/users`
+- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用
+- **请求**: Query 参数 `page=1&size=20&sortField=tCreateDate&sortOrder=desc&queryField=username&matchMode=contains&queryValue=张&userType=NORMAL&isDeleted=false`
+  - `queryField`: 枚举 `username|employeeName|userCode|departmentName|userType|isDeleted|lastLoginDate|createdBy`
+  - `matchMode`: 枚举 `contains|notContains|equals`，缺省 `contains`
+  - `queryValue`: 字符串，空字符串表示不限
+- **响应**: `PageResult<UserListItemVo>`，`UserListItemVo { userId, username, employeeName, userCode, departmentName, userType, language, isDeleted, lastLoginDate, createdBy, createdDate }`（密码字段不返回）
  
 #### 错误码
-- `40010` — 参数校验失败（`pageSize > 100` / `matchMode` 不合法 / `searchField` 不合法）
+- `40001` — 分页参数越界或类型错误（page<1 / size 越界 / sortOrder 非 asc-desc / userType 非枚举 / lastLoginDate 入参非法日期 / isDeleted 入参非布尔）
+- `40003` — `sortField` / `queryField` / `matchMode` 不在白名单
+- `40101` — 未携带或无效 Token
+- `40301` — 当前用户非超级管理员，无权调用
@@ -6,88 +6,95 @@
  
 ### 1.1 操作反馈
  
-- **成功提示**：使用 Ant Design `message.success()`，默认 3s 自动消失；新增 / 修改 / 删除等写操作必须给反馈。
-- **失败提示**：使用 `message.error()` 显示后端返回的 `message` 字段；表单字段级错误用 Form 的 `validateStatus="error"` + `help` 同步显示。
-- **危险操作二次确认**：删除 / 禁用 / 重置密码等不可逆操作必须用 `Modal.confirm({ okType: 'danger' })` 二次确认，按钮文案使用业务动词（如「确认禁用」），不用「确定」。
-- **长耗时按钮 loading**：提交类按钮在请求未返回前必须置为 `loading=true` 并禁用，避免重复提交；查询类操作在表格组件上启用 `loading` 属性即可。
+- **成功提示**：使用 Ant Design `message.success`，3 秒自动消失；不阻塞操作。
+- **失败提示**：使用 `message.error` 显示后端 `Result.message`；4.5 秒消失；保留可复制。
+- **危险操作**（删除 / 停用 / 重置密码）：必须 `Modal.confirm` 二次确认，标题写明动作，正文写明影响对象 + 不可逆性。
+- **长耗时按钮**（>300ms）：按钮 `loading` 态 + 禁用，避免重复提交；提交完成后恢复。
+- **表单校验失败**：字段下方红字提示；首个错误字段自动聚焦并滚入视口。
  
 ### 1.2 数据展示
  
-- **空状态**：列表 / 表格无数据时使用 `<Empty description="暂无数据" />`，明细页无数据时附加「返回列表」按钮。
-- **加载状态**：页面级加载用 `<Spin spinning>` 包裹主区域；表格 / 卡片局部加载用组件自带 `loading` 属性。
-- **异常状态**：接口 5xx 或网络异常时显示 `<Result status="error" title="加载失败" extra={<Button>重试</Button>} />`；403 时显示「无权限」并提供「返回首页」按钮。
+- **空状态**：使用 `Empty` 组件，图标 + 一句话说明（如 `暂无用户`）+ 主操作按钮（如 `新增用户`）。
+- **加载中**：列表用 `Skeleton`；单组件用 `Spin`；全屏首次加载允许使用 `Spin` 覆盖。
+- **异常态**：网络 / 5xx 错误使用 `Result status="error"` 显示，附 `重试` 按钮。
+- **分页**：默认 20 条 / 页，可选 10 / 20 / 50 / 100；显示总数 + 当前页 / 总页数。
+- **表格列**：必显列固定在左侧；操作列固定在右侧；时间列统一格式 `YYYY-MM-DD HH:mm`。
  
 ### 1.3 权限控制（前端）
  
-- **菜单级**：登录后由后端返回菜单权限码列表，前端 Layout 按权限码过滤后渲染左侧菜单。
-- **按钮级**：包装 `<AuthButton code="USR:ADD">新增</AuthButton>`，权限码不在用户列表时直接不渲染（避免显示再禁用）。
-- **路由级**：在 React Router 外层包 `<AuthRoute />`，路由元数据声明 `meta.code`，无权限重定向 403 页面。
-- **关联后端 RBAC**：权限码格式 `<模块代码>:<动作>`（如 `USR:ADD` / `USR:EDIT` / `USR:DELETE`），与后端 Spring Security `@PreAuthorize("hasAuthority('USR:ADD')")` 一一对应。
+- **菜单级**：Redux `auth.user.permissions` 驱动；菜单项无权限直接不渲染。
+- **路由级**：`router/index.tsx` 用 `RequireAuth` + `RequireRole` 高阶守卫；未授权重定向到登录或 403 页。
+- **按钮级**：`<Permission code="...">` 包裹按钮，无权限时不渲染（不显示 disabled 灰按钮）。
+- **后端 RBAC 同源**：前端权限码与后端 `Permission` 表严格对齐（codename 一致）；前端只做展示控制，最终鉴权由后端兜底。
  
 ## 二、Design Tokens
  
-> 所有色值统一以 CSS 变量定义于 `src/styles/tokens.css`；命名规范见 docs/04 § 2.5。
+> 所有色值统一以 CSS 变量定义于 `frontend/src/styles/tokens.css`；命名规范见 docs/04 § 2.5。组件样式只引用 `var(--color-xxx)`，禁止硬编码 hex / rgba。
  
 ### 2.1 全局调色板
  
-与 Ant Design 5 主题对齐，统一通过 `<ConfigProvider theme={{ token: {...} }}>` 注入。
+与 Ant Design 5 默认主题对齐，按语义分组。
  
 | 语义 | 变量名 | 默认值 | 用途 |
 |---|---|---|---|
-| 主色 | `--color-primary` | `#1677ff` | 主操作按钮 / 链接 / 选中态 |
-| 成功 | `--color-success` | `#52c41a` | 成功消息 / 启用状态标签 |
-| 警告 | `--color-warning` | `#faad14` | 警告消息 / 待处理状态 |
-| 错误 | `--color-error` | `#ff4d4f` | 错误消息 / 危险按钮 / 禁用状态 |
-| 主文字 | `--color-text-primary` | `rgba(0, 0, 0, 0.88)` | 正文 / 表格内容 |
-| 次文字 | `--color-text-secondary` | `rgba(0, 0, 0, 0.65)` | 辅助说明 / 占位 |
-| 边框 | `--color-border` | `#d9d9d9` | 表单输入 / 卡片边界 |
-| 背景 | `--color-bg-base` | `#ffffff` | 页面主背景 |
-| 弱背景 | `--color-bg-layout` | `#f5f5f5` | 页面 layout 间隙 / 灰底 |
+| 主色 | `--color-primary` | `#1677ff` | 主按钮、链接、激活态边框 |
+| 主色-悬浮 | `--color-primary-hover` | `#4096ff` | 主色控件 hover |
+| 主色-激活 | `--color-primary-active` | `#0958d9` | 主色控件 active / pressed |
+| 成功 | `--color-success` | `#52c41a` | 成功提示、积极状态标签 |
+| 警告 | `--color-warning` | `#faad14` | 警告提示、需注意状态 |
+| 错误 | `--color-error` | `#ff4d4f` | 错误提示、危险按钮 |
+| 信息 | `--color-info` | `#1677ff` | 普通信息提示 |
+| 主文字 | `--color-text` | `rgba(0,0,0,0.88)` | 标题、正文 |
+| 次文字 | `--color-text-secondary` | `rgba(0,0,0,0.65)` | 辅助说明 |
+| 禁用文字 | `--color-text-disabled` | `rgba(0,0,0,0.25)` | 禁用态 |
+| 边框 | `--color-border` | `#d9d9d9` | 输入框 / 卡片边框 |
+| 分割线 | `--color-split` | `#f0f0f0` | 列表分割线 |
+| 背景-页面 | `--color-bg-page` | `#f5f5f5` | 页面底色 |
+| 背景-容器 | `--color-bg-container` | `#ffffff` | 卡片 / 表单 / Modal |
+| 背景-禁用 | `--color-bg-disabled` | `#f5f5f5` | 禁用控件 |
  
 ### 2.2 组件级状态色
  
-| 序号 | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 |
-|---|---|---|---|---|---|---|---|---|
-| 1 | 表单输入框 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | 只读态边框使用 `transparent` |
-| 2 | 下拉单选 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | — |
-| 3 | 表格行 | — | `var(--color-bg-base)` | `var(--color-bg-row-hover)` | — | `var(--color-text-primary)` | `var(--color-text-primary)` | 编辑态走 Modal，行内不编辑 |
-| 4 | 主按钮 | `var(--color-primary)` | `var(--color-bg-layout)` | `var(--color-primary-hover)` | `#ffffff` | `var(--color-text-secondary)` | `#ffffff` | 危险按钮替换 `--color-error` |
-| 5 | 链接 | — | — | `var(--color-primary-hover)` | `var(--color-primary)` | — | `var(--color-primary-hover)` | — |
+按场景 × 状态映射，单元格写 token 引用形式（`var(--color-xxx)`）。`—` 表示该状态不适用。
  
-**Token 默认值**：
+| # | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 |
+|---|---|---|---|---|---|---|---|---|
+| 1 | Input | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 只读用 `readOnly`，禁用用 `disabled` |
+| 2 | Select | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 同 Input |
+| 3 | Button-Primary | `var(--color-primary)` | — | `var(--color-primary-hover)` | `#fff` | — | `#fff` | 主操作 |
+| 4 | Button-Default | `var(--color-bg-container)` | — | `var(--color-bg-container)` | `var(--color-text)` | — | `var(--color-primary)` | 次操作 |
+| 5 | Button-Danger | `var(--color-error)` | — | `#ff7875` | `#fff` | — | `#fff` | 删除 / 停用 |
+| 6 | Table-Row | `var(--color-bg-container)` | — | `#fafafa` | `var(--color-text)` | — | `var(--color-text)` | 斑马纹关闭 |
+| 7 | Tag-Success | `#f6ffed` | — | — | `var(--color-success)` | — | — | 正常 / 启用状态 |
+| 8 | Tag-Error | `#fff2f0` | — | — | `var(--color-error)` | — | — | 停用 / 失败状态 |
  
-| Token | 默认值 |
-|---|---|
-| `--color-primary-hover` | `#4096ff` |
-| `--color-bg-row-hover` | `#fafafa` |
+**Token 默认值**（与 § 2.1 完整一致；新增 token 时此表与 tokens.css 同步更新）。
  
 ### 2.3 引用约定
  
-- 组件样式只用 `var(--color-xxx)`，禁止硬编码 hex / rgba。
-- 新增 token 须先登记到 § 2.1 / 2.2 再补 `tokens.css`。
-- 修改色值只改 `tokens.css` 一处，不允许组件覆盖。
+- 组件样式只用 `var(--color-xxx)`，**禁止**直接写 hex / rgb / rgba。
+- 新增 token 必须先登记到 § 2.1 / 2.2，再写入 `tokens.css`。
+- 修改色值只改 `tokens.css` 一处；组件层不允许覆盖（如 `.ant-btn-primary { background: ... }` 之类禁止）。
  
 ## 三、页面清单
+（由 `downstream-gen` 按模块追加段落）
  
-### module_usr USR-用户管理
+### module_usr 用户管理
  
 - **登录页** (`/login`)
   - 类型: 表单页
   - 对应 REQ: REQ-USR-001
-  - 入口菜单: 无（未登录态唯一可达页面）
-  - 主要交互: 表单输入 用户名 / 密码 / 版本 → 提交 → 成功跳首页 / 失败留页并显示通用错误消息；账号锁定时显示锁定提示
-- **用户列表页** (`/usr/users`)
+  - 入口菜单: 未登录访问任何路径均重定向至此
+  - 主要交互: 公司/版本下拉（页面加载时拉取 `GET /api/v1/companies`）→ 输入用户名 / 密码（密码星号显示）→ 提交按钮带 loading 态防重复提交；连续 5 次失败显示锁定剩余时间；成功后写 access token 到内存并跳转默认主页
+
+- **用户列表** (`/users`)
   - 类型: 列表页
-  - 对应 REQ: REQ-USR-004
-  - 入口菜单: 系统管理 → 用户管理 → 用户列表
-  - 主要交互: 查询字段 + 匹配方式 + 查询值 三段筛选 → 表格分页展示 → 行内「编辑」「禁用 / 启用」按钮（权限码 `USR:EDIT`）；顶部「新增用户」按钮（权限码 `USR:ADD`）跳新增表单
-- **用户新增页** (`/usr/users/new`)
-  - 类型: 表单页
-  - 对应 REQ: REQ-USR-002
-  - 入口菜单: 系统管理 → 用户管理 → 用户列表 → 新增按钮
-  - 主要交互: 员工名（下拉单选）选择后自动回填用户号 / 用户名；类型 / 语言下拉；权限组表格（多选）；提交校验失败显示字段级 `validateStatus="error"`；成功 message.success 后回列表页
-- **用户编辑页** (`/usr/users/:id/edit`)
-  - 类型: 表单页
-  - 对应 REQ: REQ-USR-003
-  - 入口菜单: 用户列表 → 行内「编辑」按钮
-  - 主要交互: 复用新增表单组件；用户名只读；提供「重置密码」按钮（二次确认）；提供「禁用 / 启用」开关；禁用自己时按钮置灰
+  - 对应 REQ: REQ-USR-002（"新增"入口）、REQ-USR-003（"编辑"行内按钮）、REQ-USR-004（列表分页 + 筛选）
+  - 入口菜单: 系统管理 → 用户管理
+  - 主要交互: 顶部筛选区（查询字段下拉 / 匹配方式下拉 / 查询值输入框 / 查询按钮）+ 右上"新增用户"按钮 + Ant Design Table（含序号 / 用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 语言 / 作废标签 / 登录日期 / 制单人 / 制单日期 / 操作列）+ 分页器（10/20/50/100）；编辑按钮打开 Modal 复用新增表单组件（按 REQ-USR-003 字段差异置只读 / 禁用）；不允许停用当前登录账号自己（按钮 disabled + tooltip 解释）
+
+- **用户表单**（嵌入式 Modal，无独立路由）
+  - 类型: 表单页（Modal）
+  - 对应 REQ: REQ-USR-002 / REQ-USR-003
+  - 入口菜单: 由用户列表的"新增" / "编辑"按钮触发
+  - 主要交互: 左侧基础信息区（员工名下拉 / 用户号 / 用户名 / 类型下拉 / 语言下拉 / 单据修改权限复选框 / 作废复选框（仅编辑））+ 右侧权限组区（按 `sys_permission_category` 渲染勾选列表）+ 底部"保存"/"取消"；保存调 `POST /api/v1/users`（新增）或 `PUT /api/v1/users/{userId}`（编辑），成功后关闭 Modal 并刷新列表
@@ -4,43 +4,46 @@
  
 | 层 | 依赖 | 版本 | 说明 |
 |---|---|---|---|
-| 运行时 | Java (JDK) | 17 / 21 | Spring Boot 3 推荐版本 |
-| 运行时 | MySQL | 8.x | 关系数据库 |
-| 运行时 | Redis | 最新稳定版 | 缓存 / 会话 |
-| 运行时 | Node.js | 20.x LTS | 前端构建 + 本地 dev server |
-| 构建（后端） | Maven | 3.9.x | Java 依赖与构建工具 |
-| 构建（前端） | pnpm | 8.x（或 npm 10.x） | 前端依赖管理 |
-| 构建（前端） | Vite | 最新稳定版 | 前端开发与打包 |
-| 容器 | Docker | 最新稳定版 | 容器化部署 |
-| 容器 | Docker Compose | 最新稳定版 | 本地一键启依赖（MySQL + Redis） |
-| 反向代理 | Nginx | 最新稳定版 | 前端静态托管 / 反向代理 |
-| CLI 工具 | git | 2.30+ | 代码版本控制 |
-| CLI 工具 | mysql client | 8.x | 本地执行 SQL / 验证 migration |
-| CLI 工具 | glab（可选） | 最新稳定版 | GitLab MR 创建（亦可直接走 Web） |
+| 运行时 | Java JDK | 17 或 21 | Spring Boot 3.x 运行环境 |
+| 运行时 | Node.js | 20.x LTS | Vite 5 / React 18 构建运行 |
+| 运行时 | MySQL | 8.x | 关系型数据库 |
+| 运行时 | Redis | 最新稳定 | 缓存 / 会话 |
+| 运行时 | Nginx | 最新稳定 | 反向代理、前端静态托管（生产） |
+| 构建 | Maven | 3.9.x | 后端依赖管理与构建 |
+| 构建 | npm（或 pnpm） | 与 Node 配套 | 前端包管理器 |
+| 构建 | Flyway core + mysql | 10.x | Spring Boot 启动时自动 apply migration |
+| 构建 | Vite | 最新稳定 | 前端打包 |
+| 容器 | Docker | 最新稳定 | 镜像构建与本地编排 |
+| 容器 | docker-compose | 最新稳定 | 本地 mysql / redis 编排 |
+| CLI 工具 | git | ≥ 2.40 | 版本控制 |
+| CLI 工具 | mysql client | 8.x | `scripts/setup-test-db.sh` 调用 |
+| CLI 工具 | curl / jq | 最新稳定 | API 调试、脚本辅助 |
  
 ## 二、端口约定
  
 | 服务 | 端口 | 说明 |
 |---|---|---|
-| 后端 HTTP | 8080 | Spring Boot 默认端口（`server.port`） |
-| 前端 dev server | 5173 | Vite 默认端口（`vite --port`） |
-| MySQL | 3306 | 默认端口，本地开发可用 Docker Compose 暴露 |
-| Redis | 6379 | 默认端口 |
-| Nginx | 80 / 443 | 生产部署反向代理入口 |
+| 后端 HTTP | 9090 | 项目锁定（避开常见 8080 冲突） |
+| 前端 dev server | 5173 | Vite 默认 |
+| MySQL | 3306 | 主库 |
+| MySQL（测试） | 3307 | 本地独立测试库（避免与开发库冲突，可选） |
+| Redis | 6379 | 默认 |
+| Nginx | 80 / 443 | 生产反代 |
  
 ## 三、环境变量
  
-运行时凭据（数据库连接、JWT 密钥等）全部放在仓库根的 `.env.local`，不入 git。
-字段清单与占位符见该文件，真实值由开发者本地填写。
+运行时凭据（数据库连接、JWT 密钥、Redis 密码等）全部放在仓库根的 `.env.local`，**不入 git**（由 `.gitignore` 强制忽略）。
+
+字段清单与占位符见 `.env.local`，真实值由开发者本地填写。CC 不读取 `.env.local` 的真实值；任何引用都用 `${VAR_NAME}` 形式。
  
 ## 四、常用命令
  
 | 命令 | 说明 |
 |---|---|
-| `./mvnw spring-boot:run` | 本地启动后端（含 Flyway 自动 apply migration） |
-| `pnpm dev` | 本地启动前端 dev server（默认 5173） |
-| `./mvnw clean package -DskipTests` | 后端打包生成 jar |
-| `pnpm build` | 前端打包到 `dist/` |
-| `bash scripts/test.sh` | 执行后端 + 前端测试组合（lint / unit / e2e） |
-| `bash scripts/setup-test-db.sh` | 重置本地测试数据库（DROP + CREATE + apply V1） |
-| `glab mr create` | 推送当前分支并创建 GitLab MR（亦可走 Web 端） |
+| `cd backend && ./mvnw spring-boot:run` | 启动后端服务（监听 8080） |
+| `cd frontend && npm run dev` | 启动前端 dev server（监听 5173） |
+| `cd backend && ./mvnw clean package` | 后端打包（生成 jar） |
+| `cd frontend && npm run build` | 前端打包（生成 dist/） |
+| `bash scripts/test.sh` | 跑后端 + 前端全部测试（test-gate 入口） |
+| `bash scripts/setup-test-db.sh` | DROP+CREATE 测试库（Flyway V1 会在测试启动时 apply） |
+| `glab mr create` 或 `gh pr create` | 创建 MR / PR（mr-create skill 调用） |
@@ -55,15 +55,15 @@
     - [ ] REQ-SYS-002 用户注册
 -->
  
-- module_usr USR-用户管理
+- module_usr 用户管理
   - 依赖: —
-  - 路径: backend/src/main/java/com/example/erp/module/usr/
-  - MR: —
+  - 路径: backend/module/usr/
+  - MR: !1
   - 功能:
-    - [ ] REQ-USR-001 用户登录
-    - [ ] REQ-USR-002 新增用户
-    - [ ] REQ-USR-003 修改用户
-    - [ ] REQ-USR-004 查询用户
+    - [x] REQ-USR-001 用户登录
+    - [x] REQ-USR-002 新增用户
+    - [x] REQ-USR-003 修改用户
+    - [x] REQ-USR-004 查询用户
  
 ## 三、Coding 阶段（前端整体）
  
@@ -4,93 +4,108 @@
  
 ```
 .
-├── CLAUDE.md                  # 项目级规范与流程指令
-├── README.md                  # 项目说明（可选）
-├── .env.local                 # 本地凭据（不入 git）
+├── CLAUDE.md                 # Claude Code 主指令
+├── README.md                 # 项目说明
+├── .env.local                # 本地凭据（不入 git）
 ├── .gitignore
-├── .githooks/
-│   └── pre-push               # 推送前自动跑 scripts/test.sh
-├── scripts/
-│   ├── test.sh                # 后端 + 前端测试组合入口
-│   └── setup-test-db.sh       # 重置本地测试数据库
+├── .githooks/                # 仓库级 git hooks（core.hooksPath 指向）
+│   └── pre-push
+├── scripts/                  # 项目脚本（test.sh / setup-test-db.sh 等）
+├── docs/                     # 全部规划与设计文档
+├── prototype/                # 前端 HTML mockup（前端阶段的布局权威）
 ├── sql/
-│   └── migrations/            # Flyway V*__*.sql 文件
-├── docs/                      # 全量项目文档（见 § 四）
-├── prototype/                 # 静态 HTML mockup（前端实现权威）
-├── backend/                   # 后端工程（Spring Boot + Maven）
-└── frontend/                  # 前端工程（Vite + React）
+│   └── migrations/           # Flyway V_n__*.sql
+├── backend/                  # Spring Boot 服务
+│   ├── pom.xml
+│   └── src/
+└── frontend/                 # Vite + React 应用
+    ├── package.json
+    ├── vite.config.ts
+    └── src/
 ```
  
 ## 二、后端目录
  
+后端按 Spring Boot 3 + MyBatis-Plus 的惯例组织；业务代码按 docs/01 模块索引落到 `module/<module_code_lower>/`。
+
 ```
 backend/
 ├── pom.xml
-└── src/
-    ├── main/
-    │   ├── java/
-    │   │   └── com.example.erp/
-    │   │       ├── ErpApplication.java
-    │   │       ├── common/                # 全局响应 / 异常 / 拦截器 / 工具
-    │   │       │   ├── result/
-    │   │       │   ├── exception/
-    │   │       │   ├── interceptor/
-    │   │       │   └── util/
-    │   │       ├── config/                # Spring 配置类（Security / Redis / MyBatis-Plus / Swagger / Activiti）
-    │   │       ├── module/                # 业务模块（按 docs/01 索引拆分）
-    │   │       │   └── usr/               # USR 用户管理
-    │   │       │       ├── controller/
-    │   │       │       ├── service/
-    │   │       │       │   └── impl/
-    │   │       │       ├── mapper/
-    │   │       │       ├── entity/
-    │   │       │       ├── dto/
-    │   │       │       └── vo/
-    │   │       └── security/              # 认证 / 鉴权 / JWT
-    │   └── resources/
-    │       ├── application.yml
-    │       ├── application-dev.yml
-    │       ├── application-prod.yml
-    │       ├── mapper/                    # MyBatis XML（按模块再分子目录）
-    │       └── logback-spring.xml
-    └── test/
-        └── java/
-            └── com.example.erp/
-                └── module/
-                    └── usr/               # 与 main/ 镜像
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── com/xly/erp/
+│   │   │       ├── Application.java          # Spring Boot 启动类
+│   │   │       ├── common/                   # 跨模块基础组件
+│   │   │       │   ├── response/             # 统一响应包装（Result / PageResult）
+│   │   │       │   ├── exception/            # 全局异常处理 + 业务异常
+│   │   │       │   ├── security/             # Spring Security / JWT 配置
+│   │   │       │   ├── config/               # 通用配置（CORS / Swagger / MyBatis-Plus 等）
+│   │   │       │   └── util/                 # 工具类
+│   │   │       └── module/
+│   │   │           └── usr/                  # 用户管理（REQ-USR-*）
+│   │   │               ├── controller/
+│   │   │               ├── service/
+│   │   │               ├── service/impl/
+│   │   │               ├── mapper/
+│   │   │               ├── entity/
+│   │   │               ├── dto/              # Request DTO
+│   │   │               ├── vo/               # Response VO
+│   │   │               └── converter/        # MapStruct DTO/VO/Entity 转换
+│   │   └── resources/
+│   │       ├── application.yml               # 主配置
+│   │       ├── application-dev.yml           # 开发环境
+│   │       ├── application-test.yml          # 测试环境
+│   │       ├── mapper/                       # MyBatis XML（与 module 子目录对应）
+│   │       │   └── usr/
+│   │       └── logback-spring.xml
+│   └── test/
+│       └── java/
+│           └── com/xly/erp/
+│               └── module/
+│                   └── usr/                  # 单元测试 + 集成测试
+└── target/                                   # Maven 构建产物（gitignore）
 ```
  
+> Flyway migration 不在 backend/ 下，统一在仓库根 `sql/migrations/`，由 Spring Boot 启动时自动 apply（见 docs/04 § Schema 演化规约）。
+
 ## 三、前端目录
  
+前端按 Vite + React 18 + Ant Design 5 + Redux Toolkit + React Router v6 的惯例组织；业务页面按模块分组放在 `pages/<module>/`。
+
 ```
 frontend/
 ├── package.json
 ├── vite.config.ts
 ├── tsconfig.json
 ├── index.html
-└── src/
-    ├── main.tsx                   # 入口（挂载 React + Router + Store + ConfigProvider）
-    ├── App.tsx                    # 顶层路由 + 全局 Layout
-    ├── api/                       # Axios 实例 + 各模块 API（数据访问统一入口）
-    │   └── usr.ts                 # USR 用户管理 API
-    ├── components/                # 跨页面通用组件（AuthButton / AppTable / PageHeader 等）
-    ├── pages/                     # 按业务模块组织页面
-    │   └── usr/                   # USR 用户管理
-    │       ├── UserList.tsx
-    │       ├── UserEdit.tsx
-    │       └── Login.tsx
-    ├── store/                     # Redux Toolkit slices（全局状态）
-    │   └── slices/
-    ├── hooks/                     # 自定义 hook（useAuth / usePagination 等）
-    ├── utils/                     # 工具函数（formatDate / formatMoney / regex 等）
-    ├── styles/
-    │   ├── tokens.css             # Design Tokens（docs/06 § 二）
-    │   └── global.css             # 全局样式 reset / typography
-    ├── router/                    # 路由表（含 meta.code 权限码）
-    └── assets/                    # 静态资源（图片 / 字体）
+├── src/
+│   ├── main.tsx                              # 入口
+│   ├── App.tsx                               # 根组件 + 路由
+│   ├── api/                                  # Axios 实例 + 接口调用层
+│   │   ├── client.ts                         # axios 实例 + 拦截器（401 / 错误统一处理）
+│   │   └── usr.ts                            # 用户管理接口（按模块拆分）
+│   ├── store/                                # Redux Toolkit
+│   │   ├── index.ts                          # configureStore
+│   │   └── slices/
+│   │       └── auth.ts                       # 登录态 slice
+│   ├── router/                               # React Router 配置
+│   │   └── index.tsx
+│   ├── pages/                                # 页面（按模块分组）
+│   │   ├── login/                            # FE-NN 登录页
+│   │   └── usr/                              # 用户管理页面
+│   ├── components/                           # 跨页面通用组件
+│   ├── layouts/                              # 框架布局（侧栏 / 顶栏 / 内容区）
+│   ├── hooks/                                # 自定义 hook
+│   ├── utils/                                # 工具方法
+│   ├── styles/
+│   │   └── tokens.css                        # Design Tokens（docs/06 § 二）
+│   └── types/                                # 全局 TypeScript 类型
+├── tests/                                    # Playwright E2E
+└── dist/                                     # Vite 构建产物（gitignore）
 ```
  
-> 注：仓库根 `src/styles/tokens.css` 由 skeleton-gen 创建，作为 Design Tokens 的「上游」源；前端工程化前可先保留在根 `src/styles/` 下，前端工程初始化时迁入 `frontend/src/styles/`（同名同内容）。
+> Vitest 组件测试与对应源码同级（`*.test.tsx`）。
  
 ## 四、docs/ 结构
  
@@ -111,14 +126,37 @@ docs/
  
 ## 五、命名与放置约定
  
-- **后端根包**：`com.example.erp`，下文统称 `<ROOT>`；新增业务模块时落到 `<ROOT>.module.<模块代码小写>`（如 `<ROOT>.module.usr`）。
-- **Controller**：`<ROOT>.module.<m>.controller.<Module>Controller`，文件名首字母大写驼峰，URI 前缀 `/api/<模块代码小写>`。
-- **Service**：接口 `<Module>Service` + 实现 `<Module>ServiceImpl`，实现类放 `service/impl/`。
-- **Mapper**：`<Module>Mapper`（Java 接口）+ `resources/mapper/<m>/<Module>Mapper.xml`（XML 同名）。
-- **Entity / DTO / VO**：
-  - `entity/` 数据库实体（与表 1:1，字段类型同 docs/03）
-  - `dto/` 入参（前端 → 后端的请求体）
-  - `vo/` 出参（后端 → 前端的响应体）
-- **前端组件**：通用组件放 `frontend/src/components/`，文件名首字母大写驼峰（`AuthButton.tsx`）；样式同名 `.module.css`（启用 CSS Modules）。
-- **前端页面**：放 `frontend/src/pages/<模块代码小写>/`，文件名按业务功能命名（`UserList.tsx` / `UserEdit.tsx`），路由 path 前缀 `/<模块代码小写>`。
-- **API 客户端**：每个模块一个文件 `frontend/src/api/<模块代码小写>.ts`，导出该模块所有接口函数；禁止在组件里直接 `axios.xxx`。
+### 5.1 根包 / 命名空间
+
+- **Java 根包**: `com.xly.erp`
+- **前端 npm 包名**: `xly-erp-frontend`
+
+### 5.2 后端文件放置
+
+| 类型 | 路径 | 命名 |
+|---|---|---|
+| Controller | `module/<m>/controller/<Entity>Controller.java` | 大驼峰 + `Controller` 后缀 |
+| Service 接口 | `module/<m>/service/<Entity>Service.java` | 大驼峰 + `Service` 后缀 |
+| Service 实现 | `module/<m>/service/impl/<Entity>ServiceImpl.java` | 大驼峰 + `ServiceImpl` 后缀 |
+| Mapper 接口 | `module/<m>/mapper/<Entity>Mapper.java` | 大驼峰 + `Mapper` 后缀 |
+| Mapper XML | `resources/mapper/<m>/<Entity>Mapper.xml` | 与接口同名 |
+| Entity | `module/<m>/entity/<Entity>.java` | 大驼峰，业务实体名 |
+| DTO（请求） | `module/<m>/dto/<Action><Entity>Req.java` | 动词 + 实体 + `Req`，如 `CreateUserReq` |
+| VO（响应） | `module/<m>/vo/<Entity>Vo.java` 或 `<Entity>DetailVo.java` | 大驼峰 + `Vo` 后缀 |
+| Converter | `module/<m>/converter/<Entity>Converter.java` | MapStruct 接口 |
+
+### 5.3 前端文件放置
+
+| 类型 | 路径 | 命名 |
+|---|---|---|
+| 页面 | `pages/<module>/<PageName>.tsx` | 大驼峰，与路由对齐 |
+| 通用组件 | `components/<ComponentName>/index.tsx` | 大驼峰 |
+| 接口调用 | `api/<module>.ts` | 小写模块名 |
+| Redux slice | `store/slices/<feature>.ts` | 小驼峰 |
+| 测试 | 与源文件同级 `<X>.test.tsx`（组件） / `tests/<X>.spec.ts`（E2E） | 与被测对象对齐 |
+
+### 5.4 通用规则
+
+- 所有 Java 包名小写；类名大驼峰；方法 / 字段小驼峰；常量全大写下划线。
+- TypeScript / TSX 文件用大驼峰命名组件，其他用小驼峰。
+- 业务模块代码与 docs/01 模块代码（USR / PUR / ...）保持一致，小写下划线作为目录名（`module/usr/`）。
+---
+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
+## Local test gate — module_usr
+
+执行时间: 2026-05-15T10:33:28+08:00
+
+### scripts/test.sh (subagent)
+- 子会话: a9aa7d814ffd7dd13
+- 命令: `cd /Users/reporkey/Desktop/test5 && set -a && . ./.env.local && set +a && ./scripts/test.sh`
+- 退出码: 0
+- 通过: 201 / 失败: 0
+- 关键 stdout (≤30 行):
+
+```
+[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.746 s -- in com.xly.erp.common.exception.GlobalExceptionHandlerTest
+[INFO]
+[INFO] Results:
+[INFO]
+[INFO] Tests run: 201, Failures: 0, Errors: 0, Skipped: 0
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  02:32 min
+[INFO] Finished at: 2026-05-15T10:33:28+08:00
+[test.sh] skip frontend test
+[test.sh] 5/6 E2E
+[test.sh] e2e 略 (no frontend)
+[test.sh] 6/6 reset test db
+[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts
+[test.sh] GREEN
+```
+
+### 备注
+
+首次运行 test-gate 时 `scripts/test.sh` 在 stage 2/6 build 失败，因为脚本调用 `./mvnw` 而 backend 没有 Maven Wrapper。修复：把 `./mvnw` 全部替换为系统 `mvn`（与 docs/07 § 一 声明的 Maven 3.9.x 依赖一致）。修后 6 个 stage 全部 GREEN。
+
+结论: green
+---
+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-002
+date: 2026-05-15
+spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-002.md
+---
+
+# REQ-USR-002 新增用户 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `POST /api/v1/users` 接口，超级管理员新建用户（初始密码 `666666` 系统生成 + 哈希），同时落地 JWT 鉴权 HandlerInterceptor + `@RequireSuperAdmin` 角色守卫基础设施。
+
+**Architecture:**
+- 鉴权：手写 `JwtHandlerInterceptor` 实现 `HandlerInterceptor`，通过 `WebMvcConfigurer` 注册，匹配 `/api/v1/**`，放行 `/api/v1/auth/login`；通过 `LoginContext` ThreadLocal 把当前用户上下文传递到 controller / service。
+- 角色守卫：`@RequireSuperAdmin` 方法级注解；同一 interceptor 在 `handler instanceof HandlerMethod` 时检查注解 + `LoginContext.userType`。
+- 业务：`UserCreateService` 单一职责（创建用户 + 写权限分类授权），事务边界一整个写入流程；唯一性预检 + DB 唯一索引兜底；外键存在性预检（employee + permissionCategory）。
+- docs/05 同步：删除 CreateUserReq 的 `password` 字段与 `40002` 错误码（在 Task 1 一并完成）。
+
+**Tech Stack:** 复用 REQ-USR-001 已建（Spring Boot 3 / MyBatis-Plus / BCrypt / JJWT）；本 REQ 新增依赖：无。
+
+---
+
+## Schema 改动
+
+无。V1 已建。
+
+---
+
+## 文件变更清单
+
+**基础设施（鉴权 / 角色守卫）**：
+- `backend/src/main/java/com/xly/erp/common/security/LoginContext.java` — Create（ThreadLocal 工具）
+- `backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java` — Create
+- `backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java` — Create（注解）
+- `backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java` — Create（注册 interceptor）
+- `backend/src/main/resources/application.yml` — Modify:21（启用 `spring.jackson.deserialization.fail-on-unknown-properties: true`）
+
+**业务（REQ-USR-002 专属）**：
+- `backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — Modify（新增 `selectByUserCode` + `existsByUsername` + `existsByUserCode` 方法）
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java` — Create（接口）
+- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java` — Create
+- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java` — Create
+
+**文档同步**：
+- `docs/05-API接口契约.md` — Modify（去掉 `password` + `40002`）
+
+**测试**：
+- `backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java` — Create（鉴权 / 角色守卫单测，含 MockMvc）
+- `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java` — Create（service 集成测）
+- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java` — Create（controller 端到端）
+- `backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java` — Modify（扩展 seed：添加 SUPER_ADMIN 用户 + 2 个权限分类）
+
+---
+
+## 约束常量
+
+**错误码新增**（添加到 `ErrorCode`）：
+
+| 常量 | 值 | HTTP |
+|---|---|---|
+| `FORBIDDEN` | `40301` | 403 |
+| `CONFLICT_USERNAME` | `40901` | 409 |
+| `CONFLICT_USERCODE` | `40902` | 409 |
+
+**初始密码**：常量 `UserCreateServiceImpl.INITIAL_PASSWORD = "666666"`。
+
+**LoginContext API**（ThreadLocal 工具）：
+- `LoginContext.set(int userId, String username, String userType, String companyCode)`
+- `LoginContext.current() : LoginUser`（含上述 4 字段，未登录返 null）
+- `LoginContext.clear()`
+
+**`@RequireSuperAdmin`**：方法级注解，无属性。
+
+**`JwtHandlerInterceptor`** 行为序列（`preHandle`）：
+1. handler 非 HandlerMethod → return true（静态资源等）
+2. method 标注 `@RequireSuperAdmin` 或在 `/api/v1/**` 路径下（非 login）→ 必须鉴权
+3. 取 `Authorization` 头；缺失或无 `Bearer ` 前缀 → `BizException(40101, "未携带 token")`
+4. `jwtUtil.parse(token)` 取 claims
+5. `userMapper.selectByUsername(claims.username)` 查最新状态；不存在 / `iIsDeleted=1` / `tLockUntil > NOW()` → `BizException(40101, "token 关联用户不可用")`
+6. `LoginContext.set(...)`
+7. 若 method 标注 `@RequireSuperAdmin` 且 `userType != "SUPER_ADMIN"` → `BizException(40301, "权限不足，仅超级管理员可调用")`
+8. return true
+9. `afterCompletion` 调 `LoginContext.clear()`
+
+---
+
+## 任务步骤
+
+### Task 1: docs/05 同步 + ErrorCode 新增 3 个常量
+
+**Files:**
+- Modify: `docs/05-API接口契约.md` § REQ-USR-002 — 删除 password 字段 + 40002 错误码
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 新增 FORBIDDEN / CONFLICT_USERNAME / CONFLICT_USERCODE 常量 + 在 `toHttpStatus` 对 40301 / 40901 / 40902 加映射
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java` — Create（覆盖新增 HTTP 映射）
+
+**API shape:**
+- `ErrorCode.FORBIDDEN = 40301`
+- `ErrorCode.CONFLICT_USERNAME = 40901`
+- `ErrorCode.CONFLICT_USERCODE = 40902`
+- `ErrorCode.toHttpStatus(40301) == 403`、`toHttpStatus(40901) == 409`、`toHttpStatus(40902) == 409`
+
+- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes`
+- [ ] **Step 2: 实现最小代码** + 改 docs/05
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `chore(usr): docs/05 去 password 字段 + ErrorCode 新增 40301/40901/40902 REQ-USR-002`
+
+### Task 2: LoginContext ThreadLocal
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/security/LoginContext.java`
+- Create: `backend/src/test/java/com/xly/erp/common/security/LoginContextTest.java`
+
+**API shape:**
+- `LoginContext.LoginUser` — record（userId:Integer, username:String, userType:String, companyCode:String）
+- `LoginContext.set(LoginUser)` / `LoginContext.current()` / `LoginContext.clear()`
+- 用 `InheritableThreadLocal` 否，纯 `ThreadLocal`（避免子线程意外继承）
+
+- [ ] **Step 1: 写失败测试**
+  - `LoginContextTest#setAndCurrent_isolatedPerThread` — 两个线程 set 不同值，互不影响
+  - `LoginContextTest#clear_returnsNullForCurrent`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): LoginContext ThreadLocal REQ-USR-002`
+
+### Task 3: @RequireSuperAdmin 注解 + JwtHandlerInterceptor + WebMvcConfig
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java`
+- Create: `backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java`
+- Create: `backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java`
+- Create: `backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java`
+
+**API shape:**
+- `@RequireSuperAdmin` — `@Target(METHOD) @Retention(RUNTIME)`
+- `JwtHandlerInterceptor implements HandlerInterceptor` —— 行为见"约束常量"
+- `WebMvcConfig implements WebMvcConfigurer` —— `addInterceptors(registry)`：注册 JwtHandlerInterceptor，`.addPathPatterns("/api/v1/**").excludePathPatterns("/api/v1/auth/login")`
+
+测试用一个 `@TestController` 暴露 `/api/v1/_test/admin-only`（标 `@RequireSuperAdmin`）和 `/api/v1/_test/any-auth`（不标），MockMvc 调用：
+
+- [ ] **Step 1: 写失败测试**
+  - `noAuthHeader_returns401_40101`
+  - `invalidToken_returns401_40101`
+  - `tokenForDeletedUser_returns401_40101`
+  - `tokenForLockedUser_returns401_40101`
+  - `validToken_normalUser_canAccessAnyAuthEndpoint`
+  - `validToken_normalUser_cannotAccessAdminOnly_returns403_40301`
+  - `validToken_superAdmin_canAccessAdminOnly`
+  - `loginEndpointPath_skipsInterceptor`（鉴权未注入也能调 /api/v1/auth/login）
+  - `loginContext_clearedAfterRequest`（请求结束后 ThreadLocal 应清空）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): JwtHandlerInterceptor + @RequireSuperAdmin REQ-USR-002`
+
+### Task 4: SysPermissionCategory + SysUserPermissionCategory entity + mapper
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java` — 扩展插入 SUPER_ADMIN 用户 + 2 个权限分类，并暴露 alice 的 ID + admin 的 ID + 权限分类 ID 给 Fixture record
+
+**API shape:**
+- entity 字段对齐 docs/03（与 SysUser 一致风格，匈牙利前缀 + Lombok @Data）
+- `SysPermissionCategoryMapper#countActiveByIds(List<Integer> ids) : int`（@Select 显式列，过滤 iIsDeleted=0）
+- `SysUserPermissionCategoryMapper extends BaseMapper<...>`，无自定义方法
+- Fixture record 扩展：`Fixture(aliceId, bobDeletedId, employeeId, adminId, permissionCategoryIds)` 其中 permissionCategoryIds 是 List<Integer>，admin 用户名常量 `USER_ADMIN = "admin"`
+
+- [ ] **Step 1: 写失败测试**
+  - `SysPermissionCategoryMapperTest#countActiveByIds_excludesDeleted`
+  - `LoginTestSeederTest#fixture_includesAdminAndPermissionCategories`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): sys_permission_category + sys_user_permission_category entity/mapper REQ-USR-002`
+
+### Task 5: SysUserMapper 唯一性查询方法
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — 新增 `existsByUsername / existsByUserCode`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java` — 补测试
+
+**API shape:**
+- `SysUserMapper#existsByUsername(String username) : boolean`（@Select `SELECT COUNT(*) > 0 FROM sys_user WHERE sUsername = #{username}`；MyBatis 把 int 0/1 自动转 boolean，或用 Integer 后 service 层做判断）
+- `SysUserMapper#existsByUserCode(String userCode) : boolean`
+
+- [ ] **Step 1: 写失败测试**
+  - `SysUserMapperTest#existsByUsername_trueForExisting / falseForUnknown`
+  - `SysUserMapperTest#existsByUserCode_trueForExisting / falseForUnknown`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 用户名/用户号唯一性查询 REQ-USR-002`
+
+### Task 6: CreateUserReq + CreateUserVo
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/CreateUserReqValidationTest.java`
+- Modify: `backend/src/main/resources/application.yml` — 启用 `spring.jackson.deserialization.fail-on-unknown-properties: true`
+- Modify: `backend/src/main/resources/application-test.yml` — 同上
+
+**API shape:**
+- `CreateUserReq { @NotBlank @Pattern(regexp="^[A-Za-z0-9_]{3,20}$") username, @NotBlank @Size(max=50) userCode, @NotBlank @Pattern(regexp="NORMAL|SUPER_ADMIN") userType, @NotBlank @Pattern(regexp="zh-CN|en-US|zh-TW") language, @NotNull Boolean canEditDocument, Integer employeeId, List<Integer> permissionCategoryIds }`
+- `CreateUserVo { Integer userId; String username; String userCode; }` + @Builder
+
+注意：不定义 `password` 字段；启用 fail-on-unknown-properties 后，请求带 password 会被 Jackson 直接拒绝。Jackson 反序列化异常 → 在 `GlobalExceptionHandler` 已有 `HttpMessageNotReadableException` handler（如果没有，本 Task 顺带补；同 round 1 review 推迟项）
+
+> 实际：round 1 没补 HttpMessageNotReadable handler。本 Task 顺手补到 `GlobalExceptionHandler`，让"包含未知字段"返 40001 / 400 而非 50000。
+
+- [ ] **Step 1: 写失败测试**
+  - `CreateUserReqValidationTest`（10 个用例）：空 / 越长 / 用户名非法字符 / userType 非枚举 / language 非枚举 / canEditDocument 缺失 / employeeId 可空 / permissionCategoryIds 可空 / 全合法 / userCode 越长
+- [ ] **Step 2: 实现最小代码** + 改两份 application yml + 补 HttpMessageNotReadable handler
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): CreateUserReq/Vo + Jackson 严格反序列化 REQ-USR-002`
+
+### Task 7: UserCreateService 接口 + Impl 骨架（仅唯一性 / 外键校验）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java`
+
+**API shape:**
+- `UserCreateService#create(CreateUserReq req, String operatorUsername) : CreateUserVo`
+- `UserCreateServiceImpl` 注入：SysUserMapper / SysEmployeeMapper / SysPermissionCategoryMapper / SysUserPermissionCategoryMapper / BCryptPasswordEncoder
+- 常量 `INITIAL_PASSWORD = "666666"`
+- `@Transactional`
+
+本 Task 范围：实现 4 项校验（唯一用户名、唯一用户号、employeeId 存在、permissionCategoryIds 全部存在），但不实现实际写入——直接返回 dummy CreateUserVo(0, ..., ...)；写入路径在 Task 8。
+
+- [ ] **Step 1: 写失败测试**（service 集成测，复用扩展后的 LoginTestSeeder）
+  - `create_usernameExists_throws40901`
+  - `create_userCodeExists_throws40902`
+  - `create_employeeIdNotFound_throws40004`
+  - `create_employeeIdSoftDeleted_throws40004`
+  - `create_permissionCategoryNotFound_throws40004`（含数组中混入不存在 ID）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserCreateService 唯一性 + 外键校验 REQ-USR-002`
+
+### Task 8: UserCreateService 写入路径（sys_user + sys_user_permission_category 事务）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java`
+
+**API behavior:**
+- 校验全过 → BCrypt encode "666666" → 插入 sys_user（sCreatedBy = operatorUsername）→ 批量插入 sys_user_permission_category（每条 sGrantedBy = operatorUsername）→ 返回 CreateUserVo(新 userId, username, userCode)
+- 捕获 `DataIntegrityViolationException`（如并发同名）→ 抛 40901 / 40902（按异常消息含 `uk_sys_user_username` / `uk_sys_user_code` 判别）
+
+- [ ] **Step 1: 写失败测试**
+  - `create_minimalFields_persistsUserWithInitialPassword`
+  - `create_fullFields_persistsUserAndPermissionMappings`
+  - `create_emptyPermissionCategories_persistsUserOnly`（permissionCategoryIds=空数组 / null 都允许）
+  - `create_initialPasswordMatchesBcrypt666666`（用 BCryptPasswordEncoder.matches("666666", DB hash) == true）
+  - `create_dataIntegrityViolation_username_throws40901`（先 select 返 false 但插入时报 DuplicateKey；用 spy / 模拟难，可在测试用并发场景模拟，或直接抛模拟异常验证转换）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserCreateService 写入用户 + 权限分类授权 REQ-USR-002`
+
+### Task 9: UserController POST /api/v1/users + 端到端测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java`
+
+**API shape:**
+- `UserController` — `@RestController @RequestMapping("/api/v1/users")`
+- `POST /api/v1/users`：标注 `@RequireSuperAdmin`，方法签名 `Result<CreateUserVo> create(@RequestBody @Valid CreateUserReq req)`；调用 `userCreateService.create(req, LoginContext.current().username())`；返回 `ResponseEntity.status(201).body(Result.ok(vo))`
+
+端到端测试（`@SpringBootTest + @AutoConfigureMockMvc`）：用 admin token 调用，覆盖：
+
+- [ ] **Step 1: 写失败测试**
+  - `post_users_success_returns201_andCreatedVo`
+  - `post_users_blankUsername_returns400_40001`
+  - `post_users_invalidUserType_returns400_40001`
+  - `post_users_unknownPropertyPassword_returns400_40001`（请求 body 含 `"password":"...".` 字段）
+  - `post_users_noAuthHeader_returns401_40101`
+  - `post_users_normalUserToken_returns403_40301`
+  - `post_users_deletedUserToken_returns401_40101`
+  - `post_users_duplicateUsername_returns409_40901`
+  - `post_users_duplicateUserCode_returns409_40902`
+  - `post_users_unknownEmployee_returns400_40004`
+  - `post_users_unknownPermissionCategory_returns400_40004`
+  - `post_users_success_canLoginWithInitialPassword`（创建后立即调 /auth/login 用 666666 应成功）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): POST /api/v1/users controller + 端到端测试 REQ-USR-002`
+
+---
+
+## 提交计划
+
+| Task | Commit message |
+|---|---|
+| 1 | `chore(usr): docs/05 去 password 字段 + ErrorCode 新增 40301/40901/40902 REQ-USR-002` |
+| 2 | `feat(usr): LoginContext ThreadLocal REQ-USR-002` |
+| 3 | `feat(usr): JwtHandlerInterceptor + @RequireSuperAdmin REQ-USR-002` |
+| 4 | `feat(usr): sys_permission_category + sys_user_permission_category entity/mapper REQ-USR-002` |
+| 5 | `feat(usr): SysUserMapper 用户名/用户号唯一性查询 REQ-USR-002` |
+| 6 | `feat(usr): CreateUserReq/Vo + Jackson 严格反序列化 REQ-USR-002` |
+| 7 | `feat(usr): UserCreateService 唯一性 + 外键校验 REQ-USR-002` |
+| 8 | `feat(usr): UserCreateService 写入用户 + 权限分类授权 REQ-USR-002` |
+| 9 | `feat(usr): POST /api/v1/users controller + 端到端测试 REQ-USR-002` |
+---
+req_id: REQ-USR-003
+date: 2026-05-15
+spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-003.md
+---
+
+# REQ-USR-003 修改用户 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `GET /api/v1/users/{userId}` + `PUT /api/v1/users/{userId}` 两个端点；PUT 支持部分字段更新 + permissionCategoryIds 增量增删差集 + 自我停用守卫；GET 返回 UserDetailVo（含 employeeName + permissionCategoryIds）。
+
+**Architecture:**
+- 鉴权 / 角色守卫 / 事务 / Result / 异常处理全部复用 REQ-USR-002 基础设施。
+- 新增 `UserUpdateService`（PUT）+ `UserDetailService`（GET），单一职责。
+- permissionCategoryIds 用差集：先 select 现有 → 计算 toAdd / toRemove → DELETE + INSERT 在同一事务。
+- PATCH 语义简化：缺省 / 显式 null 都视为不变；`employeeId=0` 作为约定的"解除关联"信号。
+
+**Tech Stack:** 复用 REQ-USR-002（Spring Boot 3 + MyBatis-Plus + Jakarta Validation）。
+
+---
+
+## Schema 改动
+
+无。
+
+---
+
+## 文件变更清单
+
+**新增**：
+- `backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java`
+- `backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java`
+
+**修改**：
+- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`（新增 40302 / 40401 + 404 映射）
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（新增 `existsByUserCodeExcludingId`）
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java`（新增 `selectPermissionCategoryIdsByUserId` + `deleteByUserAndCategoryIds`）
+- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（新增 GET + PUT 方法）
+
+**文档**：本 REQ 不改 docs/05（已含 REQ-USR-003 段，但 docs/05 当前漏写 GET 详情接口；本 REQ 补充）。
+
+**测试**：
+- `backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java`
+- `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java`
+- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java`（独立文件避免冲击 REQ-USR-002 既有 UserControllerTest）
+
+---
+
+## 约束常量
+
+**ErrorCode 新增**：
+
+| 常量 | 值 | HTTP |
+|---|---|---|
+| `USER_FORBIDDEN_SELF_DEACTIVATE` | `40302` | 403 |
+| `USER_NOT_FOUND` | `40401` | 404 |
+
+> `ErrorCode.toHttpStatus` 已含 401/403/404 段位映射，不需新增。
+
+**API 形状**：
+
+```
+GET /api/v1/users/{userId}      @RequireSuperAdmin
+  → Result<UserDetailVo>
+  errors: 40101, 40301, 40401
+
+PUT /api/v1/users/{userId}      @RequireSuperAdmin
+  body: UpdateUserReq (PATCH)
+  → Result<UserDetailVo>
+  errors: 40001, 40004, 40101, 40301, 40302, 40401, 40902
+
+UserDetailVo {
+  Integer userId, String username, String userCode,
+  String userType, String language, Boolean canEditDocument, Boolean isDeleted,
+  Integer employeeId, String employeeName,
+  List<Integer> permissionCategoryIds,
+  String updatedBy, LocalDateTime updatedDate
+}
+
+UpdateUserReq {
+  String userCode,                   // 缺省/null = 不变
+  String userType,                   // 同上
+  String language,                   // 同上
+  Boolean canEditDocument,           // 同上
+  Integer employeeId,                // 缺省/null = 不变；0 = 解除关联；正整数 = 更新
+  Boolean isDeleted,                 // 同上
+  List<Integer> permissionCategoryIds // 缺省/null = 不变；空数组 = 清空；非空 = 增删差集
+}
+```
+
+**PATCH 语义约定**（写死，跨任务一致）：所有字段缺省 / null 视为 "保持原值"；`employeeId == 0` 视为 "解除关联"，DB 写 NULL。其他字段无清除语义。
+
+---
+
+## 任务步骤
+
+### Task 1: ErrorCode 新增 40302 / 40401 + 404 映射 + docs/05 补 GET 详情段
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java`
+- Modify: `docs/05-API接口契约.md` § REQ-USR-003 之前加 `GET /api/v1/users/{userId}` 段
+
+**API shape:**
+- `ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE = 40302`
+- `ErrorCode.USER_NOT_FOUND = 40401`
+- `ErrorCode.toHttpStatus(40302) == 403`
+- `ErrorCode.toHttpStatus(40401) == 404`
+
+docs/05 补充内容（追加到现 REQ-USR-003 段之前）：
+
+```
+### REQ-USR-003 GET 用户详情
+
+- Method: GET
+- Path: /api/v1/users/{userId}
+- Auth: Bearer Token；仅 userType=SUPER_ADMIN 可调用
+- 请求: Path userId: int
+- 响应: JSON UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds[], updatedBy, updatedDate }
+
+#### 错误码
+- 40101 — 未携带或无效 Token
+- 40301 — 当前用户非超级管理员，无权调用
+- 40401 — 用户不存在
+```
+
+- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes_v003`
+- [ ] **Step 2: 实现最小代码** + docs/05 改动
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `chore(usr): docs/05 补 GET 详情 + ErrorCode 新增 40302/40401 REQ-USR-003`
+
+### Task 2: UpdateUserReq + UserDetailVo
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/UpdateUserReqValidationTest.java`
+
+**API shape**: 见 "约束常量"。
+
+校验注解（仅在字段非 null 时生效，jakarta `@Pattern` 等天然 null-safe）：
+- `userCode`: `@Size(max=50)`
+- `userType`: `@Pattern(regexp="NORMAL|SUPER_ADMIN")`
+- `language`: `@Pattern(regexp="zh-CN|en-US|zh-TW")`
+- `employeeId`: `@Min(0)` （0 = 解除关联约定）
+- 其余字段无 @ 注解
+
+- [ ] **Step 1: 写失败测试** `UpdateUserReqValidationTest` 覆盖：
+  - 全空请求体合法（PATCH，所有字段可选）
+  - userType 非枚举 → 失败
+  - language 非枚举 → 失败
+  - userCode 越长 → 失败
+  - userCode 空字符串 → 失败（@Size 不限定下界，但建议加 @Pattern("\S+") 防空白；本任务不强制）
+  - employeeId=-1 → 失败
+  - employeeId=0 合法（约定的解除关联）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UpdateUserReq + UserDetailVo REQ-USR-003`
+
+### Task 3: SysUserMapper.existsByUserCodeExcludingId
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java`
+
+**API shape:**
+- `SysUserMapper#existsByUserCodeExcludingId(String userCode, Integer excludedUserId) : boolean`
+- SQL: `SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUserCode = #{userCode} AND iIncrement <> #{excludedUserId})`
+
+- [ ] **Step 1: 写失败测试**
+  - `existsByUserCodeExcludingId_otherUserHasCode_returnsTrue` (alice U001, query U001 excluding admin → true)
+  - `existsByUserCodeExcludingId_selfHasCode_returnsFalse` (alice U001, query U001 excluding alice → false)
+  - `existsByUserCodeExcludingId_unknownCode_returnsFalse`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 排除自身的 userCode 唯一查询 REQ-USR-003`
+
+### Task 4: SysUserPermissionCategoryMapper 增删辅助方法
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapperTest.java`
+
+**API shape:**
+- `SysUserPermissionCategoryMapper#selectPermissionCategoryIdsByUserId(Integer userId) : List<Integer>`
+  - SQL: `SELECT iPermissionCategoryId FROM sys_user_permission_category WHERE iUserId = #{userId}`
+- `SysUserPermissionCategoryMapper#deleteByUserAndCategoryIds(@Param("userId") Integer userId, @Param("ids") List<Integer> categoryIds) : int`
+  - SQL: `DELETE FROM sys_user_permission_category WHERE iUserId = #{userId} AND iPermissionCategoryId IN (...)` （@Select script）
+
+- [ ] **Step 1: 写失败测试**
+  - 准备：admin user + 授权 {PUR, SAL}
+  - `selectPermissionCategoryIdsByUserId_returnsAllCurrent`
+  - `deleteByUserAndCategoryIds_onlyDeletesGivenSubset`（删 {PUR} 后剩 {SAL}）
+  - `deleteByUserAndCategoryIds_nonMatchingIds_noop_returns0`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): SysUserPermissionCategoryMapper 查/删辅助方法 REQ-USR-003`
+
+### Task 5: UserDetailService 接口 + 实现
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java`
+
+**API shape:**
+- `UserDetailService#getById(Integer userId) : UserDetailVo`
+- 找不到用户 → `BizException(ErrorCode.USER_NOT_FOUND, "用户不存在")`
+- 包含作废用户（用于恢复启用场景的回显）
+- 装配逻辑：select sys_user → 若 iEmployeeId 非空 select sys_employee.sEmployeeName → selectPermissionCategoryIdsByUserId
+
+- [ ] **Step 1: 写失败测试**
+  - `getById_existingActiveUser_returnsFullVo`（含 employeeName + permissionCategoryIds）
+  - `getById_userWithoutEmployee_employeeNameIsNull`
+  - `getById_userWithoutPermissions_emptyList`
+  - `getById_deletedUser_stillReturned`（iIsDeleted=1 的用户也能查到，VO.isDeleted=true）
+  - `getById_unknownId_throws40401`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserDetailService 用户详情查询 REQ-USR-003`
+
+### Task 6: UserUpdateService 接口 + 校验骨架
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java`
+
+**API shape:**
+- `UserUpdateService#update(Integer userId, UpdateUserReq req, Integer operatorUserId, String operatorUsername) : UserDetailVo`
+- `@Transactional`
+- 注入：SysUserMapper / SysEmployeeMapper / SysPermissionCategoryMapper / SysUserPermissionCategoryMapper / UserDetailService（复用详情装配返回最终 VO）
+
+本 Task 范围：校验路径（不写入），全部抛 BizException 路径覆盖：
+1. `userId` 不存在 → 40401
+2. `req.isDeleted == true && userId == operatorUserId` → 40302
+3. `req.userCode` 非 null 且 `existsByUserCodeExcludingId(userCode, userId)` → 40902
+4. `req.employeeId` 是正整数（非 0）且不存在或软删 → 40004
+5. `req.permissionCategoryIds` 非 null 且非空且含不存在 ID → 40004
+
+- [ ] **Step 1: 写失败测试** 5 个测试覆盖以上路径
+- [ ] **Step 2: 实现最小代码**（更新方法体仅 throw，不写 DB）
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 校验路径骨架 REQ-USR-003`
+
+### Task 7: UserUpdateService 部分字段写入 + employee 三态
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java`
+
+**API behavior:**
+- 校验全过后用 `UpdateWrapper<SysUser>().eq("iIncrement", userId)` 链式 set：
+  - `if (req.userCode != null)` → set sUserCode
+  - `if (req.userType != null)` → set sUserType
+  - `if (req.language != null)` → set sLanguage
+  - `if (req.canEditDocument != null)` → set iCanEditDocument (true → 1, false → 0)
+  - `if (req.employeeId != null)`：req.employeeId == 0 → set iEmployeeId NULL；正整数 → set iEmployeeId 值
+  - `if (req.isDeleted != null)` → set iIsDeleted (true → 1, false → 0)
+  - 总是 set sUpdatedBy=operatorUsername、tUpdatedDate=NOW()
+- 不处理 permissionCategoryIds（推到 Task 8）
+
+- [ ] **Step 1: 写失败测试**
+  - `update_userCode_only_persisted_otherFieldsUnchanged`
+  - `update_userType_language_canEditDocument`
+  - `update_employeeId_positiveInteger_setsToValue`
+  - `update_employeeId_zero_setsToNull`
+  - `update_employeeId_unchanged_preservesOriginalValue`（缺省字段不变）
+  - `update_isDeleted_true_marksUserDeleted`
+  - `update_isDeleted_false_revivesUser`
+  - `update_emptyRequest_onlyUpdatesAuditFields`（sUpdatedBy + tUpdatedDate）
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 部分字段写入 + employeeId 三态 REQ-USR-003`
+
+### Task 8: UserUpdateService permissionCategoryIds 增量差集
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java`
+
+**API behavior:**
+- 仅当 `req.permissionCategoryIds != null` 时执行：
+  - `current = selectPermissionCategoryIdsByUserId(userId)`（Set 化以便比较）
+  - `target = new HashSet<>(req.permissionCategoryIds)`（dedup）
+  - `toRemove = current \ target` → `deleteByUserAndCategoryIds(userId, toRemove)`（若 toRemove 非空）
+  - `toAdd = target \ current` → 循环 insert SysUserPermissionCategory（sGrantedBy=operator）
+- 返回 `userDetailService.getById(userId)` 作为响应（聚合最新状态）
+
+- [ ] **Step 1: 写失败测试**
+  - `update_permissionCategories_emptyList_clearsAll`（初始 {PUR,SAL} → 请求 [] → 最终 ∅）
+  - `update_permissionCategories_subsetDelta_addsAndRemoves`（初始 {PUR,SAL} → 请求 [SAL, 新分类 X] → 最终 {SAL, X}）；断言 SAL 行 iIncrement 不变（差集而非全量替换）
+  - `update_permissionCategories_omitted_preservesExisting`（请求中无 permissionCategoryIds → 不动）
+  - `update_permissionCategories_duplicateInRequest_deduped`（请求 [PUR, PUR, SAL] → 最终 {PUR, SAL}）
+  - `update_returnsUserDetailVoReflectingFinalState`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 权限分类增量增删差集 REQ-USR-003`
+
+### Task 9: UserController GET + PUT + 端到端测试
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（追加 GET + PUT 方法）
+- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java`
+
+**API shape:**
+- `@GetMapping("/{userId}") @RequireSuperAdmin getById(@PathVariable Integer userId) : Result<UserDetailVo>`
+- `@PutMapping("/{userId}") @RequireSuperAdmin update(@PathVariable Integer userId, @RequestBody @Valid UpdateUserReq req) : Result<UserDetailVo>`
+- PUT 调用 `userUpdateService.update(userId, req, LoginContext.current().userId(), LoginContext.current().username())`
+
+端到端测试（覆盖 spec § 验收 1-23）：
+
+**GET（5 个）**：
+- `get_existingUser_returns200_andFullVo`
+- `get_unknownUser_returns404_40401`
+- `get_normalUser_returns403_40301`
+- `get_noAuthHeader_returns401_40101`
+- `get_deletedUser_stillReturns200`
+
+**PUT（16 个）**：
+- `put_updateUserCodeAndType_returns200`
+- `put_updateEmployeeId_toAnotherEmployee`
+- `put_updateEmployeeId_zero_clearsRelation`
+- `put_updateEmployeeId_unknown_returns400_40004`
+- `put_isDeletedTrue_marksAndOriginalTokenRejectedNextCall`（修改后用旧 token 调 GET 应得 40101）
+- `put_permissionCategories_subsetDelta`（断言差集行为）
+- `put_permissionCategories_emptyArray_clearsAll`
+- `put_permissionCategories_unknownId_returns400_40004_andRollsBack`（断言事务回滚——sys_user 也未被改）
+- `put_duplicateUserCode_returns409_40902`
+- `put_userCodeUnchangedSameAsSelf_returns200`
+- `put_selfDeactivate_returns403_40302`
+- `put_unknownProperty_username_returns400_40001`
+- `put_unknownProperty_password_returns400_40001`
+- `put_unknownUserId_returns404_40401`
+- `put_normalUser_returns403_40301`
+- `put_emptyBody_only_updates_audit_fields`
+
+- [ ] **Step 1: 写失败测试** （21 个测试）
+- [ ] **Step 2: 实现最小代码**（在现有 UserController 上追加方法）
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): GET + PUT /api/v1/users/{userId} controller + 端到端测试 REQ-USR-003`
+
+---
+
+## 提交计划
+
+| Task | Commit message |
+|---|---|
+| 1 | `chore(usr): docs/05 补 GET 详情 + ErrorCode 新增 40302/40401 REQ-USR-003` |
+| 2 | `feat(usr): UpdateUserReq + UserDetailVo REQ-USR-003` |
+| 3 | `feat(usr): SysUserMapper 排除自身的 userCode 唯一查询 REQ-USR-003` |
+| 4 | `feat(usr): SysUserPermissionCategoryMapper 查/删辅助方法 REQ-USR-003` |
+| 5 | `feat(usr): UserDetailService 用户详情查询 REQ-USR-003` |
+| 6 | `feat(usr): UserUpdateService 校验路径骨架 REQ-USR-003` |
+| 7 | `feat(usr): UserUpdateService 部分字段写入 + employeeId 三态 REQ-USR-003` |
+| 8 | `feat(usr): UserUpdateService 权限分类增量增删差集 REQ-USR-003` |
+| 9 | `feat(usr): GET + PUT /api/v1/users/{userId} controller + 端到端测试 REQ-USR-003` |
+---
+req_id: REQ-USR-004
+date: 2026-05-15
+spec_ref: docs/superpowers/specs/2026-05-15-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:** 实现 `GET /api/v1/users` 分页 + 多字段筛选 + 排序的用户列表查询；服务端做白名单 + 类型转换 + 越界矫正；输出 PageResult<UserListItemVo>（JOIN sys_employee/sys_department 取员工名 / 部门名）。
+
+**Architecture:**
+- 复用 REQ-USR-002 / 003 已建的鉴权 + 角色守卫 + 异常处理。
+- 新增 `UserListService` 单一职责；动态 SQL 通过 MyBatis XML（@Select script 也可，本任务用 XML 便于维护）实现 JOIN + WHERE 动态拼接。
+- 白名单映射：queryField / sortField / matchMode / sortOrder 全部在 service 层校验后才进 SQL。
+- 越界矫正在 service 层：先查目标 page，若 records 为空但 total>0 → 重算 lastPage 再查。
+- PageResult 引入为通用类（放 common.response 包，供后续 REQ 复用）。
+
+**Tech Stack:** 复用 Spring Boot 3 + MyBatis-Plus（本 REQ 用 mapper XML 写动态查询）+ Jakarta Validation。
+
+---
+
+## Schema 改动
+
+无。
+
+---
+
+## 文件变更清单
+
+**新增（通用）**：
+- `backend/src/main/java/com/xly/erp/common/response/PageResult.java`
+
+**新增（业务）**：
+- `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java`
+- `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java`
+- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java`
+- `backend/src/main/resources/mapper/usr/SysUserMapper.xml`
+
+**修改**：
+- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`（新增 INVALID_ENUM_PARAM=40003）
+- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（新增 selectByQuery + countByQuery）
+- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（新增 GET / list 方法）
+
+**测试**：
+- `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java`
+- `backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java`
+- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java`
+
+---
+
+## 约束常量
+
+**ErrorCode 新增**：
+
+| 常量 | 值 | HTTP |
+|---|---|---|
+| `INVALID_ENUM_PARAM` | `40003` | 400 |
+
+> ErrorCode.toHttpStatus(40003) → 400/100=400，已在现有映射，新增常量即可。
+
+**白名单常量**（全部定义在 `UserListServiceImpl` 的 `static final Map`）：
+
+```
+SORT_FIELDS = {"tCreateDate", "tLastLoginDate", "sUsername", "sUserCode"}
+
+QUERY_FIELD_TO_SQL = {
+    "username":       "u.sUsername",
+    "employeeName":   "e.sEmployeeName",
+    "userCode":       "u.sUserCode",
+    "departmentName": "d.sDepartmentName",
+    "userType":       "u.sUserType",
+    "isDeleted":      "u.iIsDeleted",
+    "lastLoginDate":  "u.tLastLoginDate",
+    "createdBy":      "u.sCreatedBy"
+}
+
+MATCH_MODES = {"contains", "notContains", "equals"}
+SORT_ORDERS = {"asc", "desc"}
+
+USER_TYPES = {"NORMAL", "SUPER_ADMIN"}
+
+DEFAULT_PAGE = 1
+DEFAULT_SIZE = 20
+MAX_SIZE = 100
+DEFAULT_SORT_FIELD = "tCreateDate"
+DEFAULT_SORT_ORDER = "desc"
+DEFAULT_MATCH_MODE = "contains"
+```
+
+**API 形状**：
+
+```
+GET /api/v1/users?page=1&size=20&sortField=tCreateDate&sortOrder=desc
+                 &queryField=username&matchMode=contains&queryValue=ali
+                 &userType=NORMAL&isDeleted=false
+@RequireSuperAdmin
+→ Result<PageResult<UserListItemVo>>
+
+PageResult<T> {
+  List<T> records;
+  long total;
+  int page;
+  int size;
+}
+
+UserListItemVo {
+  Integer userId, String username, String employeeName, String userCode,
+  String departmentName, String userType, String language,
+  Boolean isDeleted, LocalDateTime lastLoginDate,
+  String createdBy, LocalDateTime createdDate
+}
+
+UserQueryReq {
+  Integer page,         // @Min(1)
+  Integer size,         // @Min(1) @Max(100)
+  String sortField,
+  String sortOrder,
+  String queryField,
+  String matchMode,
+  String queryValue,
+  String userType,
+  Boolean isDeleted
+}
+```
+
+---
+
+## 任务步骤
+
+### Task 1: ErrorCode 新增 40003 + PageResult 通用类
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Create: `backend/src/main/java/com/xly/erp/common/response/PageResult.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java`
+
+**API shape:**
+- `ErrorCode.INVALID_ENUM_PARAM = 40003`
+- `ErrorCode.toHttpStatus(40003) == 400`
+- `PageResult<T> { records: List<T>; total: long; page: int; size: int }` + @Builder
+
+- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes_v004` 验 40003→400
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): ErrorCode 新增 40003 + PageResult 通用类 REQ-USR-004`
+
+### Task 2: UserQueryReq DTO + UserListItemVo
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java`
+
+**API shape:**
+- `UserQueryReq` 所有字段可选；jakarta 注解只用 `@Min(1)`（page）、`@Min(1) @Max(100)`（size）；其他枚举值在 service 层做白名单校验（不用 @Pattern，因为 @Pattern 失败会落到 40001，本 REQ 要 40003）
+- `UserListItemVo` 字段同 spec § 输出
+
+- [ ] **Step 1: 写失败测试** 5 个用例：
+  - 全空合法（PATCH 风格）
+  - page=0 → @Min(1) 失败
+  - size=101 → @Max(100) 失败
+  - size=0 → @Min(1) 失败
+  - 全合法字段 → pass
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserQueryReq + UserListItemVo + PageResult REQ-USR-004`
+
+### Task 3: SysUserMapper.selectByQuery + countByQuery (XML)
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（声明方法）
+- Create: `backend/src/main/resources/mapper/usr/SysUserMapper.xml`（动态 SQL）
+- Modify: `backend/src/main/resources/application.yml`（mybatis-plus.mapper-locations: classpath*:/mapper/**/*.xml）
+- Modify: `backend/src/main/resources/application-test.yml`（同上）
+- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperQueryTest.java`
+
+**API shape:**
+- `SysUserMapper#selectByQuery(@Param("p") QueryParams p) : List<UserListItemRow>`
+- `SysUserMapper#countByQuery(@Param("p") QueryParams p) : long`
+- `QueryParams` — 内部 record / DTO，包含已通过白名单校验的字段：`sqlSortField`（列名）, `sqlSortOrder`（asc/desc）, `sqlQueryColumn`（已映射列名 OR null）, `matchMode`, `queryValue`, `userType`, `isDeleted`（Integer 0/1 或 null）, `offset`, `limit`
+
+> service 层把 spec 入参规范化为 `QueryParams`，mapper XML 用 `${}` 拼接 `sqlSortField` / `sqlSortOrder` / `sqlQueryColumn`（白名单值），用 `#{}` 绑定 queryValue / userType / isDeleted / offset / limit。
+
+XML 关键片段（仅作为 plan 锁定的契约，TDD 实现可改细节）：
+
+```xml
+<sql id="baseFrom">
+  FROM sys_user u
+  LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId
+  LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId
+</sql>
+
+<sql id="whereClause">
+  <where>
+    <if test="p.sqlQueryColumn != null and p.queryValue != null and p.queryValue != ''">
+      <choose>
+        <when test="p.matchMode == 'contains'">
+          AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%')
+        </when>
+        <when test="p.matchMode == 'notContains'">
+          AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%')
+               OR ${p.sqlQueryColumn} IS NULL)
+        </when>
+        <otherwise>
+          AND ${p.sqlQueryColumn} = #{p.queryValue}
+        </otherwise>
+      </choose>
+    </if>
+    <if test="p.userType != null">AND u.sUserType = #{p.userType}</if>
+    <if test="p.isDeleted != null">AND u.iIsDeleted = #{p.isDeleted}</if>
+  </where>
+</sql>
+
+<select id="selectByQuery" resultType="com.xly.erp.module.usr.vo.UserListItemVo">
+  SELECT u.iIncrement AS userId, u.sUsername AS username,
+         e.sEmployeeName AS employeeName, u.sUserCode AS userCode,
+         d.sDepartmentName AS departmentName, u.sUserType AS userType,
+         u.sLanguage AS language, u.iIsDeleted AS isDeleted,
+         u.tLastLoginDate AS lastLoginDate, u.sCreatedBy AS createdBy,
+         u.tCreateDate AS createdDate
+  <include refid="baseFrom"/>
+  <include refid="whereClause"/>
+  ORDER BY u.${p.sqlSortField} ${p.sqlSortOrder}
+  LIMIT #{p.offset}, #{p.limit}
+</select>
+
+<select id="countByQuery" resultType="long">
+  SELECT COUNT(*)
+  <include refid="baseFrom"/>
+  <include refid="whereClause"/>
+</select>
+```
+
+> MyBatis-Plus 默认 `mapper-locations: classpath*:/mapper/**/*.xml`，但需在 application.yml 显式声明以确保 XML 被加载。当前 application.yml 仅声明了 mybatis-plus 配置项，未声明 mapper-locations；本任务添加。
+
+- [ ] **Step 1: 写失败测试** `SysUserMapperQueryTest`：
+  - `count_noFilters_returnsAllRows`
+  - `select_withSortByUsername_ascending`
+  - `select_withQueryFieldUsername_contains`
+  - `select_joinsEmployeeAndDepartment_returnsBothNames`
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 动态查询 XML + JOIN 员工/部门 REQ-USR-004`
+
+### Task 4: UserListService 白名单 + 越界矫正
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java`
+
+**API shape:**
+- `UserListService#list(UserQueryReq req) : PageResult<UserListItemVo>`
+- 内部规范化流程：
+  1. 应用默认值（page=1, size=20, sortField=tCreateDate, sortOrder=desc, matchMode=contains）
+  2. 白名单校验：sortField / sortOrder / queryField / matchMode / userType — 不在白名单抛 `BizException(40003)` 或 `BizException(40001)` 按入参类型决定
+  3. queryField→sqlQueryColumn 映射；queryValue 转换（对 isDeleted 列：'true'→1, 'false'→0；其他不在 {true,false,0,1} 抛 40001）
+  4. 越界矫正：先查 `selectByQuery(目标 page)`；若 records 空 && total>0 → 重算 lastPage 再查；响应 page 反映实际页
+
+> userType 入参既可作 explicit query param 也可作 queryField=userType+queryValue。两条路径都要走白名单校验。
+
+- [ ] **Step 1: 写失败测试** 12 个用例覆盖 spec 验收 5-21
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): UserListService 白名单校验 + 动态查询 + 越界矫正 REQ-USR-004`
+
+### Task 5: UserController GET / + 端到端测试
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（追加 GET / 方法）
+- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java`
+
+**API shape:**
+- `@GetMapping @RequireSuperAdmin list(@Valid UserQueryReq req) : Result<PageResult<UserListItemVo>>`
+- 用 `@ModelAttribute` 或省略让 Spring 默认从 query 绑定 DTO
+
+端到端测试（覆盖 spec § 验收 1-26）：
+
+GET 路径（admin token）：
+- `list_default_returnsAllUsersSortedByCreateDateDesc`
+- `list_pagination_secondPage`
+- `list_sizeOver100_returns400_40001`
+- `list_pageZero_returns400_40001`
+- `list_sortByUsernameAsc`
+- `list_sortFieldInvalid_returns400_40003`
+- `list_sortOrderInvalid_returns400_40001`
+- `list_queryByUsernameContains`
+- `list_queryByUsernameEquals_returnsExactOne`
+- `list_queryByUsernameNotContains`
+- `list_queryByEmployeeName_joinsCorrectly`
+- `list_queryByDepartmentName_multiLevelJoin`
+- `list_queryByUserType_equals`
+- `list_queryByIsDeletedTrue_filtersDeleted`
+- `list_queryFieldInvalid_returns400_40003`
+- `list_matchModeInvalid_returns400_40003`
+- `list_queryFieldWithoutValue_skipsCondition`
+- `list_explicitUserTypeFilter`
+- `list_explicitUserTypeInvalid_returns400_40001`
+- `list_explicitIsDeletedFalse_filtersActiveOnly`
+- `list_composedFilters_andSemantics`（queryField+queryValue + userType + isDeleted）
+- `list_pageBeyondTotal_returnsLastPage`
+- `list_normalUserToken_returns403_40301`
+- `list_noAuthHeader_returns401_40101`
+- `list_responseDoesNotContainPasswordField`
+- `list_emptyTable_returnsZeroTotal`（drop + recreate 用户为空时）
+
+- [ ] **Step 1: 写失败测试**
+- [ ] **Step 2: 实现最小代码**
+- [ ] **Step 3: 子会话验证 PASS**
+- [ ] **Step 4: Commit** `feat(usr): GET /api/v1/users controller + 端到端测试 REQ-USR-004`
+
+---
+
+## 提交计划
+
+| Task | Commit message |
+|---|---|
+| 1 | `feat(usr): ErrorCode 新增 40003 + PageResult 通用类 REQ-USR-004` |
+| 2 | `feat(usr): UserQueryReq + UserListItemVo + PageResult REQ-USR-004` |
+| 3 | `feat(usr): SysUserMapper 动态查询 XML + JOIN 员工/部门 REQ-USR-004` |
+| 4 | `feat(usr): UserListService 白名单校验 + 动态查询 + 越界矫正 REQ-USR-004` |
+| 5 | `feat(usr): GET /api/v1/users controller + 端到端测试 REQ-USR-004` |
+---
+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-002
+date: 2026-05-15
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-002 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:82 — DataIntegrityViolationException 转 40901/40902 用 message 文本匹配，与驱动版本/locale 强耦合；建议改判 SQLState='23000' + 错误号 1062，并补 @SpyBean Mockito 回归测试（spec § 15 唯一索引并发兜底测试缺口）
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:93 — 权限分类批量插入用 for + 单条 insert（N 次 IO）；建议改 saveBatch 或在注释里写明 'N < 20 不批量'
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:57 — countActiveByIds 用 COUNT(*) + size 比较，重复 ID（如 [1,1,2]）会误判 40004；建议先 dedup 或改用 COUNT(DISTINCT iIncrement)
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:52 — employee/permissionCategory 校验失败抛 COMPANY_NOT_FOUND 但 message 含义错位；后续可拆 RESOURCE_NOT_FOUND 段位或重命名 COMPANY_NOT_FOUND → REFERENCE_NOT_FOUND
+- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:48 — 每请求 1 次 selectByUsername DB 查询；后续可加 Caffeine 短期缓存（容量评估时再做）
+- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:60 — claims.get('companyCode') 未做 null 校验；建议在 LoginUser 处文档化或加 log.warn
+- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:66 — set LoginContext 早于角色守卫；建议加注释说明该顺序是有意的，afterCompletion 保证清理
+- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:35 — plan 声明 'handler 非 HandlerMethod → return true'，实际未实现该顶部短路；建议补齐对齐 plan
+- backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java:124 — plan 列出 `loginContext_clearedAfterRequest` 测试用例但未实现；建议补显式清理回归
+- backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java:24 — userType/language 用 @Pattern 枚举校验失类型安全；可改为 service 层 toEnum 模式
+- backend/src/main/resources/application.yml:8 — fail-on-unknown-properties=true 是全局开关；建议在 docs/04 § 1.3 留痕说明所有 DTO 必须完整定义
+- backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java:28 — LoginContext.current() 未 null 校验；建议加防御性 Optional.ofNullable
+- backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java:17 — entity 含未写入的多租户字段（sId/sBrandsId 等），与 SysUser 风格一致，可接受
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 15「唯一索引兜底（DataIntegrityViolationException 路径）」未实测——UserCreateServiceImplTest 缺乏对 catch 分支的回归
+2. plan § Step 1 列出 `loginContext_clearedAfterRequest` 但实际未实现，ThreadLocal 清理路径无显式回归
+3. docs/04 § 1.3 段位（10xxx/20xxx/...）与代码 / docs/05 实际使用的 HTTP-aligned 段位（40001/40101/40301/...）冲突——round 1 REQ-USR-001 已记录，本 REQ 沿用未拉齐；建议单独 PR 修订 docs/04 § 1.3
+4. `permissionCategoryIds` 含重复 ID 行为未定义（countActiveByIds 用 COUNT(*) + size 会 false-negative），无对应测试
+
+## 总结
+
+REQ-USR-002 整体实现质量较高：鉴权 / 角色守卫拦截器流程清晰、事务边界正确、唯一性预检 + DB 兜底双层防御、初始密码 BCrypt 哈希、Jackson 严格反序列化拒绝 password 字段、85 测试覆盖 spec 验收 1-14。文档同步（docs/05 删除 password+40002）已完成，错误码新增 40301/40901/40902 + HTTP 映射准确。功能、安全、文档与 plan/spec 三方一致，无高/中级阻塞问题。Approve。
+---
+req_id: REQ-USR-003
+date: 2026-05-15
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-003 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- docs/05-API接口契约.md PUT § REQ-USR-003 错误码列表缺 40101（GET 段已列）— 本轮归档前已修
+- docs/superpowers/specs/2026-05-15-REQ-USR-003.md § 输入表行写 "显式 null 表示解除关联"，与 § PATCH 语义实现细节的 "null = 不变；employeeId=0 = 解除关联" 约定矛盾；代码遵循后者，建议日后回填修订前者
+- backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java:52 — existsByUserCodeExcludingId 未过滤 iIsDeleted；如希望软删用户不参与唯一性，可补 `AND iIsDeleted=0`，但当前 spec 未要求
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java:108 — permissionCategoryIds 差集流程在 @Transactional 内无行锁；并发 PUT 同一用户可能出现交叉写入。建议未来引入 sys_user.iVersion 做乐观锁
+- backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java:127 — update_employeeId_positiveInteger_setsToValue 注释 '避开自我停用守卫' 误导（本测试不会触发守卫）；建议改用合法对手用户或删除该注释
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java:78 — 复用 COMPANY_NOT_FOUND（40004）抛"权限分类不存在"，常量名与 message 字面冲突；建议未来将 40004 重命名为更通用的 RELATED_ENTITY_NOT_FOUND 或拆分专用 code（跨模块技术债）
+
+## 反例 / 测试覆盖缺口
+
+无功能或安全级 gap。spec 验收 1-22 全部映射到测试；验收 23（作废用户登录 40103）spec 明确声明属 REQ-USR-001 既有路径，符合约定。事务边界（@Transactional + BizException extends RuntimeException + Spring 默认回滚）正确；自我停用守卫精确；userCode 唯一性"自身同值跳过查询"优化有效；employee 三态（null/0/正整数）与 permissionCategoryIds 三态（缺省/空数组/非空）语义清晰且测试覆盖；作废即时生效由 JwtHandlerInterceptor 每请求重查保证；权限分类差集策略保留项 iIncrement 不变已用单测显式断言。N+1 仅出现在 UserDetailService（user + employee + pcIds 三查），单详情场景可接受。
+
+## 总结
+
+REQ-USR-003 实现严格对齐 spec / plan：GET + PUT 共用 UserDetailVo、PATCH 三态、permissionCategoryIds 增删差集、自我停用守卫、userCode 唯一性排除自身、作废即时生效、事务回滚全部正确实现，147 测试覆盖 spec 验收 1-22。仅有若干文档不一致与可读性建议，本轮归档前已补 docs/05 PUT 错误码 40101。无功能/安全/正确性阻塞。Approve。
+---
+req_id: REQ-USR-004
+date: 2026-05-15
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-004 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java:148 — `normalizeQueryValue` 用全限定 `java.time.LocalDate.parse` 而非顶部 import，纯风格瑕疵
+- matchMode 白名单校验在 forced-equals 覆盖之前；调用方传 matchMode=contains + queryField=isDeleted 时白名单接受 contains 再静默覆盖为 equals — 行为正确但稍不透明，可加 logger.debug 留痕
+- UserListServiceImplTest 末尾 `@Autowired JdbcTemplate jdbc` 字段定义在测试方法之后，风格不一致；建议挪到类顶部
+- round 1 已标记『推迟』的 4 项保持不变（queryField=userType 不走 USER_TYPES 白名单；UserQueryParams public 可变字段；list_emptyTable_returnsZeroTotal 命名；mapper ORDER BY 硬编码 u.* 前缀）
+
+## 反例 / 测试覆盖缺口
+
+Round 2 测试覆盖完整：spec § 业务规则 3 的 isDeleted/lastLoginDate matchMode 强制 equals + 类型归一化由 3 个新测试明确断言；spec § 验收 1-26 由 198+3 测试映射；spec § 验收 26 空表场景由 list_emptyTable_returnsZeroTotal（虽命名不准）覆盖。Reviewer 子会话无本地 MySQL，未独立复跑 mvn test；信任 commit 8bf84c9 + 主会话 feature-verify 报告的 201/0 结果。
+
+## 本轮变更归档
+
+Round 1 全部修复落地：
+
+| # | 项目 | 状态 |
+|---|------|-----|
+| M1 | EQUALS_ONLY_FIELDS 强制 matchMode=equals | ✓ 仅在 queryField+queryValue 都非空时覆盖，scoped 严格，不影响其他路径 |
+| M2 | lastLoginDate 类型归一化 | ✓ 支持 LocalDateTime / LocalDate，非法值抛 40001 |
+| M3 | queryValue 用 isBlank 判空 | ✓ |
+| M4 | docs/05 错误码补 sortField + 40101 | ✓ |
+| Test | 新增 3 个回归测试 | ✓ |
+
+未引入新回归。verdict=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 抽样验证即可）。
+---
+req_id: REQ-USR-002
+date: 2026-05-15
+module: module_usr
+---
+
+# Spec: REQ-USR-002 — 新增用户
+
+## 目标
+
+超级管理员通过 `POST /api/v1/users` 新建用户账号。账号立即生效；初始密码由系统统一设为 `666666`（哈希后存入）；可选关联职员；同时按勾选写入权限分类授权关系。
+
+## 输入 / 触发
+
+HTTP 入口 `POST /api/v1/users`。要求请求头 `Authorization: Bearer <accessToken>`。
+
+**请求体 CreateUserReq**（JSON）：
+
+| 字段 | 类型 | 必填 | 校验规则 |
+|---|---|---|---|
+| `username` | string | 是 | 非空；3-20 位字母数字下划线（正则 `^[A-Za-z0-9_]{3,20}$`）；系统内唯一（命中 `sys_user.sUsername` 返 40901） |
+| `userCode` | string | 是 | 非空；最大 50；系统内唯一（命中 `sys_user.sUserCode` 返 40902） |
+| `userType` | string | 是 | 枚举 `NORMAL` / `SUPER_ADMIN` |
+| `language` | string | 是 | 枚举 `zh-CN` / `en-US` / `zh-TW` |
+| `canEditDocument` | boolean | 是 | true / false |
+| `employeeId` | int | 否 | 若不为 null，必须命中 `sys_employee.iIncrement` AND `iIsDeleted=0`，否则返 40004 |
+| `permissionCategoryIds` | int[] | 否 | 可为空数组或省略；每个元素必须命中 `sys_permission_category.iIncrement` AND `iIsDeleted=0`，否则返 40004 |
+
+> **本 REQ 不接受 `password` 字段**：用户提交的任何 password 字段被忽略（或返 40001）。docs/05 应同步删除 `password` 与 `40002` —— 本 REQ 落地时由实现方在 docs/05 一并修订（spec 自审范畴）。
+
+## 输出 / 结果
+
+**成功 201 Created**：`Result<CreateUserVo>`
+
+```json
+{ "code": 200, "message": "操作成功", "data": { "userId": 42, "username": "alice", "userCode": "U001" }, "timestamp": ... }
+```
+
+> HTTP 201 体现新资源创建；body 仍走统一 `Result` 包装（docs/04 § 1.3）。
+
+副作用（同一事务）：
+1. `sys_user` 插入一条新记录：
+   - `sPasswordHash` = `BCryptPasswordEncoder.encode("666666")`
+   - `iFailedLoginCount` = 0、`tLockUntil` = NULL、`tLastLoginDate` = NULL
+   - `iIsDeleted` = 0
+   - `sCreatedBy` = 当前登录用户 username（来自 JWT claim）
+2. `sys_user_permission_category` 按 `permissionCategoryIds` 批量插入授权记录，`sGrantedBy` = 当前登录用户 username
+
+**失败**：
+
+| HTTP | code | 含义 | 触发条件 |
+|---|---|---|---|
+| 400 | 40001 | 必填字段缺失或格式错误 | jakarta 校验失败（@NotBlank / @Pattern / 枚举不合法）；请求包含 `password` 字段（本 REQ 不允许） |
+| 400 | 40004 | 员工或权限分类不存在 | `employeeId` 或 `permissionCategoryIds` 中任一不命中 |
+| 401 | 40101 | 未携带或无效 Token | Authorization 缺失 / 解析失败 / 用户已作废 / 用户已锁定 |
+| 403 | 40301 | 非超级管理员调用 | JWT claim `userType != SUPER_ADMIN` |
+| 409 | 40901 | 用户名已存在 | sUsername 唯一冲突（DB 唯一键 `uk_sys_user_username` 兜底；service 层 select 预检以返友好错误） |
+| 409 | 40902 | 用户号已存在 | sUserCode 唯一冲突 |
+
+## 业务规则
+
+1. **鉴权**：手写 `JwtHandlerInterceptor` 实现 `HandlerInterceptor`，注册到 `WebMvcConfigurer`，匹配 `/api/v1/**` 但排除 `/api/v1/auth/login`：
+   - 读 `Authorization: Bearer <token>` 头；缺失 → 抛 `BizException(40101, "未携带 token")`
+   - `JwtUtil.parse(token)` 抛 BizException 时透传（JwtUtil 内部已返 40101）
+   - 解析 claims → 查 `sys_user.iIncrement = sub`；若不存在 / `iIsDeleted=1` / `tLockUntil > NOW()` → 抛 `BizException(40101, "token 关联用户不可用")`
+   - 把 username / userType / userId / companyCode 放入 `LoginContext`（ThreadLocal 工具）供后续使用
+   - 业务方法结束时（`afterCompletion`）清理 ThreadLocal
+2. **角色守卫**：用自定义注解 `@RequireSuperAdmin`（标注在 controller 方法上）+ 同一 interceptor 检查 `handler instanceof HandlerMethod && method.isAnnotationPresent(...)` → 校验 `LoginContext.userType == SUPER_ADMIN`；不匹配 → 抛 `BizException(40301, "权限不足，仅超级管理员可调用")`
+3. **唯一性校验**：在 service 写入前用 `selectByUsername` / `selectByUserCode` 查重（友好返 40901 / 40902）；DB 唯一索引兜底（捕获 `DataIntegrityViolationException` 转 40901 或 40902，避免堆栈泄漏）
+4. **外键校验**：employeeId / permissionCategoryIds 在写入前一次性 select 校验（SELECT iIncrement FROM ... WHERE iIncrement IN(...) AND iIsDeleted=0），数量不齐 → 40004
+5. **初始密码**：固定字符串 `"666666"`，通过 `BCryptPasswordEncoder.encode` 哈希；常量定义在 `LoginServiceImpl.INITIAL_PASSWORD`（已存在）或新建 `UserCreateServiceImpl.INITIAL_PASSWORD`
+6. **事务**：`@Transactional`，sys_user 插入 + sys_user_permission_category 批量插入在同一事务；唯一冲突或 FK 不存在均回滚
+7. **本 REQ 不接受 password 字段**：DTO 不定义 password 属性；若客户端误传，Jackson 默认配置（`FAIL_ON_UNKNOWN_PROPERTIES=false`）会忽略——但为防御性，建议 `application.yml` 设 `spring.jackson.deserialization.fail-on-unknown-properties: true`，确保多余字段返 40001
+
+## 边界与约束
+
+- **HTTPS / 鉴权 / 统一响应 / 异常**：复用 REQ-USR-001 已建的全部基础设施
+- **HandlerInterceptor 位置**：放在 `backend/src/main/java/com/xly/erp/common/security/`，与 `JwtUtil` 同包
+- **ThreadLocal 工具**：`LoginContext` 单例，提供 `current() / set() / clear()`；测试场景可手工 set 以模拟登录态
+- **@RequireSuperAdmin 注解**：放在 `backend/src/main/java/com/xly/erp/common/security/`
+- **不实现**：
+  - 修改密码 / 重置密码（推迟到后续 REQ）
+  - 用户软删除接口（推迟到 REQ-USR-003 的"作废"路径）
+  - 权限分类的新增 / 编辑（运营模块）
+  - 员工的 CRUD（HR 模块）
+  - JWT 黑名单 / refresh token / 多端互踢（推迟）
+- **docs/05 同步修订**：本 REQ 实现时需同步修订 docs/05 § REQ-USR-002，去掉 `password` 字段与 `40002` 错误码（与 REQ 卡片对齐为"系统生成初始密码"）
+
+## 依赖的 schema 表 / 字段
+
+写 `sys_user`（V1 已建）：
+- 写入：`sUsername`, `sUserCode`, `sPasswordHash`, `iEmployeeId`, `sUserType`, `sLanguage`, `iCanEditDocument`, `iIsDeleted=0`, `iFailedLoginCount=0`, `sCreatedBy`
+
+写 `sys_user_permission_category`（V1 已建）：
+- 写入：`iUserId`, `iPermissionCategoryId`, `sGrantedBy`
+
+只读 `sys_employee`（V1 已建）：
+- 读：`iIncrement`, `iIsDeleted`（校验 employeeId 存在）
+
+只读 `sys_permission_category`（V1 已建）：
+- 读：`iIncrement`, `iIsDeleted`（校验 permissionCategoryIds 全部存在）
+
+**本 REQ 不需要新增 migration**。
+
+## 依赖的接口
+
+- 本 REQ 提供：`POST /api/v1/users`
+- 鉴权前置依赖：JWT 由 REQ-USR-001 签发
+- 下游会消费但本 REQ 不实现的接口：
+  - `GET /api/v1/employees`（员工下拉，后续 HR 模块）
+  - `GET /api/v1/permission-categories`（权限分类下拉，后续运营模块）
+
+## 验收标准
+
+后端集成测试：
+
+1. **正常路径（最小字段）**：管理员 token + 合法 username / userCode / userType / language / canEditDocument，不带 employeeId / permissionCategoryIds → 201；DB 出现新用户记录，`sPasswordHash` 非空且可被 `BCryptPasswordEncoder.matches("666666", ...)` 验证；`iIsDeleted=0`，`iFailedLoginCount=0`，`sCreatedBy` = 管理员 username
+2. **正常路径（完整字段）**：带 employeeId + permissionCategoryIds（2 条）→ 201；DB sys_user 一行 + sys_user_permission_category 两行；`sGrantedBy` 正确
+3. **新用户立刻可登录**：调用 `POST /api/v1/auth/login` 用初始密码 `666666` + 任意有效公司 → 200 + token
+4. **缺 Authorization 头** → 401 / 40101
+5. **Token 无效（篡改）** → 401 / 40101
+6. **Token 关联用户已作废** → 401 / 40101
+7. **NORMAL 用户 token 调用** → 403 / 40301
+8. **username 重复** → 409 / 40901；DB 没有新用户被插入
+9. **userCode 重复** → 409 / 40902；DB 没有新用户被插入
+10. **employeeId 不存在 / 已软删** → 400 / 40004
+11. **permissionCategoryIds 含不存在 ID** → 400 / 40004；事务回滚（sys_user 也未插入）
+12. **请求体缺 username / username 含非法字符** → 400 / 40001
+13. **请求体携带 password 字段** → 400 / 40001（Jackson 严格反序列化）
+14. **userType / language 非枚举值** → 400 / 40001
+15. **唯一索引兜底**：模拟绕过 service 层预检的并发场景（DataIntegrityViolationException 路径），断言返 40901 而非 50000
+
+测试基础：复用 `LoginTestSeeder` + 扩展 `UserCreateTestSeeder`（管理员 token 注入 + 权限分类 fixture）。
+---
+req_id: REQ-USR-003
+date: 2026-05-15
+module: module_usr
+---
+
+# Spec: REQ-USR-003 — 修改用户
+
+## 目标
+
+超级管理员对已有用户的非密码、非用户名字段做部分更新（PATCH 语义），并支持增量增删权限分类授权。同时提供 GET 详情接口供前端表单回显（与修改入参 / 返回字段同源）。
+
+## 输入 / 触发
+
+两个 HTTP 入口（均需 `Authorization: Bearer <accessToken>` 且 `userType=SUPER_ADMIN`）：
+
+### 1. `GET /api/v1/users/{userId}` 用户详情
+
+Path：`userId: int`（命中 `sys_user.iIncrement`，否则 40401）。
+
+无请求体。
+
+### 2. `PUT /api/v1/users/{userId}` 修改用户
+
+Path：`userId: int`。
+
+**请求体 UpdateUserReq**（JSON，PATCH 语义；任一字段缺省视为不变）：
+
+| 字段 | 类型 | 必填 | 校验 |
+|---|---|---|---|
+| `userCode` | string | 否 | 提供时 `@Size(max=50) @NotBlank`；若与其他用户的 sUserCode 冲突返 40902（当前用户自身的同值视为不变，跳过冲突判定）|
+| `userType` | string | 否 | 提供时 `NORMAL` / `SUPER_ADMIN` |
+| `language` | string | 否 | 提供时 `zh-CN` / `en-US` / `zh-TW` |
+| `canEditDocument` | boolean | 否 | true / false |
+| `employeeId` | int 或 null | 否 | 提供为非 null 时必须命中 `sys_employee.iIncrement` AND `iIsDeleted=0`，否则返 40004；显式传 `null` 表示解除关联，DB 写 NULL |
+| `isDeleted` | boolean | 否 | true 表示作废 / false 表示恢复启用；尝试停用当前登录用户自己返 40302 |
+| `permissionCategoryIds` | int[] | 否 | 提供时按差集做增删；每个元素必须命中 `sys_permission_category.iIncrement AND iIsDeleted=0`，否则返 40004；缺省表示权限分类不变 |
+
+**严禁字段**：请求体含 `username` 或 `password` 字段直接返 40001（Jackson `fail-on-unknown-properties=true` 已在 REQ-USR-002 启用全局，缺省命中此防御）。
+
+### permissionCategoryIds 增删差集策略
+
+- 设当前已授权集合 `current = {pcId1, pcId2, ...}`（从 `sys_user_permission_category WHERE iUserId=?` 查）
+- 设请求集合 `target = req.permissionCategoryIds`
+- `toRemove = current \ target` → DELETE FROM sys_user_permission_category WHERE iUserId=? AND iPermissionCategoryId IN (toRemove)
+- `toAdd = target \ current` → INSERT 对应行，`sGrantedBy = 当前登录 username`
+- 同 `target ∩ current` 项保持不动（iIncrement / tCreateDate 不变）
+
+## 输出 / 结果
+
+两个接口共用 `UserDetailVo`：
+
+```json
+{
+  "userId": 42,
+  "username": "alice",
+  "userCode": "U001",
+  "userType": "NORMAL",
+  "language": "zh-CN",
+  "canEditDocument": false,
+  "isDeleted": false,
+  "employeeId": 7,
+  "employeeName": "张三",
+  "permissionCategoryIds": [1, 2],
+  "updatedBy": "admin",
+  "updatedDate": "2026-05-15T09:30:00"
+}
+```
+
+- `employeeName` 通过 `iEmployeeId` JOIN `sys_employee.sEmployeeName`；未关联职员时省略
+- `permissionCategoryIds` 是当前授权集合（增删后的最终状态）；空数组表示无授权
+- `updatedBy` / `updatedDate` 由本接口在更新时写入（`sUpdatedBy` / `tUpdatedDate`）；GET 取 DB 现有值，可能为 null
+
+**成功 200 OK**：`Result<UserDetailVo>`
+
+**失败**：
+
+| HTTP | code | 含义 | 触发条件 |
+|---|---|---|---|
+| 400 | 40001 | 请求体格式错误 / 含未知字段（username/password） | jakarta 校验 OR Jackson fail-on-unknown |
+| 400 | 40004 | 员工或权限分类不存在 | employeeId / permissionCategoryIds 校验失败 |
+| 401 | 40101 | 未携带或无效 Token | 鉴权层 |
+| 403 | 40301 | 非超级管理员调用 | 角色守卫 |
+| 403 | 40302 | 试图停用当前登录用户自己 | `req.isDeleted == true && userId == LoginContext.userId()` |
+| 404 | 40401 | 用户不存在 | `userId` 不命中 `sys_user.iIncrement` |
+| 409 | 40902 | 用户号已被占用 | 提供的 userCode 命中其他用户的 sUserCode（排除自身） |
+
+## 业务规则
+
+1. **鉴权 / 角色守卫**：复用 REQ-USR-002 的 JwtHandlerInterceptor + `@RequireSuperAdmin`。两个接口都标 `@RequireSuperAdmin`。
+2. **存在性校验**：先查 `sys_user.iIncrement = userId AND iIsDeleted ∈ {0,1}`（包含作废用户，因为恢复启用允许）；找不到 → 40401。
+3. **自我停用守卫**（PUT 专属）：`req.isDeleted == true && userId == LoginContext.current().userId()` → 40302。**注意**：恢复启用（`isDeleted == false`）即便针对自己也允许（不会有此场景，因为已登录用户必然非作废，但仍保留对称语义）。
+4. **userCode 唯一性**（PUT 专属）：仅当 `req.userCode != null && !req.userCode.equals(currentUser.sUserCode)` 时才检查；用 `selectByUserCodeExcludingId(userCode, userId)` 排除自身。冲突 → 40902。
+5. **外键校验**：employeeId（非 null）和 permissionCategoryIds（非 null）按 REQ-USR-002 同样的方式校验。`employeeId == null` 显式表示解除关联（DB 置 NULL），与字段缺省不同（缺省 = 不变）。
+6. **部分更新**：只更新请求体中显式提供的字段；用 MyBatis-Plus `UpdateWrapper` 显式列出 set 项。`sUpdatedBy = LoginContext.current().username()`、`tUpdatedDate = NOW()` 一定写。
+7. **作废即时生效**：PUT 把 `iIsDeleted=1` 写库后，该用户已签发的 token 在下一次请求时会被 JwtHandlerInterceptor 检测到 iIsDeleted=1 并返 40101（已由 REQ-USR-002 基础设施保证）。
+8. **GET 详情**：聚合 sys_user + sys_employee（JOIN）+ sys_user_permission_category（IN 查询）一次返回；不查询作废过滤之外的额外字段。
+
+## PATCH 语义实现细节
+
+`UpdateUserReq` 用包装类型（Integer / Boolean / String / List）+ 自定义 `JsonNode` 检测"字段是否在 JSON 中出现"以区分"显式 null"与"缺省"。
+
+具体方案：
+- `userCode` / `userType` / `language` / `canEditDocument` / `isDeleted` / `permissionCategoryIds` — 缺省 = 不变；提供（非 null）= 更新；**不接受**显式 null（@NotNull 在 service 层不强制，但缺省即视为 null 表示"不变"）
+- `employeeId` — 三态：缺省（不变）/ 非 null 整数（更新）/ 显式 null（解除关联）。用 `JsonNullable<Integer>`（来自 `openapi-generator` 工具库）实现三态。**最小可行替代**：在 controller 层用 `JsonNode` 解析 `employeeId` 字段，传给 service 一个 `EmployeeIdUpdate` 三态枚举（`UNCHANGED / SET(value) / UNSET`）。
+
+> **简化决策**：本 REQ 不引入 `jakarta.json` 或 `JsonNullable` 第三方库（违反技术栈表）。采用如下约定：
+> - 请求体仅当字段**存在且值非 null**时才更新；字段**完全缺省**视为不变；字段**显式 null** 视为不变（即不区分缺省与显式 null）
+> - 单独提供"清除关联"语义：`employeeId == 0` 视为解除关联（DB 写 NULL）。这是一个约定（非业界标准 PATCH），spec 必须明示
+
+实现简化后：`UpdateUserReq` 所有字段都是普通可空包装类型；`employeeId` 取值规则：null / 缺省 → 不变；`0` → 解除关联；正整数 → 更新到该 ID。
+
+## 边界与约束
+
+- **基础设施复用**：鉴权 / GlobalExceptionHandler / Result / BizException / LoginContext / JwtUtil / BCryptPasswordEncoder / SeederFixture 全部复用 REQ-USR-002
+- **ErrorCode 新增**：`USER_FORBIDDEN_SELF_DEACTIVATE = 40302`（HTTP 403）、`USER_NOT_FOUND = 40401`（HTTP 404）。`ErrorCode.toHttpStatus` 已含 401/403/404 段位映射，本 REQ 不需要新增映射。
+- **不实现**：
+  - 用户名 / 密码修改（推迟到独立 REQ）
+  - 批量修改（YAGNI）
+  - 修改历史审计表（推迟）
+  - GET 列表（REQ-USR-004 范围）
+
+## 依赖的 schema 表 / 字段
+
+读 + 写 `sys_user`（V1 已建）：
+- 读：iIncrement / sUsername / sUserCode / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / sCreatedBy / sUpdatedBy / tUpdatedDate / tCreateDate（详情查询需要）
+- 写：sUserCode / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / sUpdatedBy / tUpdatedDate
+
+读 + 写 `sys_user_permission_category`（V1 已建）：
+- 增删差集
+
+只读 `sys_employee`（V1 已建）：
+- 校验 employeeId 存在 + 取 sEmployeeName
+
+只读 `sys_permission_category`（V1 已建）：
+- countActiveByIds 校验
+
+**本 REQ 不需要新增 migration**。
+
+## 依赖的接口
+
+- 本 REQ 提供：
+  - `GET /api/v1/users/{userId}` — 用户详情
+  - `PUT /api/v1/users/{userId}` — 修改用户
+- 前置依赖：JWT 由 REQ-USR-001 签发；JwtHandlerInterceptor 由 REQ-USR-002 提供
+
+## 验收标准
+
+后端集成测试：
+
+### GET 详情
+
+1. **admin token + 存在用户** → 200，UserDetailVo 完整（含 employeeName + permissionCategoryIds）
+2. **admin token + 不存在 userId** → 404 / 40401
+3. **NORMAL token** → 403 / 40301
+4. **无 Authorization** → 401 / 40101
+5. **作废用户** → 200（详情查询包含作废用户；不过滤）
+
+### PUT 修改
+
+6. **修改 userCode + userType + language**（admin token）→ 200，DB 已更新；sUpdatedBy=admin、tUpdatedDate 非空；其他字段不变
+7. **修改 employeeId 为另一个有效员工** → 200，DB 写新值
+8. **修改 employeeId=0 解除关联** → 200，DB 写 NULL
+9. **修改 employeeId=99999 不存在** → 400 / 40004
+10. **修改 isDeleted=true** → 200，DB 写 1；该用户原 token 下一次请求返 40101
+11. **修改 permissionCategoryIds（差集增删）**：初始权限 `[1,2]`，请求 `[2,3]` → 200，最终 DB 状态 `[2,3]`；分类 1 的行被 DELETE，分类 3 的行被 INSERT；分类 2 的行 iIncrement 保持不变（验证差集而非全量替换）
+12. **permissionCategoryIds 为空数组** → 200，最终授权清空
+13. **permissionCategoryIds 含不存在 ID** → 400 / 40004，事务回滚（DB 授权无变化）
+14. **修改 userCode 冲突（其他用户已用）** → 409 / 40902
+15. **修改 userCode 等于自身原值** → 200，无 40902
+16. **试图停用自己**（admin 用 admin token 改 admin 用户 isDeleted=true）→ 403 / 40302
+17. **请求体含 username 字段** → 400 / 40001
+18. **请求体含 password 字段** → 400 / 40001
+19. **userId 不存在** → 404 / 40401
+20. **NORMAL token 调用 PUT** → 403 / 40301
+21. **空请求体 `{}`** → 200，仅写 sUpdatedBy / tUpdatedDate（其他字段不变）
+
+### PUT + 立即可观察
+
+22. **修改后调用 GET 详情** → 返回的字段反映 PUT 的写入值
+23. **作废用户尝试登录** → 401 / 40103（REQ-USR-001 既有路径，不在本 REQ 添加新测试，但成功路径验收应链路一致）
+---
+req_id: REQ-USR-004
+date: 2026-05-15
+module: module_usr
+---
+
+# Spec: REQ-USR-004 — 查询用户
+
+## 目标
+
+`GET /api/v1/users`：超级管理员分页 + 多字段筛选 + 排序查询用户列表，单条记录聚合 sys_user + sys_employee + sys_department 信息（部门名、员工名）。只读，无写副作用，不返回密码。
+
+## 输入 / 触发
+
+HTTP 入口 `GET /api/v1/users`，要求 `Authorization: Bearer <accessToken>` + `userType=SUPER_ADMIN`。
+
+**Query 参数**（全部可选）：
+
+| 参数 | 类型 | 默认 | 校验 |
+|---|---|---|---|
+| `page` | int | 1 | `@Min(1)`；< 1 返 40001；大于总页数返"最后一页"数据（不是空列表） |
+| `size` | int | 20 | `@Min(1) @Max(100)`；越界返 40001 |
+| `sortField` | string | `tCreateDate` | 白名单：`tCreateDate` / `tLastLoginDate` / `sUsername` / `sUserCode`；不在白名单返 40003 |
+| `sortOrder` | string | `desc` | `asc` / `desc`；其他值返 40001 |
+| `queryField` | string | （不筛选） | 白名单：`username` / `employeeName` / `userCode` / `departmentName` / `userType` / `isDeleted` / `lastLoginDate` / `createdBy`；不在白名单返 40003 |
+| `matchMode` | string | `contains` | `contains` / `notContains` / `equals`；不在白名单返 40003 |
+| `queryValue` | string | （不筛选） | 任意字符串；空字符串或 null 视为不应用此条件；与 queryField 配对使用——只提供 queryField 不提供 queryValue 也视为不应用 |
+| `userType` | string | （不筛选） | 若提供，必须是 `NORMAL` / `SUPER_ADMIN`；其他返 40001 |
+| `isDeleted` | boolean | （不筛选） | true / false |
+
+> **复合规则**：所有筛选条件用 `AND` 拼接：queryField+queryValue 提供时构成一条动态条件；userType / isDeleted 作为额外固定条件叠加。
+
+## 输出 / 结果
+
+**成功 200**：`Result<PageResult<UserListItemVo>>`
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "records": [
+      {
+        "userId": 42,
+        "username": "alice",
+        "employeeName": "张三",
+        "userCode": "U001",
+        "departmentName": "技术部",
+        "userType": "NORMAL",
+        "language": "zh-CN",
+        "isDeleted": false,
+        "lastLoginDate": "2026-05-15T08:00:00",
+        "createdBy": "admin",
+        "createdDate": "2026-05-15T07:00:00"
+      }
+    ],
+    "total": 17,
+    "page": 1,
+    "size": 20
+  }
+}
+```
+
+字段：
+- `userId` = sys_user.iIncrement
+- `username` / `userCode` / `userType` / `language` / `isDeleted` / `lastLoginDate` / `createdBy` / `createdDate` 直接来自 sys_user
+- `employeeName` = LEFT JOIN sys_employee.sEmployeeName（用户未关联职员时返回 null）
+- `departmentName` = LEFT JOIN sys_department.sDepartmentName via sys_employee.iDepartmentId（未关联或部门软删时返回 null）
+
+**失败**：
+
+| HTTP | code | 含义 | 触发 |
+|---|---|---|---|
+| 400 | 40001 | 分页 / 类型 / 排序参数错误 | page<1 / size<1 / size>100 / sortOrder 非 asc-desc / userType 非枚举 |
+| 400 | 40003 | queryField / matchMode / sortField 不在白名单 | 用户传非法枚举值 |
+| 401 | 40101 | 未携带或无效 Token | 鉴权层 |
+| 403 | 40301 | 非超级管理员 | 角色守卫 |
+
+## 业务规则
+
+1. **鉴权**：复用 `@RequireSuperAdmin` + JwtHandlerInterceptor。
+2. **白名单映射**（service 层维护静态 Map<String, String>）：
+   - `sortField` 入参 → SQL 列名：`tCreateDate`/`tLastLoginDate`/`sUsername`/`sUserCode` 均与列名同名（直接使用）。**禁止用户传任意列名**——必须白名单匹配。
+   - `queryField` 入参 → SQL 列引用（含 JOIN 别名）：
+     - `username` → `u.sUsername`
+     - `employeeName` → `e.sEmployeeName`
+     - `userCode` → `u.sUserCode`
+     - `departmentName` → `d.sDepartmentName`
+     - `userType` → `u.sUserType`
+     - `isDeleted` → `u.iIsDeleted`
+     - `lastLoginDate` → `u.tLastLoginDate`
+     - `createdBy` → `u.sCreatedBy`
+3. **matchMode 处理**：
+   - `contains` → `LIKE CONCAT('%', #{queryValue}, '%')`
+   - `notContains` → `NOT LIKE CONCAT('%', #{queryValue}, '%') OR <col> IS NULL`
+   - `equals` → `= #{queryValue}`
+   - 对 `isDeleted`（int）/ `lastLoginDate`（datetime）这类非字符串字段：无论 matchMode 一律按 `equals` 处理（service 层规范化 queryValue 为对应类型；非法值返 40001）。
+4. **空 queryValue**：queryField 给了但 queryValue 为 null / 空串 → 跳过此条件，不参与 WHERE。
+5. **空 queryField + 有 queryValue**：跳过（缺 queryField 没法应用）。
+6. **越界 page**：先按入参 page/size 查；若返回 records 为空但 total > 0，service 层用 `lastPage = (total + size - 1) / size` 重新查一次并返回 lastPage 的数据。响应 `page` 字段反映**实际返回的页码**（即 lastPage），让前端能感知矫正。
+7. **排序 SQL**：在 ORDER BY 前用白名单映射列名 + asc/desc 拼接；用 MyBatis 字符串替换（`${}`）但只限白名单值（白名单已校验，安全）。
+8. **不返回密码**：UserListItemVo 不含 sPasswordHash 字段；mapper SELECT 列表显式列出业务列。
+9. **N+1 防御**：JOIN 而非多次查询；单查询返回所有字段。
+10. **空查询**：所有筛选都空时返回全表分页（admin 用例需要"全部 用户"视图）。
+
+## 边界与约束
+
+- **白名单兜底**：所有动态字段（queryField / matchMode / sortField / sortOrder）必须 service 层先做白名单检查，再拼到 SQL；用户输入永远不直接进 ORDER BY / SELECT。
+- **MyBatis 注入**：用 `#{}` 参数化输入；只有列名 / 排序方向用 `${}`（已白名单约束）。
+- **size 上限 100**：与 docs/04 § 3.2 一致。
+- **作废用户参与查询**：默认不过滤；用户通过 `isDeleted=false` 显式过滤启用账号。
+- **登录追踪**：本 REQ 不修改 tLastLoginDate / iFailedLoginCount / tLockUntil — 纯查询。
+- **不实现**：
+  - 多字段同时筛选（spec 仅允许单一 queryField，多字段筛选推迟）
+  - 自定义列展示（前端事）
+  - 导出 / 导入（YAGNI）
+
+## 依赖的 schema 表 / 字段
+
+只读 `sys_user`（V1 已建）：
+- 读列：iIncrement, sUsername, sUserCode, sUserType, sLanguage, iIsDeleted, tLastLoginDate, sCreatedBy, tCreateDate, iEmployeeId
+- 排序 / 筛选列：sUsername, sUserCode, sUserType, iIsDeleted, tLastLoginDate, sCreatedBy, tCreateDate
+
+只读 `sys_employee`（V1 已建）：
+- LEFT JOIN：iIncrement = u.iEmployeeId
+- 读 / 筛选列：sEmployeeName, iDepartmentId
+
+只读 `sys_department`（V1 已建）：
+- LEFT JOIN：iIncrement = e.iDepartmentId
+- 读 / 筛选列：sDepartmentName
+
+**本 REQ 不需要新增 migration**。
+
+## 依赖的接口
+
+- 本 REQ 提供：`GET /api/v1/users`
+
+## 验收标准
+
+后端集成测试：
+
+1. **admin token + 默认参数** → 200，返回所有用户（按 tCreateDate desc）；total = 实际行数；不含密码字段
+2. **page=2 size=2** → 返回第 2 页 2 条；page=2，total 不变
+3. **size > 100** → 400 / 40001
+4. **page < 1** → 400 / 40001
+5. **sortField=sUsername sortOrder=asc** → 按 username 升序返回
+6. **sortField=nonExisting** → 400 / 40003
+7. **sortOrder=foo** → 400 / 40001
+8. **queryField=username matchMode=contains queryValue=ali** → 返回含 "ali" 的用户
+9. **queryField=username matchMode=equals queryValue=alice** → 仅返回 alice
+10. **queryField=username matchMode=notContains queryValue=ali** → 不含 alice 但含 admin / bob_deleted
+11. **queryField=employeeName matchMode=contains queryValue=张** → 返回员工名含张的用户（JOIN）
+12. **queryField=departmentName matchMode=equals queryValue=技术部** → 返回部门=技术部的用户（多级 JOIN）
+13. **queryField=userType matchMode=equals queryValue=SUPER_ADMIN** → 仅 admin
+14. **queryField=isDeleted matchMode=equals queryValue=true** → 仅 bob_deleted
+15. **queryField=invalid** → 400 / 40003
+16. **matchMode=invalid** → 400 / 40003
+17. **queryField 提供但 queryValue 为空** → 跳过条件，返回全表（不报错）
+18. **userType=NORMAL** explicit 参数 → 仅 NORMAL 用户
+19. **userType=INVALID** → 400 / 40001
+20. **isDeleted=false** explicit → 仅启用用户
+21. **复合：queryField=username queryValue=al userType=NORMAL isDeleted=false** → 仅匹配三条件的用户（alice）
+22. **page 越界（page=999 size=10，total=3）** → 200，返回最后一页（page=1，1 个 records 或更少），total=3
+23. **NORMAL token** → 403 / 40301
+24. **无 token** → 401 / 40101
+25. **响应不含 sPasswordHash 字段** → JSON 没有 password 相关字段
+26. **空表（无用户）** → 200，records=[]，total=0
@@ -8,6 +8,13 @@ set -euo pipefail
 PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$PROJECT_ROOT"
  
+# 加载 .env.local，让后续 mvn / setup-test-db 子进程都能继承 DB / JWT 凭据
+if [ -f .env.local ]; then
+  set -a
+  . ./.env.local
+  set +a
+fi
+
 # Stack detection (runtime, mode-agnostic)
 HAS_BACKEND=0; [ -d backend ] && HAS_BACKEND=1
 HAS_FRONTEND=0; [ -d frontend ] && HAS_FRONTEND=1
@@ -20,19 +27,19 @@ echo &quot;[test.sh] 1/6 setup test db&quot;
 ./scripts/setup-test-db.sh
  
 echo "[test.sh] 2/6 build"
-if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B -DskipTests package); else echo "[test.sh] skip backend build"; fi
-if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm install --frozen-lockfile && pnpm build); else echo "[test.sh] skip frontend build"; fi
+if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B -DskipTests clean package); else echo "[test.sh] skip backend build"; fi
+if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm ci && npm run build); else echo "[test.sh] skip frontend build"; fi
  
 echo "[test.sh] 3/6 lint"
-if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B -q -P lint verify -DskipTests || ./mvnw -B -q checkstyle:check spotbugs:check || :); else echo "[test.sh] skip backend lint"; fi
-if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm lint); else echo "[test.sh] skip frontend lint"; fi
+if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B -q checkstyle:check || mvn -B -q spotless:check || echo "[test.sh] backend lint skipped (no plugin configured)"); else echo "[test.sh] skip backend lint"; fi
+if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run lint); else echo "[test.sh] skip frontend lint"; fi
  
 echo "[test.sh] 4/6 unit + integration"
-if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B test); else echo "[test.sh] skip backend test"; fi
-if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm test -- --run); else echo "[test.sh] skip frontend test"; fi
+if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B test); else echo "[test.sh] skip backend test"; fi
+if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run test -- --run); else echo "[test.sh] skip frontend test"; fi
  
 echo "[test.sh] 5/6 E2E"
-if [ $HAS_FRONTEND -eq 1 ] && [ -f frontend/playwright.config.ts ]; then (cd frontend && pnpm exec playwright test); else echo "[test.sh] e2e 略"; fi
+if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npx playwright test); else echo "[test.sh] e2e 略 (no frontend)"; fi
  
 echo "[test.sh] 6/6 reset test db"
 ./scripts/setup-test-db.sh
 -- Flyway migration V1 — initial schema for 小羚羊
--- Generated: 2026-05-14T01:37:50Z
+-- Generated: 2026-05-14T15:46:57Z
 -- Source: 由 A4 db-init 从 docs/03-数据库设计文档.md 翻译生成（schema SSoT 是 docs/03）
 -- This is the FIRST migration; subsequent schema changes must be written as new files sql/migrations/V2__<desc>.sql, V3__... etc.
 -- Apply: Flyway runs this automatically at Spring Boot startup.
 -- Do not hand-edit this file after it is committed; write a new migration instead.
  
--- ===========================================================================
--- t_user — 系统用户主表，承载登录认证与基础属性
--- ===========================================================================
-CREATE TABLE `t_user` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `sUserNo` VARCHAR(50) NOT NULL COMMENT '用户号；关联职员后自动同步员工号；系统内唯一',
-  `sUserName` VARCHAR(50) NOT NULL COMMENT '登录用户名；系统内唯一；3-50 位',
-  `iEmployeeId` INT NULL DEFAULT NULL COMMENT '关联职员 t_employee.iIncrement；可空（非员工账号如系统管理员）',
-  `sPasswordHash` VARCHAR(255) NOT NULL COMMENT '密码哈希（BCrypt / Argon2）；禁止明文；初始密码 666666 哈希后存入',
-  `sUserType` VARCHAR(20) NOT NULL DEFAULT 'NORMAL' COMMENT '用户类型枚举：NORMAL（普通用户）/ SUPER_ADMIN（超级管理员）',
-  `sLanguage` VARCHAR(10) NOT NULL DEFAULT 'zh-CN' COMMENT '语言枚举：zh-CN（中文）/ en-US（英文）/ zh-TW（繁体）',
-  `bModifyDoc` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '单据修改权限：0 否 / 1 是',
-  `bVoid` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标记（软删除）：0 启用 / 1 已作废',
-  `iLoginFailCount` INT NOT NULL DEFAULT 0 COMMENT '连续登录失败次数；达到阈值触发临时锁定；登录成功后清零',
-  `tLockUntil` DATETIME NULL DEFAULT NULL COMMENT '锁定截止时间；NULL 表示未锁定',
-  `tLastLoginDate` DATETIME NULL DEFAULT NULL COMMENT '最近一次登录时间',
-  `sCreator` VARCHAR(100) NULL DEFAULT NULL COMMENT '制单人（创建该账号的操作员用户名）',
+-- =============================================================================
+-- Table: sys_company — 公司 / 版本字典，登录页下拉选择来源
+-- =============================================================================
+CREATE TABLE `sys_company` (
+  `iIncrement`     INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`            VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`      VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`  VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `sCompanyName`   VARCHAR(100) NOT NULL                     COMMENT '公司 / 版本名称（登录页下拉显示文本）',
+  `sCompanyCode`   VARCHAR(50)  NOT NULL                     COMMENT '公司编码（前端唯一识别）',
+  `iSortOrder`     INT          NOT NULL DEFAULT 0           COMMENT '下拉列表排序权重，升序',
+  `iIsDeleted`     TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '软删除标记，0=正常 1=已删',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_user_username` (`sUserName`),
-  UNIQUE KEY `uk_user_userno` (`sUserNo`),
-  KEY `idx_user_employee` (`iEmployeeId`),
-  KEY `idx_user_tenant` (`sBrandsId`, `sSubsidiaryId`),
-  KEY `idx_user_void` (`bVoid`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='系统用户主表，承载登录认证与基础属性';
-
--- ===========================================================================
--- t_employee — 公司职员主档
--- ===========================================================================
-CREATE TABLE `t_employee` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `sEmployeeNo` VARCHAR(50) NOT NULL COMMENT '员工号；系统内唯一',
-  `sName` VARCHAR(100) NOT NULL COMMENT '姓名',
-  `iDepartmentId` INT NULL DEFAULT NULL COMMENT '部门 ID，关联 t_department.iIncrement',
-  `sPhone` VARCHAR(20) NULL DEFAULT NULL COMMENT '手机号',
-  `sEmail` VARCHAR(100) NULL DEFAULT NULL COMMENT '邮箱',
-  `bDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否离职：0 在职 / 1 离职',
+  UNIQUE KEY `uk_sys_company_code` (`sCompanyCode`),
+  KEY `idx_sys_company_is_deleted` (`iIsDeleted`, `iSortOrder`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司 / 版本字典，登录页下拉选择来源';
+
+
+-- =============================================================================
+-- Table: sys_department — 部门字典，职员归属
+-- =============================================================================
+CREATE TABLE `sys_department` (
+  `iIncrement`       INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`              VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`        VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`    VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `sDepartmentName`  VARCHAR(100) NOT NULL                     COMMENT '部门名称',
+  `sDepartmentCode`  VARCHAR(50)  NOT NULL                     COMMENT '部门编码',
+  `iIsDeleted`       TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '软删除标记',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_employee_no` (`sEmployeeNo`),
-  KEY `idx_employee_dept` (`iDepartmentId`),
-  KEY `idx_employee_name` (`sName`),
-  KEY `idx_employee_tenant` (`sBrandsId`, `sSubsidiaryId`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司职员主档';
-
--- ===========================================================================
--- t_department — 部门组织树
--- ===========================================================================
-CREATE TABLE `t_department` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `sName` VARCHAR(100) NOT NULL COMMENT '部门名称',
-  `sCode` VARCHAR(50) NOT NULL COMMENT '部门编码；系统内唯一',
-  `iParentId` INT NULL DEFAULT NULL COMMENT '上级部门 ID，NULL 表示根部门',
-  `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '排序值，小者靠前',
+  UNIQUE KEY `uk_sys_department_code` (`sDepartmentCode`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='部门字典，职员归属';
+
+
+-- =============================================================================
+-- Table: sys_employee — 职员档案，员工基础信息
+-- =============================================================================
+CREATE TABLE `sys_employee` (
+  `iIncrement`      INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`             VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`       VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`   VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`     DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `sEmployeeName`   VARCHAR(50)  NOT NULL                     COMMENT '员工姓名（2-50 字符）',
+  `sEmployeeCode`   VARCHAR(50)  NOT NULL                     COMMENT '员工工号（系统内唯一）',
+  `iDepartmentId`   INT          NOT NULL                     COMMENT '所属部门 ID（FK → sys_department.iIncrement）',
+  `sPhone`          VARCHAR(20)  NULL     DEFAULT NULL        COMMENT '手机号',
+  `sEmail`          VARCHAR(100) NULL     DEFAULT NULL        COMMENT '邮箱',
+  `iIsDeleted`      TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '软删除标记',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_department_code` (`sCode`),
-  KEY `idx_department_parent` (`iParentId`),
-  KEY `idx_department_tenant` (`sBrandsId`, `sSubsidiaryId`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='部门组织树';
-
--- ===========================================================================
--- t_permission — 权限分类字典
--- ===========================================================================
-CREATE TABLE `t_permission` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `sCode` VARCHAR(50) NOT NULL COMMENT '权限码，例如 USR:ADD / USR:EDIT；系统内唯一',
-  `sName` VARCHAR(100) NOT NULL COMMENT '权限分类名称（展示用）',
-  `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '同分类内排序',
+  UNIQUE KEY `uk_sys_employee_code` (`sEmployeeCode`),
+  KEY `idx_sys_employee_department` (`iDepartmentId`),
+  KEY `idx_sys_employee_name` (`sEmployeeName`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='职员档案，员工基础信息';
+
+
+-- =============================================================================
+-- Table: sys_user — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪）
+-- =============================================================================
+CREATE TABLE `sys_user` (
+  `iIncrement`          INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`                 VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`           VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`       VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`         DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `sUsername`           VARCHAR(50)  NOT NULL                     COMMENT '用户名（登录凭据，系统内全局唯一，3-20 位字母数字下划线）',
+  `sUserCode`           VARCHAR(50)  NOT NULL                     COMMENT '用户号（业务展示用编码，系统内唯一）',
+  `sPasswordHash`       VARCHAR(255) NOT NULL                     COMMENT '密码哈希（BCrypt / Argon2，禁明文）',
+  `iEmployeeId`         INT          NULL     DEFAULT NULL        COMMENT '关联职员 ID（可选；FK → sys_employee.iIncrement）',
+  `sUserType`           VARCHAR(20)  NOT NULL DEFAULT 'NORMAL'    COMMENT '用户类型枚举：NORMAL=普通用户 / SUPER_ADMIN=超级管理员',
+  `sLanguage`           VARCHAR(10)  NOT NULL DEFAULT 'zh-CN'     COMMENT '语言：zh-CN=中文 / en-US=英文 / zh-TW=繁体',
+  `iCanEditDocument`    TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '单据修改权限：0=否 1=是',
+  `iIsDeleted`          TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '是否作废：0=启用 1=作废（停用）',
+  `iFailedLoginCount`   INT          NOT NULL DEFAULT 0           COMMENT '累计登录失败次数，达阈值锁定，登录成功清零',
+  `tLockUntil`          DATETIME     NULL     DEFAULT NULL        COMMENT '锁定截止时间，NULL=未锁定，过期自动解锁',
+  `tLastLoginDate`      DATETIME     NULL     DEFAULT NULL        COMMENT '最后一次成功登录时间，REQ-USR-004 登录日期来源',
+  `sCreatedBy`          VARCHAR(50)  NULL     DEFAULT NULL        COMMENT '制单人（创建该用户的用户名），REQ-USR-002 制单人',
+  `sUpdatedBy`          VARCHAR(50)  NULL     DEFAULT NULL        COMMENT '最后修改人用户名',
+  `tUpdatedDate`        DATETIME     NULL     DEFAULT NULL        COMMENT '最后修改时间',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_permission_code` (`sCode`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限分类字典';
+  UNIQUE KEY `uk_sys_user_username` (`sUsername`),
+  UNIQUE KEY `uk_sys_user_code` (`sUserCode`),
+  KEY `idx_sys_user_employee` (`iEmployeeId`),
+  KEY `idx_sys_user_type` (`sUserType`),
+  KEY `idx_sys_user_is_deleted` (`iIsDeleted`),
+  KEY `idx_sys_user_created_by` (`sCreatedBy`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪）';
+
  
--- ===========================================================================
--- t_user_permission — 用户-权限分类关联表
--- ===========================================================================
-CREATE TABLE `t_user_permission` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `iUserId` INT NOT NULL COMMENT '用户 ID，关联 t_user.iIncrement',
-  `iPermissionId` INT NOT NULL COMMENT '权限分类 ID，关联 t_permission.iIncrement',
+-- =============================================================================
+-- Table: sys_permission_category — 权限分类字典
+-- =============================================================================
+CREATE TABLE `sys_permission_category` (
+  `iIncrement`     INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`            VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`      VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`  VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `sCategoryName`  VARCHAR(100) NOT NULL                     COMMENT '权限分类名称（如 采购管理 / 销售管理）',
+  `sCategoryCode`  VARCHAR(50)  NOT NULL                     COMMENT '权限分类编码（系统内唯一，代码层引用）',
+  `sCategoryDesc`  VARCHAR(255) NULL     DEFAULT NULL        COMMENT '分类说明',
+  `iSortOrder`     INT          NOT NULL DEFAULT 0           COMMENT '列表展示顺序',
+  `iIsDeleted`     TINYINT(1)   NOT NULL DEFAULT 0           COMMENT '软删除标记',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_user_perm` (`iUserId`, `iPermissionId`),
-  KEY `idx_user_perm_perm` (`iPermissionId`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户-权限分类关联表';
-
--- ===========================================================================
--- t_company — 公司 / 版本字典
--- ===========================================================================
-CREATE TABLE `t_company` (
-  `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）',
-  `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）',
-  `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）',
-  `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
-  `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
-  `sCode` VARCHAR(50) NOT NULL COMMENT '公司 / 版本编码；系统内唯一',
-  `sName` VARCHAR(100) NOT NULL COMMENT '显示名称',
+  UNIQUE KEY `uk_sys_permission_category_code` (`sCategoryCode`),
+  KEY `idx_sys_permission_category_sort` (`iIsDeleted`, `iSortOrder`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限分类字典';
+
+
+-- =============================================================================
+-- Table: sys_user_permission_category — 用户 × 权限分类授权关系
+-- =============================================================================
+CREATE TABLE `sys_user_permission_category` (
+  `iIncrement`             INT          NOT NULL AUTO_INCREMENT      COMMENT '整数主键 ID（标准列）',
+  `sId`                    VARCHAR(100) NULL     DEFAULT (UUID())    COMMENT '业务 ID（标准列）',
+  `sBrandsId`              VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）',
+  `sSubsidiaryId`          VARCHAR(100) NULL     DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）',
+  `tCreateDate`            DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）',
+  `iUserId`                INT          NOT NULL                     COMMENT '用户 ID（FK → sys_user.iIncrement）',
+  `iPermissionCategoryId`  INT          NOT NULL                     COMMENT '权限分类 ID（FK → sys_permission_category.iIncrement）',
+  `sGrantedBy`             VARCHAR(50)  NULL     DEFAULT NULL        COMMENT '授予人用户名',
   PRIMARY KEY (`iIncrement`),
-  UNIQUE KEY `uk_company_code` (`sCode`)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司 / 版本字典';
+  UNIQUE KEY `uk_sys_user_permission_category` (`iUserId`, `iPermissionCategoryId`),
+  KEY `idx_sys_user_permission_category_category` (`iPermissionCategoryId`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户 × 权限分类授权关系';
  
--- ===========================================================================
--- 外键约束（统一在最后追加，避免建表顺序依赖）
--- ===========================================================================
-ALTER TABLE `t_user`
-  ADD CONSTRAINT `fk_user_employee` FOREIGN KEY (`iEmployeeId`) REFERENCES `t_employee` (`iIncrement`) ON DELETE SET NULL ON UPDATE RESTRICT;
  
-ALTER TABLE `t_employee`
-  ADD CONSTRAINT `fk_employee_department` FOREIGN KEY (`iDepartmentId`) REFERENCES `t_department` (`iIncrement`) ON DELETE SET NULL ON UPDATE RESTRICT;
+-- =============================================================================
+-- Foreign keys
+-- =============================================================================
+ALTER TABLE `sys_employee`
+  ADD CONSTRAINT `fk_sys_employee_department`
+  FOREIGN KEY (`iDepartmentId`) REFERENCES `sys_department` (`iIncrement`)
+  ON DELETE RESTRICT ON UPDATE CASCADE;
  
-ALTER TABLE `t_department`
-  ADD CONSTRAINT `fk_department_parent` FOREIGN KEY (`iParentId`) REFERENCES `t_department` (`iIncrement`) ON DELETE RESTRICT ON UPDATE RESTRICT;
+ALTER TABLE `sys_user`
+  ADD CONSTRAINT `fk_sys_user_employee`
+  FOREIGN KEY (`iEmployeeId`) REFERENCES `sys_employee` (`iIncrement`)
+  ON DELETE SET NULL ON UPDATE CASCADE;
  
-ALTER TABLE `t_user_permission`
-  ADD CONSTRAINT `fk_userperm_user` FOREIGN KEY (`iUserId`) REFERENCES `t_user` (`iIncrement`) ON DELETE CASCADE ON UPDATE RESTRICT;
+ALTER TABLE `sys_user_permission_category`
+  ADD CONSTRAINT `fk_sys_upc_user`
+  FOREIGN KEY (`iUserId`) REFERENCES `sys_user` (`iIncrement`)
+  ON DELETE CASCADE ON UPDATE CASCADE;
  
-ALTER TABLE `t_user_permission`
-  ADD CONSTRAINT `fk_userperm_perm` FOREIGN KEY (`iPermissionId`) REFERENCES `t_permission` (`iIncrement`) ON DELETE RESTRICT ON UPDATE RESTRICT;
+ALTER TABLE `sys_user_permission_category`
+  ADD CONSTRAINT `fk_sys_upc_permission_category`
+  FOREIGN KEY (`iPermissionCategoryId`) REFERENCES `sys_permission_category` (`iIncrement`)
+  ON DELETE CASCADE ON UPDATE CASCADE;