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());
+        }
+    }
+}