zichun · zichun · zichun · zichun · zichun · zichun
Showing 102 changed files
backend/pom.xml
backend/src/main/java/com/xly/erp/ErpApplication.java
backend/src/main/java/com/xly/erp/common/exception/AccountLockedException.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/ApiResponse.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/config/JacksonConfig.java
backend/src/main/java/com/xly/erp/config/MybatisPlusConfig.java
backend/src/main/java/com/xly/erp/config/PasswordConfig.java
backend/src/main/java/com/xly/erp/config/SecurityConfig.java
backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java
backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java
backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java
backend/src/main/java/com/xly/erp/module/mod/dto/ModuleUpdateDTO.java
backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java
backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java
backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java
backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java
+<?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.2.5</version>
+        <relativePath/>
+    </parent>
+
+    <groupId>com.xly.erp</groupId>
+    <artifactId>erp-backend</artifactId>
+    <version>0.1.0-SNAPSHOT</version>
+    <packaging>jar</packaging>
+    <name>erp-backend</name>
+    <description>小羚羊 ERP 后端</description>
+
+    <properties>
+        <java.version>17</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <mybatis-plus.version>3.5.7</mybatis-plus.version>
+        <mapstruct.version>1.5.5.Final</mapstruct.version>
+        <hutool.version>5.8.27</hutool.version>
+        <flyway.version>10.10.0</flyway.version>
+        <lombok.version>1.18.32</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.boot</groupId>
+            <artifactId>spring-boot-starter-security</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>com.baomidou</groupId>
+            <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
+            <version>${mybatis-plus.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-core</artifactId>
+            <version>${flyway.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.flywaydb</groupId>
+            <artifactId>flyway-mysql</artifactId>
+            <version>${flyway.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>com.mysql</groupId>
+            <artifactId>mysql-connector-j</artifactId>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <optional>true</optional>
+        </dependency>
+        <dependency>
+            <groupId>org.mapstruct</groupId>
+            <artifactId>mapstruct</artifactId>
+            <version>${mapstruct.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>cn.hutool</groupId>
+            <artifactId>hutool-all</artifactId>
+            <version>${hutool.version}</version>
+        </dependency>
+
+        <!-- REQ-USR-004 JWT (jjwt 0.12.x) -->
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-api</artifactId>
+            <version>0.12.6</version>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-impl</artifactId>
+            <version>0.12.6</version>
+            <scope>runtime</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.jsonwebtoken</groupId>
+            <artifactId>jjwt-jackson</artifactId>
+            <version>0.12.6</version>
+            <scope>runtime</scope>
+        </dependency>
+
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.security</groupId>
+            <artifactId>spring-security-test</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <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>
+                    <includes>
+                        <include>**/*Test.java</include>
+                        <include>**/*Tests.java</include>
+                        <include>**/*IT.java</include>
+                    </includes>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                    <annotationProcessorPaths>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok</artifactId>
+                            <version>${lombok.version}</version>
+                        </path>
+                        <path>
+                            <groupId>org.mapstruct</groupId>
+                            <artifactId>mapstruct-processor</artifactId>
+                            <version>${mapstruct.version}</version>
+                        </path>
+                        <path>
+                            <groupId>org.projectlombok</groupId>
+                            <artifactId>lombok-mapstruct-binding</artifactId>
+                            <version>0.2.0</version>
+                        </path>
+                    </annotationProcessorPaths>
+                </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 ErpApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(ErpApplication.class, args);
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ErrorCode;
+import lombok.Getter;
+
+/**
+ * REQ-USR-004 账号被临时锁定时抛出。携带剩余 cooldownSeconds，
+ * GlobalExceptionHandler 会把它转换成 ApiResponse.data 的 cooldownSeconds 字段。
+ */
+@Getter
+public class AccountLockedException extends BizException {
+
+    private final long cooldownSeconds;
+
+    public AccountLockedException(long cooldownSeconds) {
+        super(ErrorCode.LOGIN_ACCOUNT_LOCKED);
+        this.cooldownSeconds = cooldownSeconds;
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ErrorCode;
+import lombok.Getter;
+
+@Getter
+public class BizException extends RuntimeException {
+    private final int code;
+
+    public BizException(ErrorCode ec) {
+        super(ec.getMessage());
+        this.code = ec.getCode();
+    }
+
+    public BizException(ErrorCode ec, String detail) {
+        super(detail);
+        this.code = ec.getCode();
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ApiResponse;
+import com.xly.erp.common.response.ErrorCode;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    /** REQ-USR-004 账号锁定专用：把 cooldownSeconds 暴露在 data.cooldownSeconds */
+    @ExceptionHandler(AccountLockedException.class)
+    public ApiResponse<java.util.Map<String, Object>> handleAccountLocked(AccountLockedException e) {
+        log.warn("AccountLocked code={} cooldown={}s", e.getCode(), e.getCooldownSeconds());
+        java.util.Map<String, Object> data = java.util.Map.of("cooldownSeconds", e.getCooldownSeconds());
+        return new ApiResponse<>(e.getCode(), e.getMessage(), data, System.currentTimeMillis());
+    }
+
+    @ExceptionHandler(BizException.class)
+    public ApiResponse<Void> handleBiz(BizException e) {
+        log.warn("BizException code={} message={}", e.getCode(), e.getMessage());
+        return ApiResponse.fail(e.getCode(), e.getMessage());
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ApiResponse<Void> handleValidation(MethodArgumentNotValidException e) {
+        FieldError fe = e.getBindingResult().getFieldError();
+        String detail = fe == null
+                ? ErrorCode.PARAM_INVALID.getMessage()
+                : fe.getField() + ": " + fe.getDefaultMessage();
+        return ApiResponse.fail(ErrorCode.PARAM_INVALID, detail);
+    }
+
+    @ExceptionHandler(Exception.class)
+    public ApiResponse<Void> handleAll(Exception e) {
+        log.error("Uncaught exception", e);
+        return ApiResponse.fail(ErrorCode.INTERNAL_ERROR);
+    }
+}
+package com.xly.erp.common.response;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class ApiResponse<T> {
+    private int code;
+    private String message;
+    private T data;
+    private long timestamp;
+
+    public static <T> ApiResponse<T> ok(T data) {
+        return new ApiResponse<>(ErrorCode.SUCCESS.getCode(), ErrorCode.SUCCESS.getMessage(), data, System.currentTimeMillis());
+    }
+
+    public static <T> ApiResponse<T> ok(String message, T data) {
+        return new ApiResponse<>(ErrorCode.SUCCESS.getCode(), message, data, System.currentTimeMillis());
+    }
+
+    public static <T> ApiResponse<T> fail(ErrorCode ec) {
+        return new ApiResponse<>(ec.getCode(), ec.getMessage(), null, System.currentTimeMillis());
+    }
+
+    public static <T> ApiResponse<T> fail(ErrorCode ec, String detail) {
+        return new ApiResponse<>(ec.getCode(), detail, null, System.currentTimeMillis());
+    }
+
+    public static <T> ApiResponse<T> fail(int code, String message) {
+        return new ApiResponse<>(code, message, null, System.currentTimeMillis());
+    }
+}
+package com.xly.erp.common.response;
+
+import lombok.Getter;
+
+@Getter
+public enum ErrorCode {
+    SUCCESS(200, "操作成功"),
+    PARAM_INVALID(40010, "参数错误"),
+    LOGIN_INVALID_CREDENTIALS(40101, "用户名或密码错误"),
+    LOGIN_ACCOUNT_LOCKED(40301, "账号已临时锁定"),
+    MOD_PARENT_NOT_FOUND(40411, "父模块不存在或已删除"),
+    MOD_NOT_FOUND(40421, "模块不存在或已删除"),
+    STAFF_NOT_FOUND(40421, "职员不存在或已删除"),
+    PERM_CATEGORY_NOT_FOUND(40422, "权限分类不存在或已删除"),
+    USR_NOT_FOUND(40431, "用户不存在或已删除"),
+    MOD_PROC_NAME_DUP(40911, "存储过程名称已存在"),
+    MOD_HAS_REFERENCES(40912, "存在子模块或外部业务引用，禁止删除"),
+    MOD_PARENT_LOOP(40921, "iParentId 不能等于自身或后代"),
+    USR_USER_NAME_OR_NO_DUP(40921, "用户名或用户号已存在"),
+    INTERNAL_ERROR(50000, "服务器内部错误");
+
+    private final int code;
+    private final String message;
+
+    ErrorCode(int code, String message) {
+        this.code = code;
+        this.message = message;
+    }
+}
+package com.xly.erp.common.response;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** REQ-USR-003 引入的通用分页 VO。`data` 字段嵌套此结构。 */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class PageResult<T> {
+    private long total;
+    private List<T> list = new ArrayList<>();
+    private long pageNum;
+    private long pageSize;
+
+    public static <T> PageResult<T> of(IPage<T> page) {
+        return new PageResult<>(page.getTotal(), page.getRecords(), page.getCurrent(), page.getSize());
+    }
+}
+package com.xly.erp.config;
+
+import com.fasterxml.jackson.annotation.JsonAutoDetect;
+import com.fasterxml.jackson.annotation.PropertyAccessor;
+import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * 让 Jackson 通过字段名（而非 getter/setter 推断）确定 JSON 属性名。
+ *
+ * <p>项目沿用 docs/03 的匈牙利前缀命名（如 {@code iIncrement} / {@code sUserName}），
+ * Lombok 生成的 getter（{@code getIIncrement}）经 JavaBeans Introspector 解析为
+ * {@code IIncrement}（首两字符全大写时保留），导致 JSON 输出 {@code "IIncrement"}
+ * 而非期望的 {@code "iIncrement"}。改为字段访问后，Jackson 直接用字段名作 JSON key。</p>
+ */
+@Configuration
+public class JacksonConfig {
+
+    @Bean
+    public Jackson2ObjectMapperBuilderCustomizer fieldOnlyVisibility() {
+        return builder -> builder
+                .visibility(PropertyAccessor.FIELD, JsonAutoDetect.Visibility.ANY)
+                .visibility(PropertyAccessor.GETTER, JsonAutoDetect.Visibility.NONE)
+                .visibility(PropertyAccessor.IS_GETTER, JsonAutoDetect.Visibility.NONE)
+                .visibility(PropertyAccessor.SETTER, JsonAutoDetect.Visibility.NONE);
+    }
+}
+package com.xly.erp.config;
+
+import com.baomidou.mybatisplus.annotation.DbType;
+import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
+import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/** REQ-USR-003 引入：注册 MyBatis-Plus 分页拦截器，让 `Page<T>` 自动追加 LIMIT 子句。 */
+@Configuration
+public class MybatisPlusConfig {
+
+    @Bean
+    public MybatisPlusInterceptor mybatisPlusInterceptor() {
+        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
+        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
+        return interceptor;
+    }
+}
+package com.xly.erp.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+
+/**
+ * REQ-USR-001 引入：BCryptPasswordEncoder 注册为 Spring bean，
+ * 供 UserService.create / REQ-USR-004 登录校验复用。strength 用 BCrypt 默认（10）。
+ */
+@Configuration
+public class PasswordConfig {
+
+    @Bean
+    public PasswordEncoder passwordEncoder() {
+        return new BCryptPasswordEncoder();
+    }
+}
+package com.xly.erp.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.web.SecurityFilterChain;
+
+@Configuration
+public class SecurityConfig {
+
+    /**
+     * REQ-MOD-001 临时配置：所有 /api/** 一律 permitAll，禁用 CSRF / 表单登录。
+     * REQ-USR-004 完成时改为 .authenticated() + JWT filter。
+     */
+    @Bean
+    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+        http
+                .csrf(csrf -> csrf.disable())
+                .formLogin(form -> form.disable())
+                .httpBasic(basic -> basic.disable())
+                .authorizeHttpRequests(auth -> auth.anyRequest().permitAll());
+        return http.build();
+    }
+}
+package com.xly.erp.module.mod.controller;
+
+import com.xly.erp.common.response.ApiResponse;
+import com.xly.erp.module.mod.dto.ModuleCreateDTO;
+import com.xly.erp.module.mod.dto.ModuleQueryDTO;
+import com.xly.erp.module.mod.dto.ModuleUpdateDTO;
+import com.xly.erp.module.mod.service.ModuleService;
+import com.xly.erp.module.mod.vo.ModuleDeleteResultVO;
+import com.xly.erp.module.mod.vo.ModuleTreeNodeVO;
+import com.xly.erp.module.mod.vo.ModuleVO;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.DeleteMapping;
+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;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/modules")
+@RequiredArgsConstructor
+public class ModuleController {
+
+    private final ModuleService moduleService;
+
+    /** REQ-MOD-001 模块新增 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:CREATE')") */
+    @PostMapping
+    public ApiResponse<ModuleVO> create(@Valid @RequestBody ModuleCreateDTO dto) {
+        return ApiResponse.ok(moduleService.create(dto));
+    }
+
+    /** REQ-MOD-002 模块修改 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:UPDATE')") */
+    @PutMapping("/{id}")
+    public ApiResponse<ModuleVO> update(@PathVariable Integer id, @Valid @RequestBody ModuleUpdateDTO dto) {
+        return ApiResponse.ok(moduleService.update(id, dto));
+    }
+
+    /** REQ-MOD-003 模块软删除 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:DELETE')") */
+    @DeleteMapping("/{id}")
+    public ApiResponse<ModuleDeleteResultVO> delete(@PathVariable Integer id) {
+        return ApiResponse.ok(moduleService.delete(id));
+    }
+
+    /** REQ-MOD-004 模块树查询 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:READ')") */
+    @GetMapping
+    public ApiResponse<List<ModuleTreeNodeVO>> tree(@Valid ModuleQueryDTO query) {
+        return ApiResponse.ok(moduleService.tree(query));
+    }
+}
+package com.xly.erp.module.mod.dto;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+@Data
+public class ModuleCreateDTO {
+
+    @NotBlank
+    @Pattern(regexp = "^(手机端|前端业务|系统配置|接口)$", message = "sDisplayType 必须是 手机端/前端业务/系统配置/接口 之一")
+    private String sDisplayType;
+
+    @NotBlank
+    @Size(max = 100)
+    private String sProcedureName;
+
+    @NotBlank
+    @Size(max = 50)
+    private String sModuleType;
+
+    @NotBlank
+    @Size(max = 50)
+    private String sManageDeptEn;
+
+    /** 可空，service 层 default false */
+    private Boolean bShowPermission;
+
+    @NotBlank
+    @Size(max = 100)
+    private String sModuleNameZh;
+
+    /** 可空 */
+    private Integer iParentId;
+
+    @Min(0)
+    private Integer iSortOrder;
+}
+package com.xly.erp.module.mod.dto;
+
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/** REQ-MOD-004 模块查询参数 DTO */
+@Data
+public class ModuleQueryDTO {
+
+    /** 可空：对 sModuleNameZh 模糊匹配；空字符串视为不过滤 */
+    @Size(max = 50, message = "keyword 长度不能超过 50")
+    private String keyword;
+}
+package com.xly.erp.module.mod.dto;
+
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/**
+ * REQ-MOD-002 模块修改入参。
+ * 与 {@link ModuleCreateDTO} 相比剥除了 sProcedureName（不可改）；其余 7 个字段规则一致。
+ */
+@Data
+public class ModuleUpdateDTO {
+
+    @NotBlank
+    @Pattern(regexp = "^(手机端|前端业务|系统配置|接口)$", message = "sDisplayType 必须是 手机端/前端业务/系统配置/接口 之一")
+    private String sDisplayType;
+
+    @NotBlank
+    @Size(max = 50)
+    private String sModuleType;
+
+    @NotBlank
+    @Size(max = 50)
+    private String sManageDeptEn;
+
+    /** 可空：null 表示保持原值 */
+    private Boolean bShowPermission;
+
+    @NotBlank
+    @Size(max = 100)
+    private String sModuleNameZh;
+
+    /** 可空：null 表示设为根模块 */
+    private Integer iParentId;
+
+    /** 可空：null 表示保持原值 */
+    @Min(0)
+    private Integer iSortOrder;
+}
+package com.xly.erp.module.mod.entity;
+
+import com.baomidou.mybatisplus.annotation.FieldStrategy;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 业务模块定义。表 {@code tModule}（详见 docs/03-数据库设计文档.md § tModule）。
+ *
+ * <p>字段名沿用 docs/03 的匈牙利前缀命名（i/s/t/b），保持 schema 与 Java 字段一一对应，
+ * 避免双向映射歧义。@TableField 显式声明列名以兼容 MyBatis-Plus 默认的下划线转换关闭场景。</p>
+ */
+@Data
+@TableName("tModule")
+public class ModuleEntity {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    @TableField("sId")
+    private String sId;
+
+    @TableField("sBrandsId")
+    private String sBrandsId;
+
+    @TableField("sSubsidiaryId")
+    private String sSubsidiaryId;
+
+    @TableField("tCreateDate")
+    private LocalDateTime tCreateDate;
+
+    @TableField("sDisplayType")
+    private String sDisplayType;
+
+    @TableField("sProcedureName")
+    private String sProcedureName;
+
+    @TableField("sModuleType")
+    private String sModuleType;
+
+    @TableField("sManageDeptEn")
+    private String sManageDeptEn;
+
+    @TableField("bShowPermission")
+    private Boolean bShowPermission;
+
+    @TableField("sModuleNameZh")
+    private String sModuleNameZh;
+
+    /** REQ-MOD-002 允许更新为 null（清空父模块），用 IGNORED 让 MP updateById 把 NULL 写入 SQL。 */
+    @TableField(value = "iParentId", updateStrategy = FieldStrategy.IGNORED)
+    private Integer iParentId;
+
+    @TableField("iSortOrder")
+    private Integer iSortOrder;
+
+    @TableField("sCreatedBy")
+    private String sCreatedBy;
+
+    @TableField("bDeleted")
+    private Boolean bDeleted;
+
+    @TableField("tDeletedDate")
+    private LocalDateTime tDeletedDate;
+
+    @TableField("sDeletedBy")
+    private String sDeletedBy;
+}
+package com.xly.erp.module.mod.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.mod.entity.ModuleEntity;
+
+public interface ModuleMapper extends BaseMapper<ModuleEntity> {
+}
+package com.xly.erp.module.mod.service;
+
+import com.xly.erp.module.mod.dto.ModuleCreateDTO;
+import com.xly.erp.module.mod.dto.ModuleQueryDTO;
+import com.xly.erp.module.mod.dto.ModuleUpdateDTO;
+import com.xly.erp.module.mod.vo.ModuleDeleteResultVO;
+import com.xly.erp.module.mod.vo.ModuleTreeNodeVO;
+import com.xly.erp.module.mod.vo.ModuleVO;
+
+import java.util.List;
+
+public interface ModuleService {
+    /** REQ-MOD-001 模块新增 */
+    ModuleVO create(ModuleCreateDTO dto);
+
+    /** REQ-MOD-002 模块修改 */
+    ModuleVO update(Integer id, ModuleUpdateDTO dto);
+
+    /** REQ-MOD-003 模块软删除 */
+    ModuleDeleteResultVO delete(Integer id);
+
+    /** REQ-MOD-004 模块树查询（可选 keyword 模糊匹配 + 祖先链） */
+    List<ModuleTreeNodeVO> tree(ModuleQueryDTO query);
+}
+package com.xly.erp.module.mod.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.mod.dto.ModuleCreateDTO;
+import com.xly.erp.module.mod.dto.ModuleQueryDTO;
+import com.xly.erp.module.mod.dto.ModuleUpdateDTO;
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import com.xly.erp.module.mod.mapper.ModuleMapper;
+import com.xly.erp.module.mod.service.ModuleService;
+import com.xly.erp.module.mod.vo.ModuleDeleteResultVO;
+import com.xly.erp.module.mod.vo.ModuleTreeNodeVO;
+import com.xly.erp.module.mod.vo.ModuleVO;
+import lombok.RequiredArgsConstructor;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+@Service
+@RequiredArgsConstructor
+public class ModuleServiceImpl implements ModuleService {
+
+    private final ModuleMapper moduleMapper;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public ModuleVO create(ModuleCreateDTO dto) {
+        // 1. 父模块校验（仅当 iParentId 非空）
+        if (dto.getIParentId() != null) {
+            ModuleEntity parent = moduleMapper.selectById(dto.getIParentId());
+            if (parent == null || Boolean.TRUE.equals(parent.getBDeleted())) {
+                throw new BizException(ErrorCode.MOD_PARENT_NOT_FOUND);
+            }
+        }
+
+        // 2. sProcedureName 唯一性预检（未软删除范围）
+        Long exist = moduleMapper.selectCount(
+                new LambdaQueryWrapper<ModuleEntity>()
+                        .eq(ModuleEntity::getSProcedureName, dto.getSProcedureName())
+                        .eq(ModuleEntity::getBDeleted, false));
+        if (exist != null && exist > 0L) {
+            throw new BizException(ErrorCode.MOD_PROC_NAME_DUP);
+        }
+
+        // 3. 构造 entity
+        ModuleEntity e = new ModuleEntity();
+        e.setSDisplayType(dto.getSDisplayType());
+        e.setSProcedureName(dto.getSProcedureName());
+        e.setSModuleType(dto.getSModuleType());
+        e.setSManageDeptEn(dto.getSManageDeptEn());
+        e.setBShowPermission(dto.getBShowPermission() != null ? dto.getBShowPermission() : Boolean.FALSE);
+        e.setSModuleNameZh(dto.getSModuleNameZh());
+        e.setIParentId(dto.getIParentId());
+        e.setISortOrder(dto.getISortOrder() != null ? dto.getISortOrder() : 0);
+        e.setTCreateDate(LocalDateTime.now());
+        e.setBDeleted(Boolean.FALSE);
+        // sId / sBrandsId / sSubsidiaryId / sCreatedBy / tDeletedDate / sDeletedBy 留 null（REQ-USR-004 后由登录上下文 / 多租户上下文回填）
+
+        // 4. 插入；并发下唯一约束兜底
+        try {
+            moduleMapper.insert(e);
+        } catch (DuplicateKeyException dup) {
+            throw new BizException(ErrorCode.MOD_PROC_NAME_DUP);
+        }
+
+        // 5. 返回 VO
+        return ModuleVO.from(e);
+    }
+
+    /** REQ-MOD-002 模块修改 */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public ModuleVO update(Integer id, ModuleUpdateDTO dto) {
+        // 1. 目标模块校验
+        ModuleEntity target = moduleMapper.selectById(id);
+        if (target == null || Boolean.TRUE.equals(target.getBDeleted())) {
+            throw new BizException(ErrorCode.MOD_NOT_FOUND);
+        }
+
+        // 2. iParentId 校验
+        Integer newParentId = dto.getIParentId();
+        if (newParentId != null) {
+            // 2a. 自引用
+            if (newParentId.equals(id)) {
+                throw new BizException(ErrorCode.MOD_PARENT_LOOP);
+            }
+            // 2b. 父存在性
+            ModuleEntity parent = moduleMapper.selectById(newParentId);
+            if (parent == null || Boolean.TRUE.equals(parent.getBDeleted())) {
+                throw new BizException(ErrorCode.MOD_PARENT_NOT_FOUND);
+            }
+            // 2c. 环路检查：从 newParentId 沿父链 walk up，最多 5 层；遇到 id 即环路
+            ModuleEntity cur = parent;
+            int depth = 1;
+            while (cur != null && cur.getIParentId() != null && depth <= 5) {
+                if (cur.getIParentId().equals(id)) {
+                    throw new BizException(ErrorCode.MOD_PARENT_LOOP);
+                }
+                ModuleEntity next = moduleMapper.selectById(cur.getIParentId());
+                if (next == null || Boolean.TRUE.equals(next.getBDeleted())) {
+                    break;
+                }
+                cur = next;
+                depth++;
+            }
+        }
+
+        // 3. 字段合并到 target（sProcedureName / iIncrement / tCreateDate / sCreatedBy / 多租户字段 / bDeleted 等保留原值）
+        target.setSDisplayType(dto.getSDisplayType());
+        target.setSModuleType(dto.getSModuleType());
+        target.setSManageDeptEn(dto.getSManageDeptEn());
+        target.setSModuleNameZh(dto.getSModuleNameZh());
+        if (dto.getBShowPermission() != null) {
+            target.setBShowPermission(dto.getBShowPermission());
+        }
+        target.setIParentId(dto.getIParentId()); // null 设根
+        if (dto.getISortOrder() != null) {
+            target.setISortOrder(dto.getISortOrder());
+        }
+
+        // 4. 落库
+        moduleMapper.updateById(target);
+
+        // 5. 返回 VO
+        return ModuleVO.from(target);
+    }
+
+    /** REQ-MOD-003 模块软删除 */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public ModuleDeleteResultVO delete(Integer id) {
+        // 1. 目标存在 + 未软删除
+        ModuleEntity target = moduleMapper.selectById(id);
+        if (target == null || Boolean.TRUE.equals(target.getBDeleted())) {
+            throw new BizException(ErrorCode.MOD_NOT_FOUND);
+        }
+
+        // 2. 子模块（未软删除）引用检查
+        Long childCount = moduleMapper.selectCount(
+                new LambdaQueryWrapper<ModuleEntity>()
+                        .eq(ModuleEntity::getIParentId, id)
+                        .eq(ModuleEntity::getBDeleted, false));
+        if (childCount != null && childCount > 0L) {
+            throw new BizException(ErrorCode.MOD_HAS_REFERENCES);
+        }
+
+        // 3. 软删除写入：用 LambdaUpdateWrapper.set 显式声明 SET 列，避免 entity 驱动 SET
+        //    （iParentId 字段的 FieldStrategy.IGNORED 策略会让 entity-driven update 把
+        //     iParentId 写成 NULL，破坏父引用——这里用 wrapper.set 完全绕开 entity）
+        //    sDeletedBy 暂写 null（REQ-USR-004 后由登录上下文回填）。
+        //    eq(bDeleted, false) 兜底并发：影响 0 行视为已被并发删除 → 40421
+        LambdaUpdateWrapper<ModuleEntity> uw = new LambdaUpdateWrapper<ModuleEntity>()
+                .eq(ModuleEntity::getIIncrement, id)
+                .eq(ModuleEntity::getBDeleted, false)
+                .set(ModuleEntity::getBDeleted, true)
+                .set(ModuleEntity::getTDeletedDate, LocalDateTime.now())
+                .set(ModuleEntity::getSDeletedBy, null);
+
+        int affected = moduleMapper.update(null, uw);
+        if (affected == 0) {
+            throw new BizException(ErrorCode.MOD_NOT_FOUND);
+        }
+
+        return ModuleDeleteResultVO.of(id, true);
+    }
+
+    /** REQ-MOD-004 模块树查询 */
+    @Override
+    @Transactional(readOnly = true)
+    public List<ModuleTreeNodeVO> tree(ModuleQueryDTO query) {
+        // 1. 拉取所有未软删除模块
+        List<ModuleEntity> all = moduleMapper.selectList(
+                new LambdaQueryWrapper<ModuleEntity>().eq(ModuleEntity::getBDeleted, false));
+        if (all.isEmpty()) {
+            return new ArrayList<>();
+        }
+
+        // 2. id → entity 索引
+        Map<Integer, ModuleEntity> byId = all.stream()
+                .collect(Collectors.toMap(ModuleEntity::getIIncrement, e -> e));
+
+        // 3. 计算 survivors 集合
+        String keyword = query == null ? null : query.getKeyword();
+        Set<Integer> survivorIds;
+        if (keyword == null || keyword.isEmpty()) {
+            survivorIds = byId.keySet();
+        } else {
+            survivorIds = new HashSet<>();
+            // 命中节点
+            List<ModuleEntity> hits = all.stream()
+                    .filter(e -> e.getSModuleNameZh() != null && e.getSModuleNameZh().contains(keyword))
+                    .toList();
+            for (ModuleEntity hit : hits) {
+                survivorIds.add(hit.getIIncrement());
+                // 沿父链向上收集祖先（深度上限 5）
+                Integer parentId = hit.getIParentId();
+                int depth = 0;
+                while (parentId != null && depth < 5) {
+                    if (!survivorIds.add(parentId)) {
+                        break; // 已存在，提前结束避免循环
+                    }
+                    ModuleEntity parent = byId.get(parentId);
+                    if (parent == null) break;
+                    parentId = parent.getIParentId();
+                    depth++;
+                }
+            }
+            if (survivorIds.isEmpty()) {
+                return new ArrayList<>();
+            }
+        }
+
+        // 4. 转 VO + 按 (iSortOrder, iIncrement) 排序
+        Comparator<ModuleTreeNodeVO> cmp = Comparator
+                .comparingInt((ModuleTreeNodeVO v) -> v.getISortOrder() == null ? 0 : v.getISortOrder())
+                .thenComparingInt(ModuleTreeNodeVO::getIIncrement);
+
+        Map<Integer, ModuleTreeNodeVO> nodeById = new HashMap<>();
+        for (Integer id : survivorIds) {
+            ModuleEntity e = byId.get(id);
+            if (e != null) {
+                nodeById.put(id, ModuleTreeNodeVO.from(e));
+            }
+        }
+
+        // 5. 挂 children + 收集 roots
+        List<ModuleTreeNodeVO> roots = new ArrayList<>();
+        for (ModuleTreeNodeVO node : nodeById.values()) {
+            Integer pid = node.getIParentId();
+            if (pid == null || !nodeById.containsKey(pid)) {
+                // 父不存在于 survivors（被过滤掉或本身就是根）→ 提为根
+                roots.add(node);
+            } else {
+                nodeById.get(pid).getChildren().add(node);
+            }
+        }
+
+        // 6. 排序：根节点 + 每个节点的 children
+        roots.sort(cmp);
+        for (ModuleTreeNodeVO node : nodeById.values()) {
+            node.getChildren().sort(cmp);
+        }
+
+        return roots;
+    }
+}
+package com.xly.erp.module.mod.vo;
+
+import lombok.Data;
+
+/** REQ-MOD-003 模块删除返回精简 VO（仅含主键 + 删除标记） */
+@Data
+public class ModuleDeleteResultVO {
+    private Integer iIncrement;
+    private Boolean bDeleted;
+
+    public static ModuleDeleteResultVO of(Integer id, Boolean deleted) {
+        ModuleDeleteResultVO v = new ModuleDeleteResultVO();
+        v.setIIncrement(id);
+        v.setBDeleted(deleted);
+        return v;
+    }
+}
+package com.xly.erp.module.mod.vo;
+
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/** REQ-MOD-004 模块树节点 VO（不暴露内部字段） */
+@Data
+public class ModuleTreeNodeVO {
+    private Integer iIncrement;
+    private String sModuleNameZh;
+    private String sDisplayType;
+    private String sManageDeptEn;
+    private Integer iParentId;
+    private Integer iSortOrder;
+    private List<ModuleTreeNodeVO> children = new ArrayList<>();
+
+    public static ModuleTreeNodeVO from(ModuleEntity e) {
+        ModuleTreeNodeVO v = new ModuleTreeNodeVO();
+        v.setIIncrement(e.getIIncrement());
+        v.setSModuleNameZh(e.getSModuleNameZh());
+        v.setSDisplayType(e.getSDisplayType());
+        v.setSManageDeptEn(e.getSManageDeptEn());
+        v.setIParentId(e.getIParentId());
+        v.setISortOrder(e.getISortOrder());
+        v.setChildren(new ArrayList<>());
+        return v;
+    }
+}
+package com.xly.erp.module.mod.vo;
+
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+public class ModuleVO {
+    private Integer iIncrement;
+    private String sDisplayType;
+    private String sProcedureName;
+    private String sModuleType;
+    private String sManageDeptEn;
+    private Boolean bShowPermission;
+    private String sModuleNameZh;
+    private Integer iParentId;
+    private Integer iSortOrder;
+    private LocalDateTime tCreateDate;
+    private Boolean bDeleted;
+
+    public static ModuleVO from(ModuleEntity e) {
+        ModuleVO v = new ModuleVO();
+        v.setIIncrement(e.getIIncrement());
+        v.setSDisplayType(e.getSDisplayType());
+        v.setSProcedureName(e.getSProcedureName());
+        v.setSModuleType(e.getSModuleType());
+        v.setSManageDeptEn(e.getSManageDeptEn());
+        v.setBShowPermission(e.getBShowPermission());
+        v.setSModuleNameZh(e.getSModuleNameZh());
+        v.setIParentId(e.getIParentId());
+        v.setISortOrder(e.getISortOrder());
+        v.setTCreateDate(e.getTCreateDate());
+        v.setBDeleted(e.getBDeleted());
+        return v;
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.xly.erp.common.response.ApiResponse;
+import com.xly.erp.module.usr.dto.LoginDTO;
+import com.xly.erp.module.usr.service.LoginService;
+import com.xly.erp.module.usr.vo.LoginResultVO;
+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-004 用户登录入口 — 永久 permitAll；其他既有端点鉴权切换由后续 REQ 完成。 */
+@RestController
+@RequestMapping("/api/auth")
+@RequiredArgsConstructor
+public class LoginController {
+
+    private final LoginService loginService;
+
+    @PostMapping("/login")
+    public ApiResponse<LoginResultVO> login(@Valid @RequestBody LoginDTO dto) {
+        return ApiResponse.ok(loginService.login(dto));
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.xly.erp.common.response.ApiResponse;
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.module.usr.dto.UserCreateDTO;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.dto.UserUpdateDTO;
+import com.xly.erp.module.usr.service.UserService;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import com.xly.erp.module.usr.vo.UserVO;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+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/users")
+@RequiredArgsConstructor
+public class UserController {
+
+    private final UserService userService;
+
+    /** REQ-USR-001 用户新增 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:CREATE')") */
+    @PostMapping
+    public ApiResponse<UserVO> create(@Valid @RequestBody UserCreateDTO dto) {
+        return ApiResponse.ok(userService.create(dto));
+    }
+
+    /** REQ-USR-002 用户修改 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:UPDATE')") */
+    @PutMapping("/{id}")
+    public ApiResponse<UserVO> update(@PathVariable Integer id, @Valid @RequestBody UserUpdateDTO dto) {
+        return ApiResponse.ok(userService.update(id, dto));
+    }
+
+    /** REQ-USR-003 用户列表查询 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:READ')") */
+    @GetMapping
+    public ApiResponse<PageResult<UserListItemVO>> search(@Valid UserQueryDTO query) {
+        return ApiResponse.ok(userService.search(query));
+    }
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/** REQ-USR-004 用户登录入参 */
+@Data
+public class LoginDTO {
+
+    @NotBlank
+    @Size(max = 50)
+    private String sUserName;
+
+    @NotBlank
+    @Size(max = 100)
+    private String sPassword;
+
+    @NotBlank
+    @Pattern(regexp = "^standard$", message = "sVersion 仅支持 standard")
+    private String sVersion;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.util.List;
+
+/** REQ-USR-001 用户新增入参（密码不在 DTO 里，service 层固定哈希 666666 落库）。 */
+@Data
+public class UserCreateDTO {
+
+    @NotBlank
+    @Size(max = 50)
+    private String sUserNo;
+
+    @NotBlank
+    @Size(max = 50)
+    private String sUserName;
+
+    /** 可空：关联职员 id */
+    private Integer iStaffId;
+
+    @NotBlank
+    @Pattern(regexp = "^(普通用户|超级管理员)$", message = "sUserType 必须是 普通用户/超级管理员 之一")
+    private String sUserType;
+
+    @NotBlank
+    @Pattern(regexp = "^(zh|en|zh-TW)$", message = "sLanguage 必须是 zh/en/zh-TW 之一")
+    private String sLanguage;
+
+    /** 可空：默认 false */
+    private Boolean bCanModifyDocs;
+
+    /** 可空：每个 id 必须指向未删除的 tPermissionCategory.iIncrement */
+    private List<Integer> permissionCategoryIds;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+/** REQ-USR-003 用户查询参数 DTO（query string 绑定）。 */
+@Data
+public class UserQueryDTO {
+
+    @Min(1)
+    private Integer pageNum = 1;
+
+    @Min(1)
+    @Max(100)
+    private Integer pageSize = 20;
+
+    /** 可空：缺省视为不过滤；服务层白名单映射为 SQL 列名后通过 mapper @Param 单独传入 */
+    @Pattern(regexp = "^(username|staffname|userno|department|usertype|language|deleted|lastLoginDate|createdBy)?$",
+            message = "queryField 非法")
+    private String queryField;
+
+    /** 可空：默认 contains */
+    @Pattern(regexp = "^(contains|notContains|equals)?$", message = "matchType 非法")
+    private String matchType;
+
+    /** 可空：缺省视为不过滤 */
+    @Size(max = 100)
+    private String queryValue;
+}
+package com.xly.erp.module.usr.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Pattern;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * REQ-USR-002 用户修改入参。
+ * 与 {@link UserCreateDTO} 相比剥除 sUserNo / sUserName（登录身份不可改）；
+ * 密码不通过本接口修改，亦不在 DTO 里。
+ */
+@Data
+public class UserUpdateDTO {
+
+    /** 可空：null 表示清空员工关联（service 层借 iStaffId.IGNORED 策略写入 NULL） */
+    private Integer iStaffId;
+
+    @NotBlank
+    @Pattern(regexp = "^(普通用户|超级管理员)$", message = "sUserType 必须是 普通用户/超级管理员 之一")
+    private String sUserType;
+
+    @NotBlank
+    @Pattern(regexp = "^(zh|en|zh-TW)$", message = "sLanguage 必须是 zh/en/zh-TW 之一")
+    private String sLanguage;
+
+    /** 可空：null 表示保持原值；显式覆盖 */
+    private Boolean bCanModifyDocs;
+
+    /** 可空：每元素须存在且未软删除；空数组 / null 都视为清空全部授权关联 */
+    private List<Integer> permissionCategoryIds;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-001 引入。表 tPermissionCategory（详见 docs/03 § tPermissionCategory）。 */
+@Data
+@TableName("tPermissionCategory")
+public class PermissionCategoryEntity {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    @TableField("sId")
+    private String sId;
+
+    @TableField("sBrandsId")
+    private String sBrandsId;
+
+    @TableField("sSubsidiaryId")
+    private String sSubsidiaryId;
+
+    @TableField("tCreateDate")
+    private LocalDateTime tCreateDate;
+
+    @TableField("sCategoryCode")
+    private String sCategoryCode;
+
+    @TableField("sCategoryName")
+    private String sCategoryName;
+
+    @TableField("iParentId")
+    private Integer iParentId;
+
+    @TableField("iSortOrder")
+    private Integer iSortOrder;
+
+    @TableField("sCreatedBy")
+    private String sCreatedBy;
+
+    @TableField("bDeleted")
+    private Boolean bDeleted;
+
+    @TableField("tDeletedDate")
+    private LocalDateTime tDeletedDate;
+
+    @TableField("sDeletedBy")
+    private String sDeletedBy;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-001 引入。表 tStaff（详见 docs/03 § tStaff）。 */
+@Data
+@TableName("tStaff")
+public class StaffEntity {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    @TableField("sId")
+    private String sId;
+
+    @TableField("sBrandsId")
+    private String sBrandsId;
+
+    @TableField("sSubsidiaryId")
+    private String sSubsidiaryId;
+
+    @TableField("tCreateDate")
+    private LocalDateTime tCreateDate;
+
+    @TableField("sStaffNo")
+    private String sStaffNo;
+
+    @TableField("sStaffName")
+    private String sStaffName;
+
+    @TableField("sDepartment")
+    private String sDepartment;
+
+    @TableField("sCreatedBy")
+    private String sCreatedBy;
+
+    @TableField("bDeleted")
+    private Boolean bDeleted;
+
+    @TableField("tDeletedDate")
+    private LocalDateTime tDeletedDate;
+
+    @TableField("sDeletedBy")
+    private String sDeletedBy;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.FieldStrategy;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-001 用户主数据。表 tUser（详见 docs/03 § tUser）。 */
+@Data
+@TableName("tUser")
+public class UserEntity {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    @TableField("sId")
+    private String sId;
+
+    @TableField("sBrandsId")
+    private String sBrandsId;
+
+    @TableField("sSubsidiaryId")
+    private String sSubsidiaryId;
+
+    @TableField("tCreateDate")
+    private LocalDateTime tCreateDate;
+
+    @TableField("sUserNo")
+    private String sUserNo;
+
+    @TableField("sUserName")
+    private String sUserName;
+
+    /** REQ-USR-002 允许更新为 null（清空员工关联），用 IGNORED 让 MP updateById 把 NULL 写入 SQL。
+     *  注意：此策略意味着任何 updateById 都会写 iStaffId；调用方必须 selectById 后再 updateById（load-then-modify）。 */
+    @TableField(value = "iStaffId", updateStrategy = FieldStrategy.IGNORED)
+    private Integer iStaffId;
+
+    @TableField("sUserType")
+    private String sUserType;
+
+    @TableField("sLanguage")
+    private String sLanguage;
+
+    @TableField("bCanModifyDocs")
+    private Boolean bCanModifyDocs;
+
+    @TableField("sPasswordHash")
+    private String sPasswordHash;
+
+    @TableField("tLastLoginDate")
+    private LocalDateTime tLastLoginDate;
+
+    @TableField("sCreatedBy")
+    private String sCreatedBy;
+
+    @TableField("bDeleted")
+    private Boolean bDeleted;
+
+    @TableField("tDeletedDate")
+    private LocalDateTime tDeletedDate;
+
+    @TableField("sDeletedBy")
+    private String sDeletedBy;
+}
+package com.xly.erp.module.usr.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-001 引入。表 tUserPermission（详见 docs/03 § tUserPermission）。 */
+@Data
+@TableName("tUserPermission")
+public class UserPermissionEntity {
+
+    @TableId(value = "iIncrement", type = IdType.AUTO)
+    private Integer iIncrement;
+
+    @TableField("sId")
+    private String sId;
+
+    @TableField("sBrandsId")
+    private String sBrandsId;
+
+    @TableField("sSubsidiaryId")
+    private String sSubsidiaryId;
+
+    @TableField("tCreateDate")
+    private LocalDateTime tCreateDate;
+
+    @TableField("iUserId")
+    private Integer iUserId;
+
+    @TableField("iCategoryId")
+    private Integer iCategoryId;
+
+    // docs/03 § tUserPermission 修订版无 bSelected 列——关联记录存在即「已选」，无需独立 flag。
+    // 早期 REQ-USR-001 spec/plan 草稿曾包含 bSelected，与 SSoT docs/03 不一致；以 docs/03 为准。
+
+    @TableField("sCreatedBy")
+    private String sCreatedBy;
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.PermissionCategoryEntity;
+
+public interface PermissionCategoryMapper extends BaseMapper<PermissionCategoryEntity> {
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.StaffEntity;
+
+public interface StaffMapper extends BaseMapper<StaffEntity> {
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import org.apache.ibatis.annotations.Param;
+
+public interface UserMapper extends BaseMapper<UserEntity> {
+
+    /**
+     * REQ-USR-003 用户列表查询：跨表 JOIN tStaff，按 query 过滤 + 分页。XML 实现。
+     * @param column service 层白名单映射后的 SQL 列字符串（如 "u.sUserName"）；外部输入绝不直接走这里。
+     */
+    IPage<UserListItemVO> searchUsers(IPage<UserListItemVO> page,
+                                       @Param("query") UserQueryDTO query,
+                                       @Param("column") String column);
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.xly.erp.module.usr.entity.UserPermissionEntity;
+
+public interface UserPermissionMapper extends BaseMapper<UserPermissionEntity> {
+}
+package com.xly.erp.module.usr.security;
+
+import org.springframework.stereotype.Component;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+
+/**
+ * REQ-USR-004 内存版登录失败计数 / 锁定。
+ * 注意：单机有效；多实例部署需要替换为 Redis 实现（后续 REQ）。
+ */
+@Component
+public class InMemoryLoginAttemptStore implements LoginAttemptStore {
+
+    static final int LOCK_THRESHOLD = 5;
+    static final Duration LOCK_DURATION = Duration.ofMinutes(15);
+
+    private final ConcurrentMap<String, FailRecord> store = new ConcurrentHashMap<>();
+
+    @Override
+    public long cooldownSeconds(String username) {
+        FailRecord r = store.get(username);
+        if (r == null || r.lockUntil == null) {
+            return 0L;
+        }
+        long remaining = r.lockUntil.getEpochSecond() - Instant.now().getEpochSecond();
+        if (remaining <= 0L) {
+            // 锁定到期 → 清空 record（spec § 业务规则 4 第 4 条：reset count=0）
+            store.remove(username);
+            return 0L;
+        }
+        return remaining;
+    }
+
+    @Override
+    public void recordFailure(String username) {
+        Instant now = Instant.now();
+        store.compute(username, (k, prev) -> {
+            // 锁定到期 → reset 重新起算
+            FailRecord r = (prev != null && prev.lockUntil != null && now.isAfter(prev.lockUntil))
+                    ? new FailRecord()
+                    : (prev == null ? new FailRecord() : prev);
+            r.count++;
+            if (r.count >= LOCK_THRESHOLD && r.lockUntil == null) {
+                r.lockUntil = now.plus(LOCK_DURATION);
+            }
+            return r;
+        });
+    }
+
+    @Override
+    public void clear(String username) {
+        store.remove(username);
+    }
+
+    /** 测试辅助：把锁定到期时间手工拨到过去（验证「锁定到期后可登录」语义）。
+     *  public 因 LoginControllerIT 跨包调用；命名后缀 ForTest 提示生产代码不应使用。 */
+    public void expireLockForTest(String username) {
+        store.computeIfPresent(username, (k, r) -> {
+            r.lockUntil = Instant.now().minusSeconds(1);
+            return r;
+        });
+    }
+
+    static class FailRecord {
+        int count;
+        Instant lockUntil;
+    }
+}
+package com.xly.erp.module.usr.security;
+
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.security.Keys;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import javax.crypto.SecretKey;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.Date;
+
+/** REQ-USR-004 JWT 签发 / 校验封装。HS256，secret 来自 .env.local JWT_SECRET。 */
+@Component
+public class JwtTokenProvider {
+
+    private final SecretKey key;
+    private final long expiresInSeconds;
+
+    public JwtTokenProvider(@Value("${erp.jwt.secret}") String secret,
+                            @Value("${erp.jwt.expires-in-seconds}") long expiresInSeconds) {
+        this.key = Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8));
+        this.expiresInSeconds = expiresInSeconds;
+    }
+
+    public long getExpiresInSeconds() {
+        return expiresInSeconds;
+    }
+
+    public String sign(int uid, String username, String userType) {
+        Instant now = Instant.now();
+        return Jwts.builder()
+                .subject(username)
+                .claim("uid", uid)
+                .claim("type", userType)
+                .issuedAt(Date.from(now))
+                .expiration(Date.from(now.plusSeconds(expiresInSeconds)))
+                .signWith(key)
+                .compact();
+    }
+
+    public Claims parse(String token) {
+        return Jwts.parser()
+                .verifyWith(key)
+                .build()
+                .parseSignedClaims(token)
+                .getPayload();
+    }
+}
+package com.xly.erp.module.usr.security;
+
+/** REQ-USR-004 登录失败计数 / 锁定接口；本期 InMemory 实现，后续 REQ 用 Redis 替换。 */
+public interface LoginAttemptStore {
+
+    /** 已锁定且未到期 → 返回 cooldownSeconds（>0）；未锁定或已到期 → 返回 0 */
+    long cooldownSeconds(String username);
+
+    /** 记录一次失败：count++；count==5 触发 15min 锁定 */
+    void recordFailure(String username);
+
+    /** 登录成功清空记录 */
+    void clear(String username);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.module.usr.dto.LoginDTO;
+import com.xly.erp.module.usr.vo.LoginResultVO;
+
+public interface LoginService {
+    /** REQ-USR-004 用户登录 */
+    LoginResultVO login(LoginDTO dto);
+}
+package com.xly.erp.module.usr.service;
+
+import com.xly.erp.common.response.PageResult;
+import com.xly.erp.module.usr.dto.UserCreateDTO;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.dto.UserUpdateDTO;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import com.xly.erp.module.usr.vo.UserVO;
+
+public interface UserService {
+    /** REQ-USR-001 用户新增 */
+    UserVO create(UserCreateDTO dto);
+
+    /** REQ-USR-002 用户修改 */
+    UserVO update(Integer id, UserUpdateDTO dto);
+
+    /** REQ-USR-003 用户列表查询 */
+    PageResult<UserListItemVO> search(UserQueryDTO query);
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.xly.erp.common.exception.AccountLockedException;
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.LoginDTO;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.security.JwtTokenProvider;
+import com.xly.erp.module.usr.security.LoginAttemptStore;
+import com.xly.erp.module.usr.service.LoginService;
+import com.xly.erp.module.usr.vo.LoginResultVO;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-004 用户登录 service */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class LoginServiceImpl implements LoginService {
+
+    private final UserMapper userMapper;
+    private final PasswordEncoder passwordEncoder;
+    private final LoginAttemptStore attemptStore;
+    private final JwtTokenProvider jwtTokenProvider;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public LoginResultVO login(LoginDTO dto) {
+        String username = dto.getSUserName();
+
+        // 1. 锁定检查
+        long cooldown = attemptStore.cooldownSeconds(username);
+        if (cooldown > 0L) {
+            log.info("Login locked username={} cooldown={}s", username, cooldown);
+            throw new AccountLockedException(cooldown);
+        }
+
+        // 2. 查用户
+        UserEntity user = userMapper.selectOne(
+                new LambdaQueryWrapper<UserEntity>()
+                        .eq(UserEntity::getSUserName, username)
+                        .eq(UserEntity::getBDeleted, false));
+        if (user == null) {
+            log.info("Login user-not-found username={}", username);
+            attemptStore.recordFailure(username);
+            // 检查 record 后是否触发锁定（边界：第 5 次失败，下一次再调时已锁）
+            long cd = attemptStore.cooldownSeconds(username);
+            if (cd > 0L) {
+                throw new AccountLockedException(cd);
+            }
+            throw new BizException(ErrorCode.LOGIN_INVALID_CREDENTIALS);
+        }
+
+        // 3. BCrypt 校验
+        if (!passwordEncoder.matches(dto.getSPassword(), user.getSPasswordHash())) {
+            log.info("Login bad-password username={}", username);
+            attemptStore.recordFailure(username);
+            long cd = attemptStore.cooldownSeconds(username);
+            if (cd > 0L) {
+                throw new AccountLockedException(cd);
+            }
+            throw new BizException(ErrorCode.LOGIN_INVALID_CREDENTIALS);
+        }
+
+        // 4. 成功：清失败计数 + 签发 token + 更新 tLastLoginDate
+        attemptStore.clear(username);
+        String token = jwtTokenProvider.sign(user.getIIncrement(), user.getSUserName(), user.getSUserType());
+        userMapper.update(null,
+                new LambdaUpdateWrapper<UserEntity>()
+                        .eq(UserEntity::getIIncrement, user.getIIncrement())
+                        .set(UserEntity::getTLastLoginDate, LocalDateTime.now()));
+        log.info("Login success username={} uid={}", username, user.getIIncrement());
+
+        LoginResultVO.LoginUserInfo info = new LoginResultVO.LoginUserInfo(
+                user.getIIncrement(), user.getSUserNo(), user.getSUserName(),
+                user.getSUserType(), user.getSLanguage());
+        return new LoginResultVO(token, jwtTokenProvider.getExpiresInSeconds(), info);
+    }
+}
+package com.xly.erp.module.usr.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+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.UserCreateDTO;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.dto.UserUpdateDTO;
+import com.xly.erp.module.usr.entity.PermissionCategoryEntity;
+import com.xly.erp.module.usr.entity.StaffEntity;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.entity.UserPermissionEntity;
+import com.xly.erp.module.usr.mapper.PermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.StaffMapper;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.mapper.UserPermissionMapper;
+import com.xly.erp.module.usr.service.UserService;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import com.xly.erp.module.usr.vo.UserVO;
+import lombok.RequiredArgsConstructor;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.security.crypto.password.PasswordEncoder;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/** REQ-USR-001 用户新增 */
+@Service
+@RequiredArgsConstructor
+public class UserServiceImpl implements UserService {
+
+    private static final String INITIAL_PASSWORD = "666666";
+
+    private final UserMapper userMapper;
+    private final StaffMapper staffMapper;
+    private final PermissionCategoryMapper permissionCategoryMapper;
+    private final UserPermissionMapper userPermissionMapper;
+    private final PasswordEncoder passwordEncoder;
+
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public UserVO create(UserCreateDTO dto) {
+        // 1. 唯一性预检：sUserName / sUserNo（bDeleted=0 范围）
+        Long existsByName = userMapper.selectCount(
+                new LambdaQueryWrapper<UserEntity>()
+                        .eq(UserEntity::getSUserName, dto.getSUserName())
+                        .eq(UserEntity::getBDeleted, false));
+        if (existsByName != null && existsByName > 0L) {
+            throw new BizException(ErrorCode.USR_USER_NAME_OR_NO_DUP);
+        }
+        Long existsByNo = userMapper.selectCount(
+                new LambdaQueryWrapper<UserEntity>()
+                        .eq(UserEntity::getSUserNo, dto.getSUserNo())
+                        .eq(UserEntity::getBDeleted, false));
+        if (existsByNo != null && existsByNo > 0L) {
+            throw new BizException(ErrorCode.USR_USER_NAME_OR_NO_DUP);
+        }
+
+        // 2. iStaffId 校验
+        if (dto.getIStaffId() != null) {
+            StaffEntity staff = staffMapper.selectById(dto.getIStaffId());
+            if (staff == null || Boolean.TRUE.equals(staff.getBDeleted())) {
+                throw new BizException(ErrorCode.STAFF_NOT_FOUND);
+            }
+        }
+
+        // 3. 权限分类校验：批量查；要求每个 id 都存在且未软删除
+        List<Integer> categoryIds = dto.getPermissionCategoryIds() == null
+                ? new ArrayList<>() : dto.getPermissionCategoryIds();
+        if (!categoryIds.isEmpty()) {
+            List<PermissionCategoryEntity> found = permissionCategoryMapper.selectBatchIds(categoryIds);
+            if (found.size() != categoryIds.size()
+                    || found.stream().anyMatch(p -> Boolean.TRUE.equals(p.getBDeleted()))) {
+                throw new BizException(ErrorCode.PERM_CATEGORY_NOT_FOUND);
+            }
+        }
+
+        // 4. 构造 UserEntity 并 insert
+        UserEntity user = new UserEntity();
+        user.setSUserNo(dto.getSUserNo());
+        user.setSUserName(dto.getSUserName());
+        user.setIStaffId(dto.getIStaffId());
+        user.setSUserType(dto.getSUserType());
+        user.setSLanguage(dto.getSLanguage());
+        user.setBCanModifyDocs(dto.getBCanModifyDocs() != null ? dto.getBCanModifyDocs() : Boolean.FALSE);
+        user.setSPasswordHash(passwordEncoder.encode(INITIAL_PASSWORD));
+        user.setTCreateDate(LocalDateTime.now());
+        user.setBDeleted(Boolean.FALSE);
+        // tLastLoginDate / sCreatedBy / sBrandsId / sSubsidiaryId / sId / tDeletedDate / sDeletedBy 留 null
+
+        try {
+            userMapper.insert(user);
+        } catch (DuplicateKeyException dup) {
+            throw new BizException(ErrorCode.USR_USER_NAME_OR_NO_DUP);
+        }
+
+        // 5. 批量 insert UserPermission
+        for (Integer categoryId : categoryIds) {
+            UserPermissionEntity up = new UserPermissionEntity();
+            up.setIUserId(user.getIIncrement());
+            up.setICategoryId(categoryId);
+            up.setTCreateDate(LocalDateTime.now());
+            // sCreatedBy 留 null（REQ-USR-004 后回填）
+            userPermissionMapper.insert(up);
+        }
+
+        return UserVO.from(user, categoryIds);
+    }
+
+    /** REQ-USR-002 用户修改 */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public UserVO update(Integer id, UserUpdateDTO dto) {
+        // 1. 目标用户存在 + 未软删除
+        UserEntity target = userMapper.selectById(id);
+        if (target == null || Boolean.TRUE.equals(target.getBDeleted())) {
+            throw new BizException(ErrorCode.USR_NOT_FOUND);
+        }
+
+        // 2. iStaffId 校验（仅当非空）
+        if (dto.getIStaffId() != null) {
+            StaffEntity staff = staffMapper.selectById(dto.getIStaffId());
+            if (staff == null || Boolean.TRUE.equals(staff.getBDeleted())) {
+                throw new BizException(ErrorCode.STAFF_NOT_FOUND);
+            }
+        }
+
+        // 3. 权限分类校验（仅当非空）
+        List<Integer> categoryIds = dto.getPermissionCategoryIds() == null
+                ? new ArrayList<>() : dto.getPermissionCategoryIds();
+        if (!categoryIds.isEmpty()) {
+            List<PermissionCategoryEntity> found = permissionCategoryMapper.selectBatchIds(categoryIds);
+            if (found.size() != categoryIds.size()
+                    || found.stream().anyMatch(p -> Boolean.TRUE.equals(p.getBDeleted()))) {
+                throw new BizException(ErrorCode.PERM_CATEGORY_NOT_FOUND);
+            }
+        }
+
+        // 4. 字段合并到 target（保留 sUserNo / sUserName / sPasswordHash 等保护字段）
+        target.setIStaffId(dto.getIStaffId()); // 含 null 清空（依赖 iStaffId.IGNORED 策略）
+        target.setSUserType(dto.getSUserType());
+        target.setSLanguage(dto.getSLanguage());
+        if (dto.getBCanModifyDocs() != null) {
+            target.setBCanModifyDocs(dto.getBCanModifyDocs());
+        }
+
+        // 5. 落库 user
+        userMapper.updateById(target);
+
+        // 6. 重建权限关联：先删后插（清空原有，再按 dto 插入）
+        userPermissionMapper.delete(
+                new LambdaQueryWrapper<UserPermissionEntity>()
+                        .eq(UserPermissionEntity::getIUserId, id));
+        for (Integer categoryId : categoryIds) {
+            UserPermissionEntity up = new UserPermissionEntity();
+            up.setIUserId(id);
+            up.setICategoryId(categoryId);
+            up.setTCreateDate(LocalDateTime.now());
+            userPermissionMapper.insert(up);
+        }
+
+        return UserVO.from(target, categoryIds);
+    }
+
+    /** REQ-USR-003 用户列表查询 — queryField 白名单映射 + LEFT JOIN tStaff 分页 */
+    private static final Map<String, String> QUERY_COLUMN_MAP = Map.ofEntries(
+            Map.entry("username", "u.sUserName"),
+            Map.entry("staffname", "s.sStaffName"),
+            Map.entry("userno", "u.sUserNo"),
+            Map.entry("department", "s.sDepartment"),
+            Map.entry("usertype", "u.sUserType"),
+            Map.entry("language", "u.sLanguage"),
+            Map.entry("deleted", "u.bDeleted"),
+            Map.entry("lastLoginDate", "u.tLastLoginDate"),
+            Map.entry("createdBy", "u.sCreatedBy"));
+
+    private static final Set<String> MATCH_TYPES = Set.of("contains", "notContains", "equals");
+
+    @Override
+    @Transactional(readOnly = true)
+    public PageResult<UserListItemVO> search(UserQueryDTO query) {
+        // 1. queryField 白名单 + 列映射（防 SQL 注入）。
+        //    column 是 service 内部局部变量，通过 mapper @Param("column") 单独传入；不写回 DTO，
+        //    避免 GET query-string 绑定（@JsonIgnore 仅对 Jackson 生效，无法防 setter 注入）。
+        String column = null;
+        if (query.getQueryField() != null && !query.getQueryField().isEmpty()) {
+            column = QUERY_COLUMN_MAP.get(query.getQueryField());
+            if (column == null) {
+                throw new BizException(ErrorCode.PARAM_INVALID, "queryField 非法: " + query.getQueryField());
+            }
+        }
+
+        // 2. matchType 白名单
+        if (query.getMatchType() != null && !query.getMatchType().isEmpty()
+                && !MATCH_TYPES.contains(query.getMatchType())) {
+            throw new BizException(ErrorCode.PARAM_INVALID, "matchType 非法: " + query.getMatchType());
+        }
+
+        // 3. spec § 业务规则 6：deleted 字段值标准化（'true'/'1' → '1'；'false'/'0' → '0'；其它非法）
+        if ("deleted".equals(query.getQueryField())
+                && query.getQueryValue() != null && !query.getQueryValue().isEmpty()) {
+            String v = query.getQueryValue().trim().toLowerCase();
+            if ("true".equals(v) || "1".equals(v)) {
+                query.setQueryValue("1");
+            } else if ("false".equals(v) || "0".equals(v)) {
+                query.setQueryValue("0");
+            } else {
+                throw new BizException(ErrorCode.PARAM_INVALID, "deleted queryValue 仅支持 true/false/1/0");
+            }
+        }
+
+        // 4. 默认值兜底
+        int pageNum = query.getPageNum() == null ? 1 : query.getPageNum();
+        int pageSize = query.getPageSize() == null ? 20 : query.getPageSize();
+
+        // 5. MP 分页查询
+        IPage<UserListItemVO> page = new Page<>(pageNum, pageSize);
+        IPage<UserListItemVO> result = userMapper.searchUsers(page, query, column);
+
+        return PageResult.of(result);
+    }
+}
+package com.xly.erp.module.usr.vo;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/** REQ-USR-004 登录结果 VO（含 JWT + 用户基本信息） */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class LoginResultVO {
+    private String accessToken;
+    private long expiresIn;
+    private LoginUserInfo user;
+
+    @Data
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class LoginUserInfo {
+        private Integer iIncrement;
+        private String sUserNo;
+        private String sUserName;
+        private String sUserType;
+        private String sLanguage;
+    }
+}
+package com.xly.erp.module.usr.vo;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** REQ-USR-003 用户列表行 VO（含 LEFT JOIN tStaff 出来的 sStaffName / sDepartment）。 */
+@Data
+public class UserListItemVO {
+    private Integer iIncrement;
+    private String sUserName;
+    private String sStaffName;
+    private String sUserNo;
+    private String sDepartment;
+    private String sUserType;
+    private String sLanguage;
+    private Boolean bDeleted;
+    private LocalDateTime tLastLoginDate;
+    private String sCreatedBy;
+    private LocalDateTime tCreateDate;
+}
+package com.xly.erp.module.usr.vo;
+
+import com.xly.erp.module.usr.entity.UserEntity;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+
+/** REQ-USR-001 用户 VO（不含 sPasswordHash 等内部字段）。 */
+@Data
+public class UserVO {
+    private Integer iIncrement;
+    private String sUserNo;
+    private String sUserName;
+    private Integer iStaffId;
+    private String sUserType;
+    private String sLanguage;
+    private Boolean bCanModifyDocs;
+    private LocalDateTime tCreateDate;
+    private Boolean bDeleted;
+    private List<Integer> permissionCategoryIds = new ArrayList<>();
+
+    public static UserVO from(UserEntity e, List<Integer> permissionCategoryIds) {
+        UserVO v = new UserVO();
+        v.setIIncrement(e.getIIncrement());
+        v.setSUserNo(e.getSUserNo());
+        v.setSUserName(e.getSUserName());
+        v.setIStaffId(e.getIStaffId());
+        v.setSUserType(e.getSUserType());
+        v.setSLanguage(e.getSLanguage());
+        v.setBCanModifyDocs(e.getBCanModifyDocs());
+        v.setTCreateDate(e.getTCreateDate());
+        v.setBDeleted(e.getBDeleted());
+        v.setPermissionCategoryIds(permissionCategoryIds == null ? new ArrayList<>() : permissionCategoryIds);
+        return v;
+    }
+}
+spring:
+  flyway:
+    enabled: true
+    locations: filesystem:../sql/migrations
+    baseline-on-migrate: true
+    baseline-version: 1
+    baseline-description: "REQ-MOD-001 baseline (V1 already applied manually in A4)"
+server:
+  port: 8080
+  servlet:
+    context-path: /
+
+spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:dev}
+  datasource:
+    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
+    username: ${DB_USER}
+    password: ${DB_PASSWORD}
+    driver-class-name: com.mysql.cj.jdbc.Driver
+  flyway:
+    enabled: true
+    locations: filesystem:../sql/migrations
+    baseline-on-migrate: true
+    baseline-version: 0
+    validate-on-migrate: true
+
+mybatis-plus:
+  configuration:
+    map-underscore-to-camel-case: false
+  global-config:
+    db-config:
+      id-type: auto
+
+erp:
+  jwt:
+    secret: ${JWT_SECRET}
+    expires-in-seconds: 7200
+<?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.mod.mapper.ModuleMapper">
+    <!-- REQ-MOD-001 仅使用 BaseMapper 默认 SQL；后续 REQ 按需扩展自定义查询 -->
+</mapper>
+<?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.UserMapper">
+
+    <!-- REQ-USR-003 用户列表查询：LEFT JOIN tStaff + 动态 WHERE。
+         column 由 service 层白名单映射后通过 @Param("column") 单独传入，
+         绝不接受 DTO 中可被 GET query-string 绑定的字段。 -->
+    <select id="searchUsers" resultType="com.xly.erp.module.usr.vo.UserListItemVO">
+        SELECT
+            u.iIncrement, u.sUserName, s.sStaffName, u.sUserNo,
+            s.sDepartment, u.sUserType, u.sLanguage, u.bDeleted,
+            u.tLastLoginDate, u.sCreatedBy, u.tCreateDate
+        FROM tUser u
+        LEFT JOIN tStaff s ON u.iStaffId = s.iIncrement AND s.bDeleted = 0
+        <where>
+            <!-- 默认过滤已软删除：仅当 queryField=='deleted' 且 queryValue 非空时让用户控制 bDeleted 取值 -->
+            <if test="query.queryField != 'deleted' or query.queryValue == null or query.queryValue == ''">
+                u.bDeleted = 0
+            </if>
+            <if test="column != null and column != '' and query.queryValue != null and query.queryValue != ''">
+                AND
+                <choose>
+                    <!-- deleted 是 bit(1) 列，MySQL 与字符串 '1'/'0' 隐式比较不可靠；
+                         service 已把 queryValue 标准化为 '0' / '1'，此处显式 CAST 成整数。 -->
+                    <when test="query.queryField == 'deleted'">
+                        ${column} = CAST(#{query.queryValue} AS UNSIGNED)
+                    </when>
+                    <when test="query.matchType == 'equals'">
+                        ${column} = #{query.queryValue}
+                    </when>
+                    <when test="query.matchType == 'notContains'">
+                        ${column} NOT LIKE CONCAT('%', #{query.queryValue}, '%')
+                    </when>
+                    <otherwise>
+                        ${column} LIKE CONCAT('%', #{query.queryValue}, '%')
+                    </otherwise>
+                </choose>
+            </if>
+        </where>
+        ORDER BY u.tCreateDate DESC, u.iIncrement DESC
+    </select>
+</mapper>
+package com.xly.erp;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class ErpApplicationTest {
+    @Test
+    void contextLoads() {
+        // Spring ApplicationContext 启动成功 + Flyway 完成 baseline / migrate 即视为通过
+    }
+}
+package com.xly.erp.common.exception;
+
+import com.xly.erp.common.response.ErrorCode;
+import jakarta.validation.constraints.NotBlank;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+import org.springframework.web.bind.annotation.GetMapping;
+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;
+
+import static org.assertj.core.api.Assertions.assertThat;
+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;
+
+class GlobalExceptionHandlerTest {
+
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        mockMvc = MockMvcBuilders.standaloneSetup(new DummyController())
+                .setControllerAdvice(new GlobalExceptionHandler())
+                .build();
+    }
+
+    @RestController
+    @RequestMapping("/api/__dummy")
+    static class DummyController {
+        @GetMapping("/biz")
+        public Object biz() { throw new BizException(ErrorCode.MOD_PARENT_NOT_FOUND); }
+
+        @GetMapping("/runtime")
+        public Object runtime() { throw new RuntimeException("internal boom\nstack-line-1\nstack-line-2"); }
+
+        @PostMapping(value = "/validation", consumes = MediaType.APPLICATION_JSON_VALUE)
+        public Object validation(@jakarta.validation.Valid @RequestBody Payload p) { return "ok"; }
+    }
+
+    static class Payload {
+        @NotBlank String name;
+        public String getName() { return name; }
+        public void setName(String n) { this.name = n; }
+    }
+
+    @Test
+    void bizException_returns200WithBizCode() throws Exception {
+        mockMvc.perform(get("/api/__dummy/biz"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40411))
+                .andExpect(jsonPath("$.message").value("父模块不存在或已删除"));
+    }
+
+    @Test
+    void validationException_returns200WithParamInvalidCode() throws Exception {
+        mockMvc.perform(post("/api/__dummy/validation")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"\"}"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void uncaughtException_returns200WithInternalErrorCode() throws Exception {
+        mockMvc.perform(get("/api/__dummy/runtime"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(50000));
+    }
+
+    @Test
+    void response_doesNotContainStackTrace() throws Exception {
+        String body = mockMvc.perform(get("/api/__dummy/runtime"))
+                .andReturn().getResponse().getContentAsString();
+        assertThat(body)
+                .doesNotContain("stack-line-1")
+                .doesNotContain("internal boom")
+                .doesNotContain("at java.")
+                .doesNotContain("Caused by");
+    }
+}
+package com.xly.erp.common.response;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class ApiResponseTest {
+
+    @Test
+    void ok_setsCode200AndDataAndTimestamp() {
+        long before = System.currentTimeMillis();
+        ApiResponse<String> r = ApiResponse.ok("hello");
+        long after = System.currentTimeMillis();
+
+        assertThat(r.getCode()).isEqualTo(200);
+        assertThat(r.getMessage()).isEqualTo("操作成功");
+        assertThat(r.getData()).isEqualTo("hello");
+        assertThat(r.getTimestamp()).isBetween(before, after);
+    }
+
+    @Test
+    void okWithMessage_overridesDefaultMessage() {
+        ApiResponse<Integer> r = ApiResponse.ok("created", 42);
+        assertThat(r.getCode()).isEqualTo(200);
+        assertThat(r.getMessage()).isEqualTo("created");
+        assertThat(r.getData()).isEqualTo(42);
+    }
+
+    @Test
+    void fail_mapsErrorCodeFields() {
+        ApiResponse<Void> r = ApiResponse.fail(ErrorCode.PARAM_INVALID);
+        assertThat(r.getCode()).isEqualTo(40010);
+        assertThat(r.getMessage()).isEqualTo("参数错误");
+        assertThat(r.getData()).isNull();
+    }
+
+    @Test
+    void failWithDetail_overridesDefaultMessage() {
+        ApiResponse<Void> r = ApiResponse.fail(ErrorCode.PARAM_INVALID, "sUserName: blank");
+        assertThat(r.getCode()).isEqualTo(40010);
+        assertThat(r.getMessage()).isEqualTo("sUserName: blank");
+    }
+
+    @Test
+    void errorCode_constantsMatchDocs05Spec() {
+        assertThat(ErrorCode.SUCCESS.getCode()).isEqualTo(200);
+        assertThat(ErrorCode.PARAM_INVALID.getCode()).isEqualTo(40010);
+        assertThat(ErrorCode.MOD_PARENT_NOT_FOUND.getCode()).isEqualTo(40411);
+        assertThat(ErrorCode.MOD_PROC_NAME_DUP.getCode()).isEqualTo(40911);
+        assertThat(ErrorCode.INTERNAL_ERROR.getCode()).isEqualTo(50000);
+        assertThat(ErrorCode.MOD_NOT_FOUND.getCode()).isEqualTo(40421);
+        assertThat(ErrorCode.MOD_PARENT_LOOP.getCode()).isEqualTo(40921);
+        assertThat(ErrorCode.MOD_HAS_REFERENCES.getCode()).isEqualTo(40912);
+        assertThat(ErrorCode.STAFF_NOT_FOUND.getCode()).isEqualTo(40421);
+        assertThat(ErrorCode.PERM_CATEGORY_NOT_FOUND.getCode()).isEqualTo(40422);
+        assertThat(ErrorCode.USR_USER_NAME_OR_NO_DUP.getCode()).isEqualTo(40921);
+        assertThat(ErrorCode.USR_NOT_FOUND.getCode()).isEqualTo(40431);
+        assertThat(ErrorCode.LOGIN_INVALID_CREDENTIALS.getCode()).isEqualTo(40101);
+        assertThat(ErrorCode.LOGIN_ACCOUNT_LOCKED.getCode()).isEqualTo(40301);
+    }
+}
+package com.xly.erp.config;
+
+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.context.annotation.Bean;
+import org.springframework.boot.test.context.TestConfiguration;
+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 static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+class SecurityConfigTest {
+
+    @Autowired MockMvc mockMvc;
+
+    @TestConfiguration
+    static class PingConfig {
+        @Bean PingController pingController() { return new PingController(); }
+    }
+
+    @RestController
+    @RequestMapping("/api/__ping")
+    static class PingController {
+        @GetMapping
+        public String ping() { return "pong"; }
+    }
+
+    @Test
+    void anyApiEndpoint_isPermittedWithoutAuth() throws Exception {
+        mockMvc.perform(get("/api/__ping"))
+                .andExpect(status().isOk())
+                .andExpect(content().string("pong"));
+    }
+}
+package com.xly.erp.module.mod.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.xly.erp.module.mod.dto.ModuleCreateDTO;
+import com.xly.erp.module.mod.dto.ModuleUpdateDTO;
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import com.xly.erp.module.mod.mapper.ModuleMapper;
+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.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.delete;
+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.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@Transactional
+@Rollback
+class ModuleControllerIT {
+
+    @Autowired MockMvc mockMvc;
+    @Autowired ObjectMapper objectMapper;
+    @Autowired ModuleMapper moduleMapper;
+
+    private ModuleCreateDTO valid(String procName) {
+        ModuleCreateDTO d = new ModuleCreateDTO();
+        d.setSDisplayType("前端业务");
+        d.setSProcedureName(procName);
+        d.setSModuleType("USR");
+        d.setSManageDeptEn("IT");
+        d.setBShowPermission(false);
+        d.setSModuleNameZh("用户管理");
+        d.setIParentId(null);
+        d.setISortOrder(0);
+        return d;
+    }
+
+    private String json(Object o) throws Exception { return objectMapper.writeValueAsString(o); }
+
+    @Test
+    void post_validRootModule_returns200WithVO() throws Exception {
+        ModuleCreateDTO dto = valid("sp_audit_root_" + System.nanoTime());
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iIncrement").isNumber())
+                .andExpect(jsonPath("$.data.sProcedureName").value(dto.getSProcedureName()))
+                .andExpect(jsonPath("$.data.bDeleted").value(false));
+    }
+
+    @Test
+    void post_validChildModule_returns200() throws Exception {
+        // 先建 root
+        ModuleCreateDTO root = valid("sp_audit_parent_" + System.nanoTime());
+        String rootBody = mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(root)))
+                .andExpect(status().isOk())
+                .andReturn().getResponse().getContentAsString();
+        Integer parentId = objectMapper.readTree(rootBody).path("data").path("iIncrement").asInt();
+
+        // 再建 child
+        ModuleCreateDTO child = valid("sp_audit_child_" + System.nanoTime());
+        child.setIParentId(parentId);
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(child)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iParentId").value(parentId));
+    }
+
+    @Test
+    void post_duplicateProcedureName_returns200WithCode40911() throws Exception {
+        String procName = "sp_audit_dup_" + System.nanoTime();
+        ModuleCreateDTO first = valid(procName);
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(first)))
+                .andExpect(status().isOk());
+
+        ModuleCreateDTO second = valid(procName);
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(second)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40911));
+    }
+
+    @Test
+    void post_parentNotFound_returns200WithCode40411() throws Exception {
+        ModuleCreateDTO d = valid("sp_audit_orphan_" + System.nanoTime());
+        d.setIParentId(999999);
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40411));
+    }
+
+    @Test
+    void post_missingRequiredField_returns200WithCode40010() throws Exception {
+        ModuleCreateDTO d = valid("sp_audit_miss_" + System.nanoTime());
+        d.setSModuleNameZh(null); // 必填缺失
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void post_invalidDisplayTypeEnum_returns200WithCode40010() throws Exception {
+        ModuleCreateDTO d = valid("sp_audit_enum_" + System.nanoTime());
+        d.setSDisplayType("非法值");
+        mockMvc.perform(post("/api/modules")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    // ============================================================
+    //  REQ-MOD-002 PUT 系列
+    // ============================================================
+
+    private Integer insertExisting(String procName, Integer parentId) {
+        ModuleEntity e = new ModuleEntity();
+        e.setSDisplayType("前端业务");
+        e.setSProcedureName(procName);
+        e.setSModuleType("USR");
+        e.setSManageDeptEn("IT");
+        e.setBShowPermission(false);
+        e.setSModuleNameZh("用户管理");
+        e.setIParentId(parentId);
+        e.setISortOrder(0);
+        e.setBDeleted(false);
+        e.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(e);
+        return e.getIIncrement();
+    }
+
+    private ModuleUpdateDTO updateDto() {
+        ModuleUpdateDTO d = new ModuleUpdateDTO();
+        d.setSDisplayType("系统配置");
+        d.setSModuleType("USR_REVISED");
+        d.setSManageDeptEn("OPS");
+        d.setBShowPermission(true);
+        d.setSModuleNameZh("用户管理（修订）");
+        d.setIParentId(null);
+        d.setISortOrder(5);
+        return d;
+    }
+
+    @Test
+    void put_validUpdate_returns200() throws Exception {
+        String origProc = "sp_put_valid_" + System.nanoTime();
+        Integer id = insertExisting(origProc, null);
+        mockMvc.perform(put("/api/modules/" + id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(updateDto())))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iIncrement").value(id))
+                .andExpect(jsonPath("$.data.sDisplayType").value("系统配置"))
+                .andExpect(jsonPath("$.data.sModuleNameZh").value("用户管理（修订）"))
+                .andExpect(jsonPath("$.data.sProcedureName").value(origProc));
+
+        ModuleEntity reloaded = moduleMapper.selectById(id);
+        assertThat(reloaded.getSModuleType()).isEqualTo("USR_REVISED");
+        assertThat(reloaded.getSManageDeptEn()).isEqualTo("OPS");
+        assertThat(reloaded.getBShowPermission()).isTrue();
+        assertThat(reloaded.getISortOrder()).isEqualTo(5);
+        assertThat(reloaded.getSProcedureName()).isEqualTo(origProc);
+    }
+
+    @Test
+    void put_setParentToNull_clearsParent() throws Exception {
+        Integer parentId = insertExisting("sp_put_parent_" + System.nanoTime(), null);
+        Integer childId = insertExisting("sp_put_child_" + System.nanoTime(), parentId);
+
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(null);
+
+        mockMvc.perform(put("/api/modules/" + childId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iParentId").doesNotExist());
+
+        assertThat(moduleMapper.selectById(childId).getIParentId()).isNull();
+    }
+
+    @Test
+    void put_targetNotFound_returns40421() throws Exception {
+        mockMvc.perform(put("/api/modules/999999")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(updateDto())))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40421));
+    }
+
+    @Test
+    void put_parentNotFound_returns40411() throws Exception {
+        Integer id = insertExisting("sp_put_orphan_" + System.nanoTime(), null);
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(999999);
+        mockMvc.perform(put("/api/modules/" + id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40411));
+    }
+
+    @Test
+    void put_parentSelfRef_returns40921() throws Exception {
+        Integer id = insertExisting("sp_put_self_" + System.nanoTime(), null);
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(id);
+        mockMvc.perform(put("/api/modules/" + id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40921));
+    }
+
+    @Test
+    void put_parentIsDescendant_returns40921() throws Exception {
+        // grandparent -> parent -> child；尝试把 grandparent 的 iParentId 设为 child
+        Integer grandId = insertExisting("sp_put_grand_" + System.nanoTime(), null);
+        Integer parentId = insertExisting("sp_put_par_" + System.nanoTime(), grandId);
+        Integer childId = insertExisting("sp_put_chi_" + System.nanoTime(), parentId);
+
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(childId);
+        mockMvc.perform(put("/api/modules/" + grandId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40921));
+    }
+
+    @Test
+    void put_missingRequired_returns40010() throws Exception {
+        Integer id = insertExisting("sp_put_miss_" + System.nanoTime(), null);
+        ModuleUpdateDTO d = updateDto();
+        d.setSModuleNameZh(null);
+        mockMvc.perform(put("/api/modules/" + id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(d)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    // ============================================================
+    //  REQ-MOD-003 DELETE 系列
+    // ============================================================
+
+    @Test
+    void delete_validLeaf_returns200WithBDeletedTrue() throws Exception {
+        Integer id = insertExisting("sp_del_leaf_" + System.nanoTime(), null);
+
+        mockMvc.perform(delete("/api/modules/" + id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iIncrement").value(id))
+                .andExpect(jsonPath("$.data.bDeleted").value(true));
+
+        ModuleEntity reloaded = moduleMapper.selectById(id);
+        assertThat(reloaded.getBDeleted()).isTrue();
+        assertThat(reloaded.getTDeletedDate()).isNotNull();
+    }
+
+    @Test
+    void delete_targetNotFound_returns40421() throws Exception {
+        mockMvc.perform(delete("/api/modules/999999"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40421));
+    }
+
+    @Test
+    void delete_targetAlreadyDeleted_returns40421() throws Exception {
+        Integer id = insertExisting("sp_del_already_" + System.nanoTime(), null);
+        // 手工置 bDeleted=true
+        ModuleEntity patch = new ModuleEntity();
+        patch.setIIncrement(id);
+        patch.setBDeleted(true);
+        moduleMapper.updateById(patch);
+
+        mockMvc.perform(delete("/api/modules/" + id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40421));
+    }
+
+    @Test
+    void delete_hasUndeletedChildren_returns40912() throws Exception {
+        Integer parentId = insertExisting("sp_del_par_" + System.nanoTime(), null);
+        insertExisting("sp_del_chi_" + System.nanoTime(), parentId);
+
+        mockMvc.perform(delete("/api/modules/" + parentId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40912));
+
+        // parent 仍未删除
+        assertThat(moduleMapper.selectById(parentId).getBDeleted()).isFalse();
+    }
+
+    @Test
+    void delete_softDeletedChildren_doesNotBlock_returns200() throws Exception {
+        Integer parentId = insertExisting("sp_del_pp_" + System.nanoTime(), null);
+        Integer childId = insertExisting("sp_del_cc_" + System.nanoTime(), parentId);
+
+        // 先 DELETE child（应成功）
+        mockMvc.perform(delete("/api/modules/" + childId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        // 再 DELETE parent（已删除子不阻塞）
+        mockMvc.perform(delete("/api/modules/" + parentId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        assertThat(moduleMapper.selectById(parentId).getBDeleted()).isTrue();
+    }
+
+    @Test
+    void delete_preservesOtherFields_onChildModule() throws Exception {
+        // 反例：非 root 子模块软删除后，iParentId / sProcedureName / sModuleNameZh /
+        // iSortOrder 等字段必须保持原值（spec § 业务规则 #4 + 验收 #1）。
+        Integer parentId = insertExisting("sp_del_pres_p_" + System.nanoTime(), null);
+        String childProc = "sp_del_pres_c_" + System.nanoTime();
+        // 用自定义字段值的 child（与 insertExisting 默认值不同），便于事后比对
+        ModuleEntity child = new ModuleEntity();
+        child.setSDisplayType("接口");
+        child.setSProcedureName(childProc);
+        child.setSModuleType("AUDIT");
+        child.setSManageDeptEn("OPS");
+        child.setBShowPermission(true);
+        child.setSModuleNameZh("待保留中文名");
+        child.setIParentId(parentId);
+        child.setISortOrder(7);
+        child.setBDeleted(false);
+        child.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(child);
+        Integer childId = child.getIIncrement();
+
+        mockMvc.perform(delete("/api/modules/" + childId))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.bDeleted").value(true));
+
+        ModuleEntity reloaded = moduleMapper.selectById(childId);
+        // 软删除三件套生效
+        assertThat(reloaded.getBDeleted()).isTrue();
+        assertThat(reloaded.getTDeletedDate()).isNotNull();
+        // 关键：其他列保持原值（曾经 iParentId.FieldStrategy.IGNORED 会清零这一列，本断言钉死该回归）
+        assertThat(reloaded.getIParentId()).isEqualTo(parentId);
+        assertThat(reloaded.getSProcedureName()).isEqualTo(childProc);
+        assertThat(reloaded.getSDisplayType()).isEqualTo("接口");
+        assertThat(reloaded.getSModuleType()).isEqualTo("AUDIT");
+        assertThat(reloaded.getSManageDeptEn()).isEqualTo("OPS");
+        assertThat(reloaded.getBShowPermission()).isTrue();
+        assertThat(reloaded.getSModuleNameZh()).isEqualTo("待保留中文名");
+        assertThat(reloaded.getISortOrder()).isEqualTo(7);
+    }
+
+    @Test
+    void delete_responseVOContainsOnlyIIncrementAndBDeleted() throws Exception {
+        Integer id = insertExisting("sp_del_vo_" + System.nanoTime(), null);
+
+        mockMvc.perform(delete("/api/modules/" + id))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.iIncrement").value(id))
+                .andExpect(jsonPath("$.data.bDeleted").value(true))
+                .andExpect(jsonPath("$.data.sProcedureName").doesNotExist())
+                .andExpect(jsonPath("$.data.sDisplayType").doesNotExist())
+                .andExpect(jsonPath("$.data.sModuleNameZh").doesNotExist());
+    }
+
+    @Test
+    void put_ignoresProcedureNameField_doesNotChange() throws Exception {
+        String origProc = "sp_put_keep_" + System.nanoTime();
+        Integer id = insertExisting(origProc, null);
+        // 手工拼一个含 sProcedureName 的请求体（DTO 没声明该字段，Jackson 默认忽略）
+        String body = """
+                {
+                  "sDisplayType": "系统配置",
+                  "sProcedureName": "hijack",
+                  "sModuleType": "USR_REVISED",
+                  "sManageDeptEn": "OPS",
+                  "bShowPermission": true,
+                  "sModuleNameZh": "用户管理（修订）",
+                  "iSortOrder": 5
+                }
+                """;
+        mockMvc.perform(put("/api/modules/" + id)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.sProcedureName").value(origProc));
+
+        assertThat(moduleMapper.selectById(id).getSProcedureName()).isEqualTo(origProc);
+    }
+
+    // ============================================================
+    //  REQ-MOD-004 GET 系列
+    // ============================================================
+
+    @Test
+    void get_emptyKeyword_returnsAllUndeletedAsTree() throws Exception {
+        // 插入一个 root + 一个 child；不带 keyword 的 GET 应能看到二者
+        Integer rootId = insertExisting("sp_get_root_" + System.nanoTime(), null);
+        Integer childId = insertExisting("sp_get_child_" + System.nanoTime(), rootId);
+
+        mockMvc.perform(get("/api/modules"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + rootId + ")]").exists())
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + rootId + ")].children[?(@.iIncrement==" + childId + ")]").exists());
+    }
+
+    @Test
+    void get_keyword_filtersByModuleNameZhWithAncestors() throws Exception {
+        // grandparent("系统配置") -> parent("用户管理") -> child("登录认证")
+        ModuleEntity gp = new ModuleEntity();
+        gp.setSDisplayType("前端业务"); gp.setSProcedureName("sp_get_kw_gp_" + System.nanoTime());
+        gp.setSModuleType("MOD"); gp.setSManageDeptEn("IT"); gp.setBShowPermission(false);
+        gp.setSModuleNameZh("系统配置-keyword test"); gp.setIParentId(null); gp.setISortOrder(0);
+        gp.setBDeleted(false); gp.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(gp);
+
+        ModuleEntity p = new ModuleEntity();
+        p.setSDisplayType("前端业务"); p.setSProcedureName("sp_get_kw_p_" + System.nanoTime());
+        p.setSModuleType("MOD"); p.setSManageDeptEn("IT"); p.setBShowPermission(false);
+        p.setSModuleNameZh("用户管理-keyword test"); p.setIParentId(gp.getIIncrement()); p.setISortOrder(0);
+        p.setBDeleted(false); p.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(p);
+
+        ModuleEntity c = new ModuleEntity();
+        c.setSDisplayType("前端业务"); c.setSProcedureName("sp_get_kw_c_" + System.nanoTime());
+        c.setSModuleType("MOD"); c.setSManageDeptEn("IT"); c.setBShowPermission(false);
+        c.setSModuleNameZh("唯一登录认证关键词"); c.setIParentId(p.getIIncrement()); c.setISortOrder(0);
+        c.setBDeleted(false); c.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(c);
+
+        mockMvc.perform(get("/api/modules").param("keyword", "唯一登录认证关键词"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                // 命中 child + 全部祖先：grandparent 在 root 数组中
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + gp.getIIncrement() + ")]").exists())
+                // grandparent.children 含 parent
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + gp.getIIncrement() + ")].children[?(@.iIncrement==" + p.getIIncrement() + ")]").exists())
+                // parent.children 含 child
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + gp.getIIncrement() + ")].children[?(@.iIncrement==" + p.getIIncrement() + ")].children[?(@.iIncrement==" + c.getIIncrement() + ")]").exists());
+    }
+
+    @Test
+    void get_keywordNoMatch_returnsEmptyArray() throws Exception {
+        insertExisting("sp_get_nm_" + System.nanoTime(), null);
+
+        mockMvc.perform(get("/api/modules").param("keyword", "绝对不存在的关键词xyz"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data").isArray())
+                .andExpect(jsonPath("$.data.length()").value(0));
+    }
+
+    @Test
+    void get_keywordTooLong_returns40010() throws Exception {
+        String longKw = "a".repeat(51);
+        mockMvc.perform(get("/api/modules").param("keyword", longKw))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void get_softDeletedNotInResult() throws Exception {
+        Integer id = insertExisting("sp_get_sd_" + System.nanoTime(), null);
+        // 软删除该模块
+        ModuleEntity patch = new ModuleEntity();
+        patch.setIIncrement(id);
+        patch.setBDeleted(true);
+        moduleMapper.updateById(patch);
+
+        mockMvc.perform(get("/api/modules"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + id + ")]").doesNotExist());
+    }
+
+    @Test
+    void get_responseExcludesInternalFields() throws Exception {
+        insertExisting("sp_get_priv_" + System.nanoTime(), null);
+
+        mockMvc.perform(get("/api/modules"))
+                .andExpect(status().isOk())
+                // 树节点不应包含内部字段
+                .andExpect(jsonPath("$.data[0].sProcedureName").doesNotExist())
+                .andExpect(jsonPath("$.data[0].sModuleType").doesNotExist())
+                .andExpect(jsonPath("$.data[0].bShowPermission").doesNotExist())
+                .andExpect(jsonPath("$.data[0].tCreateDate").doesNotExist())
+                .andExpect(jsonPath("$.data[0].bDeleted").doesNotExist());
+    }
+
+    @Test
+    void get_leafNodeChildrenIsEmptyArrayNotNull() throws Exception {
+        Integer id = insertExisting("sp_get_leaf_" + System.nanoTime(), null);
+
+        mockMvc.perform(get("/api/modules"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + id + ")].children").isArray())
+                .andExpect(jsonPath("$.data[?(@.iIncrement==" + id + ")].children.length()").value(0));
+    }
+}
+package com.xly.erp.module.mod.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.assertj.core.api.Assertions.assertThat;
+
+class ModuleCreateDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private ModuleCreateDTO valid() {
+        ModuleCreateDTO d = new ModuleCreateDTO();
+        d.setSDisplayType("前端业务");
+        d.setSProcedureName("sp_audit_user");
+        d.setSModuleType("USR");
+        d.setSManageDeptEn("IT");
+        d.setBShowPermission(false);
+        d.setSModuleNameZh("用户管理");
+        d.setIParentId(null);
+        d.setISortOrder(0);
+        return d;
+    }
+
+    @Test
+    void allValidFields_yieldsNoViolations() {
+        Set<ConstraintViolation<ModuleCreateDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void blankRequiredFields_yieldsViolations() {
+        ModuleCreateDTO d = new ModuleCreateDTO();
+        // 全部不填，触发 5 个 @NotBlank
+        Set<ConstraintViolation<ModuleCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sDisplayType", "sProcedureName", "sModuleType", "sManageDeptEn", "sModuleNameZh");
+    }
+
+    @Test
+    void invalidDisplayTypeEnum_yieldsViolation() {
+        ModuleCreateDTO d = valid();
+        d.setSDisplayType("非法值");
+        Set<ConstraintViolation<ModuleCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sDisplayType");
+    }
+
+    @Test
+    void overSizedFields_yieldsViolations() {
+        ModuleCreateDTO d = valid();
+        d.setSProcedureName("a".repeat(101));
+        d.setSModuleType("a".repeat(51));
+        Set<ConstraintViolation<ModuleCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sProcedureName", "sModuleType");
+    }
+
+    @Test
+    void negativeSortOrder_yieldsViolation() {
+        ModuleCreateDTO d = valid();
+        d.setISortOrder(-1);
+        Set<ConstraintViolation<ModuleCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("iSortOrder");
+    }
+}
+package com.xly.erp.module.mod.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.assertj.core.api.Assertions.assertThat;
+
+class ModuleUpdateDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private ModuleUpdateDTO valid() {
+        ModuleUpdateDTO d = new ModuleUpdateDTO();
+        d.setSDisplayType("前端业务");
+        d.setSModuleType("USR");
+        d.setSManageDeptEn("IT");
+        d.setBShowPermission(true);
+        d.setSModuleNameZh("用户管理（修订）");
+        d.setIParentId(null);
+        d.setISortOrder(0);
+        return d;
+    }
+
+    @Test
+    void allValidFields_yieldsNoViolations() {
+        Set<ConstraintViolation<ModuleUpdateDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void blankRequiredFields_yieldsViolations() {
+        ModuleUpdateDTO d = new ModuleUpdateDTO();
+        Set<ConstraintViolation<ModuleUpdateDTO>> v = validator.validate(d);
+        // 5 个 @NotBlank：sDisplayType / sModuleType / sManageDeptEn / sModuleNameZh
+        // （bShowPermission / iParentId / iSortOrder 可空）
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sDisplayType", "sModuleType", "sManageDeptEn", "sModuleNameZh");
+    }
+
+    @Test
+    void invalidDisplayTypeEnum_yieldsViolation() {
+        ModuleUpdateDTO d = valid();
+        d.setSDisplayType("非法值");
+        Set<ConstraintViolation<ModuleUpdateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sDisplayType");
+    }
+
+    @Test
+    void negativeSortOrder_yieldsViolation() {
+        ModuleUpdateDTO d = valid();
+        d.setISortOrder(-1);
+        Set<ConstraintViolation<ModuleUpdateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("iSortOrder");
+    }
+}
+package com.xly.erp.module.mod.mapper;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest
+@ActiveProfiles("test")
+@Transactional
+@Rollback
+class ModuleMapperIT {
+
+    @Autowired ModuleMapper moduleMapper;
+
+    @Test
+    void insertAndSelectById_persistsAllFields() {
+        ModuleEntity e = new ModuleEntity();
+        e.setSDisplayType("前端业务");
+        e.setSProcedureName("sp_audit_test_" + System.nanoTime());
+        e.setSModuleType("USR");
+        e.setSManageDeptEn("IT");
+        e.setBShowPermission(false);
+        e.setSModuleNameZh("测试模块");
+        e.setIParentId(null);
+        e.setISortOrder(0);
+        e.setBDeleted(false);
+        e.setTCreateDate(LocalDateTime.now());
+
+        int rows = moduleMapper.insert(e);
+        assertThat(rows).isEqualTo(1);
+        assertThat(e.getIIncrement()).isNotNull().isPositive();
+
+        ModuleEntity loaded = moduleMapper.selectById(e.getIIncrement());
+        assertThat(loaded).isNotNull();
+        assertThat(loaded.getSDisplayType()).isEqualTo("前端业务");
+        assertThat(loaded.getSProcedureName()).isEqualTo(e.getSProcedureName());
+        assertThat(loaded.getSModuleType()).isEqualTo("USR");
+        assertThat(loaded.getSManageDeptEn()).isEqualTo("IT");
+        assertThat(loaded.getBShowPermission()).isFalse();
+        assertThat(loaded.getSModuleNameZh()).isEqualTo("测试模块");
+        assertThat(loaded.getIParentId()).isNull();
+        assertThat(loaded.getISortOrder()).isZero();
+        assertThat(loaded.getBDeleted()).isFalse();
+    }
+
+    @Test
+    void selectCountByProcedureName_returnsExisting() {
+        String name = "sp_audit_uniq_" + System.nanoTime();
+        ModuleEntity e = new ModuleEntity();
+        e.setSDisplayType("接口");
+        e.setSProcedureName(name);
+        e.setSModuleType("MOD");
+        e.setSManageDeptEn("IT");
+        e.setBShowPermission(false);
+        e.setSModuleNameZh("唯一性检测");
+        e.setISortOrder(0);
+        e.setBDeleted(false);
+        e.setTCreateDate(LocalDateTime.now());
+        moduleMapper.insert(e);
+
+        Long count = moduleMapper.selectCount(
+                new LambdaQueryWrapper<ModuleEntity>()
+                        .eq(ModuleEntity::getSProcedureName, name)
+                        .eq(ModuleEntity::getBDeleted, false)
+        );
+        assertThat(count).isEqualTo(1L);
+    }
+}
+package com.xly.erp.module.mod.service;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.mod.dto.ModuleCreateDTO;
+import com.xly.erp.module.mod.dto.ModuleQueryDTO;
+import com.xly.erp.module.mod.dto.ModuleUpdateDTO;
+import com.xly.erp.module.mod.entity.ModuleEntity;
+import com.xly.erp.module.mod.mapper.ModuleMapper;
+import com.xly.erp.module.mod.service.impl.ModuleServiceImpl;
+import com.xly.erp.module.mod.vo.ModuleDeleteResultVO;
+import com.xly.erp.module.mod.vo.ModuleTreeNodeVO;
+import com.xly.erp.module.mod.vo.ModuleVO;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.ArgumentMatchers;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.dao.DuplicateKeyException;
+
+import java.time.LocalDateTime;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class ModuleServiceImplTest {
+
+    @Mock ModuleMapper moduleMapper;
+
+    @InjectMocks ModuleServiceImpl service;
+
+    private ModuleCreateDTO baseDto() {
+        ModuleCreateDTO d = new ModuleCreateDTO();
+        d.setSDisplayType("前端业务");
+        d.setSProcedureName("sp_audit_user");
+        d.setSModuleType("USR");
+        d.setSManageDeptEn("IT");
+        d.setBShowPermission(false);
+        d.setSModuleNameZh("用户管理");
+        return d;
+    }
+
+    @Test
+    void create_rootModule_returnsVOWithGeneratedId() {
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(moduleMapper.insert((ModuleEntity) any())).thenAnswer(inv -> {
+            ModuleEntity e = inv.getArgument(0);
+            e.setIIncrement(123);
+            return 1;
+        });
+
+        ModuleVO vo = service.create(baseDto());
+
+        assertThat(vo.getIIncrement()).isEqualTo(123);
+        assertThat(vo.getSProcedureName()).isEqualTo("sp_audit_user");
+        assertThat(vo.getBShowPermission()).isFalse();
+        assertThat(vo.getISortOrder()).isZero();
+        assertThat(vo.getBDeleted()).isFalse();
+        assertThat(vo.getTCreateDate()).isNotNull();
+    }
+
+    @Test
+    void create_childModule_validatesParentExists() {
+        ModuleCreateDTO d = baseDto();
+        d.setIParentId(7);
+
+        ModuleEntity parent = new ModuleEntity();
+        parent.setIIncrement(7);
+        parent.setBDeleted(false);
+        when(moduleMapper.selectById(7)).thenReturn(parent);
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(moduleMapper.insert((ModuleEntity) any())).thenAnswer(inv -> {
+            ModuleEntity e = inv.getArgument(0);
+            e.setIIncrement(8);
+            return 1;
+        });
+
+        ModuleVO vo = service.create(d);
+        assertThat(vo.getIIncrement()).isEqualTo(8);
+        assertThat(vo.getIParentId()).isEqualTo(7);
+    }
+
+    @Test
+    void create_parentNotFound_throwsBizException40411() {
+        ModuleCreateDTO d = baseDto();
+        d.setIParentId(999999);
+        when(moduleMapper.selectById(999999)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.create(d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PARENT_NOT_FOUND.getCode());
+        verify(moduleMapper, never()).insert((ModuleEntity) any());
+    }
+
+    @Test
+    void create_parentSoftDeleted_throwsBizException40411() {
+        ModuleCreateDTO d = baseDto();
+        d.setIParentId(5);
+
+        ModuleEntity deleted = new ModuleEntity();
+        deleted.setIIncrement(5);
+        deleted.setBDeleted(true);
+        when(moduleMapper.selectById(5)).thenReturn(deleted);
+
+        assertThatThrownBy(() -> service.create(d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PARENT_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void create_duplicateProcedureName_preCheck_throwsBizException40911() {
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        assertThatThrownBy(() -> service.create(baseDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PROC_NAME_DUP.getCode());
+        verify(moduleMapper, never()).insert((ModuleEntity) any());
+    }
+
+    @Test
+    void create_duplicateProcedureName_concurrentInsert_throwsBizException40911() {
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(moduleMapper.insert((ModuleEntity) any()))
+                .thenThrow(new DuplicateKeyException("uk_procedure_name"));
+
+        assertThatThrownBy(() -> service.create(baseDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PROC_NAME_DUP.getCode());
+    }
+
+    // ============================================================
+    //  REQ-MOD-002 update 系列
+    // ============================================================
+
+    private ModuleUpdateDTO updateDto() {
+        ModuleUpdateDTO d = new ModuleUpdateDTO();
+        d.setSDisplayType("系统配置");
+        d.setSModuleType("USR_REVISED");
+        d.setSManageDeptEn("OPS");
+        d.setBShowPermission(true);
+        d.setSModuleNameZh("用户管理（修订）");
+        d.setIParentId(null);
+        d.setISortOrder(5);
+        return d;
+    }
+
+    private ModuleEntity existingTarget(int id) {
+        ModuleEntity t = new ModuleEntity();
+        t.setIIncrement(id);
+        t.setSDisplayType("前端业务");
+        t.setSProcedureName("sp_audit_existing");
+        t.setSModuleType("USR");
+        t.setSManageDeptEn("IT");
+        t.setBShowPermission(false);
+        t.setSModuleNameZh("用户管理");
+        t.setIParentId(null);
+        t.setISortOrder(0);
+        t.setBDeleted(false);
+        t.setTCreateDate(LocalDateTime.of(2026, 1, 1, 0, 0));
+        t.setSCreatedBy("admin");
+        return t;
+    }
+
+    @Test
+    void update_targetNotFound_throws40421() {
+        when(moduleMapper.selectById(10)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.update(10, updateDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_targetSoftDeleted_throws40421() {
+        ModuleEntity t = existingTarget(11);
+        t.setBDeleted(true);
+        when(moduleMapper.selectById(11)).thenReturn(t);
+
+        assertThatThrownBy(() -> service.update(11, updateDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_parentSelfReference_throws40921() {
+        ModuleEntity t = existingTarget(12);
+        when(moduleMapper.selectById(12)).thenReturn(t);
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(12);
+
+        assertThatThrownBy(() -> service.update(12, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PARENT_LOOP.getCode());
+    }
+
+    @Test
+    void update_parentNotFound_throws40411() {
+        ModuleEntity t = existingTarget(13);
+        when(moduleMapper.selectById(13)).thenReturn(t);
+        when(moduleMapper.selectById(999999)).thenReturn(null);
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(999999);
+
+        assertThatThrownBy(() -> service.update(13, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PARENT_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_parentIsDescendant_throws40921() {
+        // 三层结构: 14(target) <- 20(child) <- 30(grand)
+        ModuleEntity target = existingTarget(14);
+        ModuleEntity child = existingTarget(20);
+        child.setIParentId(14);
+        ModuleEntity grand = existingTarget(30);
+        grand.setIParentId(20);
+
+        when(moduleMapper.selectById(14)).thenReturn(target);
+        when(moduleMapper.selectById(30)).thenReturn(grand);
+        when(moduleMapper.selectById(20)).thenReturn(child);
+
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(30); // 想把 14 的父设成 30，但 30 是 14 的孙子 → 环路
+
+        assertThatThrownBy(() -> service.update(14, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_PARENT_LOOP.getCode());
+    }
+
+    @Test
+    void update_full_returnsVOWithUpdatedFields() {
+        ModuleEntity target = existingTarget(15);
+        when(moduleMapper.selectById(15)).thenReturn(target);
+        when(moduleMapper.updateById((ModuleEntity) any())).thenReturn(1);
+
+        ModuleVO vo = service.update(15, updateDto());
+
+        ArgumentCaptor<ModuleEntity> cap = ArgumentCaptor.forClass(ModuleEntity.class);
+        verify(moduleMapper).updateById(cap.capture());
+        ModuleEntity saved = cap.getValue();
+
+        // 已修改字段
+        assertThat(saved.getSDisplayType()).isEqualTo("系统配置");
+        assertThat(saved.getSModuleType()).isEqualTo("USR_REVISED");
+        assertThat(saved.getSManageDeptEn()).isEqualTo("OPS");
+        assertThat(saved.getSModuleNameZh()).isEqualTo("用户管理（修订）");
+        assertThat(saved.getBShowPermission()).isTrue();
+        assertThat(saved.getISortOrder()).isEqualTo(5);
+        assertThat(saved.getIParentId()).isNull();
+        // 保持原值
+        assertThat(saved.getIIncrement()).isEqualTo(15);
+        assertThat(saved.getSProcedureName()).isEqualTo("sp_audit_existing");
+        assertThat(saved.getTCreateDate()).isEqualTo(LocalDateTime.of(2026, 1, 1, 0, 0));
+        assertThat(saved.getSCreatedBy()).isEqualTo("admin");
+        assertThat(saved.getBDeleted()).isFalse();
+
+        assertThat(vo.getSDisplayType()).isEqualTo("系统配置");
+        assertThat(vo.getSProcedureName()).isEqualTo("sp_audit_existing");
+    }
+
+    @Test
+    void update_partialNullFields_keepsOriginalValues() {
+        ModuleEntity target = existingTarget(16);
+        target.setBShowPermission(true);
+        target.setISortOrder(99);
+        when(moduleMapper.selectById(16)).thenReturn(target);
+        when(moduleMapper.updateById((ModuleEntity) any())).thenReturn(1);
+
+        ModuleUpdateDTO d = updateDto();
+        d.setBShowPermission(null);
+        d.setISortOrder(null);
+
+        service.update(16, d);
+
+        ArgumentCaptor<ModuleEntity> cap = ArgumentCaptor.forClass(ModuleEntity.class);
+        verify(moduleMapper).updateById(cap.capture());
+        ModuleEntity saved = cap.getValue();
+        assertThat(saved.getBShowPermission()).isTrue(); // 原值保留
+        assertThat(saved.getISortOrder()).isEqualTo(99); // 原值保留
+    }
+
+    @Test
+    void update_clearParent_setsParentToNull() {
+        ModuleEntity target = existingTarget(17);
+        target.setIParentId(7); // 原本有父
+        when(moduleMapper.selectById(17)).thenReturn(target);
+        when(moduleMapper.updateById((ModuleEntity) any())).thenReturn(1);
+
+        ModuleUpdateDTO d = updateDto();
+        d.setIParentId(null); // 显式清空
+
+        service.update(17, d);
+
+        ArgumentCaptor<ModuleEntity> cap = ArgumentCaptor.forClass(ModuleEntity.class);
+        verify(moduleMapper).updateById(cap.capture());
+        assertThat(cap.getValue().getIParentId()).isNull();
+    }
+
+    // ============================================================
+    //  REQ-MOD-003 delete 系列
+    // ============================================================
+
+    @Test
+    void delete_targetNotFound_throws40421() {
+        when(moduleMapper.selectById(20)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.delete(20))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void delete_targetAlreadyDeleted_throws40421() {
+        ModuleEntity t = existingTarget(21);
+        t.setBDeleted(true);
+        when(moduleMapper.selectById(21)).thenReturn(t);
+
+        assertThatThrownBy(() -> service.delete(21))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void delete_hasUndeletedChildren_throws40912() {
+        ModuleEntity t = existingTarget(22);
+        when(moduleMapper.selectById(22)).thenReturn(t);
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(3L);
+
+        assertThatThrownBy(() -> service.delete(22))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_HAS_REFERENCES.getCode());
+    }
+
+    @Test
+    void delete_leafModule_writesSoftDeleteFields_returnsResult() {
+        ModuleEntity t = existingTarget(23);
+        when(moduleMapper.selectById(23)).thenReturn(t);
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(moduleMapper.update((ModuleEntity) any(), (Wrapper<ModuleEntity>) any())).thenReturn(1);
+
+        ModuleDeleteResultVO vo = service.delete(23);
+
+        assertThat(vo.getIIncrement()).isEqualTo(23);
+        assertThat(vo.getBDeleted()).isTrue();
+        // SET 列由 LambdaUpdateWrapper 声明，entity 第一参数为 null（避免 iParentId.IGNORED 策略副作用）
+        // 实际 SQL SET 子句的列覆盖由 IT (delete_preservesOtherFields_onChildModule) 验证
+        verify(moduleMapper).update((ModuleEntity) isNull(), (Wrapper<ModuleEntity>) any());
+    }
+
+    @Test
+    void delete_softDeletedChildren_doesNotBlock() {
+        ModuleEntity t = existingTarget(24);
+        when(moduleMapper.selectById(24)).thenReturn(t);
+        // 子全部已软删除 → selectCount(bDeleted=0 过滤) 返回 0
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(moduleMapper.update((ModuleEntity) any(), (Wrapper<ModuleEntity>) any())).thenReturn(1);
+
+        ModuleDeleteResultVO vo = service.delete(24);
+        assertThat(vo.getBDeleted()).isTrue();
+    }
+
+    @Test
+    void delete_concurrentRace_throws40421() {
+        ModuleEntity t = existingTarget(25);
+        when(moduleMapper.selectById(25)).thenReturn(t);
+        when(moduleMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        // update 影响行数 0 → 视为并发删除
+        when(moduleMapper.update((ModuleEntity) any(), (Wrapper<ModuleEntity>) any())).thenReturn(0);
+
+        assertThatThrownBy(() -> service.delete(25))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.MOD_NOT_FOUND.getCode());
+    }
+
+    // ============================================================
+    //  REQ-MOD-004 tree 系列
+    // ============================================================
+
+    private ModuleEntity buildModule(int id, Integer parentId, String name, int sortOrder) {
+        ModuleEntity e = new ModuleEntity();
+        e.setIIncrement(id);
+        e.setIParentId(parentId);
+        e.setSModuleNameZh(name);
+        e.setSDisplayType("前端业务");
+        e.setSManageDeptEn("IT");
+        e.setSProcedureName("sp_" + id);
+        e.setSModuleType("MOD");
+        e.setBShowPermission(false);
+        e.setISortOrder(sortOrder);
+        e.setBDeleted(false);
+        e.setTCreateDate(LocalDateTime.now());
+        return e;
+    }
+
+    @Test
+    void tree_emptyDb_returnsEmptyList() {
+        when(moduleMapper.selectList(any(Wrapper.class))).thenReturn(Collections.emptyList());
+        List<ModuleTreeNodeVO> result = service.tree(new ModuleQueryDTO());
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void tree_singleRoot_returnsOneNodeWithEmptyChildren() {
+        when(moduleMapper.selectList(any(Wrapper.class)))
+                .thenReturn(Arrays.asList(buildModule(1, null, "系统配置", 0)));
+
+        List<ModuleTreeNodeVO> result = service.tree(new ModuleQueryDTO());
+        assertThat(result).hasSize(1);
+        assertThat(result.get(0).getIIncrement()).isEqualTo(1);
+        assertThat(result.get(0).getChildren()).isNotNull().isEmpty();
+    }
+
+    @Test
+    void tree_multiLevel_buildsNestedStructureSortedByISortOrder() {
+        when(moduleMapper.selectList(any(Wrapper.class))).thenReturn(Arrays.asList(
+                buildModule(1, null, "RootB", 2),
+                buildModule(2, null, "RootA", 1),
+                buildModule(3, 1, "ChildOfB", 0)
+        ));
+
+        List<ModuleTreeNodeVO> result = service.tree(new ModuleQueryDTO());
+
+        // 根节点按 sortOrder 升序：RootA (sort=1) 在前，RootB (sort=2) 在后
+        assertThat(result).hasSize(2);
+        assertThat(result.get(0).getIIncrement()).isEqualTo(2); // RootA
+        assertThat(result.get(1).getIIncrement()).isEqualTo(1); // RootB
+        // RootB 的 children 含 ChildOfB
+        assertThat(result.get(1).getChildren()).hasSize(1);
+        assertThat(result.get(1).getChildren().get(0).getIIncrement()).isEqualTo(3);
+        // RootA 是叶子
+        assertThat(result.get(0).getChildren()).isEmpty();
+    }
+
+    @Test
+    void tree_keywordHit_includesAncestorChain() {
+        when(moduleMapper.selectList(any(Wrapper.class))).thenReturn(Arrays.asList(
+                buildModule(1, null, "系统配置", 0),
+                buildModule(2, 1, "用户管理", 0),
+                buildModule(3, 2, "登录", 0),
+                buildModule(99, null, "无关模块", 0)
+        ));
+
+        ModuleQueryDTO q = new ModuleQueryDTO();
+        q.setKeyword("登录");
+        List<ModuleTreeNodeVO> result = service.tree(q);
+
+        // 应返回 1 → 2 → 3 三层链；不含 99
+        assertThat(result).hasSize(1);
+        ModuleTreeNodeVO root = result.get(0);
+        assertThat(root.getIIncrement()).isEqualTo(1);
+        assertThat(root.getChildren()).hasSize(1);
+        ModuleTreeNodeVO mid = root.getChildren().get(0);
+        assertThat(mid.getIIncrement()).isEqualTo(2);
+        assertThat(mid.getChildren()).hasSize(1);
+        assertThat(mid.getChildren().get(0).getIIncrement()).isEqualTo(3);
+    }
+
+    @Test
+    void tree_keywordNoMatch_returnsEmptyList() {
+        when(moduleMapper.selectList(any(Wrapper.class))).thenReturn(Arrays.asList(
+                buildModule(1, null, "系统配置", 0),
+                buildModule(2, null, "权限分配", 0)
+        ));
+
+        ModuleQueryDTO q = new ModuleQueryDTO();
+        q.setKeyword("不存在的关键词");
+        List<ModuleTreeNodeVO> result = service.tree(q);
+        assertThat(result).isEmpty();
+    }
+
+    @Test
+    void tree_softDeletedExcluded_passesBDeletedZeroToMapper() {
+        when(moduleMapper.selectList(any(Wrapper.class))).thenReturn(Collections.emptyList());
+
+        service.tree(new ModuleQueryDTO());
+
+        // 验证调用了 selectList 一次（mapper 端用 wrapper.eq(bDeleted, false) 已是 service 实现细节，
+        // 这里仅验证 service 调用了 selectList，wrapper 形状由 IT 在真实 DB 上 cross-check）
+        verify(moduleMapper).selectList(any(Wrapper.class));
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.xly.erp.module.usr.dto.LoginDTO;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.security.InMemoryLoginAttemptStore;
+import com.xly.erp.module.usr.security.JwtTokenProvider;
+import io.jsonwebtoken.Claims;
+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.security.crypto.password.PasswordEncoder;
+import org.springframework.test.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+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")
+@Transactional
+@Rollback
+class LoginControllerIT {
+
+    @Autowired MockMvc mockMvc;
+    @Autowired ObjectMapper objectMapper;
+    @Autowired UserMapper userMapper;
+    @Autowired PasswordEncoder passwordEncoder;
+    @Autowired InMemoryLoginAttemptStore attemptStore;
+    @Autowired JwtTokenProvider jwtTokenProvider;
+
+    private String userName;
+
+    @BeforeEach
+    void setUp() {
+        userName = "login_" + System.nanoTime();
+        // 每个测试在 store 里清干净（store 是 Spring singleton 跨测试存活）
+        attemptStore.clear(userName);
+    }
+
+    private Integer insertUser(String pw) {
+        UserEntity u = new UserEntity();
+        u.setSUserNo("uno_" + System.nanoTime());
+        u.setSUserName(userName);
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash(passwordEncoder.encode(pw));
+        u.setBDeleted(false);
+        u.setTCreateDate(LocalDateTime.now());
+        userMapper.insert(u);
+        return u.getIIncrement();
+    }
+
+    private LoginDTO loginDto(String name, String pw) {
+        LoginDTO d = new LoginDTO();
+        d.setSUserName(name);
+        d.setSPassword(pw);
+        d.setSVersion("standard");
+        return d;
+    }
+
+    private String json(Object o) throws Exception { return objectMapper.writeValueAsString(o); }
+
+    @Test
+    void login_validCredentials_returns200WithToken() throws Exception {
+        insertUser("666666");
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.accessToken").isString())
+                .andExpect(jsonPath("$.data.expiresIn").value(7200))
+                .andExpect(jsonPath("$.data.user.sUserName").value(userName))
+                .andExpect(jsonPath("$.data.user.sUserType").value("普通用户"));
+    }
+
+    @Test
+    void login_jwtClaimsAreCorrect() throws Exception {
+        Integer userId = insertUser("666666");
+
+        MvcResult result = mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        String body = result.getResponse().getContentAsString();
+        String token = objectMapper.readTree(body).path("data").path("accessToken").asText();
+        assertThat(token).isNotEmpty();
+
+        Claims claims = jwtTokenProvider.parse(token);
+        assertThat(claims.getSubject()).isEqualTo(userName);
+        assertThat(claims.get("uid", Integer.class)).isEqualTo(userId);
+        assertThat(claims.get("type", String.class)).isEqualTo("普通用户");
+    }
+
+    @Test
+    void login_invalidUsername_returns40101() throws Exception {
+        // 不插入用户
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto("ghost_" + System.nanoTime(), "any"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40101));
+    }
+
+    @Test
+    void login_wrongPassword_returns40101() throws Exception {
+        insertUser("666666");
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "wrong_password"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40101));
+    }
+
+    @Test
+    void login_softDeletedUser_returns40101() throws Exception {
+        Integer userId = insertUser("666666");
+        UserEntity patch = new UserEntity();
+        patch.setIIncrement(userId);
+        patch.setBDeleted(true);
+        userMapper.updateById(patch);
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40101));
+    }
+
+    @Test
+    void login_missingPassword_returns40010() throws Exception {
+        LoginDTO dto = loginDto(userName, "any");
+        dto.setSPassword(null);
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void login_invalidVersion_returns40010() throws Exception {
+        LoginDTO dto = loginDto(userName, "any");
+        dto.setSVersion("experimental");
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void login_5thFailureLocks_returns40301() throws Exception {
+        insertUser("666666");
+
+        // 4 次错误密码（不锁定）
+        for (int i = 0; i < 4; i++) {
+            mockMvc.perform(post("/api/auth/login")
+                            .contentType(MediaType.APPLICATION_JSON)
+                            .content(json(loginDto(userName, "wrong_" + i))))
+                    .andExpect(jsonPath("$.code").value(40101));
+        }
+
+        // 第 5 次错误密码：触发锁定，返回 40301 + cooldownSeconds
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "wrong_5"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40301))
+                .andExpect(jsonPath("$.data.cooldownSeconds").isNumber());
+
+        // 锁定后正确密码也 40301
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(jsonPath("$.code").value(40301));
+    }
+
+    @Test
+    void login_responseExcludesSPasswordHash() throws Exception {
+        insertUser("666666");
+
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.user.sPasswordHash").doesNotExist());
+    }
+
+    @Test
+    void login_afterLockExpiry_returns200() throws Exception {
+        insertUser("666666");
+
+        // 5 次错误密码 → 锁定
+        for (int i = 0; i < 5; i++) {
+            mockMvc.perform(post("/api/auth/login")
+                    .contentType(MediaType.APPLICATION_JSON)
+                    .content(json(loginDto(userName, "wrong_" + i))))
+                    .andReturn();
+        }
+
+        // 验证当前确实锁定
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(jsonPath("$.code").value(40301));
+
+        // 把 lockUntil 拨到过去模拟锁定到期
+        attemptStore.expireLockForTest(userName);
+
+        // 锁定到期 + 正确密码 → 200
+        mockMvc.perform(post("/api/auth/login")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(loginDto(userName, "666666"))))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.accessToken").isString());
+    }
+}
+package com.xly.erp.module.usr.controller;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.xly.erp.module.usr.dto.UserCreateDTO;
+import com.xly.erp.module.usr.dto.UserUpdateDTO;
+import com.xly.erp.module.usr.entity.PermissionCategoryEntity;
+import com.xly.erp.module.usr.entity.StaffEntity;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.entity.UserPermissionEntity;
+import com.xly.erp.module.usr.mapper.PermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.StaffMapper;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.mapper.UserPermissionMapper;
+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.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static com.baomidou.mybatisplus.core.toolkit.Wrappers.lambdaQuery;
+import static org.assertj.core.api.Assertions.assertThat;
+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.request.MockMvcRequestBuilders.put;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@Transactional
+@Rollback
+class UserControllerIT {
+
+    @Autowired MockMvc mockMvc;
+    @Autowired ObjectMapper objectMapper;
+    @Autowired UserMapper userMapper;
+    @Autowired StaffMapper staffMapper;
+    @Autowired PermissionCategoryMapper permissionCategoryMapper;
+    @Autowired UserPermissionMapper userPermissionMapper;
+
+    private UserCreateDTO baseDto(String userName) {
+        UserCreateDTO d = new UserCreateDTO();
+        d.setSUserNo("uno_" + System.nanoTime());
+        d.setSUserName(userName);
+        d.setSUserType("普通用户");
+        d.setSLanguage("zh");
+        return d;
+    }
+
+    private String json(Object o) throws Exception { return objectMapper.writeValueAsString(o); }
+
+    private Integer insertStaff() {
+        StaffEntity s = new StaffEntity();
+        s.setSStaffNo("st_" + System.nanoTime());
+        s.setSStaffName("员工A");
+        s.setBDeleted(false);
+        s.setTCreateDate(LocalDateTime.now());
+        staffMapper.insert(s);
+        return s.getIIncrement();
+    }
+
+    private Integer insertCategory() {
+        PermissionCategoryEntity p = new PermissionCategoryEntity();
+        p.setSCategoryCode("c_" + System.nanoTime());
+        p.setSCategoryName("分类");
+        p.setISortOrder(0);
+        p.setBDeleted(false);
+        p.setTCreateDate(LocalDateTime.now());
+        permissionCategoryMapper.insert(p);
+        return p.getIIncrement();
+    }
+
+    @Test
+    void post_minimalFields_returns200() throws Exception {
+        UserCreateDTO dto = baseDto("alice_" + System.nanoTime());
+
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iIncrement").isNumber())
+                .andExpect(jsonPath("$.data.sUserName").value(dto.getSUserName()))
+                .andExpect(jsonPath("$.data.bCanModifyDocs").value(false))
+                .andExpect(jsonPath("$.data.permissionCategoryIds").isArray())
+                .andExpect(jsonPath("$.data.permissionCategoryIds.length()").value(0));
+    }
+
+    @Test
+    void post_withStaffAndPermissions_returns200_andDbAssociated() throws Exception {
+        Integer staffId = insertStaff();
+        Integer cat1 = insertCategory();
+        Integer cat2 = insertCategory();
+        Integer cat3 = insertCategory();
+
+        UserCreateDTO dto = baseDto("bob_" + System.nanoTime());
+        dto.setIStaffId(staffId);
+        dto.setPermissionCategoryIds(List.of(cat1, cat2, cat3));
+
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iStaffId").value(staffId));
+
+        UserEntity u = userMapper.selectOne(lambdaQuery(UserEntity.class)
+                .eq(UserEntity::getSUserName, dto.getSUserName()));
+        assertThat(u).isNotNull();
+        Long upCount = userPermissionMapper.selectCount(lambdaQuery(UserPermissionEntity.class)
+                .eq(UserPermissionEntity::getIUserId, u.getIIncrement()));
+        assertThat(upCount).isEqualTo(3L);
+    }
+
+    @Test
+    void post_duplicateUserName_returns40921() throws Exception {
+        String userName = "dup_" + System.nanoTime();
+        UserCreateDTO first = baseDto(userName);
+        mockMvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON).content(json(first)))
+                .andExpect(status().isOk());
+
+        UserCreateDTO second = baseDto(userName);
+        mockMvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON).content(json(second)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40921));
+    }
+
+    @Test
+    void post_staffNotFound_returns40421() throws Exception {
+        UserCreateDTO dto = baseDto("noStaff_" + System.nanoTime());
+        dto.setIStaffId(999999);
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40421));
+    }
+
+    @Test
+    void post_permissionCategoryNotFound_returns40422() throws Exception {
+        UserCreateDTO dto = baseDto("noCat_" + System.nanoTime());
+        dto.setPermissionCategoryIds(List.of(999999));
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40422));
+    }
+
+    @Test
+    void post_passwordHashedInDb_notPlaintext() throws Exception {
+        UserCreateDTO dto = baseDto("pw_" + System.nanoTime());
+
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk());
+
+        UserEntity u = userMapper.selectOne(lambdaQuery(UserEntity.class)
+                .eq(UserEntity::getSUserName, dto.getSUserName()));
+        assertThat(u.getSPasswordHash())
+                .satisfiesAnyOf(
+                        h -> assertThat(h).startsWith("$2a$"),
+                        h -> assertThat(h).startsWith("$2b$"),
+                        h -> assertThat(h).startsWith("$2y$"))
+                .doesNotContain("666666");
+    }
+
+    @Test
+    void post_responseExcludesSPasswordHash() throws Exception {
+        UserCreateDTO dto = baseDto("priv_" + System.nanoTime());
+
+        mockMvc.perform(post("/api/users")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.sPasswordHash").doesNotExist());
+    }
+
+    // ============================================================
+    //  REQ-USR-002 PUT 系列
+    // ============================================================
+
+    private Integer insertUser(String userName, Integer staffId, List<Integer> categoryIds) {
+        UserEntity u = new UserEntity();
+        u.setSUserNo("uno_" + System.nanoTime());
+        u.setSUserName(userName);
+        u.setIStaffId(staffId);
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash("$2a$10$origUser");
+        u.setBDeleted(false);
+        u.setTCreateDate(LocalDateTime.now());
+        userMapper.insert(u);
+        for (Integer cid : categoryIds) {
+            UserPermissionEntity up = new UserPermissionEntity();
+            up.setIUserId(u.getIIncrement());
+            up.setICategoryId(cid);
+            up.setTCreateDate(LocalDateTime.now());
+            userPermissionMapper.insert(up);
+        }
+        return u.getIIncrement();
+    }
+
+    private UserUpdateDTO updateDto(Integer staffId, List<Integer> permissionIds) {
+        UserUpdateDTO d = new UserUpdateDTO();
+        d.setIStaffId(staffId);
+        d.setSUserType("超级管理员");
+        d.setSLanguage("en");
+        d.setBCanModifyDocs(true);
+        d.setPermissionCategoryIds(permissionIds);
+        return d;
+    }
+
+    @Test
+    void put_validUpdate_returns200_andDbReflects() throws Exception {
+        Integer staff1 = insertStaff();
+        Integer staff2 = insertStaff();
+        Integer cat1 = insertCategory();
+        Integer cat2 = insertCategory();
+        Integer cat3 = insertCategory();
+        Integer userId = insertUser("upd_" + System.nanoTime(), staff1, List.of(cat1, cat2, cat3));
+
+        Integer catNew1 = insertCategory();
+        Integer catNew2 = insertCategory();
+
+        UserUpdateDTO dto = updateDto(staff2, List.of(catNew1, catNew2));
+
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.iStaffId").value(staff2))
+                .andExpect(jsonPath("$.data.sUserType").value("超级管理员"))
+                .andExpect(jsonPath("$.data.sLanguage").value("en"));
+
+        UserEntity reloaded = userMapper.selectById(userId);
+        assertThat(reloaded.getIStaffId()).isEqualTo(staff2);
+        assertThat(reloaded.getSUserType()).isEqualTo("超级管理员");
+        assertThat(reloaded.getBCanModifyDocs()).isTrue();
+        Long upCount = userPermissionMapper.selectCount(lambdaQuery(UserPermissionEntity.class)
+                .eq(UserPermissionEntity::getIUserId, userId));
+        assertThat(upCount).isEqualTo(2L); // 原 3 删 + 新 2 插
+    }
+
+    @Test
+    void put_clearStaffId_setsNull() throws Exception {
+        Integer staffId = insertStaff();
+        Integer userId = insertUser("clr_" + System.nanoTime(), staffId, List.of());
+
+        UserUpdateDTO dto = updateDto(null, List.of());
+
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        assertThat(userMapper.selectById(userId).getIStaffId()).isNull();
+    }
+
+    @Test
+    void put_emptyPermissionCategoryIds_clearsAssociations() throws Exception {
+        Integer cat1 = insertCategory();
+        Integer cat2 = insertCategory();
+        Integer userId = insertUser("emp_" + System.nanoTime(), null, List.of(cat1, cat2));
+
+        UserUpdateDTO dto = updateDto(null, List.of());
+
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        Long upCount = userPermissionMapper.selectCount(lambdaQuery(UserPermissionEntity.class)
+                .eq(UserPermissionEntity::getIUserId, userId));
+        assertThat(upCount).isZero();
+    }
+
+    @Test
+    void put_targetNotFound_returns40431() throws Exception {
+        UserUpdateDTO dto = updateDto(null, List.of());
+        mockMvc.perform(put("/api/users/999999")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40431));
+    }
+
+    @Test
+    void put_staffNotFound_returns40421() throws Exception {
+        Integer userId = insertUser("nost_" + System.nanoTime(), null, List.of());
+        UserUpdateDTO dto = updateDto(999999, List.of());
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40421));
+    }
+
+    @Test
+    void put_permissionCategoryNotFound_returns40422() throws Exception {
+        Integer userId = insertUser("noc_" + System.nanoTime(), null, List.of());
+        UserUpdateDTO dto = updateDto(null, List.of(999999));
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40422));
+    }
+
+    @Test
+    void put_missingRequired_returns40010() throws Exception {
+        Integer userId = insertUser("miss_" + System.nanoTime(), null, List.of());
+        UserUpdateDTO dto = updateDto(null, List.of());
+        dto.setSUserType(null); // 必填缺失
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(json(dto)))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void put_ignoresProtectedFields_doesNotChangeUserNoOrName() throws Exception {
+        String origName = "prot_" + System.nanoTime();
+        Integer userId = insertUser(origName, null, List.of());
+        String origNo = userMapper.selectById(userId).getSUserNo();
+        String origHash = userMapper.selectById(userId).getSPasswordHash();
+
+        // 手工拼 body 含保护字段
+        String body = """
+                {
+                  "sUserNo": "hijack",
+                  "sUserName": "hijack",
+                  "sPasswordHash": "$2a$10$hijacked",
+                  "iStaffId": null,
+                  "sUserType": "超级管理员",
+                  "sLanguage": "zh-TW",
+                  "bCanModifyDocs": true,
+                  "permissionCategoryIds": []
+                }
+                """;
+        mockMvc.perform(put("/api/users/" + userId)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content(body))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        UserEntity reloaded = userMapper.selectById(userId);
+        assertThat(reloaded.getSUserNo()).isEqualTo(origNo);
+        assertThat(reloaded.getSUserName()).isEqualTo(origName);
+        assertThat(reloaded.getSPasswordHash()).isEqualTo(origHash);
+        // 但其他字段已修改
+        assertThat(reloaded.getSUserType()).isEqualTo("超级管理员");
+        assertThat(reloaded.getSLanguage()).isEqualTo("zh-TW");
+    }
+
+    // ============================================================
+    //  REQ-USR-003 GET 系列
+    // ============================================================
+
+    @Test
+    void get_emptyKeyword_returnsAllUndeleted() throws Exception {
+        Integer staffId = insertStaff();
+        insertUser("getall_a_" + System.nanoTime(), staffId, List.of());
+        insertUser("getall_b_" + System.nanoTime(), null, List.of());
+
+        mockMvc.perform(get("/api/users"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.list").isArray())
+                .andExpect(jsonPath("$.data.total").isNumber());
+    }
+
+    @Test
+    void get_filterByUsernameContains_returnsMatchedSubset() throws Exception {
+        String alicePrefix = "filt_ali_" + System.nanoTime();
+        insertUser(alicePrefix + "_alice", null, List.of());
+        insertUser("filt_bob_" + System.nanoTime(), null, List.of());
+
+        mockMvc.perform(get("/api/users")
+                        .param("queryField", "username")
+                        .param("matchType", "contains")
+                        .param("queryValue", alicePrefix))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.list[0].sUserName", org.hamcrest.Matchers.startsWith(alicePrefix)));
+    }
+
+    @Test
+    void get_filterByStaffnameContains_returnsJoinedResults() throws Exception {
+        // staff with unique sStaffName, then user referencing it
+        StaffEntity s = new StaffEntity();
+        String staffName = "joined_staff_" + System.nanoTime();
+        s.setSStaffNo("st_" + System.nanoTime());
+        s.setSStaffName(staffName);
+        s.setSDepartment("研发部");
+        s.setBDeleted(false);
+        s.setTCreateDate(LocalDateTime.now());
+        staffMapper.insert(s);
+        insertUser("for_staff_" + System.nanoTime(), s.getIIncrement(), List.of());
+
+        mockMvc.perform(get("/api/users")
+                        .param("queryField", "staffname")
+                        .param("matchType", "contains")
+                        .param("queryValue", staffName))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.total").value(1))
+                .andExpect(jsonPath("$.data.list[0].sStaffName").value(staffName));
+    }
+
+    @Test
+    void get_filterByDeletedTrue_returnsOnlyDeleted() throws Exception {
+        // 插一个用户后软删
+        Integer userId = insertUser("del_" + System.nanoTime(), null, List.of());
+        UserEntity patch = new UserEntity();
+        patch.setIIncrement(userId);
+        patch.setBDeleted(true);
+        userMapper.updateById(patch);
+
+        mockMvc.perform(get("/api/users")
+                        .param("queryField", "deleted")
+                        .param("matchType", "equals")
+                        .param("queryValue", "true"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.list[?(@.iIncrement==" + userId + ")]").exists());
+    }
+
+    @Test
+    void get_pagination_returnsCorrectSlice() throws Exception {
+        for (int i = 0; i < 3; i++) {
+            insertUser("page_" + i + "_" + System.nanoTime(), null, List.of());
+        }
+
+        mockMvc.perform(get("/api/users")
+                        .param("pageNum", "1")
+                        .param("pageSize", "2"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.pageNum").value(1))
+                .andExpect(jsonPath("$.data.pageSize").value(2))
+                .andExpect(jsonPath("$.data.list.length()").value(2));
+    }
+
+    @Test
+    void get_responseExcludesInternalFields() throws Exception {
+        insertUser("priv_" + System.nanoTime(), null, List.of());
+
+        mockMvc.perform(get("/api/users").param("pageSize", "5"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.list[0].sPasswordHash").doesNotExist())
+                .andExpect(jsonPath("$.data.list[0].sId").doesNotExist())
+                .andExpect(jsonPath("$.data.list[0].iStaffId").doesNotExist())
+                .andExpect(jsonPath("$.data.list[0].sBrandsId").doesNotExist());
+    }
+
+    @Test
+    void get_pageSizeTooLarge_returns40010() throws Exception {
+        mockMvc.perform(get("/api/users").param("pageSize", "101"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void get_invalidQueryField_returns40010() throws Exception {
+        mockMvc.perform(get("/api/users").param("queryField", "invalid_xyz"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(40010));
+    }
+
+    @Test
+    void get_userWithoutStaff_listItemHasNullStaffFields() throws Exception {
+        String userName = "nostaff_" + System.nanoTime();
+        insertUser(userName, null, List.of());
+
+        mockMvc.perform(get("/api/users")
+                        .param("queryField", "username")
+                        .param("matchType", "equals")
+                        .param("queryValue", userName))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.data.list[0].sUserName").value(userName))
+                .andExpect(jsonPath("$.data.list[0].sStaffName").doesNotExist())
+                .andExpect(jsonPath("$.data.list[0].sDepartment").doesNotExist());
+    }
+}
+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.assertj.core.api.Assertions.assertThat;
+
+class LoginDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private LoginDTO valid() {
+        LoginDTO d = new LoginDTO();
+        d.setSUserName("alice");
+        d.setSPassword("666666");
+        d.setSVersion("standard");
+        return d;
+    }
+
+    @Test
+    void allValid_yieldsNoViolations() {
+        Set<ConstraintViolation<LoginDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void blankRequiredFields_yieldsViolations() {
+        LoginDTO d = new LoginDTO();
+        Set<ConstraintViolation<LoginDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sUserName", "sPassword", "sVersion");
+    }
+
+    @Test
+    void invalidVersion_yieldsViolation() {
+        LoginDTO d = valid();
+        d.setSVersion("experimental");
+        Set<ConstraintViolation<LoginDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sVersion");
+    }
+
+    @Test
+    void overSized_yieldsViolation() {
+        LoginDTO d = valid();
+        d.setSUserName("a".repeat(51));
+        d.setSPassword("p".repeat(101));
+        Set<ConstraintViolation<LoginDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sUserName", "sPassword");
+    }
+}
+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.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class UserCreateDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private UserCreateDTO valid() {
+        UserCreateDTO d = new UserCreateDTO();
+        d.setSUserNo("u001");
+        d.setSUserName("alice");
+        d.setSUserType("普通用户");
+        d.setSLanguage("zh");
+        d.setBCanModifyDocs(false);
+        d.setPermissionCategoryIds(List.of());
+        return d;
+    }
+
+    @Test
+    void allValidFields_yieldsNoViolations() {
+        Set<ConstraintViolation<UserCreateDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void blankRequiredFields_yieldsViolations() {
+        UserCreateDTO d = new UserCreateDTO();
+        Set<ConstraintViolation<UserCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sUserNo", "sUserName", "sUserType", "sLanguage");
+    }
+
+    @Test
+    void invalidUserTypeEnum_yieldsViolation() {
+        UserCreateDTO d = valid();
+        d.setSUserType("非法值");
+        Set<ConstraintViolation<UserCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sUserType");
+    }
+
+    @Test
+    void invalidLanguageEnum_yieldsViolation() {
+        UserCreateDTO d = valid();
+        d.setSLanguage("fr");
+        Set<ConstraintViolation<UserCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sLanguage");
+    }
+
+    @Test
+    void overSizedFields_yieldsViolations() {
+        UserCreateDTO d = valid();
+        d.setSUserNo("a".repeat(51));
+        d.setSUserName("a".repeat(51));
+        Set<ConstraintViolation<UserCreateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sUserNo", "sUserName");
+    }
+}
+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.assertj.core.api.Assertions.assertThat;
+
+class UserQueryDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private UserQueryDTO valid() {
+        UserQueryDTO d = new UserQueryDTO();
+        d.setPageNum(1);
+        d.setPageSize(20);
+        d.setQueryField("username");
+        d.setMatchType("contains");
+        d.setQueryValue("alice");
+        return d;
+    }
+
+    @Test
+    void allValid_yieldsNoViolations() {
+        Set<ConstraintViolation<UserQueryDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void pageSizeTooLarge_yieldsViolation() {
+        UserQueryDTO d = valid();
+        d.setPageSize(101);
+        Set<ConstraintViolation<UserQueryDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("pageSize");
+    }
+
+    @Test
+    void pageSizeTooSmall_yieldsViolation() {
+        UserQueryDTO d = valid();
+        d.setPageSize(0);
+        Set<ConstraintViolation<UserQueryDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("pageSize");
+    }
+
+    @Test
+    void queryFieldInvalidEnum_yieldsViolation() {
+        UserQueryDTO d = valid();
+        d.setQueryField("invalid_field");
+        Set<ConstraintViolation<UserQueryDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("queryField");
+    }
+
+    @Test
+    void queryValueOverSized_yieldsViolation() {
+        UserQueryDTO d = valid();
+        d.setQueryValue("a".repeat(101));
+        Set<ConstraintViolation<UserQueryDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("queryValue");
+    }
+}
+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.List;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class UserUpdateDTOValidationTest {
+
+    private static final ValidatorFactory FACTORY = Validation.buildDefaultValidatorFactory();
+    private final Validator validator = FACTORY.getValidator();
+
+    private UserUpdateDTO valid() {
+        UserUpdateDTO d = new UserUpdateDTO();
+        d.setSUserType("超级管理员");
+        d.setSLanguage("en");
+        d.setBCanModifyDocs(true);
+        d.setIStaffId(7);
+        d.setPermissionCategoryIds(List.of(1, 2));
+        return d;
+    }
+
+    @Test
+    void allValidFields_yieldsNoViolations() {
+        Set<ConstraintViolation<UserUpdateDTO>> v = validator.validate(valid());
+        assertThat(v).isEmpty();
+    }
+
+    @Test
+    void blankRequiredFields_yieldsViolations() {
+        UserUpdateDTO d = new UserUpdateDTO();
+        Set<ConstraintViolation<UserUpdateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString())
+                .contains("sUserType", "sLanguage");
+    }
+
+    @Test
+    void invalidUserTypeEnum_yieldsViolation() {
+        UserUpdateDTO d = valid();
+        d.setSUserType("非法值");
+        Set<ConstraintViolation<UserUpdateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sUserType");
+    }
+
+    @Test
+    void invalidLanguageEnum_yieldsViolation() {
+        UserUpdateDTO d = valid();
+        d.setSLanguage("fr");
+        Set<ConstraintViolation<UserUpdateDTO>> v = validator.validate(d);
+        assertThat(v).extracting(cv -> cv.getPropertyPath().toString()).contains("sLanguage");
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.entity.StaffEntity;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest
+@ActiveProfiles("test")
+@Transactional
+@Rollback
+class UserMapperSearchIT {
+
+    @Autowired UserMapper userMapper;
+    @Autowired StaffMapper staffMapper;
+
+    private Integer insertStaff(String name) {
+        StaffEntity s = new StaffEntity();
+        s.setSStaffNo("st_" + System.nanoTime());
+        s.setSStaffName(name);
+        s.setSDepartment("研发部");
+        s.setBDeleted(false);
+        s.setTCreateDate(LocalDateTime.now());
+        staffMapper.insert(s);
+        return s.getIIncrement();
+    }
+
+    private Integer insertUser(String userName, Integer staffId) {
+        UserEntity u = new UserEntity();
+        u.setSUserNo("uno_" + System.nanoTime());
+        u.setSUserName(userName);
+        u.setIStaffId(staffId);
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash("$2a$10$x");
+        u.setBDeleted(false);
+        u.setTCreateDate(LocalDateTime.now());
+        userMapper.insert(u);
+        return u.getIIncrement();
+    }
+
+    @Test
+    void searchUsers_emptyFilter_returnsAllUndeletedAsPage() {
+        Integer staffId = insertStaff("张三");
+        insertUser("alice_" + System.nanoTime(), staffId);
+        insertUser("bob_" + System.nanoTime(), null);
+
+        UserQueryDTO query = new UserQueryDTO();
+        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query, null);
+
+        assertThat(result.getTotal()).isGreaterThanOrEqualTo(2L);
+        assertThat(result.getRecords()).extracting(UserListItemVO::getSUserName)
+                .anyMatch(n -> n.startsWith("alice_") || n.startsWith("bob_"));
+    }
+
+    @Test
+    void searchUsers_filterByUserName_filtersCorrectly() {
+        String alicePrefix = "ali_" + System.nanoTime();
+        insertUser(alicePrefix + "_alice", null);
+        insertUser("bob_unmatch_" + System.nanoTime(), null);
+
+        UserQueryDTO query = new UserQueryDTO();
+        query.setQueryField("username");
+        query.setMatchType("contains");
+        query.setQueryValue(alicePrefix);
+
+        // column 由 service 层映射；mapper IT 直接传 "u.sUserName"
+        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query, "u.sUserName");
+
+        assertThat(result.getRecords()).hasSize(1);
+        assertThat(result.getRecords().get(0).getSUserName()).startsWith(alicePrefix);
+    }
+}
+package com.xly.erp.module.usr.mapper;
+
+import com.xly.erp.module.usr.entity.PermissionCategoryEntity;
+import com.xly.erp.module.usr.entity.StaffEntity;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.entity.UserPermissionEntity;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.annotation.Rollback;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest
+@ActiveProfiles("test")
+@Transactional
+@Rollback
+class UsrMappersIT {
+
+    @Autowired UserMapper userMapper;
+    @Autowired StaffMapper staffMapper;
+    @Autowired PermissionCategoryMapper permissionCategoryMapper;
+    @Autowired UserPermissionMapper userPermissionMapper;
+
+    @Test
+    void staff_insertAndSelect() {
+        StaffEntity s = new StaffEntity();
+        s.setSStaffNo("staff_" + System.nanoTime());
+        s.setSStaffName("张三");
+        s.setSDepartment("研发部");
+        s.setBDeleted(false);
+        s.setTCreateDate(LocalDateTime.now());
+        assertThat(staffMapper.insert(s)).isEqualTo(1);
+        assertThat(s.getIIncrement()).isPositive();
+        StaffEntity loaded = staffMapper.selectById(s.getIIncrement());
+        assertThat(loaded.getSStaffName()).isEqualTo("张三");
+        assertThat(loaded.getSDepartment()).isEqualTo("研发部");
+    }
+
+    @Test
+    void permissionCategory_insertAndSelect() {
+        PermissionCategoryEntity p = new PermissionCategoryEntity();
+        p.setSCategoryCode("cat_" + System.nanoTime());
+        p.setSCategoryName("基础权限");
+        p.setISortOrder(0);
+        p.setBDeleted(false);
+        p.setTCreateDate(LocalDateTime.now());
+        assertThat(permissionCategoryMapper.insert(p)).isEqualTo(1);
+        PermissionCategoryEntity loaded = permissionCategoryMapper.selectById(p.getIIncrement());
+        assertThat(loaded.getSCategoryName()).isEqualTo("基础权限");
+    }
+
+    @Test
+    void user_insertAndSelect() {
+        UserEntity u = new UserEntity();
+        u.setSUserNo("u_" + System.nanoTime());
+        u.setSUserName("alice_" + System.nanoTime());
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash("$2a$10$abcdefghijklmnopqrstuv");
+        u.setBDeleted(false);
+        u.setTCreateDate(LocalDateTime.now());
+        assertThat(userMapper.insert(u)).isEqualTo(1);
+        UserEntity loaded = userMapper.selectById(u.getIIncrement());
+        assertThat(loaded.getSUserName()).startsWith("alice_");
+        assertThat(loaded.getSUserType()).isEqualTo("普通用户");
+        assertThat(loaded.getSLanguage()).isEqualTo("zh");
+    }
+
+    @Test
+    void userPermission_insertAndSelect_requiresValidUserAndCategory() {
+        // 先建合法 user + category（FK 兜底）
+        UserEntity u = new UserEntity();
+        u.setSUserNo("upu_" + System.nanoTime());
+        u.setSUserName("upa_" + System.nanoTime());
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash("$2a$10$x");
+        u.setBDeleted(false);
+        u.setTCreateDate(LocalDateTime.now());
+        userMapper.insert(u);
+
+        PermissionCategoryEntity p = new PermissionCategoryEntity();
+        p.setSCategoryCode("upc_" + System.nanoTime());
+        p.setSCategoryName("upcat");
+        p.setISortOrder(0);
+        p.setBDeleted(false);
+        p.setTCreateDate(LocalDateTime.now());
+        permissionCategoryMapper.insert(p);
+
+        UserPermissionEntity up = new UserPermissionEntity();
+        up.setIUserId(u.getIIncrement());
+        up.setICategoryId(p.getIIncrement());
+        up.setTCreateDate(LocalDateTime.now());
+        assertThat(userPermissionMapper.insert(up)).isEqualTo(1);
+        UserPermissionEntity loaded = userPermissionMapper.selectById(up.getIIncrement());
+        assertThat(loaded.getIUserId()).isEqualTo(u.getIIncrement());
+        assertThat(loaded.getICategoryId()).isEqualTo(p.getIIncrement());
+    }
+}
+package com.xly.erp.module.usr.security;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class InMemoryLoginAttemptStoreTest {
+
+    private InMemoryLoginAttemptStore store;
+
+    @BeforeEach
+    void setUp() {
+        store = new InMemoryLoginAttemptStore();
+    }
+
+    @Test
+    void cooldown_initial_returnsZero() {
+        assertThat(store.cooldownSeconds("alice")).isZero();
+    }
+
+    @Test
+    void recordFailure_under5_doesNotLock() {
+        for (int i = 0; i < 4; i++) {
+            store.recordFailure("alice");
+        }
+        assertThat(store.cooldownSeconds("alice")).isZero();
+    }
+
+    @Test
+    void recordFailure_at5_triggersLock_cooldownPositive() {
+        for (int i = 0; i < 5; i++) {
+            store.recordFailure("alice");
+        }
+        long cd = store.cooldownSeconds("alice");
+        assertThat(cd).isGreaterThan(0L);
+        assertThat(cd).isLessThanOrEqualTo(15L * 60L); // 锁定 15 min
+    }
+
+    @Test
+    void clear_resetsCount() {
+        for (int i = 0; i < 5; i++) {
+            store.recordFailure("alice");
+        }
+        store.clear("alice");
+        assertThat(store.cooldownSeconds("alice")).isZero();
+    }
+
+    @Test
+    void cooldown_afterExpiry_resetsCount() {
+        for (int i = 0; i < 5; i++) {
+            store.recordFailure("alice");
+        }
+        assertThat(store.cooldownSeconds("alice")).isGreaterThan(0L);
+
+        // 把锁定时间拨到过去 → 模拟到期
+        store.expireLockForTest("alice");
+
+        // 到期后 cooldownSeconds 应返回 0 + record 清空
+        assertThat(store.cooldownSeconds("alice")).isZero();
+
+        // 验证 reset 真的清空了 count——再 recordFailure 4 次仍未锁定
+        for (int i = 0; i < 4; i++) {
+            store.recordFailure("alice");
+        }
+        assertThat(store.cooldownSeconds("alice")).isZero();
+
+        // 第 5 次 record 后再次锁定（业务规则 4 完整重启）
+        store.recordFailure("alice");
+        assertThat(store.cooldownSeconds("alice")).isGreaterThan(0L);
+    }
+}
+package com.xly.erp.module.usr.security;
+
+import io.jsonwebtoken.Claims;
+import io.jsonwebtoken.ExpiredJwtException;
+import io.jsonwebtoken.Jwts;
+import io.jsonwebtoken.security.Keys;
+import org.junit.jupiter.api.Test;
+
+import javax.crypto.SecretKey;
+import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.util.Date;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class JwtTokenProviderTest {
+
+    // 测试专用 fake secret——与 .env.local 生产 JWT_SECRET 无关。
+    // 32 字节（256 bit）随机 hex，仅用于单元测试隔离。
+    private static final String SECRET = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+    private static final long EXPIRES_IN = 7200L;
+
+    @Test
+    void signAndParse_returnsClaims() {
+        JwtTokenProvider provider = new JwtTokenProvider(SECRET, EXPIRES_IN);
+
+        String token = provider.sign(42, "alice", "普通用户");
+
+        Claims claims = provider.parse(token);
+        assertThat(claims.getSubject()).isEqualTo("alice");
+        assertThat(claims.get("uid", Integer.class)).isEqualTo(42);
+        assertThat(claims.get("type", String.class)).isEqualTo("普通用户");
+        assertThat(claims.getExpiration().getTime() - claims.getIssuedAt().getTime())
+                .isEqualTo(EXPIRES_IN * 1000L);
+    }
+
+    @Test
+    void parseExpiredToken_throwsExpiredJwtException() {
+        // 用同一 secret 手工签一个已过期 token
+        SecretKey key = Keys.hmacShaKeyFor(SECRET.getBytes(StandardCharsets.UTF_8));
+        Instant now = Instant.now();
+        String expired = Jwts.builder()
+                .subject("alice")
+                .issuedAt(Date.from(now.minusSeconds(7200)))
+                .expiration(Date.from(now.minusSeconds(60)))
+                .signWith(key)
+                .compact();
+
+        JwtTokenProvider provider = new JwtTokenProvider(SECRET, EXPIRES_IN);
+
+        assertThatThrownBy(() -> provider.parse(expired))
+                .isInstanceOf(ExpiredJwtException.class);
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.xly.erp.common.exception.AccountLockedException;
+import com.xly.erp.common.exception.BizException;
+import com.xly.erp.common.response.ErrorCode;
+import com.xly.erp.module.usr.dto.LoginDTO;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.security.JwtTokenProvider;
+import com.xly.erp.module.usr.security.LoginAttemptStore;
+import com.xly.erp.module.usr.service.impl.LoginServiceImpl;
+import com.xly.erp.module.usr.vo.LoginResultVO;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.security.crypto.password.PasswordEncoder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.isNull;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class LoginServiceImplTest {
+
+    @Mock UserMapper userMapper;
+    @Mock PasswordEncoder passwordEncoder;
+    @Mock LoginAttemptStore attemptStore;
+    @Mock JwtTokenProvider jwtTokenProvider;
+
+    @InjectMocks LoginServiceImpl service;
+
+    private LoginDTO dto() {
+        LoginDTO d = new LoginDTO();
+        d.setSUserName("alice");
+        d.setSPassword("666666");
+        d.setSVersion("standard");
+        return d;
+    }
+
+    private UserEntity userEntity() {
+        UserEntity u = new UserEntity();
+        u.setIIncrement(42);
+        u.setSUserNo("u001");
+        u.setSUserName("alice");
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setSPasswordHash("$2a$10$hash");
+        u.setBDeleted(false);
+        return u;
+    }
+
+    @Test
+    void login_validCredentials_returnsTokenAndClearsFailCount() {
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(0L);
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(userEntity());
+        when(passwordEncoder.matches("666666", "$2a$10$hash")).thenReturn(true);
+        when(jwtTokenProvider.sign(42, "alice", "普通用户")).thenReturn("jwt.token.value");
+        when(jwtTokenProvider.getExpiresInSeconds()).thenReturn(7200L);
+
+        LoginResultVO vo = service.login(dto());
+
+        assertThat(vo.getAccessToken()).isEqualTo("jwt.token.value");
+        assertThat(vo.getExpiresIn()).isEqualTo(7200L);
+        assertThat(vo.getUser().getIIncrement()).isEqualTo(42);
+        assertThat(vo.getUser().getSUserName()).isEqualTo("alice");
+        assertThat(vo.getUser().getSUserType()).isEqualTo("普通用户");
+        verify(attemptStore).clear("alice");
+        verify(userMapper).update(isNull(), any(Wrapper.class));
+    }
+
+    @Test
+    void login_userNotFound_returns40101_recordsFailure() {
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(0L);
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(null);
+
+        assertThatThrownBy(() -> service.login(dto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.LOGIN_INVALID_CREDENTIALS.getCode());
+
+        verify(attemptStore).recordFailure("alice");
+        verify(userMapper, never()).update(any(), any(Wrapper.class));
+    }
+
+    @Test
+    void login_passwordMismatch_returns40101_recordsFailure() {
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(0L);
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(userEntity());
+        when(passwordEncoder.matches("666666", "$2a$10$hash")).thenReturn(false);
+
+        assertThatThrownBy(() -> service.login(dto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.LOGIN_INVALID_CREDENTIALS.getCode());
+
+        verify(attemptStore).recordFailure("alice");
+        verify(userMapper, never()).update(any(), any(Wrapper.class));
+    }
+
+    @Test
+    void login_accountLocked_throwsAccountLockedException_withCooldown() {
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(540L);
+
+        assertThatThrownBy(() -> service.login(dto()))
+                .isInstanceOf(AccountLockedException.class)
+                .extracting(e -> ((AccountLockedException) e).getCooldownSeconds())
+                .isEqualTo(540L);
+
+        verify(userMapper, never()).selectOne(any(Wrapper.class));
+    }
+
+    @Test
+    void login_5thFailureTriggersLock_throwsAccountLockedException() {
+        when(attemptStore.cooldownSeconds("alice"))
+                .thenReturn(0L)   // 入口检查通过
+                .thenReturn(900L); // recordFailure 后再查时已锁定
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(userEntity());
+        when(passwordEncoder.matches("666666", "$2a$10$hash")).thenReturn(false);
+
+        assertThatThrownBy(() -> service.login(dto()))
+                .isInstanceOf(AccountLockedException.class)
+                .extracting(e -> ((AccountLockedException) e).getCooldownSeconds())
+                .isEqualTo(900L);
+
+        verify(attemptStore).recordFailure("alice");
+    }
+
+    @Test
+    void login_successUpdatesTLastLoginDate_viaSetClause() {
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(0L);
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(userEntity());
+        when(passwordEncoder.matches(anyString(), anyString())).thenReturn(true);
+        when(jwtTokenProvider.sign(anyInt(), anyString(), anyString())).thenReturn("token");
+        when(jwtTokenProvider.getExpiresInSeconds()).thenReturn(7200L);
+
+        service.login(dto());
+
+        // 验证 update(entity=null, wrapper=non-null)，对应 LambdaUpdateWrapper.set(tLastLoginDate, now)
+        verify(userMapper, times(1)).update(isNull(), any(Wrapper.class));
+    }
+
+    @Test
+    void login_userSoftDeleted_returns40101() {
+        // selectOne 已过滤 bDeleted=0 → 软删用户返回 null（与 not found 等效路径）
+        when(attemptStore.cooldownSeconds("alice")).thenReturn(0L);
+        when(userMapper.selectOne(any(Wrapper.class))).thenReturn(null);
+
+        assertThatThrownBy(() -> service.login(dto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.LOGIN_INVALID_CREDENTIALS.getCode());
+    }
+}
+package com.xly.erp.module.usr.service;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.baomidou.mybatisplus.core.metadata.IPage;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+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.UserCreateDTO;
+import com.xly.erp.module.usr.dto.UserQueryDTO;
+import com.xly.erp.module.usr.dto.UserUpdateDTO;
+import com.xly.erp.module.usr.entity.PermissionCategoryEntity;
+import com.xly.erp.module.usr.entity.StaffEntity;
+import com.xly.erp.module.usr.entity.UserEntity;
+import com.xly.erp.module.usr.entity.UserPermissionEntity;
+import com.xly.erp.module.usr.mapper.PermissionCategoryMapper;
+import com.xly.erp.module.usr.mapper.StaffMapper;
+import com.xly.erp.module.usr.mapper.UserMapper;
+import com.xly.erp.module.usr.mapper.UserPermissionMapper;
+import com.xly.erp.module.usr.service.impl.UserServiceImpl;
+import com.xly.erp.module.usr.vo.UserListItemVO;
+import com.xly.erp.module.usr.vo.UserVO;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.security.crypto.password.PasswordEncoder;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyList;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class UserServiceImplTest {
+
+    @Mock UserMapper userMapper;
+    @Mock StaffMapper staffMapper;
+    @Mock PermissionCategoryMapper permissionCategoryMapper;
+    @Mock UserPermissionMapper userPermissionMapper;
+    @Mock PasswordEncoder passwordEncoder;
+
+    @InjectMocks UserServiceImpl service;
+
+    private UserCreateDTO baseDto() {
+        UserCreateDTO d = new UserCreateDTO();
+        d.setSUserNo("u001");
+        d.setSUserName("alice");
+        d.setSUserType("普通用户");
+        d.setSLanguage("zh");
+        return d;
+    }
+
+    @Test
+    void create_minimalFields_returnsVOWithBCryptHash() {
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(passwordEncoder.encode("666666")).thenReturn("$2a$10$mockhash");
+        when(userMapper.insert((UserEntity) any())).thenAnswer(inv -> {
+            UserEntity u = inv.getArgument(0);
+            u.setIIncrement(101);
+            return 1;
+        });
+
+        UserVO vo = service.create(baseDto());
+
+        assertThat(vo.getIIncrement()).isEqualTo(101);
+        assertThat(vo.getSUserName()).isEqualTo("alice");
+        assertThat(vo.getBCanModifyDocs()).isFalse();
+        assertThat(vo.getPermissionCategoryIds()).isEmpty();
+
+        ArgumentCaptor<UserEntity> cap = ArgumentCaptor.forClass(UserEntity.class);
+        verify(userMapper).insert(cap.capture());
+        UserEntity saved = cap.getValue();
+        assertThat(saved.getSPasswordHash()).isEqualTo("$2a$10$mockhash");
+        assertThat(saved.getBDeleted()).isFalse();
+        assertThat(saved.getTCreateDate()).isNotNull();
+        assertThat(saved.getSCreatedBy()).isNull();
+        assertThat(saved.getSBrandsId()).isNull();
+    }
+
+    @Test
+    void create_withStaffAndPermissions_writesAssociation() {
+        UserCreateDTO d = baseDto();
+        d.setIStaffId(7);
+        d.setPermissionCategoryIds(List.of(1, 2, 3));
+
+        StaffEntity staff = new StaffEntity();
+        staff.setIIncrement(7);
+        staff.setBDeleted(false);
+        when(staffMapper.selectById(7)).thenReturn(staff);
+
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(
+                cat(1), cat(2), cat(3)
+        ));
+        when(passwordEncoder.encode("666666")).thenReturn("$2a$10$h");
+        when(userMapper.insert((UserEntity) any())).thenAnswer(inv -> {
+            UserEntity u = inv.getArgument(0);
+            u.setIIncrement(202);
+            return 1;
+        });
+
+        UserVO vo = service.create(d);
+
+        assertThat(vo.getIIncrement()).isEqualTo(202);
+        assertThat(vo.getIStaffId()).isEqualTo(7);
+        assertThat(vo.getPermissionCategoryIds()).containsExactly(1, 2, 3);
+
+        ArgumentCaptor<UserPermissionEntity> upCap = ArgumentCaptor.forClass(UserPermissionEntity.class);
+        verify(userPermissionMapper, times(3)).insert(upCap.capture());
+        List<UserPermissionEntity> ups = upCap.getAllValues();
+        assertThat(ups).extracting(UserPermissionEntity::getIUserId).containsOnly(202);
+        assertThat(ups).extracting(UserPermissionEntity::getICategoryId).containsExactly(1, 2, 3);
+    }
+
+    @Test
+    void create_duplicateUserName_throws40921() {
+        // 第一次 selectCount(sUserName) 返回 1
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        assertThatThrownBy(() -> service.create(baseDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.USR_USER_NAME_OR_NO_DUP.getCode());
+        verify(userMapper, never()).insert((UserEntity) any());
+    }
+
+    @Test
+    void create_duplicateUserNo_throws40921() {
+        // 第一次 (sUserName) 返回 0；第二次 (sUserNo) 返回 1
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L, 1L);
+
+        assertThatThrownBy(() -> service.create(baseDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.USR_USER_NAME_OR_NO_DUP.getCode());
+        verify(userMapper, never()).insert((UserEntity) any());
+    }
+
+    @Test
+    void create_staffNotFound_throws40421() {
+        UserCreateDTO d = baseDto();
+        d.setIStaffId(999999);
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(staffMapper.selectById(999999)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.create(d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.STAFF_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void create_staffSoftDeleted_throws40421() {
+        UserCreateDTO d = baseDto();
+        d.setIStaffId(5);
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        StaffEntity deleted = new StaffEntity();
+        deleted.setIIncrement(5);
+        deleted.setBDeleted(true);
+        when(staffMapper.selectById(5)).thenReturn(deleted);
+
+        assertThatThrownBy(() -> service.create(d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.STAFF_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void create_permissionCategoryNotFound_throws40422() {
+        UserCreateDTO d = baseDto();
+        d.setPermissionCategoryIds(List.of(1, 999999));
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(cat(1))); // 只返回 1 条，缺 999999
+
+        assertThatThrownBy(() -> service.create(d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.PERM_CATEGORY_NOT_FOUND.getCode());
+        verify(userMapper, never()).insert((UserEntity) any());
+    }
+
+    @Test
+    void create_emptyPermissionCategoryIds_doesNotInsertAssociation() {
+        UserCreateDTO d = baseDto();
+        d.setPermissionCategoryIds(List.of());
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(passwordEncoder.encode("666666")).thenReturn("$2a$10$h");
+        when(userMapper.insert((UserEntity) any())).thenAnswer(inv -> {
+            ((UserEntity) inv.getArgument(0)).setIIncrement(303);
+            return 1;
+        });
+
+        service.create(d);
+
+        verify(userPermissionMapper, never()).insert((UserPermissionEntity) any());
+    }
+
+    @Test
+    void create_concurrentDuplicate_dupKeyException_mappedTo40921() {
+        when(userMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        when(passwordEncoder.encode("666666")).thenReturn("$2a$10$h");
+        when(userMapper.insert((UserEntity) any()))
+                .thenThrow(new DuplicateKeyException("uk_user_name"));
+
+        assertThatThrownBy(() -> service.create(baseDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.USR_USER_NAME_OR_NO_DUP.getCode());
+    }
+
+    private static PermissionCategoryEntity cat(int id) {
+        PermissionCategoryEntity p = new PermissionCategoryEntity();
+        p.setIIncrement(id);
+        p.setBDeleted(false);
+        return p;
+    }
+
+    // ============================================================
+    //  REQ-USR-002 update 系列
+    // ============================================================
+
+    private UserUpdateDTO updateDto() {
+        UserUpdateDTO d = new UserUpdateDTO();
+        d.setIStaffId(7);
+        d.setSUserType("超级管理员");
+        d.setSLanguage("en");
+        d.setBCanModifyDocs(true);
+        d.setPermissionCategoryIds(List.of(10, 20));
+        return d;
+    }
+
+    private UserEntity existingTargetUser(int id) {
+        UserEntity u = new UserEntity();
+        u.setIIncrement(id);
+        u.setSUserNo("u_orig");
+        u.setSUserName("alice_orig");
+        u.setIStaffId(3);
+        u.setSUserType("普通用户");
+        u.setSLanguage("zh");
+        u.setBCanModifyDocs(false);
+        u.setSPasswordHash("$2a$10$origHash");
+        u.setBDeleted(false);
+        u.setSCreatedBy("system");
+        return u;
+    }
+
+    @Test
+    void update_targetNotFound_throws40431() {
+        when(userMapper.selectById(99)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.update(99, updateDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.USR_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_targetSoftDeleted_throws40431() {
+        UserEntity target = existingTargetUser(100);
+        target.setBDeleted(true);
+        when(userMapper.selectById(100)).thenReturn(target);
+
+        assertThatThrownBy(() -> service.update(100, updateDto()))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.USR_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_staffNotFound_throws40421() {
+        UserEntity target = existingTargetUser(101);
+        when(userMapper.selectById(101)).thenReturn(target);
+        UserUpdateDTO d = updateDto();
+        d.setIStaffId(999999);
+        when(staffMapper.selectById(999999)).thenReturn(null);
+
+        assertThatThrownBy(() -> service.update(101, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.STAFF_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_staffSoftDeleted_throws40421() {
+        UserEntity target = existingTargetUser(102);
+        when(userMapper.selectById(102)).thenReturn(target);
+        UserUpdateDTO d = updateDto();
+        d.setIStaffId(8);
+        StaffEntity staff = new StaffEntity();
+        staff.setIIncrement(8);
+        staff.setBDeleted(true);
+        when(staffMapper.selectById(8)).thenReturn(staff);
+
+        assertThatThrownBy(() -> service.update(102, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.STAFF_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_permissionCategoryNotFound_throws40422() {
+        UserEntity target = existingTargetUser(103);
+        when(userMapper.selectById(103)).thenReturn(target);
+        UserUpdateDTO d = updateDto();
+        d.setIStaffId(null); // 跳过 staff 校验
+        d.setPermissionCategoryIds(List.of(10, 999999));
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(cat(10)));
+
+        assertThatThrownBy(() -> service.update(103, d))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.PERM_CATEGORY_NOT_FOUND.getCode());
+    }
+
+    @Test
+    void update_full_returnsVOWithUpdatedFields_andRebuildsPermissions() {
+        UserEntity target = existingTargetUser(104);
+        when(userMapper.selectById(104)).thenReturn(target);
+        StaffEntity staff = new StaffEntity();
+        staff.setIIncrement(7);
+        staff.setBDeleted(false);
+        when(staffMapper.selectById(7)).thenReturn(staff);
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(cat(10), cat(20)));
+
+        UserVO vo = service.update(104, updateDto());
+
+        ArgumentCaptor<UserEntity> userCap = ArgumentCaptor.forClass(UserEntity.class);
+        verify(userMapper).updateById(userCap.capture());
+        UserEntity saved = userCap.getValue();
+        // 已修改字段
+        assertThat(saved.getIStaffId()).isEqualTo(7);
+        assertThat(saved.getSUserType()).isEqualTo("超级管理员");
+        assertThat(saved.getSLanguage()).isEqualTo("en");
+        assertThat(saved.getBCanModifyDocs()).isTrue();
+        // 保留字段
+        assertThat(saved.getSUserNo()).isEqualTo("u_orig");
+        assertThat(saved.getSUserName()).isEqualTo("alice_orig");
+        assertThat(saved.getSPasswordHash()).isEqualTo("$2a$10$origHash");
+        assertThat(saved.getSCreatedBy()).isEqualTo("system");
+
+        // 关联表先删后插
+        verify(userPermissionMapper).delete(any(Wrapper.class));
+        ArgumentCaptor<UserPermissionEntity> upCap = ArgumentCaptor.forClass(UserPermissionEntity.class);
+        verify(userPermissionMapper, times(2)).insert(upCap.capture());
+        assertThat(upCap.getAllValues()).extracting(UserPermissionEntity::getICategoryId)
+                .containsExactly(10, 20);
+        assertThat(upCap.getAllValues()).extracting(UserPermissionEntity::getIUserId)
+                .containsOnly(104);
+
+        assertThat(vo.getPermissionCategoryIds()).containsExactly(10, 20);
+    }
+
+    @Test
+    void update_partialNullBCanModifyDocs_keepsOriginal() {
+        UserEntity target = existingTargetUser(105);
+        target.setBCanModifyDocs(true); // 原值 true
+        when(userMapper.selectById(105)).thenReturn(target);
+        StaffEntity staff = new StaffEntity();
+        staff.setIIncrement(7);
+        staff.setBDeleted(false);
+        when(staffMapper.selectById(7)).thenReturn(staff);
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(cat(10), cat(20)));
+
+        UserUpdateDTO d = updateDto();
+        d.setBCanModifyDocs(null); // 期望保留原值
+
+        service.update(105, d);
+
+        ArgumentCaptor<UserEntity> userCap = ArgumentCaptor.forClass(UserEntity.class);
+        verify(userMapper).updateById(userCap.capture());
+        assertThat(userCap.getValue().getBCanModifyDocs()).isTrue();
+    }
+
+    @Test
+    void update_clearStaffId_setsToNull() {
+        UserEntity target = existingTargetUser(106);
+        target.setIStaffId(3); // 原本有
+        when(userMapper.selectById(106)).thenReturn(target);
+        when(permissionCategoryMapper.selectBatchIds(anyList())).thenReturn(List.of(cat(10), cat(20)));
+
+        UserUpdateDTO d = updateDto();
+        d.setIStaffId(null); // 显式清空
+
+        service.update(106, d);
+
+        ArgumentCaptor<UserEntity> userCap = ArgumentCaptor.forClass(UserEntity.class);
+        verify(userMapper).updateById(userCap.capture());
+        assertThat(userCap.getValue().getIStaffId()).isNull();
+    }
+
+    @Test
+    void update_emptyPermissionCategoryIds_clearsAllAssociations() {
+        UserEntity target = existingTargetUser(107);
+        when(userMapper.selectById(107)).thenReturn(target);
+        StaffEntity staff = new StaffEntity();
+        staff.setIIncrement(7);
+        staff.setBDeleted(false);
+        when(staffMapper.selectById(7)).thenReturn(staff);
+
+        UserUpdateDTO d = updateDto();
+        d.setPermissionCategoryIds(List.of()); // 清空全部
+
+        service.update(107, d);
+
+        verify(userPermissionMapper).delete(any(Wrapper.class));
+        verify(userPermissionMapper, never()).insert((UserPermissionEntity) any());
+    }
+
+    // ============================================================
+    //  REQ-USR-003 search 系列
+    // ============================================================
+
+    @Test
+    void search_emptyDb_returnsEmptyPage() {
+        UserQueryDTO query = new UserQueryDTO();
+        IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
+        emptyPage.setTotal(0L);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
+
+        PageResult<UserListItemVO> result = service.search(query);
+        assertThat(result.getTotal()).isZero();
+        assertThat(result.getList()).isEmpty();
+    }
+
+    @Test
+    void search_invalidQueryField_throws40010() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setQueryField("invalid_field");
+
+        assertThatThrownBy(() -> service.search(query))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.PARAM_INVALID.getCode());
+    }
+
+    @Test
+    void search_invalidMatchType_throws40010() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setMatchType("like"); // 非白名单
+
+        assertThatThrownBy(() -> service.search(query))
+                .isInstanceOf(BizException.class)
+                .extracting(e -> ((BizException) e).getCode())
+                .isEqualTo(ErrorCode.PARAM_INVALID.getCode());
+    }
+
+    @Test
+    void search_passesMappedColumnToMapper() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setQueryField("username");
+        query.setQueryValue("alice");
+        IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
+
+        service.search(query);
+
+        ArgumentCaptor<String> colCap = ArgumentCaptor.forClass(String.class);
+        verify(userMapper).searchUsers(any(IPage.class), any(UserQueryDTO.class), colCap.capture());
+        assertThat(colCap.getValue()).isEqualTo("u.sUserName");
+    }
+
+    @Test
+    void search_appliesDefaultPagination_whenNullPageNumOrSize() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setPageNum(null);
+        query.setPageSize(null);
+        IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
+
+        service.search(query);
+
+        ArgumentCaptor<IPage> pageCap = ArgumentCaptor.forClass(IPage.class);
+        verify(userMapper).searchUsers(pageCap.capture(), any(UserQueryDTO.class), any());
+        IPage<?> page = pageCap.getValue();
+        assertThat(page.getCurrent()).isEqualTo(1L);
+        assertThat(page.getSize()).isEqualTo(20L);
+    }
+
+    @Test
+    void search_deletedQueryValueTrue_normalizedToOne() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setQueryField("deleted");
+        query.setQueryValue("true");
+        query.setMatchType("equals");
+        IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
+
+        service.search(query);
+
+        ArgumentCaptor<UserQueryDTO> cap = ArgumentCaptor.forClass(UserQueryDTO.class);
+        verify(userMapper).searchUsers(any(IPage.class), cap.capture(), any());
+        assertThat(cap.getValue().getQueryValue()).isEqualTo("1");
+    }
+}
+spring:
+  flyway:
+    enabled: true
+    locations: filesystem:../sql/migrations
+    baseline-on-migrate: true
+    baseline-version: 1
+    baseline-description: "REQ-MOD-001 baseline (V1 already applied manually in A4)"
@@ -58,19 +58,19 @@
 - module_mod 模块管理
   - 依赖: —
   - 路径: backend/src/main/java/com/xly/erp/module/mod/, frontend/src/pages/mod/
-  - MR: —
+  - MR: !1
   - 功能:
-    - [ ] REQ-MOD-001 模块新增
-    - [ ] REQ-MOD-002 模块修改
-    - [ ] REQ-MOD-003 模块删除
-    - [ ] REQ-MOD-004 模块查询
+    - [x] REQ-MOD-001 模块新增
+    - [x] REQ-MOD-002 模块修改
+    - [x] REQ-MOD-003 模块删除
+    - [x] REQ-MOD-004 模块查询
 - module_usr 用户管理
   - 依赖: —
   - 路径: backend/src/main/java/com/xly/erp/module/usr/, frontend/src/pages/usr/
   - MR: —
   - 功能:
-    - [ ] REQ-USR-001 用户新增
-    - [ ] REQ-USR-002 用户修改
-    - [ ] REQ-USR-003 用户查询
-    - [ ] REQ-USR-004 用户登录
+    - [x] REQ-USR-001 用户新增
+    - [x] REQ-USR-002 用户修改
+    - [x] REQ-USR-003 用户查询
+    - [x] REQ-USR-004 用户登录
+---
+module_id: module_mod
+date: 2026-05-06
+git_range: ace5841..c64a026 (24 commits)
+---
+
+# 模块完成报告 — module_mod 模块管理
+
+## ① 模块信息
+- 模块 ID: module_mod
+- 模块名: 模块管理（业务模块定义 / 树形菜单 / 权限分组基础单位）
+- 开发区间: ace5841（master, plan phase done）→ c64a026（test-gate evidence），共 24 个 commits
+
+## ② REQ 完成清单
+
+- [x] REQ-MOD-001 — 模块新增（`POST /api/modules`）
+  - spec: docs/superpowers/specs/2026-05-06-REQ-MOD-001.md
+  - plan: docs/superpowers/plans/2026-05-06-REQ-MOD-001.md
+  - review: docs/superpowers/reviews/2026-05-06-REQ-MOD-001.md
+- [x] REQ-MOD-002 — 模块修改（`PUT /api/modules/{id}`）
+  - spec: docs/superpowers/specs/2026-05-06-REQ-MOD-002.md
+  - plan: docs/superpowers/plans/2026-05-06-REQ-MOD-002.md
+  - review: docs/superpowers/reviews/2026-05-06-REQ-MOD-002.md
+- [x] REQ-MOD-003 — 模块软删除（`DELETE /api/modules/{id}`）
+  - spec: docs/superpowers/specs/2026-05-06-REQ-MOD-003.md
+  - plan: docs/superpowers/plans/2026-05-06-REQ-MOD-003.md
+  - review: docs/superpowers/reviews/2026-05-06-REQ-MOD-003.md
+- [x] REQ-MOD-004 — 模块树查询（`GET /api/modules?keyword=`）
+  - spec: docs/superpowers/specs/2026-05-06-REQ-MOD-004.md
+  - plan: docs/superpowers/plans/2026-05-06-REQ-MOD-004.md
+  - review: docs/superpowers/reviews/2026-05-06-REQ-MOD-004.md
+
+## ③ 文件变更表
+
+| 文件 | 操作 | 说明 |
+|---|---|---|
+| backend/pom.xml | A | Spring Boot 3.2.5 父 pom + 依赖（mybatis-plus 3.5.7、flyway 10、hutool、mapstruct、test）+ surefire includes 修复（让 *IT.java 跑入 mvn test） |
+| backend/src/main/java/com/xly/erp/ErpApplication.java | A | Spring Boot 启动类 + @MapperScan |
+| backend/src/main/resources/application.yml | A | DB / Flyway / MyBatis-Plus 配置；从 .env.local 注入凭据 |
+| backend/src/main/resources/application-test.yml | A | test profile：Flyway baseline-on-migrate=true / baseline-version=1 |
+| backend/src/main/java/com/xly/erp/common/response/ApiResponse.java | A | 统一响应 `{code, message, data, timestamp}` + 静态工厂 |
+| backend/src/main/java/com/xly/erp/common/response/ErrorCode.java | A | 错误码枚举：SUCCESS / PARAM_INVALID / MOD_PARENT_NOT_FOUND / MOD_NOT_FOUND / MOD_PROC_NAME_DUP / MOD_HAS_REFERENCES / MOD_PARENT_LOOP / INTERNAL_ERROR |
+| backend/src/main/java/com/xly/erp/common/exception/BizException.java | A | 业务异常（带 ErrorCode） |
+| backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java | A | @RestControllerAdvice：BizException → ApiResponse.fail(code)，MethodArgumentNotValidException → 40010，Exception → 50000，**不回显堆栈** |
+| backend/src/main/java/com/xly/erp/config/SecurityConfig.java | A | SecurityFilterChain permitAll（占位，REQ-USR-004 时收紧为 JWT） |
+| backend/src/main/java/com/xly/erp/config/JacksonConfig.java | A | Jackson 字段访问可见性配置（解决 Lombok getter `iIncrement` 被 Introspector 解析为 `IIncrement` 导致 JSON key 错位） |
+| backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java | A | tModule 实体；保留匈牙利前缀；iParentId 用 `FieldStrategy.IGNORED` 让 update 时显式 NULL 写入 |
+| backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java | A | extends BaseMapper<ModuleEntity>；只用 BaseMapper 默认 SQL |
+| backend/src/main/resources/mapper/mod/ModuleMapper.xml | A | 空骨架（预留扩展） |
+| backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java | A | POST 入参 + Bean Validation（@NotBlank / @Pattern 枚举 / @Size / @Min） |
+| backend/src/main/java/com/xly/erp/module/mod/dto/ModuleUpdateDTO.java | A | PUT 入参；剥除 sProcedureName（不可改） |
+| backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java | A | GET 入参 keyword（@Size max=50） |
+| backend/src/main/java/com/xly/erp/module/mod/vo/ModuleVO.java | A | 创建/修改返回 VO（11 字段）+ 静态 from(ModuleEntity) |
+| backend/src/main/java/com/xly/erp/module/mod/vo/ModuleDeleteResultVO.java | A | 删除返回精简 VO（iIncrement + bDeleted） |
+| backend/src/main/java/com/xly/erp/module/mod/vo/ModuleTreeNodeVO.java | A | 树查询节点 VO（7 字段 + children=[]） |
+| backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java | A | 接口：create / update / delete / tree |
+| backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java | A | 4 业务方法：create（唯一性预检 + DuplicateKey 兜底）/ update（父 FK 校验 + 环路 walk-up depth=5）/ delete（子模块引用检查 + LambdaUpdateWrapper.set 显式 SET 列）/ tree（内存树构造 + keyword 模糊 + 祖先链 walk-up） |
+| backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java | A | 4 端点：POST / PUT / DELETE / GET |
+| backend/src/test/java/com/xly/erp/ErpApplicationTest.java | A | contextLoads + Flyway baseline |
+| backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java | A | 5 单测（含 7 个错误码常量断言） |
+| backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java | A | 4 单测（standaloneSetup） |
+| backend/src/test/java/com/xly/erp/config/SecurityConfigTest.java | A | 1 集成（permitAll 验证） |
+| backend/src/test/java/com/xly/erp/module/mod/dto/ModuleCreateDTOValidationTest.java | A | 5 单测（Bean Validation） |
+| backend/src/test/java/com/xly/erp/module/mod/dto/ModuleUpdateDTOValidationTest.java | A | 4 单测（Bean Validation） |
+| backend/src/test/java/com/xly/erp/module/mod/mapper/ModuleMapperIT.java | A | 2 集成（@SpringBootTest + insert/select） |
+| backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java | A | 26 单测（Mockito + ArgumentCaptor）：6 create / 8 update / 6 delete / 6 tree |
+| backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java | A | 28 集成（MockMvc + @Transactional rollback）：6 POST / 8 PUT / 7 DELETE / 7 GET |
+| backend/src/test/resources/application-test.yml | A | test profile 副本 |
+| docs/08-模块任务管理.md | M | § 二 module_mod 4 个 REQ 全部勾选 |
+| docs/superpowers/specs/2026-05-06-REQ-MOD-00{1..4}.md | A | 4 份功能规格 |
+| docs/superpowers/plans/2026-05-06-REQ-MOD-00{1..4}.md | A | 4 份任务级实现计划 |
+| docs/superpowers/reviews/2026-05-06-REQ-MOD-00{1..4}.md | A | 4 份 AI 审阅报告 |
+| docs/superpowers/module-reports/module_mod-test-gate.md | A | 本模块 test-gate 闸门证据 |
+
+## ④ 数据库使用表
+
+- 读: `tModule`（4 个 REQ 都读：create 唯一性预检 / update 父校验 + 后代环路 / delete 子模块引用检查 + 状态校验 / tree selectList）
+- 写: `tModule`（create insert / update updateById / delete update bDeleted=1 软删除）
+
+本模块不读 / 不写其他表。FK 关系：tModule 自引用 `iParentId → iIncrement`（V1 由 db-init 创建）。
+
+## ⑤ 测试结果
+
+- `scripts/test.sh` 最终：green
+- 通过: 76 / 失败: 0 / 跳过: 0
+- 覆盖率: 未启用 JaCoCo 等覆盖率工具（docs/04 § 零 技术栈表未列入）；后续模块若需要可作为软规则 S1 引入
+
+测试分布：
+- 单元测试 49（ApiResponse 5 + GlobalExceptionHandler 4 + DTO Validation 5+4 + ServiceImpl 26 + 其他 5）
+- 集成测试 31（ApplicationTest 1 + SecurityConfig 1 + ModuleMapperIT 2 + ModuleControllerIT 28）
+
+`./scripts/test.sh` 流程：setup-test-db.sh DROP+CREATE → mvn build → mvn lint(compile) → mvn test → frontend skip → e2e 略 → reset DB。耗时 ~15s。
+
+## ⑥ 本模块新增 Migration
+
+—（本模块未引入 schema 改动；tModule 由 V1__initial_schema.sql 在 A4 阶段创建）
+
+## ⑦ 跨模块改动清单（软规则 S2）
+
+—（本模块为 module_mod 独立工作，未触碰其他模块的代码 / schema；hook `log-cross-module.sh` 未生成存根，docs/superpowers/module-reports/module_mod-cross-module.md 不存在）
+
+## ⑧ 偏离 spec 清单
+
+- **REQ-MOD-001** → 顺手新增了计划外的 `JacksonConfig.java`（spec / plan 文件清单未列出）。原因：项目沿用 docs/03 匈牙利前缀命名（`iIncrement`），Lombok 生成的 `getIIncrement()` 经 JavaBeans Introspector 解析为属性 `IIncrement`（首两字符全大写时保留），导致 JSON key 输出 `"IIncrement"` 而非期望的 `"iIncrement"`，破坏 API 契约。配置 Jackson 用字段直接读取属性名修复。已在 review 报告 § Nice-to-have 披露。
+- **REQ-MOD-001** → spec 要求 Controller / Service / Mapper / DTO / VO 关键类贴 `// REQ-MOD-001` 标签；实现中只在 Controller / SecurityConfig 上写注释，其他类未贴。原因：实施时疏漏，已在 review § Nice-to-have 记录，不影响功能。
+- **REQ-MOD-002** → 在 ModuleEntity#iParentId 上加了 `FieldStrategy.IGNORED` 让 NULL 写入生效（spec 未规划 entity 层改动）。原因：MyBatis-Plus 默认 update 跳过 null，导致 `setIParentId(null)` 不能写入 SQL。这是 entity 全局行为变更，已在 review 报告标注为 Nice-to-have（未来其他 service 走 partial updateById 路径会埋雷）。
+- **REQ-MOD-003** → round 1 review 发现 high 隐患：iParentId.IGNORED 副作用导致 delete 时 entity-driven update 静默清空父引用。round 2 fix commit (2419659) 改用 `LambdaUpdateWrapper.set(...)` 显式 SET，并补 IT `delete_preservesOtherFields_onChildModule` 钉死回归。
+- **REQ-MOD-004** → 顺手修复了 `backend/pom.xml` 中 maven-surefire-plugin 默认 includes 不含 `*IT.java` 的配置缺陷。原因：之前 REQ-MOD-001/002/003 的 IT 测试在 `mvn test` 全量阶段根本未被发现 / 执行（仅在单独 `-Dtest=xxx` 下运行过），所有 verify approval 都基于不完整覆盖。修复后所有 IT 进入 mvn test，本模块累计 76 测试全部参与全量。已在 review 报告披露。
+- **跨 REQ — 鉴权延期**：所有 4 个 REQ 的 Controller 都加了说明性注释 `REQ-USR-004 完成后追加 @PreAuthorize(...)`，contract 要求的 `MOD:CREATE/UPDATE/DELETE/READ` 权限在本模块**未启用**。这是计划性技术债（docs/02 § 三关键说明 + 各 REQ spec § 边界都明确点到），由 REQ-USR-004 首次落地登录上下文时统一收紧 SecurityConfig。
+- **跨 REQ — 多租户字段 / sCreatedBy 留 NULL**：所有写入路径中 `sBrandsId / sSubsidiaryId / sCreatedBy` 都落 NULL（spec 明确点到，等 REQ-USR-004 引入登录上下文 / 多租户上下文后回填）。
+
+## ⑨ AI reviewer 报告汇总
+
+- REQ-MOD-001: round 1 — approve（link: docs/superpowers/reviews/2026-05-06-REQ-MOD-001.md）
+- REQ-MOD-002: round 1 — approve（link: docs/superpowers/reviews/2026-05-06-REQ-MOD-002.md）
+- REQ-MOD-003: round 1 — request-changes → round 2 — approve（link: docs/superpowers/reviews/2026-05-06-REQ-MOD-003.md，修复 commit 2419659）
+- REQ-MOD-004: round 1 — approve（link: docs/superpowers/reviews/2026-05-06-REQ-MOD-004.md）
+
+## ⑩ 已知问题
+
+1. **鉴权延期**：4 个端点目前 SecurityConfig permitAll；任何客户端无 token 也能调通。**REQ-USR-004 必须回头**给本模块端点加 `@PreAuthorize` + 把 `permitAll()` 改为 `authenticated()`，并补端到端鉴权 IT。
+2. **多租户字段 NULL**：tModule 中 `sBrandsId / sSubsidiaryId / sCreatedBy` 列在所有写入路径都为 NULL。REQ-USR-004 后需要：(a) 引入多租户拦截器从 SecurityContext 注入；(b) 写一个 V_n migration 给历史 NULL 行回填默认值；(c) 收紧 schema 把这几列改为 NOT NULL（视业务决策）。
+3. **iParentId 的 `FieldStrategy.IGNORED` 全局副作用**：本期所有 update 路径都走 load-then-modify 全量回填模式，所以安全；但未来若新增"只更新单字段"的 partial update 路径需特别注意——直接调 `updateById(patchEntity)` 会把 iParentId 静默清空。建议未来用 `LambdaUpdateWrapper.set(...)` 模式（参考 REQ-MOD-003 delete 实现）。
+4. **REQ-MOD-004 同级排序 IT 缺失**：spec § 验收 #7 同级排序仅在单测覆盖，端到端 IT 未直接断言。Jackson 默认保留 List 顺序，风险低，但理论上有序列化层差异的可能。下一模块或 docs sweep 时补一个端到端用例。
+5. **keyword 通配符未转义**：spec § 边界已声明本期不处理 `%` / `_`；业务模块名通常不含这些字符。后续若需要严格语义可在 service 层加 `escape \`。
+6. **覆盖率工具未引入**：docs/04 § 零 技术栈未列 JaCoCo / SonarQube；本期 76 测试由人工分析覆盖。
+7. **docs/05 § REQ-MOD-003 `data.references` 描述与实现不一致**：契约写 40912 响应附 `data.references` 列出阻塞引用清单，但实现只返回错误码 + 文案；BizException 没有 data 通道。后续 docs sweep 或 REQ-USR-004 引入完整 data payload 时统一对齐。
+
+## ⑪ 下一模块预览
+
+按 docs/02 § 二 顺序，下一个模块是 **module_usr 用户管理**（4 个 REQ：USR-001 用户新增 / USR-002 用户修改 / USR-003 用户查询 / USR-004 用户登录）。
+
+关键关注点：
+- REQ-USR-004 是项目 SecurityConfig + JWT + 登录上下文 + 多租户拦截器**首次落地**点，会同时收紧 module_mod 的 4 个 permitAll 端点。
+- REQ-USR-001 写 tUser + tUserPermission 关联表（多对多），需联动 tStaff（员工选）+ tPermissionCategory（权限分类只读字典）。tStaff 与 tPermissionCategory 当前**无增删改接口**，作为只读字典——若实施过程中发现需要增删改，可能要拆出新模块（docs/03 § tStaff / § tPermissionCategory 业务注记已点到此问题）。
+- REQ-USR-003 查询接口的列表 VO 包含跨表 JOIN（员工名 / 部门来自 tStaff），需要在 ModuleMapper 模式之外引入 selectJoinList 或 自定义 ResultMap。
+
+## ⑫ MR 链接
+
+http://git.xlyprint.cn/zhuzc/test2/merge_requests/1 (!1)
+## Local test gate — module_mod
+
+执行时间: 2026-05-06T20:07:28+08:00
+
+### scripts/test.sh (subagent)
+- 子会话: aba8704557f137ad2
+- 命令: `./scripts/test.sh`（setup-test-db.sh DROP+CREATE → mvn build/lint/test → frontend skip → e2e 略 → setup-test-db.sh reset）
+- 退出码: 0
+- 通过: 76 / 失败: 0
+- 关键 stdout (≤30 行):
+
+```
+[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.046 s -- in com.xly.erp.common.exception.GlobalExceptionHandlerTest
+[INFO]
+[INFO] Results:
+[INFO]
+[INFO] Tests run: 76, Failures: 0, Errors: 0, Skipped: 0
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  15.358 s
+[INFO] Finished at: 2026-05-06T20:07:28+08:00
+[INFO] ------------------------------------------------------------------------
+[test.sh] skip frontend test
+[test.sh] 5/6 E2E
+[test.sh] e2e 略
+[test.sh] 6/6 reset test db
+[setup-test-db] 即将 DROP + CREATE `xlyweberp_vibe_erp_test` on 118.178.19.35:3318
+[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts
+[test.sh] GREEN
+```
+
+结论: green
+## Local test gate — module_usr
+
+执行时间: 2026-05-07T09:33:12+08:00
+
+### scripts/test.sh (subagent)
+- 子会话: a04f12f4a6f932a7d
+- 命令: `./scripts/test.sh`（setup-test-db.sh DROP+CREATE → mvn build/lint/test → frontend skip → e2e 略 → setup-test-db.sh reset）
+- 退出码: 0
+- 通过: 172 / 失败: 0
+- 关键 stdout (≤30 行):
+
+```
+[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.030 s -- in com.xly.erp.common.exception.GlobalExceptionHandlerTest
+[INFO]
+[INFO] Results:
+[INFO]
+[INFO] Tests run: 172, Failures: 0, Errors: 0, Skipped: 0
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  25.464 s
+[INFO] Finished at: 2026-05-07T09:33:12+08:00
+[INFO] ------------------------------------------------------------------------
+[test.sh] skip frontend test
+[test.sh] 5/6 E2E
+[test.sh] e2e 略
+[test.sh] 6/6 reset test db
+[setup-test-db] 即将 DROP + CREATE `xlyweberp_vibe_erp_test` on 118.178.19.35:3318
+[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts
+[test.sh] GREEN
+```
+
+结论: green
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-001.md
+---
+
+# REQ-MOD-001 模块新增 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `POST /api/modules` 接口，把一条新业务模块写入 `tModule`，并顺带建立服务于本 REQ 的最小 Spring Boot 骨架。
+
+**Architecture:** 标准三层（Controller → Service → Mapper）。Spring Boot 3 + MyBatis-Plus + Flyway 自动 apply migrations。鉴权暂以 `SecurityConfig` permitAll 占位，REQ-USR-004 时回头收紧。统一响应 `ApiResponse<T>`、统一异常 `BizException` + `GlobalExceptionHandler`。
+
+**Tech Stack:** Spring Boot 3.x、MyBatis-Plus（spring-boot3-starter）、Flyway 10.x、MySQL 8、JUnit 5 + Spring Boot Test + MockMvc + Spring Security Test、Hutool、MapStruct（可选）、Maven 3.9。
+
+---
+
+## Schema 改动
+
+无（`tModule` 已由 A4 `V1__initial_schema.sql` 创建）。
+
+## 文件变更清单
+
+- `backend/pom.xml` — 创建（Spring Boot 父 pom + 依赖清单）
+- `backend/src/main/java/com/xly/erp/ErpApplication.java` — 创建（启动类）
+- `backend/src/main/resources/application.yml` — 创建（DB / Flyway / MyBatis-Plus / 端口配置，从环境变量注入）
+- `backend/src/main/resources/application-test.yml` — 创建（测试 profile，连 DB_SCHEMA test 库）
+- `backend/src/main/java/com/xly/erp/common/response/ApiResponse.java` — 创建（统一响应包装）
+- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 创建（错误码枚举）
+- `backend/src/main/java/com/xly/erp/common/exception/BizException.java` — 创建（业务异常）
+- `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java` — 创建（@RestControllerAdvice）
+- `backend/src/main/java/com/xly/erp/config/SecurityConfig.java` — 创建（permitAll 临时配置）
+- `backend/src/main/java/com/xly/erp/config/MybatisPlusConfig.java` — 创建（分页插件，本 REQ 不用，REQ-MOD-004 用，本任务先建空骨架）
+- `backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java` — 创建（@TableName("tModule")）
+- `backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java` — 创建（继承 BaseMapper）
+- `backend/src/main/resources/mapper/mod/ModuleMapper.xml` — 创建（空骨架，本 REQ 仅用 BaseMapper 默认 SQL）
+- `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java` — 创建（入参 + Bean Validation）
+- `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleVO.java` — 创建（出参）
+- `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 创建（接口）
+- `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 创建（实现，含 create 方法）
+- `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 创建（POST /api/modules）
+- `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 创建（单元）
+- `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java` — 创建（单元）
+- `backend/src/test/java/com/xly/erp/module/mod/mapper/ModuleMapperIT.java` — 创建（@SpringBootTest 集成）
+- `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 创建（单元 + Mockito）
+- `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 创建（MockMvc + @SpringBootTest）
+- `backend/src/test/resources/application-test.yml` — 创建（测试 profile 副本，便于 IDE 跑测试）
+- `.env.local` — 不修改（已有 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA / JWT_SECRET）
+
+---
+
+## 任务步骤
+
+### Task 1: 引导 Spring Boot 项目骨架（compile + boot 通过）
+
+**Files:**
+- Create: `backend/pom.xml`
+- Create: `backend/src/main/java/com/xly/erp/ErpApplication.java`
+- Create: `backend/src/main/resources/application.yml`
+- Create: `backend/src/main/resources/application-test.yml`
+- Create: `backend/src/test/resources/application-test.yml`（与上一行同内容，Spring Boot 测试时从 test/resources 优先加载）
+- Create: `backend/src/main/java/com/xly/erp/ErpApplicationTest.java`（验证 context 启动）
+
+**API shape:**
+- `ErpApplication` 主类标 `@SpringBootApplication`、`@MapperScan("com.xly.erp.**.mapper")`
+- `application.yml` 通过 `${DB_HOST}` / `${DB_PORT}` / `${DB_USER}` / `${DB_PASSWORD}` / `${DB_SCHEMA}` / `${JWT_SECRET}` 占位（值由本地启动脚本或 IDE EnvFile 插件从 `.env.local` 注入；详见 docs/04 § 3.5）
+- 启用 Flyway：`spring.flyway.locations=classpath:db/migration` —— 但项目 migrations 在 `sql/migrations/`；改为 `spring.flyway.locations=filesystem:../sql/migrations` 让 backend 直接复用仓库根的 V*.sql
+
+**pom.xml 锁定依赖**（写死，不让 TDD 自由选）：
+- `spring-boot-starter-parent` 3.2.x
+- `spring-boot-starter-web`、`-validation`、`-security`、`-test`
+- `spring-security-test`
+- `mybatis-plus-spring-boot3-starter` 最新稳定版（写明确版本号，本任务由 TDD 确认 mvn central 最新可用）
+- `flyway-core` + `flyway-mysql` 10.x
+- `mysql-connector-j` 8.x
+- `org.projectlombok:lombok`（编译期）+ `lombok-mapstruct-binding`
+- `org.mapstruct:mapstruct` 1.5.x + `mapstruct-processor`
+- `cn.hutool:hutool-all` 5.x
+- Java 编译目标 17
+
+- [ ] **Step 1.1 写测试**
+  - 文件: `backend/src/test/java/com/xly/erp/ErpApplicationTest.java`
+  - 测试名: `ErpApplicationTest#contextLoads`
+  - 内容: 空 `@SpringBootTest @ActiveProfiles("test")` + 空 test 方法
+  - 意图: ApplicationContext 能在 test profile 下成功启动 + Flyway 能 apply V1（apply 到现有 test schema 应是 no-op，因为表已存在；Flyway 跑完会建 `flyway_schema_history` 表 + 注册 V1 已 baseline）
+  - 子会话确认 FAIL（项目还没建好）
+
+- [ ] **Step 1.2 创建 pom.xml**
+  - 仅声明依赖、Java 17、surefire 配置
+  - `mvn -B -f backend/pom.xml dependency:resolve` 应通过
+
+- [ ] **Step 1.3 创建 ErpApplication + application.yml**
+  - `ErpApplication` 仅做启动 + `@MapperScan`
+  - `application.yml` 主键：`server.port=8080`、`spring.profiles.active=${SPRING_PROFILES_ACTIVE:dev}`、datasource、mybatis-plus、flyway
+  - `application-test.yml`：override `spring.flyway.baseline-on-migrate=true` + `spring.flyway.baseline-version=0`（让 Flyway 把当前已存在的 schema 作为 baseline，再追 apply）
+  - 子会话 `cd backend && mvn -B test -Dtest=ErpApplicationTest#contextLoads -DSPRING_PROFILES_ACTIVE=test` 应 PASS
+
+- [ ] **Step 1.4 提交**
+  - `git add backend/pom.xml backend/src/main/java/com/xly/erp/ErpApplication.java backend/src/main/resources/application*.yml backend/src/test/resources/application*.yml backend/src/test/java/com/xly/erp/ErpApplicationTest.java`
+  - `git commit -m "chore(mod): bootstrap spring boot skeleton REQ-MOD-001"`
+
+---
+
+### Task 2: 统一响应与错误码（ApiResponse + ErrorCode）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/response/ApiResponse.java`
+- Create: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Test: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+
+**API shape:**
+- `ApiResponse<T>`：字段 `int code`、`String message`、`T data`、`long timestamp`；静态工厂 `ok(T data)`、`ok(String message, T data)`、`fail(ErrorCode ec)`、`fail(int code, String message)`
+- `ErrorCode` 枚举（int code, String message）至少包含：
+  - `SUCCESS(200, "操作成功")`
+  - `PARAM_INVALID(40010, "参数错误")`
+  - `MODULE_PARENT_NOT_FOUND(40411, "父模块不存在或已删除")`
+  - `MODULE_PROCEDURE_NAME_DUPLICATE(40911, "存储过程名称已存在")`
+  - `INTERNAL_ERROR(50000, "服务器内部错误")`
+
+**锁定常量**（跨模块复用，写死）：
+```
+SUCCESS              = 200
+PARAM_INVALID        = 40010
+MOD_PARENT_NOT_FOUND = 40411
+MOD_PROC_NAME_DUP    = 40911
+INTERNAL_ERROR       = 50000
+```
+
+- [ ] **Step 2.1 写失败测试**
+  - 测试名: `ApiResponseTest#ok_setsCode200AndDataAndTimestamp`、`ApiResponseTest#fail_mapsErrorCodeFields`
+  - 意图: `ok(data)` → code=200，message="操作成功"，data=入参，timestamp 在合理范围；`fail(ErrorCode.PARAM_INVALID)` → code=40010，message="参数错误"
+  - 子会话 PASS：FAIL（class 不存在）
+
+- [ ] **Step 2.2 实现 ApiResponse + ErrorCode**
+  - 用 Lombok `@Data` 减少样板，但保留显式工厂方法
+  - 子会话 PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(common): unified ApiResponse and ErrorCode REQ-MOD-001"`
+
+---
+
+### Task 3: 业务异常 + 全局异常处理器
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/exception/BizException.java`
+- Create: `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java`
+- Test: `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java`（用 MockMvc + 一个临时 controller 触发各类异常）
+
+**API shape:**
+- `BizException extends RuntimeException`：构造 `BizException(ErrorCode ec)`、`BizException(ErrorCode ec, String detail)`；getter: `code()`, `message()`
+- `GlobalExceptionHandler` 处理：
+  - `BizException` → `ApiResponse.fail(ec)` 200 OK（业务错误也走 200 + 内部 code，docs/05 § 全局约定）
+  - `MethodArgumentNotValidException`（@Valid 失败）→ 提取 fieldError，组合 `ApiResponse.fail(PARAM_INVALID, "<field>: <reason>")`
+  - `Exception`（兜底）→ `ApiResponse.fail(INTERNAL_ERROR)` + log error；**响应不含堆栈**（docs/04 § 1.4）
+
+- [ ] **Step 3.1 写失败测试**
+  - 测试名（4 个）:
+    - `GlobalExceptionHandlerTest#bizException_returns200WithBizCode`
+    - `GlobalExceptionHandlerTest#validationException_returns200WithParamInvalidCode`
+    - `GlobalExceptionHandlerTest#uncaughtException_returns200WithInternalErrorCode`
+    - `GlobalExceptionHandlerTest#response_doesNotContainStackTrace`
+  - 测试方式: `@WebMvcTest(controllers=DummyController.class)` 内置一个 `DummyController` 故意抛各类异常，断言 `MockMvc.perform(...).andExpect(jsonPath("$.code").value(...))`
+  - 子会话: FAIL
+
+- [ ] **Step 3.2 实现 BizException + Handler**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(common): biz exception and global handler REQ-MOD-001"`
+
+---
+
+### Task 4: SecurityConfig（permitAll 占位）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/config/SecurityConfig.java`
+- Test: `backend/src/test/java/com/xly/erp/config/SecurityConfigTest.java`
+
+**API shape:**
+- `SecurityFilterChain securityFilterChain(HttpSecurity http)`：禁用 CSRF（API 项目）、禁用默认表单登录、所有 `/api/**` permitAll
+- 显式注释：`// REQ-USR-004 完成后改为 .authenticated() + JWT filter`
+
+- [ ] **Step 4.1 写失败测试**
+  - 测试名: `SecurityConfigTest#anyApiEndpoint_isPermittedWithoutAuth`
+  - 测试方式: `@SpringBootTest @AutoConfigureMockMvc` + 在 controller package 临时加一个 `/api/__ping` GET（**或**复用 Task 3 的 `DummyController`），无 token 请求应返回 200 而非 401/403
+  - 子会话: FAIL（默认 Spring Security 401）
+
+- [ ] **Step 4.2 实现 SecurityConfig**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 提交**
+  - `git commit -m "feat(config): permitAll security skeleton REQ-MOD-001"`
+
+---
+
+### Task 5: ModuleEntity + ModuleMapper（Mapper 集成测试落库）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java`
+- Create: `backend/src/main/resources/mapper/mod/ModuleMapper.xml`（仅头部 `<mapper namespace="...ModuleMapper"/>`，预留扩展）
+- Test: `backend/src/test/java/com/xly/erp/module/mod/mapper/ModuleMapperIT.java`
+
+**API shape:**
+- `@TableName("tModule")` ；字段名严格匹配 docs/03（保留匈牙利前缀，使用 `@TableField` 显式映射），主键 `iIncrement` 用 `@TableId(type = IdType.AUTO)`
+- 列 ↔ Java 属性命名采用**保留前缀**（如 `iIncrement` Java 字段名也叫 `iIncrement`，方便对照 schema），与 docs/04 § 1.2 命名约定中的"小驼峰"略有出入——本约束**优先**：DB schema SSoT 是 docs/03，Java 字段直接复用列名以避免双向映射歧义。Lombok `@Data`。
+- `ModuleMapper extends BaseMapper<ModuleEntity>`，本 REQ 仅用 `insert` + `selectById` + `selectCount`(条件)；不写自定义 SQL
+
+- [ ] **Step 5.1 写失败测试**
+  - 测试名: `ModuleMapperIT#insertAndSelectById_persistsAllFields`、`ModuleMapperIT#selectCountByProcedureName_returnsExisting`
+  - 测试方式: `@SpringBootTest @ActiveProfiles("test")` + `@Transactional`（自动回滚），DI `ModuleMapper`，构造 entity 调 `insert`，再 `selectById` 断言全部字段；用 `selectCount(new LambdaQueryWrapper<ModuleEntity>().eq(ModuleEntity::getSProcedureName, ...))` 验证唯一查询
+  - 子会话: FAIL
+
+- [ ] **Step 5.2 实现 Entity + Mapper**
+  - 子会话: PASS（DDL 已存在，直接 insert）
+
+- [ ] **Step 5.3 提交**
+  - `git commit -m "feat(mod): module entity and mapper REQ-MOD-001"`
+
+---
+
+### Task 6: DTO + VO
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleVO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/dto/ModuleCreateDTOValidationTest.java`
+
+**API shape:**
+
+`ModuleCreateDTO` 字段（带 Bean Validation）：
+- `@NotBlank @Pattern(regexp="^(手机端|前端业务|系统配置|接口)$") String sDisplayType`
+- `@NotBlank @Size(max=100) String sProcedureName`
+- `@NotBlank @Size(max=50) String sModuleType`
+- `@NotBlank @Size(max=50) String sManageDeptEn`
+- `Boolean bShowPermission`（可空，service 层 default false）
+- `@NotBlank @Size(max=100) String sModuleNameZh`
+- `Integer iParentId`（可空）
+- `@Min(0) Integer iSortOrder`（可空，default 0）
+
+`ModuleVO` 字段（11 个，见 spec § 输出）：`iIncrement`, `sDisplayType`, `sProcedureName`, `sModuleType`, `sManageDeptEn`, `bShowPermission`, `sModuleNameZh`, `iParentId`, `iSortOrder`, `tCreateDate`, `bDeleted`。
+
+> Entity → VO 的转换写在 `ModuleVO` 的静态工厂 `from(ModuleEntity)` 里，不引入 MapStruct 单独 mapper 类（YAGNI；REQ 多了再抽）。
+
+- [ ] **Step 6.1 写失败测试**
+  - 测试名: `ModuleCreateDTOValidationTest#blankRequiredFields_yieldsViolations`、`ModuleCreateDTOValidationTest#invalidDisplayTypeEnum_yieldsViolation`、`ModuleCreateDTOValidationTest#allValidFields_yieldsNoViolations`
+  - 测试方式: `Validation.buildDefaultValidatorFactory().getValidator()` + 断言 violation 集合
+  - 子会话: FAIL
+
+- [ ] **Step 6.2 实现 DTO + VO**
+  - 子会话: PASS
+
+- [ ] **Step 6.3 提交**
+  - `git commit -m "feat(mod): module create DTO and VO REQ-MOD-001"`
+
+---
+
+### Task 7: ModuleService.create（核心业务）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`（Mockito 单元测试，mock ModuleMapper）
+
+**API shape:**
+- `interface ModuleService { ModuleVO create(ModuleCreateDTO dto); }`
+- `@Service @RequiredArgsConstructor class ModuleServiceImpl implements ModuleService`，字段 `private final ModuleMapper moduleMapper;`
+- `create` 方法步骤（写在 plan 锁定，不让 TDD 自由发挥逻辑顺序）：
+  1. 若 `dto.iParentId != null`：`moduleMapper.selectById(iParentId)`，结果为 `null` 或 `bDeleted == true` → 抛 `BizException(MOD_PARENT_NOT_FOUND)`
+  2. 唯一性预检：`moduleMapper.selectCount(LambdaQueryWrapper.eq(ModuleEntity::getSProcedureName, dto.sProcedureName).eq(ModuleEntity::getBDeleted, 0))` > 0 → 抛 `BizException(MOD_PROC_NAME_DUP)`
+  3. 构造 `ModuleEntity`：复制 dto 字段；`bShowPermission` null → `false`；`iSortOrder` null → `0`；`tCreateDate = LocalDateTime.now()`；`bDeleted = 0`；`sBrandsId/sSubsidiaryId/sCreatedBy/sId/tDeletedDate/sDeletedBy = null`
+  4. `moduleMapper.insert(entity)`；MyBatis-Plus 回写 `iIncrement` 到 entity
+  5. 捕获 `DuplicateKeyException`（并发下 uk_procedure_name 兜底）→ 抛 `BizException(MOD_PROC_NAME_DUP)`
+  6. `return ModuleVO.from(entity)`
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+- [ ] **Step 7.1 写失败测试（6 个）**
+  - `ModuleServiceImplTest#create_rootModule_returnsVOWithGeneratedId`
+  - `ModuleServiceImplTest#create_childModule_validatesParentExists`
+  - `ModuleServiceImplTest#create_parentNotFound_throwsBizException40411`
+  - `ModuleServiceImplTest#create_parentSoftDeleted_throwsBizException40411`
+  - `ModuleServiceImplTest#create_duplicateProcedureName_preCheck_throwsBizException40911`
+  - `ModuleServiceImplTest#create_duplicateProcedureName_concurrentInsert_throwsBizException40911`（mock `moduleMapper.insert` 抛 `DuplicateKeyException`）
+  - 测试方式: `@ExtendWith(MockitoExtension.class)` + `@InjectMocks ModuleServiceImpl` + `@Mock ModuleMapper`
+  - 子会话: FAIL
+
+- [ ] **Step 7.2 实现 ModuleService + ModuleServiceImpl**
+  - 子会话: PASS
+
+- [ ] **Step 7.3 提交**
+  - `git commit -m "feat(mod): create module service REQ-MOD-001"`
+
+---
+
+### Task 8: ModuleController + 端到端集成测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`
+
+**API shape:**
+- `@RestController @RequestMapping("/api/modules")`
+- `@PostMapping public ApiResponse<ModuleVO> create(@Valid @RequestBody ModuleCreateDTO dto)` → `ApiResponse.ok(moduleService.create(dto))`
+- 类上保留注释：`// REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:CREATE')")`
+
+- [ ] **Step 8.1 写失败测试（6 个验收用例）**
+  - `ModuleControllerIT#post_validRootModule_returns200WithVO`
+  - `ModuleControllerIT#post_validChildModule_returns200`
+  - `ModuleControllerIT#post_duplicateProcedureName_returns200WithCode40911`
+  - `ModuleControllerIT#post_parentNotFound_returns200WithCode40411`
+  - `ModuleControllerIT#post_missingRequiredField_returns200WithCode40010`
+  - `ModuleControllerIT#post_invalidDisplayTypeEnum_returns200WithCode40010`
+  - 测试方式: `@SpringBootTest @AutoConfigureMockMvc @ActiveProfiles("test") @Transactional`（自动回滚），用 `MockMvc` 发 POST，断言 `$.code` / `$.data.iIncrement` / `$.data.sProcedureName` 等
+  - 子会话: FAIL
+
+- [ ] **Step 8.2 实现 ModuleController**
+  - 子会话: PASS
+
+- [ ] **Step 8.3 全量 backend 测试**
+  - `cd backend && mvn -B test -DSPRING_PROFILES_ACTIVE=test`
+  - 期望全绿（Task 1-8 累计 ~25 个测试方法）
+
+- [ ] **Step 8.4 提交**
+  - `git commit -m "feat(mod): POST /api/modules controller REQ-MOD-001"`
+
+---
+
+## 提交计划
+
+- `chore(mod): bootstrap spring boot skeleton REQ-MOD-001`（覆盖 Task 1）
+- `feat(common): unified ApiResponse and ErrorCode REQ-MOD-001`（覆盖 Task 2）
+- `feat(common): biz exception and global handler REQ-MOD-001`（覆盖 Task 3）
+- `feat(config): permitAll security skeleton REQ-MOD-001`（覆盖 Task 4）
+- `feat(mod): module entity and mapper REQ-MOD-001`（覆盖 Task 5）
+- `feat(mod): module create DTO and VO REQ-MOD-001`（覆盖 Task 6）
+- `feat(mod): create module service REQ-MOD-001`（覆盖 Task 7）
+- `feat(mod): POST /api/modules controller REQ-MOD-001`（覆盖 Task 8）
+---
+req_id: REQ-MOD-002
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-002.md
+---
+
+# REQ-MOD-002 模块修改 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `PUT /api/modules/{id}` 接口：复用 REQ-MOD-001 已落地的 entity / mapper / common / config 体系，仅追加 ModuleUpdateDTO + Service.update + Controller 方法 + 错误码常量。
+
+**Architecture:** Service 层先校验目标存在性（按 PK + bDeleted=0 查），再校验 iParentId 自引用 / 父不存在 / 父是后代环路（沿父链 walk up，深度上限 5），最后 `updateById` 落库。环路检查走"自下而上"路径，O(depth) 复杂度。
+
+**Tech Stack:** 沿用 REQ-MOD-001（Spring Boot 3.2.5 + MyBatis-Plus 3.5.7 + JUnit 5 + Mockito）。
+
+---
+
+## Schema 改动
+
+无（`tModule` schema 已由 V1 提供，本 REQ 不加列）。
+
+## 文件变更清单
+
+- 修改: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 追加 `MOD_NOT_FOUND(40421, "模块不存在或已删除")` 和 `MOD_PARENT_LOOP(40921, "iParentId 不能等于自身或后代")`
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleUpdateDTO.java` — PUT 入参（无 sProcedureName）
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 追加 `update(Integer id, ModuleUpdateDTO dto): ModuleVO`
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 实现 `update` 方法（含父校验、环路检查、字段合并）
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 追加 `@PutMapping("/{id}") ModuleVO update(...)`
+- 创建: `backend/src/test/java/com/xly/erp/module/mod/dto/ModuleUpdateDTOValidationTest.java` — DTO Bean Validation 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 追加 `update_*` 系列单元测试（mock ModuleMapper）
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 追加 `put_*` 系列集成测试
+
+## 任务步骤
+
+### Task 1: 追加错误码常量
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Test: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`（追加断言）
+
+**API shape:**
+- `MOD_NOT_FOUND(40421, "模块不存在或已删除")`
+- `MOD_PARENT_LOOP(40921, "iParentId 不能等于自身或后代")`
+
+- [ ] **Step 1.1 写失败断言**
+  - 在 `ApiResponseTest#errorCode_constantsMatchDocs05Spec` 末尾追加：
+    - `assertThat(ErrorCode.MOD_NOT_FOUND.getCode()).isEqualTo(40421);`
+    - `assertThat(ErrorCode.MOD_PARENT_LOOP.getCode()).isEqualTo(40921);`
+  - 子会话确认 FAIL（编译错：枚举常量不存在）
+
+- [ ] **Step 1.2 追加枚举常量**
+
+- [ ] **Step 1.3 子会话确认 ApiResponseTest 全绿（5 个测试，第 5 个含新断言）**
+
+- [ ] **Step 1.4 提交**
+  - `git commit -m "feat(common): error codes for module update REQ-MOD-002"`
+
+---
+
+### Task 2: ModuleUpdateDTO + 校验单测
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleUpdateDTO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/dto/ModuleUpdateDTOValidationTest.java`
+
+**API shape:**
+- 字段（与 REQ-MOD-001 的 `ModuleCreateDTO` 相比剥除 `sProcedureName`；其余 7 个字段、注解、长度规则**完全一致**）：
+  - `@NotBlank @Pattern(...) String sDisplayType`
+  - `@NotBlank @Size(max=50) String sModuleType`
+  - `@NotBlank @Size(max=50) String sManageDeptEn`
+  - `Boolean bShowPermission`（可空）
+  - `@NotBlank @Size(max=100) String sModuleNameZh`
+  - `Integer iParentId`（可空）
+  - `@Min(0) Integer iSortOrder`（可空）
+
+- [ ] **Step 2.1 写失败测试（4 个）**
+  - `ModuleUpdateDTOValidationTest#allValidFields_yieldsNoViolations`
+  - `ModuleUpdateDTOValidationTest#blankRequiredFields_yieldsViolations`（5 个 @NotBlank）
+  - `ModuleUpdateDTOValidationTest#invalidDisplayTypeEnum_yieldsViolation`
+  - `ModuleUpdateDTOValidationTest#negativeSortOrder_yieldsViolation`
+  - 子会话: FAIL（DTO 不存在）
+
+- [ ] **Step 2.2 实现 ModuleUpdateDTO**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(mod): module update DTO REQ-MOD-002"`
+
+---
+
+### Task 3: ModuleService.update — 业务逻辑（mock 单元测试）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`（追加方法签名）
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`（实现 + 私有 helper）
+- Test: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`（追加 8 个测试）
+
+**API shape:**
+- `interface ModuleService` 追加：`ModuleVO update(Integer id, ModuleUpdateDTO dto)`
+- 实现步骤（写在 plan 锁定）：
+  1. `target = moduleMapper.selectById(id)`；`target == null || target.bDeleted == true` → 抛 `BizException(MOD_NOT_FOUND)`
+  2. iParentId 校验（仅当 `dto.iParentId != null`）：
+     - 等于 `id` → `BizException(MOD_PARENT_LOOP)`
+     - `parent = moduleMapper.selectById(dto.iParentId)`；`parent == null || parent.bDeleted` → `BizException(MOD_PARENT_NOT_FOUND)`
+     - **环路检查**（沿父链 walk up，从 `dto.iParentId` 出发，最多 5 层）：
+       ```
+       cur = parent; depth = 1
+       while cur.iParentId != null && depth <= 5:
+           if cur.iParentId == id: throw MOD_PARENT_LOOP
+           cur = moduleMapper.selectById(cur.iParentId)
+           if cur == null or cur.bDeleted: break  // 链断在已删除节点，视为非环
+           depth += 1
+       ```
+       depth 超 5 仍未结束 → 视为深度违规，但 docs/03 业务注记说"深度上限 5"是预期不变量；本期不强制拦截更深，仅环路检查。
+  3. 字段合并到 `target`：
+     - 必填字段（5 个 @NotBlank + sDisplayType）：直接覆盖（dto 为 null 不可能，validation 已挡）
+     - `bShowPermission`：dto 非 null 覆盖；null 保留 `target.bShowPermission`
+     - `iParentId`：dto 中存在该 key 即覆盖（含 null 设根）。**实现细节**：DTO 用 Integer，区分"未传"和"显式传 null"在 Spring MVC 反序列化层不区分（都是 Integer null）。本 REQ 取语义"传 null = 设根"，"key 缺失 = 设根"等价。
+     - `iSortOrder`：dto 非 null 覆盖；null 保留
+     - `sProcedureName` / `iIncrement` / `tCreateDate` / `sId` / `sBrandsId` / `sSubsidiaryId` / `sCreatedBy` / `bDeleted` / `tDeletedDate` / `sDeletedBy`：**完全不动**（沿用 target 上的原值）
+  4. `moduleMapper.updateById(target)`
+  5. `return ModuleVO.from(target)`
+
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+- [ ] **Step 3.1 写失败测试（8 个）**
+  - `update_targetNotFound_throws40421`：`selectById(id)` → null
+  - `update_targetSoftDeleted_throws40421`：`selectById(id).bDeleted=true`
+  - `update_parentSelfReference_throws40921`：`dto.iParentId == id`
+  - `update_parentNotFound_throws40411`：`selectById(parentId)` → null
+  - `update_parentIsDescendant_throws40921`：构造 grandparent(id)→parent→child 链，dto.iParentId=child.id
+  - `update_full_returnsVOWithUpdatedFields`：mock target 与 update 路径，断言传给 `updateById` 的 entity：
+    - 已修改字段：sDisplayType / sModuleType / sManageDeptEn / sModuleNameZh / iParentId / iSortOrder / bShowPermission
+    - 保持原值：sProcedureName / iIncrement / tCreateDate / sCreatedBy / bDeleted
+  - `update_partialNullFields_keepsOriginalValues`：dto 中 bShowPermission=null + iSortOrder=null，断言落库 entity 的对应字段保留 target 原值
+  - `update_clearParent_setsParentToNull`：dto.iParentId=null，target.iParentId 原本是 7；断言 entity.iParentId == null
+  - 测试方式：`@ExtendWith(MockitoExtension.class)` + `ArgumentCaptor<ModuleEntity>` 捕获 `updateById` 实参
+  - 子会话: FAIL（方法不存在）
+
+- [ ] **Step 3.2 实现 ModuleService 接口签名 + ModuleServiceImpl.update**
+
+- [ ] **Step 3.3 子会话确认全部 mock 单测通过**
+  - 全量 `mvn -B test -Dtest=ModuleServiceImplTest` 应绿（含 REQ-MOD-001 的 6 个 + 新增 8 个 = 14 个）
+
+- [ ] **Step 3.4 提交**
+  - `git commit -m "feat(mod): update module service REQ-MOD-002"`
+
+---
+
+### Task 4: ModuleController PUT 端点 + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`（追加 8 个集成用例）
+
+**API shape:**
+- 类上保留 `@RequestMapping("/api/modules")`
+- 新方法：
+  ```
+  @PutMapping("/{id}")
+  public ApiResponse<ModuleVO> update(@PathVariable Integer id, @Valid @RequestBody ModuleUpdateDTO dto)
+  ```
+- 注释：`// REQ-MOD-002 模块修改 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:UPDATE')")`
+
+- [ ] **Step 4.1 写失败测试（8 个）**
+  - `put_validUpdate_returns200`：先用 ModuleMapper 直接 insert 一条，再 PUT 改若干字段，断言响应 + DB 字段
+  - `put_setParentToNull_clearsParent`：先建 parent + child(iParentId=parent.id)，PUT child 把 iParentId=null，断言 DB 中 child.iParentId IS NULL
+  - `put_targetNotFound_returns40421`：`PUT /api/modules/999999`
+  - `put_parentNotFound_returns40411`：`iParentId=999999`
+  - `put_parentSelfRef_returns40921`：`PUT /api/modules/{id}` body `iParentId={id}`
+  - `put_parentIsDescendant_returns40921`：建 grandparent→parent→child 三层；PUT grandparent 把 iParentId=child.id
+  - `put_missingRequired_returns40010`：缺 sModuleNameZh
+  - `put_ignoresProcedureNameField_doesNotChange`：body 含 `"sProcedureName":"hijack"`，断言 DB 中 sProcedureName 仍为原值
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + `@Autowired ModuleMapper` 直接预置数据
+  - 子会话: FAIL（端点不存在）
+
+- [ ] **Step 4.2 实现 PUT 端点**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 跑全量 backend 测试**
+  - `cd backend && mvn -B test`
+  - 期望累计 22 + 4(DTO valid) + 8(service update) + 8(controller put) = 42 个，全绿
+
+- [ ] **Step 4.4 提交**
+  - `git commit -m "feat(mod): PUT /api/modules/{id} controller REQ-MOD-002"`
+
+---
+
+## 提交计划
+
+- `feat(common): error codes for module update REQ-MOD-002`（覆盖 Task 1）
+- `feat(mod): module update DTO REQ-MOD-002`（覆盖 Task 2）
+- `feat(mod): update module service REQ-MOD-002`（覆盖 Task 3）
+- `feat(mod): PUT /api/modules/{id} controller REQ-MOD-002`（覆盖 Task 4）
+---
+req_id: REQ-MOD-003
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-003.md
+---
+
+# REQ-MOD-003 模块删除 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `DELETE /api/modules/{id}`：在校验子模块未删除引用的前提下，对目标做软删除（写 bDeleted/tDeletedDate/sDeletedBy）。
+
+**Architecture:** 复用 REQ-MOD-001/002 已建立的体系。Service 先 selectById 校验目标存在 + 未删除（40421），再 selectCount 子模块未删除引用（40912），最后用 `mapper.update(entity, wrapper)` 加 `bDeleted = 0` 条件做并发安全的软删除（影响 0 行视为并发删除 → 40421）。返回精简 VO。
+
+**Tech Stack:** 沿用 REQ-MOD-001/002（Spring Boot 3.2.5 + MyBatis-Plus 3.5.7 + JUnit 5 + Mockito）。
+
+---
+
+## Schema 改动
+
+无（软删除字段 `bDeleted` / `tDeletedDate` / `sDeletedBy` 在 V1 已建）。
+
+## 文件变更清单
+
+- 修改: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 追加 `MOD_HAS_REFERENCES(40912, "存在子模块或外部业务引用，禁止删除")`
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleDeleteResultVO.java` — 精简 VO（iIncrement + bDeleted）
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 追加 `delete(Integer id): ModuleDeleteResultVO`
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 实现 delete
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 追加 `@DeleteMapping("/{id}")`
+- 修改: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 追加 1 个错误码断言
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 追加 6 个 delete 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 追加 6 个 DELETE 集成测试
+
+## 任务步骤
+
+### Task 1: 错误码 + 精简 VO
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleDeleteResultVO.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+
+**API shape:**
+- `MOD_HAS_REFERENCES(40912, "存在子模块或外部业务引用，禁止删除")`
+- `ModuleDeleteResultVO` 字段：`Integer iIncrement` + `Boolean bDeleted`（带 `@Data` + 静态工厂 `of(Integer id, Boolean deleted)`）
+
+- [ ] **Step 1.1 写失败断言**
+  - 在 `ApiResponseTest#errorCode_constantsMatchDocs05Spec` 末尾追加：
+    `assertThat(ErrorCode.MOD_HAS_REFERENCES.getCode()).isEqualTo(40912);`
+  - 子会话 FAIL（枚举常量不存在）
+
+- [ ] **Step 1.2 追加枚举常量 + 创建 VO**
+
+- [ ] **Step 1.3 子会话验证 ApiResponseTest 全绿**
+
+- [ ] **Step 1.4 提交**
+  - `git commit -m "feat(common): error code MOD_HAS_REFERENCES + delete VO REQ-MOD-003"`
+
+---
+
+### Task 2: ModuleService.delete — 业务逻辑（mock 单元测试）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`（追加方法签名）
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`（追加 6 个测试）
+
+**API shape:**
+- `interface ModuleService` 追加：`ModuleDeleteResultVO delete(Integer id)`
+- 实现步骤（写在 plan 锁定）：
+  1. `target = moduleMapper.selectById(id)`；`target == null || target.bDeleted == true` → `BizException(MOD_NOT_FOUND)`（40421）
+  2. 子模块计数：`childCount = moduleMapper.selectCount(LambdaQueryWrapper.eq(iParentId, id).eq(bDeleted, false))`
+     - `childCount > 0` → `BizException(MOD_HAS_REFERENCES)`（40912）
+  3. 构造**只含软删除三件套 + 主键**的更新 entity（避免触碰其他字段）：
+     ```
+     ModuleEntity patch = new ModuleEntity();
+     patch.setIIncrement(id);
+     patch.setBDeleted(true);
+     patch.setTDeletedDate(LocalDateTime.now());
+     patch.setSDeletedBy(null); // FieldStrategy 默认 NOT_NULL，会被 MP 跳过；这里靠 IGNORED 或显式 update wrapper 写入。
+     ```
+     **方式选择**：用 `moduleMapper.update(patch, new LambdaUpdateWrapper<ModuleEntity>().eq(iIncrement, id).eq(bDeleted, false))`，确保只更新仍未删除的目标，且 `update` 影响行数为并发兜底信号。
+  4. `int affected = moduleMapper.update(...)`；`affected == 0` → `BizException(MOD_NOT_FOUND)`（视为目标在校验后被并发删除）
+  5. `return ModuleDeleteResultVO.of(id, true)`
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+- [ ] **Step 2.1 写失败测试（6 个）**
+  - `delete_targetNotFound_throws40421`：`selectById` → null
+  - `delete_targetAlreadyDeleted_throws40421`：target.bDeleted=true
+  - `delete_hasUndeletedChildren_throws40912`：selectCount > 0
+  - `delete_leafModule_returnsResult`：selectCount=0、update 返回 1，断言 VO + 断言传给 update 的 entity 字段（bDeleted=true、tDeletedDate 非 null、iIncrement 正确）
+  - `delete_softDeletedChildren_doesNotBlock`：selectCount=0（已删子不计入），update 返回 1，断言成功
+  - `delete_concurrentRace_throws40421`：selectById 返回未删除目标，selectCount=0，update 返回 0 → 抛 40421
+  - 测试方式：`@ExtendWith(MockitoExtension.class)` + `ArgumentCaptor<ModuleEntity>` 捕获 `update` 实参；用 `any(Wrapper.class)` 占位 wrapper
+  - 子会话: FAIL（方法不存在）
+
+- [ ] **Step 2.2 实现 delete**
+  - 注意：`moduleMapper.update(entity, wrapper)` 在 BaseMapper 里有重载，可能与 `update(entity, T)` 冲突。预期签名 `int update(@Param("et") T entity, @Param("ew") Wrapper<T> updateWrapper)`，调用为 `moduleMapper.update(patch, wrapper)`。Mockito stub 时用 `when(moduleMapper.update(any(ModuleEntity.class), any(Wrapper.class)))` 应能消歧；若仍 ambiguous，按 REQ-MOD-001 经验改用显式 cast `(ModuleEntity) any()` + `(Wrapper) any()`。
+
+- [ ] **Step 2.3 子会话确认 ModuleServiceImplTest 全部绿**
+  - 累计：6 (create) + 8 (update) + 6 (delete) = 20
+
+- [ ] **Step 2.4 提交**
+  - `git commit -m "feat(mod): delete module service REQ-MOD-003"`
+
+---
+
+### Task 3: ModuleController DELETE 端点 + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`（追加 6 个集成用例）
+
+**API shape:**
+- 新方法：
+  ```
+  @DeleteMapping("/{id}")
+  public ApiResponse<ModuleDeleteResultVO> delete(@PathVariable Integer id)
+  ```
+- Javadoc：`REQ-MOD-003 模块删除 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:DELETE')")`
+
+- [ ] **Step 3.1 写失败测试（6 个）**
+  - `delete_validLeaf_returns200WithBDeletedTrue`：mapper.insert 一条 → DELETE → 断言 200 + data.bDeleted=true + selectById 验证 DB 中 bDeleted=true / tDeletedDate 非 null
+  - `delete_targetNotFound_returns40421`：DELETE /api/modules/999999
+  - `delete_targetAlreadyDeleted_returns40421`：mapper.insert 一条并立刻把 bDeleted 置 true，DELETE 返回 40421
+  - `delete_hasUndeletedChildren_returns40912`：parent + child（bDeleted=0），DELETE parent → 40912；selectById parent 验证 bDeleted 仍 false
+  - `delete_softDeletedChildren_doesNotBlock_returns200`：先 DELETE child（应成功），再 DELETE parent → 200
+  - `delete_responseVOContainsOnlyIIncrementAndBDeleted`：断言 `$.data` 路径只有 iIncrement + bDeleted 两个字段（用 jsonPath `$.data.sProcedureName` 不存在）
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + `@Autowired ModuleMapper` 直接预置数据
+  - 子会话: FAIL（端点不存在）
+
+- [ ] **Step 3.2 实现 DELETE 端点**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 跑全量 backend 测试**
+  - `cd backend && mvn -B test`
+  - 期望累计 34 + 1(error code 断言扩展) + 6(service delete unit) + 6(controller delete IT) = 47 个，全绿
+
+- [ ] **Step 3.4 提交**
+  - `git commit -m "feat(mod): DELETE /api/modules/{id} controller REQ-MOD-003"`
+
+---
+
+## 提交计划
+
+- `feat(common): error code MOD_HAS_REFERENCES + delete VO REQ-MOD-003`（覆盖 Task 1）
+- `feat(mod): delete module service REQ-MOD-003`（覆盖 Task 2）
+- `feat(mod): DELETE /api/modules/{id} controller REQ-MOD-003`（覆盖 Task 3）
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-004.md
+---
+
+# REQ-MOD-004 模块查询 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `GET /api/modules?keyword=...`：返回未软删除模块的树形结构，可选按 `sModuleNameZh` 模糊匹配并保留命中节点的祖先链。
+
+**Architecture:** 一次性 selectList 拉所有未删除模块到内存，按 keyword 过滤命中集合，沿父链向上收集祖先合并到结果集，最后在内存按 iParentId 组装树。同级按 iSortOrder ASC + iIncrement ASC 排序。叶子 `children=[]`。
+
+**Tech Stack:** 沿用 REQ-MOD-001~003。
+
+---
+
+## Schema 改动
+
+无。
+
+## 文件变更清单
+
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleTreeNodeVO.java` — 树形节点 VO（7 字段 + children 列表）
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java` — 查询参数 DTO（keyword）
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 追加 `tree(ModuleQueryDTO query): List<ModuleTreeNodeVO>`
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 实现 tree
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 追加 `@GetMapping`
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 追加 6 个 tree 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 追加 7 个 GET 集成测试
+
+## 任务步骤
+
+### Task 1: VO + DTO
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleTreeNodeVO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java`
+
+**API shape:**
+- `ModuleTreeNodeVO`：7 字段 + `List<ModuleTreeNodeVO> children`，Lombok `@Data`，含静态工厂 `from(ModuleEntity e)`（创建带空 children 列表的节点）。
+- `ModuleQueryDTO`：单字段 `@Size(max=50) String keyword`（可空）。Bean Validation 由 controller 触发。
+
+- [ ] **Step 1.1 创建 VO + DTO（无独立单测；Bean Validation 在 IT 层覆盖）**
+
+- [ ] **Step 1.2 提交**
+  - `git commit -m "feat(mod): module tree VO + query DTO REQ-MOD-004"`
+
+---
+
+### Task 2: ModuleService.tree — 树构建逻辑（mock 单元测试）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`
+
+**API shape:**
+- `interface ModuleService` 追加：`List<ModuleTreeNodeVO> tree(ModuleQueryDTO query)`
+- 实现步骤：
+  1. `all = moduleMapper.selectList(LambdaQueryWrapper.eq(BDeleted, false))`
+  2. 若 `query.keyword == null || keyword.isEmpty()` → 跳到步骤 5（用全量构树）
+  3. 否则在 `all` 内存里筛选 `hits = all.filter(e -> e.sModuleNameZh.contains(keyword))`
+  4. 对每个 hit 沿 `iParentId` 链向上收集祖先（用 `byId = all.stream().toMap(IIncrement)` 索引）；合并到 `survivors = hits ∪ ancestors`
+  5. 按 iIncrement 索引 `survivors`，按 iParentId 分组子节点列表，同级按 (iSortOrder, iIncrement) ASC 排序
+  6. 取 `iParentId == null || iParentId not in survivors` 的节点作为根（这样过滤后一些祖先链断裂的节点也会被提到根，避免孤立）；递归挂 children
+  7. 返回根节点列表
+- 标 `@Transactional(readOnly = true)`
+
+**关键不变量**（写入 plan 锁定）：
+- 叶子节点 `children = new ArrayList<>()`，**不为 null**
+- 排序键稳定：`Comparator.comparingInt(ModuleTreeNodeVO::getISortOrder).thenComparingInt(ModuleTreeNodeVO::getIIncrement)`
+- 祖先链深度上限 5（与 docs/03 § tModule 注记一致）；超 5 仍向上视为业务异常并记一行 `log.warn`，不抛错（不影响 200 返回）
+
+- [ ] **Step 2.1 写失败测试（6 个）**
+  - `tree_emptyDb_returnsEmptyList`：mapper.selectList 返回空 → service 返回 `List.of()`
+  - `tree_singleRoot_returnsOneNodeWithEmptyChildren`：1 个 root，断言返回 list 长度 1，children 是 `[]`
+  - `tree_multiLevel_buildsNestedStructureSortedByISortOrder`：root(sort=2) + root(sort=1) + child of root1，断言返回顺序 [sort=1, sort=2]，root1.children 包含 child
+  - `tree_keywordHit_includesAncestorChain`：grandparent → parent → child（sModuleNameZh 各不同），keyword 匹配 child；断言返回 grandparent → parent → child 三层
+  - `tree_keywordNoMatch_returnsEmptyList`
+  - `tree_softDeletedExcluded`（验证 mapper 调用时 wrapper 含 `eq(bDeleted, false)`；ArgumentCaptor<Wrapper>）
+  - 测试方式：`@ExtendWith(MockitoExtension.class)`，构造 `List<ModuleEntity>` 喂 mock 返回值
+  - 子会话: FAIL（方法不存在）
+
+- [ ] **Step 2.2 实现 service.tree**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(mod): query module tree service REQ-MOD-004"`
+
+---
+
+### Task 3: ModuleController GET 端点 + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`
+
+**API shape:**
+- 新方法：
+  ```
+  @GetMapping
+  public ApiResponse<List<ModuleTreeNodeVO>> tree(@Valid ModuleQueryDTO query)
+  ```
+- Javadoc：`REQ-MOD-004 模块查询 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:READ')")`
+- `@Valid` 触发 Bean Validation；keyword 长度超限 → MethodArgumentNotValidException → GlobalExceptionHandler → 40010
+
+> **注意**：query 参数对象用 `@Valid ModuleQueryDTO` 时，Spring MVC 会把 `keyword` query 参数绑定到 DTO 字段（无需 @ModelAttribute，bean 类型默认走 query string）。
+
+- [ ] **Step 3.1 写失败测试（7 个）**
+  - `get_emptyKeyword_returnsAllUndeletedAsTree`：先 mapper.insert 几条（含 root + child + soft-deleted），GET 不带 keyword；断言 200 + data 长度等于未删 root 数；递归断言子树。
+  - `get_keyword_filtersByModuleNameZhWithAncestors`：插入 grandparent("系统配置") → parent("用户管理") → child("登录")；GET `?keyword=登录`；断言返回三层链。
+  - `get_keywordNoMatch_returnsEmptyArray`：GET `?keyword=不存在`，断言 `data=[]`，code=200。
+  - `get_keywordTooLong_returns40010`：keyword 51 字符。
+  - `get_softDeletedNotInResult`：插入一条并立即 update bDeleted=1，GET 全量，断言不在结果。
+  - `get_responseExcludesInternalFields`：断言 `$.data[0].sProcedureName` doesNotExist；同时验证 `sModuleType` / `bShowPermission` / `tCreateDate` / `bDeleted` 不出现。
+  - `get_leafNodeChildrenIsEmptyArrayNotNull`：断言叶子 `$.data[*].children` is array 且 length=0（非 null）。
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + `@Autowired ModuleMapper`
+  - 子会话: FAIL（端点不存在）
+
+- [ ] **Step 3.2 实现 GET 端点**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 跑全量 backend 测试**
+  - 期望累计 47 + 6(service tree) + 7(controller GET) = 60 个，全绿（mvn 报数会因共享 context 而合并）
+
+- [ ] **Step 3.4 提交**
+  - `git commit -m "feat(mod): GET /api/modules controller REQ-MOD-004"`
+
+---
+
+## 提交计划
+
+- `feat(mod): module tree VO + query DTO REQ-MOD-004`（Task 1）
+- `feat(mod): query module tree service REQ-MOD-004`（Task 2）
+- `feat(mod): GET /api/modules controller REQ-MOD-004`（Task 3）
+---
+req_id: REQ-USR-001
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-USR-001.md
+---
+
+# REQ-USR-001 用户新增 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `POST /api/users`：录入用户基本信息 + 可选员工关联 + 权限组关联，密码 `666666` 经 BCrypt 哈希落库；返回 UserVO（不含哈希）。
+
+**Architecture:** 复用 module_mod 已建立的 common / config / 异常 / Jackson / Security 体系。新建 4 个 entity + 4 个 mapper（tUser / tStaff / tPermissionCategory / tUserPermission），UserService 协调跨表写入并用 `@Transactional` 包裹整体一致性。BCryptPasswordEncoder 注册为 Spring bean 供 REQ-USR-004 复用。
+
+**Tech Stack:** Spring Boot 3.2.5 + Spring Security 6（BCryptPasswordEncoder）+ MyBatis-Plus 3.5.7 + JUnit 5 + Mockito。
+
+---
+
+## Schema 改动
+
+无（V1 已建 5 张表 + FK + UNIQUE 索引）。
+
+## 文件变更清单
+
+- 修改: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 追加 3 个常量
+- 创建: `backend/src/main/java/com/xly/erp/config/PasswordConfig.java` — BCryptPasswordEncoder bean
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/entity/UserEntity.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/entity/StaffEntity.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/entity/PermissionCategoryEntity.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/entity/UserPermissionEntity.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/mapper/{UserMapper,StaffMapper,PermissionCategoryMapper,UserPermissionMapper}.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/dto/UserCreateDTO.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/vo/UserVO.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`
+- 修改: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 追加 3 个新错误码断言
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/dto/UserCreateDTOValidationTest.java`
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/mapper/UsrMappersIT.java` — 4 张表 insert/select smoke test
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java` — 9 个 mock 单测
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java` — 7 个 MockMvc 集成测试
+
+---
+
+## 任务步骤
+
+### Task 1: 错误码 + PasswordConfig
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Create: `backend/src/main/java/com/xly/erp/config/PasswordConfig.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+
+**API shape:**
+- 新增 ErrorCode 常量（注意：与 MOD 段位共享但枚举名不同）：
+  - `STAFF_NOT_FOUND(40421, "职员不存在或已删除")`
+  - `PERM_CATEGORY_NOT_FOUND(40422, "权限分类不存在或已删除")`
+  - `USR_USER_NAME_OR_NO_DUP(40921, "用户名或用户号已存在")`
+
+  > 注：`MOD_NOT_FOUND(40421)` 与 `STAFF_NOT_FOUND(40421)` code 相同但枚举名不同——code 段位由 docs/05 全局错误码表定义，message 文案区分语义；此设计与 docs/04 § 1.3 错误码段位划分一致。
+- `PasswordConfig` 提供 `@Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }`
+
+- [ ] **Step 1.1 写失败断言**
+  - 在 `ApiResponseTest#errorCode_constantsMatchDocs05Spec` 末尾追加 3 行：
+    ```
+    assertThat(ErrorCode.STAFF_NOT_FOUND.getCode()).isEqualTo(40421);
+    assertThat(ErrorCode.PERM_CATEGORY_NOT_FOUND.getCode()).isEqualTo(40422);
+    assertThat(ErrorCode.USR_USER_NAME_OR_NO_DUP.getCode()).isEqualTo(40921);
+    ```
+  - 子会话: FAIL
+
+- [ ] **Step 1.2 实现 ErrorCode + PasswordConfig**
+  - 子会话: PASS（ApiResponseTest 5/5；上下文重启 PasswordConfig bean 注入由后续 IT 验证）
+
+- [ ] **Step 1.3 提交**
+  - `git commit -m "feat(common): error codes + PasswordConfig REQ-USR-001"`
+
+---
+
+### Task 2: 4 张表 entity + mapper + Mapper smoke IT
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/{UserEntity,StaffEntity,PermissionCategoryEntity,UserPermissionEntity}.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/{UserMapper,StaffMapper,PermissionCategoryMapper,UserPermissionMapper}.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/mapper/UsrMappersIT.java`
+
+**API shape**（每个 entity 严格按 docs/03 字段；`@TableField` 显式声明列名；保留匈牙利前缀；主键 `iIncrement` `IdType.AUTO`；与 `ModuleEntity` 同范式）：
+
+| Entity | 表 | 关键字段（不含 5 个标准列） |
+|---|---|---|
+| `UserEntity` | tUser | sUserNo / sUserName / iStaffId / sUserType / sLanguage / bCanModifyDocs / sPasswordHash / tLastLoginDate / sCreatedBy / bDeleted / tDeletedDate / sDeletedBy |
+| `StaffEntity` | tStaff | sStaffNo / sStaffName / sDepartment / sCreatedBy / bDeleted / tDeletedDate / sDeletedBy |
+| `PermissionCategoryEntity` | tPermissionCategory | sCategoryCode / sCategoryName / iParentId / iSortOrder / sCreatedBy / bDeleted / tDeletedDate / sDeletedBy |
+| `UserPermissionEntity` | tUserPermission | iUserId / iCategoryId / sCreatedBy（docs/03 修订版无 bSelected 列） |
+
+每个 mapper `extends BaseMapper<XxxEntity>`，无自定义 SQL。
+
+> **注意**：spec § Service 实现依赖 `tUser.iStaffId` 设置为 NULL 时不应被 IGNORED 策略影响（参考 REQ-MOD-002 经验）。本期 UserEntity 字段 **不**给 iStaffId 加 `FieldStrategy.IGNORED`——因为 user create 走 insert（默认 NOT_NULL 策略对 insert 没问题：null 字段被跳过，DB 列默认 NULL），不会触发 update path 上的副作用。如未来 REQ-USR-002 需要 update 中清空 iStaffId，再按 REQ-MOD-003 经验用 `LambdaUpdateWrapper.set(...)` 处理。
+
+- [ ] **Step 2.1 写失败 IT**
+  - `UsrMappersIT#allFourMappers_insertAndSelect_smoke`：用 4 个 mapper 各 insert 一条最小字段记录（构造 entity → insert → selectById 断言字段往返）
+  - `@SpringBootTest @ActiveProfiles("test") @Transactional @Rollback`
+  - 子会话: FAIL（entity / mapper 不存在）
+
+- [ ] **Step 2.2 实现 4 entity + 4 mapper**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(usr): user/staff/permission/userPermission entities + mappers REQ-USR-001"`
+
+---
+
+### Task 3: UserCreateDTO + UserVO + Validation
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UserCreateDTO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserVO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/dto/UserCreateDTOValidationTest.java`
+
+**API shape:**
+
+`UserCreateDTO`:
+- `@NotBlank @Size(max=50) String sUserNo`
+- `@NotBlank @Size(max=50) String sUserName`
+- `Integer iStaffId`（可空）
+- `@NotBlank @Pattern(regexp="^(普通用户|超级管理员)$") String sUserType`
+- `@NotBlank @Pattern(regexp="^(zh|en|zh-TW)$") String sLanguage`
+- `Boolean bCanModifyDocs`（可空，service 层 default false）
+- `List<Integer> permissionCategoryIds`（可空 / 空数组）
+
+`UserVO` 字段 10 个（spec § 输出列表；不含 sPasswordHash），含静态工厂 `from(UserEntity entity, List<Integer> permissionCategoryIds)`。
+
+- [ ] **Step 3.1 写失败测试（5 个）**
+  - `UserCreateDTOValidationTest#allValidFields_yieldsNoViolations`
+  - `UserCreateDTOValidationTest#blankRequiredFields_yieldsViolations`（4 个 @NotBlank）
+  - `UserCreateDTOValidationTest#invalidUserTypeEnum_yieldsViolation`
+  - `UserCreateDTOValidationTest#invalidLanguageEnum_yieldsViolation`
+  - `UserCreateDTOValidationTest#overSizedFields_yieldsViolations`
+  - 子会话: FAIL
+
+- [ ] **Step 3.2 实现 DTO + VO**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(usr): user create DTO and VO REQ-USR-001"`
+
+---
+
+### Task 4: UserService.create + Mockito 单元测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java`
+
+**API shape:**
+- `interface UserService { UserVO create(UserCreateDTO dto); }`
+- `@Service @RequiredArgsConstructor class UserServiceImpl`，依赖 `UserMapper` / `StaffMapper` / `PermissionCategoryMapper` / `UserPermissionMapper` / `PasswordEncoder`。
+- `create(dto)` 步骤（plan 锁定）：
+  1. **唯一性预检**：`userMapper.selectCount(eq(sUserName, dto.sUserName).eq(bDeleted, false))` > 0 → `BizException(USR_USER_NAME_OR_NO_DUP)`；同理 sUserNo。
+  2. **iStaffId 校验**：dto.iStaffId 非空 → `staffMapper.selectById(...)`；null 或 bDeleted=true → `BizException(STAFF_NOT_FOUND)`。
+  3. **权限分类校验**：dto.permissionCategoryIds 非空 → `permissionCategoryMapper.selectBatchIds(ids)`；返回的 list 长度 < ids 长度 OR 任一 bDeleted=true → `BizException(PERM_CATEGORY_NOT_FOUND)`。
+  4. **构造 UserEntity**：复制 dto；`bCanModifyDocs` null → false；`sPasswordHash = passwordEncoder.encode("666666")`；`tCreateDate = now`；`bDeleted = false`；其他字段 null。
+  5. **Insert user**：`userMapper.insert(user)`，捕 `DuplicateKeyException` → `USR_USER_NAME_OR_NO_DUP`。MyBatis-Plus 回写 `iIncrement` 到 entity。
+  6. **批量 insert UserPermission**：dto.permissionCategoryIds 非空 → 循环逐条 `userPermissionMapper.insert(...)`（每条 `iUserId = user.iIncrement` / `iCategoryId = id` / `tCreateDate = now`；无 bSelected 列）。
+  7. **返回 VO**：`UserVO.from(user, dto.permissionCategoryIds 或 [])`。
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+**初始密码常量**（写在 plan 锁定）：
+```
+private static final String INITIAL_PASSWORD = "666666";
+```
+后续若策略变化，service 单点修改。
+
+- [ ] **Step 4.1 写失败测试（9 个）**
+  - `create_minimalFields_returnsVOWithBCryptHash`：mock 全部 selectCount=0 / passwordEncoder.encode → "$2a$bcrypt"；insert 设 iIncrement；断言 VO + 断言传给 userMapper.insert 的 entity.sPasswordHash 等于 mock 返回值
+  - `create_withStaffAndPermissions_writesAssociation`：mock staff / batch ids 校验通过；断言 userPermissionMapper.insert 被调 N 次 + 每次 entity 字段
+  - `create_duplicateUserName_throws40921`：selectCount(sUserName)>0
+  - `create_duplicateUserNo_throws40921`：selectCount(sUserNo)>0
+  - `create_staffNotFound_throws40421`：staffMapper.selectById → null
+  - `create_staffSoftDeleted_throws40421`：staff.bDeleted=true
+  - `create_permissionCategoryNotFound_throws40422`：selectBatchIds 返回比 ids 短
+  - `create_emptyPermissionCategoryIds_doesNotInsertAssociation`：permissionCategoryIds=[]，断言 userPermissionMapper.insert 从未被调
+  - `create_concurrentDuplicate_dupKeyException_mappedTo40921`：mock userMapper.insert 抛 DuplicateKeyException
+  - 测试方式：`@ExtendWith(MockitoExtension.class)` + `ArgumentCaptor<UserEntity>` / `ArgumentCaptor<UserPermissionEntity>`
+  - 子会话: FAIL
+
+- [ ] **Step 4.2 实现 UserService + Impl**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 提交**
+  - `git commit -m "feat(usr): create user service REQ-USR-001"`
+
+---
+
+### Task 5: UserController + 端到端 IT
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java`
+
+**API shape:**
+- `@RestController @RequestMapping("/api/users") @RequiredArgsConstructor class UserController`
+- `@PostMapping ApiResponse<UserVO> create(@Valid @RequestBody UserCreateDTO dto)`
+- Javadoc：`REQ-MOD-001 用户新增 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:CREATE')")`
+
+- [ ] **Step 5.1 写失败测试（7 个）**
+  - `post_minimalFields_returns200`：仅必填字段；断言 200 + data.sUserName + data.bCanModifyDocs=false + data.permissionCategoryIds=[]
+  - `post_withStaffAndPermissions_returns200_andDbAssociated`：先 mapper.insert 一条 staff + 3 条 permissionCategory，POST 用户附 permissionCategoryIds；断言 DB tUserPermission 有 3 条匹配
+  - `post_duplicateUserName_returns40921`：先 POST 一次，再 POST 同 sUserName
+  - `post_staffNotFound_returns40421`：iStaffId=999999
+  - `post_permissionCategoryNotFound_returns40422`：permissionCategoryIds=[999999]
+  - `post_passwordHashedInDb_notPlaintext`：POST 后 selectById；断言 sPasswordHash 以 "$2a$" 或 "$2b$" 开头，且不含明文 "666666"
+  - `post_responseExcludesSPasswordHash`：jsonPath `$.data.sPasswordHash` doesNotExist
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + `@Autowired UserMapper / StaffMapper / PermissionCategoryMapper / UserPermissionMapper`
+  - 子会话: FAIL（端点不存在）
+
+- [ ] **Step 5.2 实现 UserController**
+  - 子会话: PASS
+
+- [ ] **Step 5.3 跑全量 backend 测试**
+  - `cd backend && mvn -B test`
+  - 期望累计 76（module_mod 现有）+ 1(ApiResponse 错误码扩展) + 4(MapperIT) + 5(DTO Valid) + 9(service unit) + 7(controller IT) = 102 测试，全绿。
+
+- [ ] **Step 5.4 提交**
+  - `git commit -m "feat(usr): POST /api/users controller REQ-USR-001"`
+
+---
+
+## 提交计划
+
+- `feat(common): error codes + PasswordConfig REQ-USR-001`（Task 1）
+- `feat(usr): user/staff/permission/userPermission entities + mappers REQ-USR-001`（Task 2）
+- `feat(usr): user create DTO and VO REQ-USR-001`（Task 3）
+- `feat(usr): create user service REQ-USR-001`（Task 4）
+- `feat(usr): POST /api/users controller REQ-USR-001`（Task 5）
+---
+req_id: REQ-USR-002
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-USR-002.md
+---
+
+# REQ-USR-002 用户修改 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task.
+
+**Goal:** 实现 `PUT /api/users/{id}`：除 sUserNo / sUserName / sPasswordHash 外的字段全量替换 + 权限组重建（先删后插），返回 UserVO。
+
+**Architecture:** 复用 REQ-USR-001 的 entity/mapper/service/exception/Jackson 体系。Service load-then-modify：`selectById` → 校验 + 字段合并 → `updateById`（user）→ `delete`(关联) + 循环 `insert`（关联）。`iStaffId` 字段加 `FieldStrategy.IGNORED` 让 NULL 写入生效。
+
+**Tech Stack:** 沿用前序 REQ。
+
+---
+
+## Schema 改动
+
+无。
+
+## 文件变更清单
+
+- 修改: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 追加 `USR_NOT_FOUND(40431, "用户不存在或已删除")`
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/entity/UserEntity.java` — `iStaffId` 加 `updateStrategy = FieldStrategy.IGNORED`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/dto/UserUpdateDTO.java`
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java` — 追加 `update(Integer id, UserUpdateDTO dto): UserVO`
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java` — 实现 update
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java` — 追加 `@PutMapping("/{id}")`
+- 修改: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 追加 1 个错误码断言
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/dto/UserUpdateDTOValidationTest.java`
+- 修改: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java` — 追加 9 个 update 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java` — 追加 8 个 PUT 集成测试
+
+---
+
+## 任务步骤
+
+### Task 1: 错误码追加 + UserEntity.iStaffId IGNORED
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/entity/UserEntity.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+
+**API shape:**
+- `USR_NOT_FOUND(40431, "用户不存在或已删除")` 追加到 ErrorCode 枚举
+- `UserEntity#iStaffId` 字段注解改为 `@TableField(value = "iStaffId", updateStrategy = FieldStrategy.IGNORED)`，并加注释说明（与 REQ-MOD-002 / module_mod 同样的副作用警告）
+
+- [ ] **Step 1.1 写失败断言**
+  - `ApiResponseTest#errorCode_constantsMatchDocs05Spec` 追加 `assertThat(ErrorCode.USR_NOT_FOUND.getCode()).isEqualTo(40431);`
+  - 子会话: FAIL
+
+- [ ] **Step 1.2 实现错误码 + Entity 注解**
+  - 子会话验证：`mvn -B test`（全量；让 SpringBootTest 预热 lambda cache）应仍 PASS（USR-001 现有用例 + 新断言）
+
+- [ ] **Step 1.3 提交**
+  - `git commit -m "feat(common): USR_NOT_FOUND + iStaffId IGNORED REQ-USR-002"`
+
+---
+
+### Task 2: UserUpdateDTO + 校验单测
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UserUpdateDTO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/dto/UserUpdateDTOValidationTest.java`
+
+**API shape:**
+- 字段（与 UserCreateDTO 相比剥除 `sUserNo` / `sUserName`）：
+  - `Integer iStaffId`（可空）
+  - `@NotBlank @Pattern(regexp="^(普通用户|超级管理员)$") String sUserType`
+  - `@NotBlank @Pattern(regexp="^(zh|en|zh-TW)$") String sLanguage`
+  - `Boolean bCanModifyDocs`（可空，service 层语义：null 保留原值）
+  - `List<Integer> permissionCategoryIds`（可空，空数组 / null 都视为清空）
+
+- [ ] **Step 2.1 写失败测试（4 个）**
+  - `UserUpdateDTOValidationTest#allValidFields_yieldsNoViolations`
+  - `UserUpdateDTOValidationTest#blankRequiredFields_yieldsViolations`（2 个 @NotBlank）
+  - `UserUpdateDTOValidationTest#invalidUserTypeEnum_yieldsViolation`
+  - `UserUpdateDTOValidationTest#invalidLanguageEnum_yieldsViolation`
+  - 子会话: FAIL
+
+- [ ] **Step 2.2 实现 DTO**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(usr): user update DTO REQ-USR-002"`
+
+---
+
+### Task 3: UserService.update + Mockito 单测
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java`（追加方法签名）
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java`（追加 9 个测试）
+
+**API shape:**
+- `UserService.update(Integer id, UserUpdateDTO dto): UserVO`
+- 实现步骤（plan 锁定）：
+  1. `target = userMapper.selectById(id)`；`null` 或 `bDeleted=true` → `BizException(USR_NOT_FOUND)`
+  2. iStaffId 校验（仅当 dto.iStaffId 非空）：`staffMapper.selectById(...)` null / bDeleted → `BizException(STAFF_NOT_FOUND)`
+  3. 权限分类校验（仅当 dto.permissionCategoryIds 非空）：`selectBatchIds` 长度 / bDeleted 检查 → `BizException(PERM_CATEGORY_NOT_FOUND)`
+  4. 字段合并到 target（保留 sUserNo / sUserName / sPasswordHash / iIncrement / tCreateDate / sCreatedBy / tLastLoginDate / 多租户 / sId / bDeleted 三件套）：
+     - `target.setIStaffId(dto.getIStaffId())`（含 null 清空）
+     - `target.setSUserType(dto.getSUserType())`
+     - `target.setSLanguage(dto.getSLanguage())`
+     - `if (dto.getBCanModifyDocs() != null) target.setBCanModifyDocs(...)`（部分更新）
+  5. `userMapper.updateById(target)`
+  6. 重建权限关联：
+     - `userPermissionMapper.delete(LambdaQueryWrapper.eq(iUserId, id))` 清空所有
+     - 若 dto.permissionCategoryIds 非空 → 循环 insert（每条 iUserId / iCategoryId / tCreateDate=now）
+  7. 返回 `UserVO.from(target, dto.permissionCategoryIds 或 [])`
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+- [ ] **Step 3.1 写失败测试（9 个）**
+  - `update_targetNotFound_throws40431`
+  - `update_targetSoftDeleted_throws40431`
+  - `update_staffNotFound_throws40421`
+  - `update_staffSoftDeleted_throws40421`
+  - `update_permissionCategoryNotFound_throws40422`
+  - `update_full_returnsVOWithUpdatedFields_andRebuildsPermissions`：mock target；ArgumentCaptor 验
+    - user 已修改字段：iStaffId / sUserType / sLanguage / bCanModifyDocs
+    - user 保留字段：sUserNo / sUserName / sPasswordHash / iIncrement / tCreateDate / sCreatedBy
+    - userPermissionMapper.delete 调一次（wrapper 含 eq iUserId）；insert 调 N 次（按 dto 的 ids）
+  - `update_partialNullBCanModifyDocs_keepsOriginal`
+  - `update_clearStaffId_setsToNull`：dto.iStaffId=null，断言 captor entity.iStaffId == null
+  - `update_emptyPermissionCategoryIds_clearsAllAssociations`：dto.permissionCategoryIds=[]，verify userPermissionMapper.delete 被调一次 + insert never
+  - 子会话: FAIL
+
+- [ ] **Step 3.2 实现 service.update**
+  - 子会话: PASS（含原 9 个 USR-001 单测 + 9 个 USR-002 单测共 18 个）
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(usr): update user service REQ-USR-002"`
+
+---
+
+### Task 4: UserController PUT + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java`（追加 8 个 PUT IT）
+
+**API shape:**
+- `@PutMapping("/{id}") ApiResponse<UserVO> update(@PathVariable Integer id, @Valid @RequestBody UserUpdateDTO dto)`
+- Javadoc：`REQ-USR-002 用户修改 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:UPDATE')")`
+
+- [ ] **Step 4.1 写失败测试（8 个）**
+  - `put_validUpdate_returns200_andDbReflects`：先 mapper.insert 一个 user + staff + 3 个 cat + 3 个 userPermission；PUT 改 staff(另一个) + sUserType + sLanguage + bCanModifyDocs + permissionCategoryIds（2 个新 cat）；断言 200 + reload 验证字段 + 关联表替换为 2 条
+  - `put_clearStaffId_setsNull`：原 user.iStaffId=staffId，PUT 时 iStaffId=null，断言 DB user.iStaffId IS NULL
+  - `put_emptyPermissionCategoryIds_clearsAssociations`：原有 3 条关联，PUT 传 []，断言 DB tUserPermission count = 0
+  - `put_targetNotFound_returns40431`
+  - `put_staffNotFound_returns40421`
+  - `put_permissionCategoryNotFound_returns40422`
+  - `put_missingRequired_returns40010`：缺 sUserType
+  - `put_ignoresProtectedFields_doesNotChangeUserNoOrName`：手工拼 body 含 sUserNo / sUserName / sPasswordHash 字段，PUT 后 reload；断言 sUserNo / sUserName / sPasswordHash 与原值相同
+  - 子会话: FAIL
+
+- [ ] **Step 4.2 实现 PUT 端点**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 跑全量 backend 测试**
+  - `cd backend && mvn -B test`
+  - 期望 101 + 1（新错误码）+ 4（DTO valid）+ 9（service unit）+ 8（controller IT）= 123 测试，全绿
+
+- [ ] **Step 4.4 提交**
+  - `git commit -m "feat(usr): PUT /api/users/{id} controller REQ-USR-002"`
+
+---
+
+## 提交计划
+
+- `feat(common): USR_NOT_FOUND + iStaffId IGNORED REQ-USR-002`（Task 1）
+- `feat(usr): user update DTO REQ-USR-002`（Task 2）
+- `feat(usr): update user service REQ-USR-002`（Task 3）
+- `feat(usr): PUT /api/users/{id} controller REQ-USR-002`（Task 4）
+---
+req_id: REQ-USR-003
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-USR-003.md
+---
+
+# REQ-USR-003 用户查询 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task.
+
+**Goal:** 实现 `GET /api/users` 列表查询：跨表 JOIN tStaff，按 queryField + matchType + queryValue 三件套过滤 + 分页，返回 PageResult<UserListItemVO>。
+
+**Architecture:** 引入 MP `PaginationInnerInterceptor` + 通用 `PageResult<T>`。Mapper.xml 自定义 `searchUsers` SQL（LEFT JOIN tStaff + dynamic WHERE）。Service 层做 queryField 白名单校验防 SQL 注入，把白名单 column 字符串放入 query 对象传给 mapper。
+
+**Tech Stack:** 沿用前序 REQ；首次启用 MP 分页插件 + XML mapper。
+
+---
+
+## Schema 改动
+
+无。
+
+## 文件变更清单
+
+- 创建: `backend/src/main/java/com/xly/erp/common/response/PageResult.java` — 通用分页 VO
+- 创建: `backend/src/main/java/com/xly/erp/config/MybatisPlusConfig.java` — `PaginationInnerInterceptor` bean
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryDTO.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVO.java`
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/mapper/UserMapper.java` — 追加 `IPage<UserListItemVO> searchUsers(IPage<UserListItemVO> page, @Param("query") UserQueryDTO query)` 方法签名
+- 创建: `backend/src/main/resources/mapper/usr/UserMapper.xml` — 自定义 SQL
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java` — 追加 `search(UserQueryDTO query): PageResult<UserListItemVO>`
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java` — 实现 search + 白名单
+- 修改: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java` — 追加 `@GetMapping`
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryDTOValidationTest.java`
+- 修改: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java` — 追加 search 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java` — 追加 GET IT
+
+---
+
+## 任务步骤
+
+### Task 1: PageResult<T> + MybatisPlusConfig（横切骨架）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/response/PageResult.java`
+- Create: `backend/src/main/java/com/xly/erp/config/MybatisPlusConfig.java`
+
+**API shape:**
+- `PageResult<T>`：字段 `long total` + `List<T> list` + `long pageNum` + `long pageSize`；@Data + 静态工厂 `of(IPage<T> mpPage)`（从 MP IPage 构造）
+- `MybatisPlusConfig`：`@Bean MybatisPlusInterceptor mybatisPlusInterceptor()` 注册 `PaginationInnerInterceptor(DbType.MYSQL)`
+
+- [ ] **Step 1.1 实现两个文件（无独立单测，由 Task 4 的 Mapper IT 验证分页）**
+
+- [ ] **Step 1.2 子会话 mvn 全量测试**（验证 SpringBoot context 启动 + 122 现有测试不回归）
+
+- [ ] **Step 1.3 提交**
+  - `git commit -m "feat(common): PageResult + MP pagination config REQ-USR-003"`
+
+---
+
+### Task 2: UserQueryDTO + UserListItemVO + Validation
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryDTO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryDTOValidationTest.java`
+
+**API shape:**
+
+`UserQueryDTO`:
+- `@Min(1) Integer pageNum = 1`（默认）
+- `@Min(1) @Max(100) Integer pageSize = 20`
+- `@Pattern(regexp="^(username|staffname|userno|department|usertype|language|deleted|lastLoginDate|createdBy)?$") String queryField`（可空）
+- `@Pattern(regexp="^(contains|notContains|equals)?$") String matchType`（可空）
+- `@Size(max=100) String queryValue`（可空）
+
+`UserListItemVO`：11 字段（spec § 输出）。Lombok `@Data`，无静态工厂（mapper 直接通过 ResultMap / autoMap 映射）。
+
+- [ ] **Step 2.1 写失败测试（5 个）**
+  - `UserQueryDTOValidationTest#allValid_yieldsNoViolations`（含 default 值）
+  - `UserQueryDTOValidationTest#pageSizeTooLarge_yieldsViolation`（>100）
+  - `UserQueryDTOValidationTest#pageSizeTooSmall_yieldsViolation`（<1）
+  - `UserQueryDTOValidationTest#queryFieldInvalidEnum_yieldsViolation`
+  - `UserQueryDTOValidationTest#queryValueOverSized_yieldsViolation`（101 字符）
+  - 子会话: FAIL
+
+- [ ] **Step 2.2 实现 DTO + VO**
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(usr): user query DTO + list item VO REQ-USR-003"`
+
+---
+
+### Task 3: UserMapper.xml searchUsers + Mapper smoke IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/UserMapper.java`（追加 `IPage<UserListItemVO> searchUsers(...)` 方法签名）
+- Create: `backend/src/main/resources/mapper/usr/UserMapper.xml` — 自定义 SQL（spec § 实现路径选择 已锁定 SQL 模板）
+- Test: `backend/src/test/java/com/xly/erp/module/usr/mapper/UserMapperSearchIT.java`（新文件，独立 IT）
+
+**XML SQL 锁定**（spec 已写）：
+
+```xml
+<select id="searchUsers" resultType="com.xly.erp.module.usr.vo.UserListItemVO">
+  SELECT
+    u.iIncrement, u.sUserName, s.sStaffName, u.sUserNo,
+    s.sDepartment, u.sUserType, u.sLanguage, u.bDeleted,
+    u.tLastLoginDate, u.sCreatedBy, u.tCreateDate
+  FROM tUser u
+  LEFT JOIN tStaff s ON u.iStaffId = s.iIncrement AND s.bDeleted = 0
+  <where>
+    <if test="query.queryField != 'deleted'">
+      u.bDeleted = 0
+    </if>
+    <if test="query.column != null and query.column != '' and query.queryValue != null and query.queryValue != ''">
+      AND
+      <choose>
+        <when test="query.matchType == 'equals'">${query.column} = #{query.queryValue}</when>
+        <when test="query.matchType == 'notContains'">${query.column} NOT LIKE CONCAT('%', #{query.queryValue}, '%')</when>
+        <otherwise>${query.column} LIKE CONCAT('%', #{query.queryValue}, '%')</otherwise>
+      </choose>
+    </if>
+  </where>
+  ORDER BY u.tCreateDate DESC, u.iIncrement DESC
+</select>
+```
+
+> `query.column` 字段是 service 层白名单映射后的 SQL 列字符串（如 `"u.sUserName"`），由 `${...}` 渲染——**绝不**接受 DTO 原 queryField 直接拼。
+
+为支持 `${query.column}`，需要在 `UserQueryDTO` 加一个 transient 字段 `String column`（service 写入；前端不接受）。
+
+- [ ] **Step 3.1 写失败 IT**
+  - `UserMapperSearchIT#searchUsers_emptyFilter_returnsAllUndeletedAsPage`：插入 2 个 user（含 1 个 staff 关联），`@Autowired UserMapper`，调用 `userMapper.searchUsers(new Page<>(1,10), query)`；断言 page.getTotal() ≥ 2、page.getRecords() 含 sUserName + sStaffName 字段
+  - `UserMapperSearchIT#searchUsers_filterByUserName_filtersCorrectly`：插入 alice / bob；query.queryField=username, column="u.sUserName", matchType=contains, queryValue="ali"；断言只返回 alice
+  - `@SpringBootTest @ActiveProfiles("test") @Transactional @Rollback` + `@Autowired UserMapper / StaffMapper`
+  - 子会话: FAIL（searchUsers 方法未定义）
+
+- [ ] **Step 3.2 实现 mapper 方法签名 + XML + UserQueryDTO 加 column 字段**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(usr): UserMapper.xml searchUsers REQ-USR-003"`
+
+---
+
+### Task 4: UserService.search + Mockito 单测
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/UserService.java`
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java`
+
+**API shape:**
+- `UserService.search(UserQueryDTO query): PageResult<UserListItemVO>`
+- 实现步骤（plan 锁定）：
+  1. 白名单校验 + 列映射：
+     ```
+     Map<String,String> COLUMN_MAP = Map.of(
+       "username", "u.sUserName", "staffname", "s.sStaffName",
+       "userno", "u.sUserNo", "department", "s.sDepartment",
+       "usertype", "u.sUserType", "language", "u.sLanguage",
+       "deleted", "u.bDeleted", "lastLoginDate", "u.tLastLoginDate",
+       "createdBy", "u.sCreatedBy");
+     ```
+     若 `query.queryField` 非空但不在 map → `BizException(PARAM_INVALID, "queryField 非法")`；
+     若 `query.matchType` 非空但不在 {contains, notContains, equals} → 同样错误。
+  2. 把映射后的列字符串写到 `query.setColumn(mappedCol)`；如果 queryField 为空，column 也为空。
+  3. 默认值兜底：pageNum 默认 1，pageSize 默认 20，matchType 默认 contains。
+  4. 构造 `Page<UserListItemVO> page = new Page<>(query.getPageNum(), query.getPageSize())`
+  5. 调 `userMapper.searchUsers(page, query)`
+  6. 返回 `PageResult.of(result)`
+- 标 `@Transactional(readOnly = true)`
+
+- [ ] **Step 4.1 写失败测试（5 个）**
+  - `search_emptyDb_returnsEmptyPage`：mock searchUsers 返回 empty Page；service 返回 PageResult total=0
+  - `search_invalidQueryField_throws40010`：query.queryField="invalid"
+  - `search_invalidMatchType_throws40010`：query.matchType="like"
+  - `search_passesMappedColumnToMapper`：query.queryField="username"；ArgumentCaptor 捕 query 实参，断言 query.column == "u.sUserName"
+  - `search_appliesDefaultPagination_whenNullPageNumOrSize`：query.pageNum=null, pageSize=null；断言 service 创建的 Page.size==20 && current==1
+  - 子会话: FAIL
+
+- [ ] **Step 4.2 实现 service.search**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 提交**
+  - `git commit -m "feat(usr): user query service REQ-USR-003"`
+
+---
+
+### Task 5: UserController GET + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java`
+
+**API shape:**
+- `@GetMapping ApiResponse<PageResult<UserListItemVO>> search(@Valid UserQueryDTO query)`
+- Javadoc：`REQ-USR-003 用户查询 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:READ')")`
+
+- [ ] **Step 5.1 写失败测试（9 个）**
+  - `get_emptyKeyword_returnsAllUndeleted`
+  - `get_filterByUsernameContains_returnsMatchedSubset`
+  - `get_filterByStaffnameContains_returnsJoinedResults`
+  - `get_filterByDeletedTrue_returnsOnlyDeleted`
+  - `get_pagination_returnsCorrectSlice`
+  - `get_responseExcludesInternalFields`：断言 jsonPath `$.data.list[0].sPasswordHash` doesNotExist + sId / iStaffId / sBrandsId 都不出现
+  - `get_pageSizeTooLarge_returns40010`
+  - `get_invalidQueryField_returns40010`
+  - `get_userWithoutStaff_listItemHasNullStaffFields`
+  - `@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + insert helpers
+  - 子会话: FAIL
+
+- [ ] **Step 5.2 实现 GET 端点**
+  - 子会话: PASS
+
+- [ ] **Step 5.3 子会话跑全量 mvn test**
+  - 期望：122 + 5(query DTO valid) + 5(service search unit) + 2(mapper IT) + 9(controller IT) = 143 测试，全绿
+
+- [ ] **Step 5.4 提交**
+  - `git commit -m "feat(usr): GET /api/users controller REQ-USR-003"`
+
+---
+
+## 提交计划
+
+- `feat(common): PageResult + MP pagination config REQ-USR-003`（Task 1）
+- `feat(usr): user query DTO + list item VO REQ-USR-003`（Task 2）
+- `feat(usr): UserMapper.xml searchUsers REQ-USR-003`（Task 3）
+- `feat(usr): user query service REQ-USR-003`（Task 4）
+- `feat(usr): GET /api/users controller REQ-USR-003`（Task 5）
+---
+req_id: REQ-USR-004
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-USR-004.md
+---
+
+# REQ-USR-004 用户登录 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task.
+
+**Goal:** 实现 `POST /api/auth/login`：BCrypt 校验密码 → 5 次失败锁定（内存）→ 签发 HS256 JWT → 回写 tLastLoginDate。
+
+**Architecture:** 引入 jjwt 0.12.x 签发 JWT；`LoginAttemptStore` 接口 + `InMemoryLoginAttemptStore` 实现（spec 注：Redis 替换为后续 REQ）；`JwtTokenProvider` 封装 sign/parse；`LoginService` 协调 4 步逻辑；`SecurityConfig` 白名单 `/api/auth/login`。本 REQ 不切换其他端点为 authenticated（技术债登记）。
+
+**Tech Stack:** 沿用 + 新增 jjwt-api/impl/jackson 0.12.x。
+
+---
+
+## Schema 改动
+
+无。
+
+## 文件变更清单
+
+- 修改: `backend/pom.xml` — 追加 jjwt 三件套
+- 修改: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 追加 LOGIN_INVALID_CREDENTIALS(40101) / LOGIN_ACCOUNT_LOCKED(40301)
+- 修改: `backend/src/main/java/com/xly/erp/config/SecurityConfig.java` — 白名单 `/api/auth/login`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/dto/LoginDTO.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/vo/LoginResultVO.java`（含嵌套 LoginUserInfo）
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/security/JwtTokenProvider.java` — sign/parse 封装
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/security/LoginAttemptStore.java` — 接口
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/security/InMemoryLoginAttemptStore.java` — 实现
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- 创建: `backend/src/main/java/com/xly/erp/module/usr/controller/LoginController.java`
+- 修改: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 追加 2 个错误码断言
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/dto/LoginDTOValidationTest.java`
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/security/JwtTokenProviderTest.java`
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+- 创建: `backend/src/test/java/com/xly/erp/module/usr/controller/LoginControllerIT.java`
+
+---
+
+## 任务步骤
+
+### Task 1: pom.xml + ErrorCode + DTO/VO + DTO Validation
+
+**Files:**
+- Modify: `backend/pom.xml`（追加 jjwt-api / jjwt-impl / jjwt-jackson 0.12.6 三个 dependency）
+- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Modify: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/LoginDTO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/LoginResultVO.java`
+- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/LoginDTOValidationTest.java`
+
+**API shape:**
+- `LOGIN_INVALID_CREDENTIALS(40101, "用户名或密码错误")`
+- `LOGIN_ACCOUNT_LOCKED(40301, "账号已临时锁定")`
+- `LoginDTO`：`@NotBlank @Size(max=50) String sUserName` / `@NotBlank @Size(max=100) String sPassword` / `@NotBlank @Pattern(regexp="^standard$") String sVersion`
+- `LoginResultVO`：`String accessToken` / `long expiresIn` / `LoginUserInfo user`（内嵌静态类 5 字段：iIncrement / sUserNo / sUserName / sUserType / sLanguage）
+
+- [ ] **Step 1.1 写失败测试**
+  - ApiResponseTest 追加：`assertThat(ErrorCode.LOGIN_INVALID_CREDENTIALS.getCode()).isEqualTo(40101);` + LOGIN_ACCOUNT_LOCKED 40301。
+  - LoginDTOValidationTest 4 个用例：allValid / blankRequired / invalidVersion / overSized。
+  - 子会话: FAIL（class 不存在）
+
+- [ ] **Step 1.2 实现**
+  - 在 pom.xml `<dependencies>` 追加：
+    ```
+    io.jsonwebtoken:jjwt-api:0.12.6
+    io.jsonwebtoken:jjwt-impl:0.12.6 (runtime)
+    io.jsonwebtoken:jjwt-jackson:0.12.6 (runtime)
+    ```
+  - ErrorCode + DTO + VO + Validation
+  - 子会话: PASS
+
+- [ ] **Step 1.3 提交**
+  - `git commit -m "feat(usr): jjwt deps + login DTO/VO + error codes REQ-USR-004"`
+
+---
+
+### Task 2: JwtTokenProvider + 单元测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/security/JwtTokenProvider.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/security/JwtTokenProviderTest.java`
+
+**API shape:**
+- `JwtTokenProvider` Spring `@Component`，构造注入 `@Value("${erp.jwt.secret}") String secret` + `@Value("${erp.jwt.expires-in-seconds}") long expiresIn`。
+- `String sign(int uid, String username, String userType)`：HS256，claims `sub=username` / `uid` / `type=userType` / `iat` / `exp = iat + expiresIn`。
+- `Claims parse(String token)`：验证签名 + 过期，抛 `JwtException` / `ExpiredJwtException`。
+
+> secret 不足 256 bit 的处理：jjwt 0.12 要求 SecretKey 至少 256 bit。`JWT_SECRET` (.env.local) 当前已是 256 bit hex。Provider 用 `Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8))`。如不足直接抛 `WeakKeyException`（启动期暴露）。
+
+- [ ] **Step 2.1 写失败测试**
+  - `JwtTokenProviderTest#signAndParse_returnsClaims`：注入 fake secret + expiresIn=7200，sign(uid=1, username=alice, type=普通用户) → parse → 断言 sub=alice / uid=1 / type=普通用户 / exp-iat=7200。
+  - `JwtTokenProviderTest#parseExpiredToken_throwsExpiredJwtException`：mock Clock 或手工构造已过期 token（用 jjwt builder 设 exp=now-1）。
+  - 测试方式：直接 `new JwtTokenProvider(secret, expiresIn)` 实例化，避免 SpringBootTest 开销。
+  - 子会话: FAIL
+
+- [ ] **Step 2.2 实现 JwtTokenProvider**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(usr): JwtTokenProvider sign/parse REQ-USR-004"`
+
+---
+
+### Task 3: LoginAttemptStore 接口 + InMemory 实现
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/security/LoginAttemptStore.java` — 接口
+- Create: `backend/src/main/java/com/xly/erp/module/usr/security/InMemoryLoginAttemptStore.java` — 实现
+- Test: `backend/src/test/java/com/xly/erp/module/usr/security/InMemoryLoginAttemptStoreTest.java`
+
+**API shape:**
+```
+interface LoginAttemptStore {
+  /** 已锁定且未到期 → 返回 cooldownSeconds（>0）；未锁定或已到期 → 返回 0 */
+  long cooldownSeconds(String username);
+
+  /** 记录一次失败：count++；count==5 触发 15min 锁定 */
+  void recordFailure(String username);
+
+  /** 登录成功清空记录 */
+  void clear(String username);
+}
+
+@Component
+class InMemoryLoginAttemptStore implements LoginAttemptStore {
+  private static final int LOCK_THRESHOLD = 5;
+  private static final Duration LOCK_DURATION = Duration.ofMinutes(15);
+  private final Map<String, FailRecord> store = new ConcurrentHashMap<>();
+  // FailRecord{int count; Instant lockUntil}; 同步 access via map.compute
+}
+```
+
+- [ ] **Step 3.1 写失败测试（4 个）**
+  - `cooldown_initial_returnsZero`
+  - `recordFailure_under5_doesNotLock`
+  - `recordFailure_at5_triggersLock_cooldownPositive`
+  - `clear_resetsCount`
+  - （不直接测"15min 后解锁"——time-based 测试用 Duration.ZERO mock 不实际可行；spec § 6 验收"锁定到期后可登录"由 LoginServiceImplTest 模拟 lockUntil 至过去验证）
+  - 子会话: FAIL
+
+- [ ] **Step 3.2 实现接口 + InMemory**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(usr): in-memory login attempt store REQ-USR-004"`
+
+---
+
+### Task 4: LoginService + Mockito 单元测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java`
+- Test: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java`
+
+**API shape:**
+- `LoginService.login(LoginDTO dto): LoginResultVO`
+- 实现步骤（plan 锁定）：
+  1. 检查锁定：`long cd = attemptStore.cooldownSeconds(dto.sUserName)`。`cd > 0` → 抛 `BizException(LOGIN_ACCOUNT_LOCKED, message + cooldownSeconds)`；message 体内含 cooldownSeconds，由 controller 层把 BizException 转换时把 cd 放到 data.cooldownSeconds。
+     - **简化方案**：直接抛 `BizException(LOGIN_ACCOUNT_LOCKED)` 不带 cooldown；controller 层 `catch BizException` 包装成 `ApiResponse.fail` 时丢失 cooldown。**改进方案**：自定义 `AccountLockedException extends BizException`，含 `long cooldownSeconds`，GlobalExceptionHandler 加专门 handler 把 cooldownSeconds 放进 `ApiResponse.data`。spec § 验收 #7 要求 `data.cooldownSeconds`，故选改进方案。
+  2. 查用户：`userMapper.selectOne(eq(sUserName).eq(bDeleted, false))`。null → `attemptStore.recordFailure(sUserName)` + 抛 `LOGIN_INVALID_CREDENTIALS`。
+  3. BCrypt 校验：`passwordEncoder.matches(dto.sPassword, user.sPasswordHash)`。false → `attemptStore.recordFailure(sUserName)` + 抛 `LOGIN_INVALID_CREDENTIALS`。
+  4. 成功：`attemptStore.clear(sUserName)`；签发 token；`userMapper.update(null, LambdaUpdateWrapper.eq(iIncrement,user.iIncrement).set(tLastLoginDate, now))`；构造 LoginResultVO 返回。
+- 标 `@Transactional(rollbackFor = Exception.class)`（成功路径有 update；失败也安全）。
+
+**新建** `AccountLockedException`（在 module_usr/security 或 common/exception，本 plan 选 common/exception）：
+```
+class AccountLockedException extends BizException {
+  private final long cooldownSeconds;
+  public AccountLockedException(long cd) {
+    super(ErrorCode.LOGIN_ACCOUNT_LOCKED);
+    this.cooldownSeconds = cd;
+  }
+}
+```
+
+GlobalExceptionHandler 追加 `@ExceptionHandler(AccountLockedException.class)` 把 cooldownSeconds 包进 `ApiResponse.data`，为此需要 `Map<String, Object>` data 形式：`Map.of("cooldownSeconds", e.getCooldownSeconds())`。
+
+- [ ] **Step 4.1 写失败测试（7 个）**
+  - `login_validCredentials_returnsTokenAndClearsFailCount`：mock attemptStore.cooldownSeconds=0 / userMapper.selectOne 返回 user / passwordEncoder.matches=true / jwt.sign 返回固定 token / userMapper.update 返回 1。断言 VO.accessToken / verify attemptStore.clear / verify userMapper.update 被调（含 LambdaUpdateWrapper）。
+  - `login_userNotFound_returns40101_recordsFailure`
+  - `login_userSoftDeleted_returns40101`：selectOne 已带 bDeleted=0 过滤，覆盖该路径等价于 userNotFound（返回 null）；mock selectOne null 即可。
+  - `login_passwordMismatch_returns40101_recordsFailure`
+  - `login_accountLocked_throwsAccountLockedException_withCooldown`
+  - `login_5thFailureTriggersLock`（mock attemptStore 检验 recordFailure 调用次数）
+  - `login_successUpdatesTLastLoginDate`：ArgumentCaptor 捕 LambdaUpdateWrapper（或 Wrapper），断言 sql set 含 tLastLoginDate。
+  - 子会话: FAIL
+
+- [ ] **Step 4.2 实现 LoginService + Impl + AccountLockedException + GlobalExceptionHandler 扩展**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 提交**
+  - `git commit -m "feat(usr): login service + account locked handling REQ-USR-004"`
+
+---
+
+### Task 5: LoginController + SecurityConfig 白名单 + 端到端 IT
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/LoginController.java`
+- Modify: `backend/src/main/java/com/xly/erp/config/SecurityConfig.java`（白名单 /api/auth/login）
+- Modify: `backend/src/main/resources/application.yml`（确认 `erp.jwt.secret` / `erp.jwt.expires-in-seconds` 已存在；REQ-USR-001 引入时已设置）
+- Test: `backend/src/test/java/com/xly/erp/module/usr/controller/LoginControllerIT.java`
+
+**API shape:**
+- `@RestController @RequestMapping("/api/auth") @RequiredArgsConstructor LoginController`
+- `@PostMapping("/login") ApiResponse<LoginResultVO> login(@Valid @RequestBody LoginDTO dto)`
+- Javadoc: `REQ-USR-004 用户登录 — 永久 permitAll；其他既有端点鉴权切换由后续 REQ 完成`
+- SecurityConfig 修改：在 `authorizeHttpRequests` 配置上下文中显式 `requestMatchers("/api/auth/login").permitAll()`，其他保持 permitAll（REQ-USR-004 不强制收紧，留作技术债登记）
+
+- [ ] **Step 5.1 写失败测试（9 个）**
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @ActiveProfiles("test") @Transactional @Rollback`，`@Autowired UserMapper / PasswordEncoder / InMemoryLoginAttemptStore`，`@BeforeEach` 调用 `attemptStore.clear(sUserName)`（避免跨测试串扰，因为 store 是单例 ConcurrentHashMap）。
+  - `login_validCredentials_returns200WithToken`：先 mapper.insert 一个 user（密码 BCrypt 哈希 666666）→ POST 登录 → 断言 200 / token 非空 / expiresIn=7200 / user 嵌套。
+  - `login_jwtClaimsAreCorrect`：上一条 token 用 JwtTokenProvider 解析（@Autowired），断言 sub / uid / type 与 DB 一致。
+  - `login_invalidUsername_returns40101`
+  - `login_wrongPassword_returns40101`
+  - `login_softDeletedUser_returns40101`
+  - `login_missingPassword_returns40010`
+  - `login_invalidVersion_returns40010`：sVersion="experimental"
+  - `login_5thFailureLocks_returns40301`：连续 5 次 wrong password，第 5 次断言 code=40301 + `data.cooldownSeconds > 0`
+  - `login_responseExcludesSPasswordHash`：jsonPath `$.data.user.sPasswordHash` doesNotExist
+  - 子会话: FAIL
+
+- [ ] **Step 5.2 实现 LoginController + SecurityConfig 白名单**
+  - 子会话: PASS
+
+- [ ] **Step 5.3 跑全量 backend 测试**
+  - `cd backend && mvn -B test`
+  - 期望 144 + 4(DTO valid) + 2(JwtTokenProvider) + 4(InMemoryStore) + 7(service unit) + 9(controller IT) = 170 测试，全绿
+
+- [ ] **Step 5.4 提交**
+  - `git commit -m "feat(usr): POST /api/auth/login controller REQ-USR-004"`
+
+---
+
+## 提交计划
+
+- `feat(usr): jjwt deps + login DTO/VO + error codes REQ-USR-004`（Task 1）
+- `feat(usr): JwtTokenProvider sign/parse REQ-USR-004`（Task 2）
+- `feat(usr): in-memory login attempt store REQ-USR-004`（Task 3）
+- `feat(usr): login service + account locked handling REQ-USR-004`（Task 4）
+- `feat(usr): POST /api/auth/login controller REQ-USR-004`（Task 5）
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-001 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java:30 — 兜底 `@ExceptionHandler(Exception.class)` 会吃掉 `HttpMessageNotReadableException` / `HttpRequestMethodNotSupportedException` / `MissingServletRequestParameterException` 等参数类异常并映射到 50000；语义上更接近 40010。建议下一个 REQ 顺手为这几类异常补独立 handler。
+- backend/src/main/java/com/xly/erp/config/SecurityConfig.java:18 — `csrf -> csrf.disable()` 等三处 lambda 可改用方法引用 `AbstractHttpConfigurer::disable`，更符合 Spring Security 6 官方示例风格。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:39 — `.eq(ModuleEntity::getBDeleted, false)` 可读性建议统一用 `Boolean.FALSE` 或抽常量，依赖 JDBC 默认转换不影响正确性。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:26 / Controller / Mapper / Entity — spec § 代码与文档要求关键类贴 `// REQ-MOD-001 模块新增` 标签；目前 Controller 仅有 REQ-USR-004 备忘注释，缺 REQ-MOD-001 标签，Service / Mapper / Entity / DTO / VO 也均未显式标。建议补一行类级注释。
+- backend/src/main/java/com/xly/erp/config/JacksonConfig.java:18 — JacksonConfig 是计划外补丁（修复匈牙利前缀字段 JSON 序列化）；plan 文件清单未列出。建议补一条 ObjectMapper 序列化测试断言 `iIncrement` 而非 `IIncrement`，把这个隐式契约钉死。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:55 — `post_validRootModule` 应额外断言 VO 字段值（sDisplayType / sModuleNameZh / iSortOrder / tCreateDate / bShowPermission），spec 验收 § 1 要求"DB 中查询新记录字段与入参一致"。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:77 — `post_validChildModule` 没有断言 iSortOrder / bShowPermission / sCreatedBy 留 NULL 等持久化字段，建议补 select-after-insert 验证。
+- backend/src/main/java/com/xly/erp/common/response/ApiResponse.java:28 — `fail(ErrorCode ec, String detail)` 把 message 替换为 detail，前端会吃到带英文字段名的中文混合串。建议将 detail 单列字段或保留 ec.getMessage() 作为 message。
+- backend/src/main/resources/application.yml:21 — 全局 `map-underscore-to-camel-case: false` 对未来非匈牙利前缀字段有传染影响；当前 entity 已显式 `@TableField`，可改回 MyBatis-Plus 默认 true。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 § 功能正确性 1 要求"DB 中查询新记录字段与入参一致"——目前 `ControllerIT` 只断言 3 个字段、未回查 DB；`ModuleMapperIT` 单独覆盖 mapper 层往返，端到端层面字段一致性不直观。
+2. spec § 测试覆盖列出"并发同 sProcedureName"用例标可选，未实现——可接受。
+3. spec § 业务规则 5 要求 `bDeleted=0` / `tDeletedDate=NULL` / `sDeletedBy=NULL` / `sBrandsId/sSubsidiaryId/sCreatedBy=NULL` 在 INSERT 后真正落库——`ModuleServiceImplTest` 用 mock 不能验证 entity 在传给 `mapper.insert` 前的赋值；建议加 `ArgumentCaptor` 断言。
+4. Controller 层缺 `HttpMessageNotReadableException` 用例（POST 非法 JSON 当前会走 50000 兜底）；spec 未显式要求，但 docs/04 § 1.4 友好错误码原则下属盲区。
+5. 计划清单列出的 `MybatisPlusConfig.java` 未创建——plan 自身注明"REQ-MOD-001 不用，先建空骨架"，YAGNI 角度可接受；建议在 plan 上同步勾掉或删除该行。
+6. 未发现硬编码凭据、未跨模块改动、未引入技术栈外组件、commit 全部带 `REQ-MOD-001` 标签、响应不回显堆栈——全部合规。spec 写明的 REQ-USR-004 技术债（permitAll + 多租户字段 NULL + sCreatedBy NULL）落地受控，无失控扩散。
+---
+req_id: REQ-MOD-002
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-002 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java:56 — `iParentId` 改为 `FieldStrategy.IGNORED` 是 entity 全局行为变更。本期 update 走 load-then-modify 全量回填路径所以安全；但未来若有 partial updateById 路径会把 iParentId 写成 NULL。建议在字段注释加 "调用方必须 selectById 后再 updateById"，或将 NULL 写入语义收敛到 update 方法本地。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:207 — spec § 验收 #2「正向 — 设置父模块到合法 sibling」只覆盖了 setParentToNull，没有覆盖"把 iParentId 改到另一个未删除模块"的正向写入路径。建议追加一个 IT 用例。
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:630 — `update_full_returnsVOWithUpdatedFields` 的 dto.iParentId 与 target.iParentId 都是 null，断言只覆盖了 null→null。建议把 dto.setIParentId(非 null) 并 mock 合法父返回，覆盖 walk-up depth=1 直接退出循环的非环场景。
+- backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java:24 — 本 REQ 顺手把 REQ-MOD-001 那行 `// REQ-USR-004 完成后追加 @PreAuthorize(...)` 类外注释改成了 Javadoc，触及既有代码（非严格 surgical）。可读性改善但 commit message 未披露；下次类似情况建议拆 refactor commit 或在 body 注脚说明。
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:597 — `when(moduleMapper.selectById(999999)).thenReturn(null)` 冗余（Mockito 默认就是 null），可删除。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 #2「正向设置父模块到 sibling」在 IT 与单元两层都缺成功路径用例；只覆盖了"清空父"和各种 parent 校验失败用例，未直接验证 iParentId 从 null/某值改到另一个有效模块后 DB 实际写入了新父 id 的主线路径。
+2. spec § 验收 #6「目标已软删除」仅在单元层覆盖（`update_targetSoftDeleted_throws40421`），IT 缺一个"先 update bDeleted=1 再 PUT 返回 40421"用例。
+3. spec § 验收 #8（枚举非法 `sDisplayType="X"`）/ #9（`sModuleType=51 字符`）只在 `ModuleUpdateDTOValidationTest` 单元层验证，未在 IT 走一遍 PUT 端到端断言 40010。
+4. 环路检查的"4-5 层深度边界"和"父链中存在已软删除节点导致提前 break 的非环场景"未单独覆盖；本期数据量低可接受。
+5. `FieldStrategy.IGNORED` 是 entity 全局变更，对未来其他 service 走 partial `updateById` 路径会埋雷；建议要么文档化要么把 NULL 写入收敛到本地策略。
+6. 未发现硬编码凭据、未跨模块改动、未引入技术栈外组件、commit 全部带 `REQ-MOD-002` 标签、响应不回显堆栈——全部合规。错误码（40010/40411/40421/40921）与 docs/05 / spec 一致。环路检查实现 walk-up 沿父链最多 5 层 + 已删节点 break，逻辑正确。
+---
+req_id: REQ-MOD-003
+date: 2026-05-06
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-003 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无；round 1 两条 must_fix 已在 commit 2419659 中修复）
+
+## Nice-to-have
+
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:16 — `org.mockito.ArgumentMatchers` 仍未使用（round 1 提过，pre-existing；可顺手清掉）。
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:358/375/387 — `(Wrapper<ModuleEntity>) any()` 强转触发 unchecked 警告，可在类上 `@SuppressWarnings("unchecked")` 或就近用 `ArgumentMatchers.<Wrapper<ModuleEntity>>any()`。
+- 可选：增加 `delete_writesSDeletedByNull_onSoftDelete` 单元测试，用 ArgumentCaptor 捕 `LambdaUpdateWrapper` 解析 `wrapper.getSqlSet()` 断言含 `sDeletedBy=NULL / bDeleted=1 / tDeletedDate=...`，把 SET 子句的列覆盖也在单元层钉一遍（目前 SET 列内容仅由 IT 兜底）。
+- docs/05-API接口契约.md § REQ-MOD-003 写「40912 响应附 data.references」，spec 未实现；属于已知契约漂移，留给 module-report 时统一对齐。
+
+## 反例 / 测试覆盖缺口
+
+Round 1 两条 must_fix 均已落实：
+
+1. `ModuleServiceImpl.delete()` 改为 `moduleMapper.update(null, uw)` + `LambdaUpdateWrapper.set(BDeleted,true).set(TDeletedDate,now()).set(SDeletedBy,null)`；`eq(BDeleted,false)` 并发兜底保留；`affected==0 → 40421` 保留。三件套全部由 wrapper 显式声明，**绕开** `iParentId.FieldStrategy.IGNORED` 副作用。
+2. `ModuleControllerIT#delete_preservesOtherFields_onChildModule` 已新增：用自定义字段值（sDisplayType='接口' / sModuleType='AUDIT' / sManageDeptEn='OPS' / bShowPermission=true / sModuleNameZh='待保留中文名' / iSortOrder=7）建 child(parentId)，DELETE 后 reload 断言 8 个字段全部保持原值 + bDeleted=true + tDeletedDate 非 null。
+
+**单元测试降级合理性**：架构改动后 entity 参数为 null，原 ArgumentCaptor 对 entity 字段的断言失去对象；MP 真正写入的 SET 列在 wrapper 内部 SqlSegment，单元层断言列覆盖复杂度高且偏离职责。新 IT 在真实 MySQL 端到端验证「除三件套外其他列保持原值 + iParentId 不被清空」，比 mock 层 ArgumentCaptor 严格得多。`verify(moduleMapper).update((ModuleEntity) isNull(), ...)` 把"entity 参数必须是 null"这一架构不变量钉死，防止未来误回滚到 entity-driven update。整体是 mock 层小幅放宽 + IT 层显著加强的净增强。
+
+非阻塞遗留：(a) docs/05 § REQ-MOD-003 `data.references` 描述与实现不一致；(b) 单元测试 `ArgumentMatchers` 未使用 import；(c) 重复 DELETE 集成层显式用例缺失（间接覆盖足够）。
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-004 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:530 — 补 IT 覆盖 spec § 验收 #7『同级排序』：插入 root(iSortOrder=2) + root(iSortOrder=1)，断言 GET 返回数组首个 iIncrement 是 sort=1 那条。当前同级排序仅在单测覆盖，缺端到端断言。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:530 — 补 IT 覆盖 spec § 验收 #6『keyword 含中英混合』：插入 sModuleNameZh='user 用户'，GET ?keyword=user 用户 命中。
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:497 — `tree_softDeletedExcluded` 仅 verify(...).selectList(any())，未捕 wrapper 形状（plan 要求 ArgumentCaptor）。建议改名或真用 ArgumentCaptor 抽 `wrapper.getTargetSql()` 断言含 `bDeleted = 0`。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:227 — Comparator 对 iSortOrder 做了 null→0 防御，但 docs/03 已注明 NOT NULL；可简化为 `Comparator.comparingInt(ModuleTreeNodeVO::getISortOrder).thenComparingInt(::getIIncrement)`。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:198 — `survivorIds = byId.keySet()` 是 live view，与 keyword 分支返回的独立 HashSet 类型不一致；建议改成 `new HashSet<>(byId.keySet())` 一致化。
+- backend/pom.xml:121 — surefire includes 修改是项目级配置；建议在 docs/04 测试规范节追加一行说明『*IT.java 走 surefire (mvn test) 而非 failsafe (mvn verify)』，避免后续贡献者破坏 includes。
+- docs/03-数据库设计文档.md § tModule 业务注记 — 建议追加一行『模块树最大深度 5 层（iParentId 自引用），由 service 层校验，REQ-MOD-002 / REQ-MOD-004 引用本约束』，把深度上限提升为 SSoT。
+- backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java:11 — 在 @Size 上方 javadoc 写明『empty 视为不过滤』。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 #7 同级排序的端到端 IT 缺失（仅单测）。
+2. spec § 验收 #6 中英混合 keyword 没有专属 IT。
+3. `tree_softDeletedExcluded` 单测断言强度低于 plan 期望。
+4. 反例缺：keyword 含 SQL 通配符 `%` / `_`（spec 声明本期不转义，作为已知边界）。
+5. 反例缺：祖先链深度 ≥ 5 的截断边界用例；docs/03 已限深度 5，正常打不到边界，可后续补 6 层强构数据单测固化截断语义。
+6. Controller javadoc 标了『REQ-USR-004 完成后追加 @PreAuthorize』但缺集中跟踪——建议在 docs/08 § 二 USR-004 子项挂 follow-up 备注。
+
+**核心结论**：实现忠实于 spec — keyword 过滤 + 祖先链 walk-up + 内存树构造 + 同级 (iSortOrder, iIncrement) 排序 + 叶子 children=[] 全部正确。API 契约字段精简到位（VO 7 个公开字段 + children）。surefire includes 修复是揭示性发现——本仓库之前 *IT.java 没在 mvn test 跑过，REQ-MOD-001/002/003 的 IT 都是"死代码"；本 REQ commit body 已披露，REQ-MOD-004 的 IT 是首次在 mvn test 跑通。
+---
+req_id: REQ-USR-001
+date: 2026-05-06
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-001 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+Round 1 两条 must_fix 处理结果：
+1. **HIGH（reviewer 误判）**：`UserServiceImpl.java:102` 实际已含 `up.setTCreateDate(LocalDateTime.now());`，round 1 reviewer 看错。fix commit 520c01f 正确不动代码。
+2. **MEDIUM（已修）**：spec/plan 中 `bSelected` 提及全部转为「无该列」注解，与 docs/03 SSoT + UserPermissionEntity 实现一致（fix commit 520c01f）。
+
+## Nice-to-have（待 sweep）
+
+- backend/src/main/java/com/xly/erp/common/response/ErrorCode.java — 3 个新常量（STAFF_NOT_FOUND / PERM_CATEGORY_NOT_FOUND / USR_USER_NAME_OR_NO_DUP）追 Javadoc，特别 `STAFF_NOT_FOUND(40421)` 与 `MOD_NOT_FOUND(40421)` 段位共享但语义不同——Javadoc 注明使用模块差异，避免 IDE 跳错枚举。
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java:30 — `INITIAL_PASSWORD = "666666"` 外置到 `application.yml` + `@Value("${xly.user.initial-password:666666}")`，便于环境差异化 + REQ-USR-004 登录校验复用。
+- backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java — 补 `post_staffSoftDeleted_returns40421`、`post_duplicateUserNo_returns40921` 两条 IT 镜像 service 单测分支。
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java:70 — `permissionCategoryIds` 含重复 id 时 found.size() < ids.size() 误报 40422；可在校验前 distinct。
+- docs/05 § REQ-USR-001 错误码段位 40020 vs spec 落地 40010 sweep 对齐。
+- docs/superpowers/plans/2026-05-06-REQ-USR-001.md Task 5 API shape — Javadoc 注释笔误 `REQ-MOD-001 用户新增`，Controller.java 内已正确为 `REQ-USR-001`；plan 同步修正即可。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 #6（iStaffId 已软删除）IT 层未覆盖（仅 service mock 单测覆盖）。
+2. spec § 验收 #4 sUserNo 唯一冲突 IT 层未直接覆盖（仅 sUserName 冲突的 IT）。
+3. spec § 业务规则 8 「DuplicateKeyException 端到端映射 40921」无 IT 触发路径（@Transactional 包裹下不易触发；service mock 已覆盖，gap 可接受）。
+4. 跨 round 1 / round 2：fix commit 520c01f 仅触及 3 份 docs，0 行代码变更；UserServiceImpl / UserPermissionEntity / 测试均保持原样，无新引入风险。`scripts/test.sh` 全量 101/0/0/0 BUILD SUCCESS。
+
+**核心结论**：round 1 must_fix #1 是 reviewer 误判（无需修），#2 已修。所有 IT + 单元测试 101 个全绿。verdict: approve。
+---
+req_id: REQ-USR-002
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-002 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java:285 — `put_permissionCategoryNotFound_returns40422` 只断言响应 code，未断言 spec § 验收 #11 要求的 "DB user 与 tUserPermission 都不变（事务回滚）"。受 IT 类整体 `@Transactional+@Rollback` 制约，需另起 `Propagation.NOT_SUPPORTED` 测试或在 service 抛异常前后分别 reload 校验字段未变。
+- backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java:235 — `put_validUpdate_returns200_andDbReflects` 仅断言 `upCount==2L`，没显式断言新 2 条关联指向 `catNew1/catNew2` 且原 3 条已不存在。建议追加 `containsExactlyInAnyOrder(catNew1, catNew2)` + `doesNotContain(cat1, cat2, cat3)`。
+- backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java — IT 缺 `put_targetSoftDeleted_returns40431` 和 `put_staffSoftDeleted_returns40421` 两条端到端用例（spec § 验收 #7 / #10 仅在 service 单测覆盖）。
+- backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java:327 — `put_ignoresProtectedFields_doesNotChangeUserNoOrName` 未断言 tCreateDate 保留（spec § 业务规则 #7 / 验收 #4 列入"不被修改"范围）。
+- backend/src/main/java/com/xly/erp/module/usr/entity/UserEntity.java:40 — `iStaffId` 全局 `FieldStrategy.IGNORED` 是已知副作用（注释已说明）。建议在 module_usr 完成报告 § ⑦ 跨模块改动 / 风险登记追加一条："UserEntity.iStaffId 已加 IGNORED；后续 partial-update path 必须 selectById 后再 updateById"，与 module_mod ModuleEntity.iParentId 同类风险并案管理。
+- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java — Service 中 iStaffId/sUserType/sLanguage 直接覆盖、bCanModifyDocs null 保留——建议加注释或抽 mergeUpdate 私有方法集中 null 语义。
+- backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java — 未覆盖 `dto.permissionCategoryIds == null` 分支（spec § 业务规则 #5 "不传则只删不插"）。当前所有相关测试都用 `List.of()` 而非 null。
+
+## 反例 / 测试覆盖缺口
+
+1. **AC11 回滚证据**：`put_permissionCategoryNotFound_returns40422` 受 `@Transactional+@Rollback` 制约，无法直接观测 service 层的回滚。
+2. **AC1 重建关联粒度**：`upCount==2` 可被任何 insert 顺序异常掩盖，需细化断言。
+3. **AC7 / AC10 端到端缺失**：目标软删除 / staff 软删除均仅在 service 单测覆盖。
+4. **AC4 tCreateDate 保留**：实现走 load-then-modify 默认 NOT_NULL 策略行为正确，但缺测试佐证。
+5. **业务规则 #5 null permissionCategoryIds 分支**：单测未直接覆盖。
+6. **iStaffId IGNORED 全局副作用**：本期安全，未来 partial-update path 风险，需在 module_usr 完成报告中登记。
+
+**核心结论**：Spec/Plan 业务规则 1-9 全部实现到位，错误码 40010 / 40421 / 40422 / 40431 全部回归，UserVO 不暴露 sPasswordHash，保留字段 sUserNo / sUserName / sPasswordHash 不被改通过 IT 验证。docs/05 § REQ-USR-002 列的 40331 / 40931 是 RBAC 范畴的本期不实施项，spec 已说明，不阻塞。verdict: approve；改进项放下一 REQ 或 module-report sweep。
+---
+req_id: REQ-USR-003
+date: 2026-05-06
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-003 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+Round 1 三条 must_fix 处理结果（commit f53689c）：
+1. **HIGH SQL 注入** — RESOLVED。UserQueryDTO 删除 `column` 字段；UserMapper.searchUsers 三参签名含 `@Param("column") String column`；UserMapper.xml 用 `${column}`；UserServiceImpl.search 用局部变量映射后通过 mapper 单独传入。
+2. **HIGH spec § 6 deleted=true** — RESOLVED。Service 实现 'true'/'false' → '1'/'0' 标准化（其它抛 PARAM_INVALID）；XML deleted 分支用 `CAST(#{queryValue} AS UNSIGNED)` 兼容 bit(1)；恢复 `get_filterByDeletedTrue_returnsOnlyDeleted` IT；新增 `search_deletedQueryValueTrue_normalizedToOne` 单测。
+3. **MEDIUM XML deleted 边界** — RESOLVED。queryField=deleted 但 queryValue 空时仍保留默认过滤 `u.bDeleted = 0`，避免返回全量含已删除。
+
+## Nice-to-have
+
+- UserServiceImpl.search:212/214 — 直接 `query.setQueryValue("1")` 改写入参 DTO，单测靠副作用断言。语义上 service 不应突变 controller 入参；可改用局部 `normalizedDeletedValue` + `@Param("deletedValue")` 传给 mapper，XML 改用 `#{deletedValue}`，更纯。
+- round 1 遗留的 6 条 IT 覆盖缺口（department equals / deleted=false / notContains / 排序 / matchType 非枚举 IT / 空结果 IT）+ UserMapperSearchIT 断言强化 + PageResult javadoc + QUERY_COLUMN_MAP 位置 + Base_Column_List 抽取——本轮也不在 must_fix 范畴，留待后续 sweep。
+
+## 反例 / 测试覆盖缺口
+
+Round 1 must_fix 1 + 2 + 3 三项均已落地：
+
+1. 注入：UserMapper.xml 唯一 `${...}` 插值仅来自 service 白名单映射，外部输入完全经过 `#{...}` 参数化绑定。
+2. deleted 标准化：单测 `search_deletedQueryValueTrue_normalizedToOne` 钉死 `query.getQueryValue() == "1"`；IT `get_filterByDeletedTrue_returnsOnlyDeleted` 端到端验证返回已删除用户。
+3. XML 边界：deleted 空值分支保留默认 `u.bDeleted = 0`，与 spec § 业务规则 1 一致。
+
+`mvn -B test` 经 .env.local 注入后 144/144 全绿，无新高危。
+
+**核心结论**：round 1 high 注入风险 + spec § 6 契约缺失全部修复；其余 nice-to-have 不阻塞，留下一 sweep。verdict: approve。
+---
+req_id: REQ-USR-004
+date: 2026-05-06
+round: 2
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-USR-004 — round 2
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+Round 1 三条 must_fix 处理结果（commit d439c0d）：
+1. **CRITICAL JwtTokenProviderTest 硬编码生产 JWT_SECRET** — RESOLVED。test SECRET 改为 fake 32-byte hex（line 21）；`.env.local` JWT_SECRET 已旋转为新随机值。**遗留运维项**：旧值已入 commit b7ed804 git history，所有已部署环境必须同步轮换 JWT_SECRET。
+2. **HIGH InMemoryLoginAttemptStore 锁定到期不重置** — RESOLVED。cooldownSeconds 过期路径 `store.remove`，recordFailure compute 入口检测 prev.lockUntil 过期重建 FailRecord；spec § 业务规则 4 第 4 条达成。
+3. **MEDIUM 验收 #9 无测试** — RESOLVED。补 `cooldown_afterExpiry_resetsCount` 单测（含 reset 后再 4 次未锁、第 5 次再锁的完整往返）+ `login_afterLockExpiry_returns200` IT；`expireLockForTest` 改 public 解决跨包可见性。
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/module/usr/controller/LoginController.java + service — spec § 业务规则 7 客户端 IP 审计未实施；service 未拿 `HttpServletRequest.getRemoteAddr()`。**需在模块完成报告 § ⑩ 登记技术债**。
+- backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java — `login_successUpdatesTLastLoginDate_viaSetClause` 仍只 `verify(...).update(isNull(), any(Wrapper.class))`，没断言 LambdaUpdateWrapper 的 set 子句包含 tLastLoginDate（plan Step 4.1 要求）。
+- backend/src/main/java/com/xly/erp/config/SecurityConfig.java — plan Step 5.2 要求 `requestMatchers("/api/auth/login").permitAll()` 显式白名单；当前 anyRequest().permitAll() 等价覆盖但未做 plan 偏离登记。
+- backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java:17 — `java.util.Map` fully-qualified；下次 sweep 加 import。
+- backend/src/main/java/com/xly/erp/module/usr/security/InMemoryLoginAttemptStore.java:51 — `expireLockForTest` 已 public 但住在生产包；下一 sweep 可挪到 src/test 的 testutil 包。
+
+## 反例 / 测试覆盖缺口
+
+Round 1 三项 must_fix 全部解决：
+1. JwtTokenProviderTest SECRET 改 fake + .env.local 已旋转；运维侧需轮换部署环境。
+2. cooldownSeconds + recordFailure 双路径处理过期重置；business rule #4 完整。
+3. 验收 #9 单测 + IT 双层覆盖；reset 后能重新触发新一轮锁定。
+
+`mvn -B test` 经 .env.local 注入后 172/172 全绿；`scripts/test.sh` GREEN；无新高危。
+
+**核心结论**：critical + high + medium 三项关键修复已落地。剩余 5 条 nice-to-have（IP 审计 / SET 子句捕获 / SecurityConfig 显式白名单 / Map import / testutil 移植）在模块完成报告 § ⑩ 登记后留给后续 sweep。verdict: approve。
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-001 — 模块新增
+
+## 目标
+
+实现后端 `POST /api/modules` 接口：将一条新的业务模块定义写入 `tModule` 表，作为 ERP 系统功能与权限分组的基础单位，返回新模块主键 `iIncrement` 与完整 VO。
+
+本 REQ 是 module_mod 模块的第一个 REQ，也是整个 B 阶段的首个 REQ；需顺带建立 Spring Boot 项目骨架（最小可运行单元），仅落地能让本接口工作的横切组件。其余横切组件（JWT 鉴权、登录用户上下文）按 docs/02 § 三 约定由 REQ-USR-004 首次落地。
+
+## 输入 / 触发
+
+**接口**：`POST /api/modules`，Content-Type `application/json`。
+
+**Request body**（`ModuleCreateDTO`）字段：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 | 落库列 |
+|---|---|---|---|---|
+| `sDisplayType` | String | 是 | 枚举：`手机端` / `前端业务` / `系统配置` / `接口` | `tModule.sDisplayType` |
+| `sProcedureName` | String | 是 | 长度 1-100；系统内唯一（`bDeleted=0` 范围内） | `tModule.sProcedureName` |
+| `sModuleType` | String | 是 | 长度 1-50（自由文本） | `tModule.sModuleType` |
+| `sManageDeptEn` | String | 是 | 长度 1-50（自由文本） | `tModule.sManageDeptEn` |
+| `bShowPermission` | Boolean | 否 | 默认 `false` | `tModule.bShowPermission` |
+| `sModuleNameZh` | String | 是 | 长度 1-100 | `tModule.sModuleNameZh` |
+| `iParentId` | Integer | 否 | 必须指向已存在且未软删除的 `tModule.iIncrement` | `tModule.iParentId` |
+| `iSortOrder` | Integer | 否 | 默认 `0`；非负整数 | `tModule.iSortOrder` |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:CREATE`。本 REQ 暂不实施实际鉴权（见 § 边界与约束），但 Controller 仍按需要鉴权的形态编写（无 `@AnonymousAccess` 标注），以便 REQ-USR-004 加入 SecurityFilterChain 后零改动。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**（统一响应格式）：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "sDisplayType": "前端业务",
+    "sProcedureName": "sp_audit_user_module",
+    "sModuleType": "USR",
+    "sManageDeptEn": "IT",
+    "bShowPermission": false,
+    "sModuleNameZh": "用户管理",
+    "iParentId": null,
+    "iSortOrder": 0,
+    "tCreateDate": "2026-05-06T10:30:00",
+    "bDeleted": false
+  },
+  "timestamp": 1746528600000
+}
+```
+
+返回 VO（`ModuleVO`）字段：`iIncrement` / `sDisplayType` / `sProcedureName` / `sModuleType` / `sManageDeptEn` / `bShowPermission` / `sModuleNameZh` / `iParentId` / `iSortOrder` / `tCreateDate` / `bDeleted`。其他标准列（`sId` / `sBrandsId` / `sSubsidiaryId` / `sCreatedBy` / `tDeletedDate` / `sDeletedBy`）不对外暴露。
+
+## 业务规则
+
+1. **唯一性**：`sProcedureName` 在未软删除范围内（`bDeleted=0`）系统内唯一。冲突返回错误码 `40911`。
+2. **父模块校验**：若 `iParentId` 非空，必须指向 `tModule` 中存在且 `bDeleted=0` 的记录；不存在或已删除返回错误码 `40411`。
+3. **bShowPermission 默认值**：未传入或传 `null` → 落库 `0`。
+4. **iSortOrder 默认值**：未传入 → 落库 `0`。
+5. **新建记录初始状态**：`bDeleted=0`、`tDeletedDate=NULL`、`sDeletedBy=NULL`、`tCreateDate=now()`（应用层取系统时间，不依赖 DB DEFAULT）。
+6. **多租户字段 (`sBrandsId` / `sSubsidiaryId`)**：本 REQ **不写入**（落库 `NULL`，列已 nullable）。多租户上下文将由 REQ-USR-004 引入登录会话后注入；后续 REQ 通过迁移补齐已有数据。
+7. **`sCreatedBy`**：本 REQ 落库 `NULL`。等待 REQ-USR-004 引入登录用户上下文后从 `SecurityContextHolder` 取当前用户号回写。
+8. **`sId`**（业务 ID 标准列）：本 REQ 落库 `NULL`，不在本接口分配。后续若有外部对接需求再以独立 migration 补齐策略。
+
+## 边界与约束
+
+### 鉴权策略（本 REQ 限定）
+
+- 项目首个 REQ，尚无 SecurityFilterChain。本 REQ 在 `SecurityConfig` 里配置 `permitAll()` 临时放行所有 `/api/**`。
+- Controller 不写 `@PreAuthorize("hasAuthority('MOD:CREATE')")`（无 SecurityContext 时该注解会因 `Authentication=null` 抛 `AccessDeniedException`）；改为在 Controller 上方写一行说明性注释：`// REQ-USR-004 完成后改为 @PreAuthorize("hasAuthority('MOD:CREATE')")`。
+- REQ-USR-004 完成后会回头给本接口加 `@PreAuthorize`，并把 `permitAll` 改为 `authenticated()`。这是已知技术债，**仅在 REQ-USR-004 范围内偿还**，本 REQ 不擅自前置。
+
+### 字段长度与字符集
+
+- 字符集统一 `utf8mb4`（DDL 已约束），允许中文落库。
+- 字符串字段超出 DDL 长度限制视为参数错误（`40010`），不截断。
+
+### 事务
+
+- Service 方法标注 `@Transactional(rollbackFor = Exception.class)`，单表写入即可，事务范围最小化。
+
+### 性能与并发
+
+- 本 REQ 是单条 INSERT，预期无高并发。`uk_procedure_name` 唯一约束兜底并发竞争；唯一冲突映射为 `40911`。
+
+### 项目骨架引导（首 REQ 一次性附带）
+
+本 REQ 顺带建立**最小可运行**的 Spring Boot 项目骨架（仅引入服务于本 REQ 的部分；后续 REQ 按需扩充）。预期新增目录与文件：
+
+```
+backend/
+├── pom.xml
+└── src/main/
+    ├── java/com/xly/erp/
+    │   ├── ErpApplication.java
+    │   ├── config/
+    │   │   ├── MybatisPlusConfig.java
+    │   │   └── SecurityConfig.java          // 临时 permitAll
+    │   ├── common/
+    │   │   ├── response/
+    │   │   │   ├── ApiResponse.java
+    │   │   │   └── ErrorCode.java
+    │   │   └── exception/
+    │   │       ├── BizException.java
+    │   │       └── GlobalExceptionHandler.java
+    │   └── module/mod/
+    │       ├── controller/ModuleController.java
+    │       ├── service/ModuleService.java
+    │       ├── service/impl/ModuleServiceImpl.java
+    │       ├── mapper/ModuleMapper.java
+    │       ├── entity/Module.java
+    │       ├── dto/ModuleCreateDTO.java
+    │       └── vo/ModuleVO.java
+    └── resources/
+        ├── application.yml                  // ${DB_HOST}/${DB_PORT}/... 占位，从 .env.local 注入
+        └── mapper/mod/ModuleMapper.xml
+```
+
+`pom.xml` 依赖：`spring-boot-starter-web` / `-validation` / `-security`、`mybatis-plus-spring-boot3-starter`、`flyway-core` + `flyway-mysql`、`mysql-connector-j`、`mapstruct`、`hutool-all`、`spring-boot-starter-test`、`spring-security-test`。
+
+`application.yml` 通过 Spring Profile + `dotenv-java`（或本地启动脚本）加载 `.env.local`；不在仓内硬编码任何凭据（与 `docs/04 § 3.5` 一致）。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tModule`（详见 `docs/03-数据库设计文档.md` § tModule）
+
+| 字段 | 落库逻辑 |
+|---|---|
+| `iIncrement` | DB 自增分配 |
+| `sId` | 落 `NULL`（本 REQ 不分配业务 ID） |
+| `sBrandsId` | 落 `NULL`（多租户 REQ-USR-004 后引入） |
+| `sSubsidiaryId` | 落 `NULL`（同上） |
+| `tCreateDate` | 应用层 `LocalDateTime.now()` |
+| `sDisplayType` | 入参（必填） |
+| `sProcedureName` | 入参（必填，唯一） |
+| `sModuleType` | 入参（必填） |
+| `sManageDeptEn` | 入参（必填） |
+| `bShowPermission` | 入参（默认 `false`） |
+| `sModuleNameZh` | 入参（必填） |
+| `iParentId` | 入参（可选；FK 校验通过的 `tModule.iIncrement`） |
+| `iSortOrder` | 入参（默认 `0`） |
+| `sCreatedBy` | 落 `NULL`（REQ-USR-004 后引入登录上下文） |
+| `bDeleted` | 落 `0` |
+| `tDeletedDate` | 落 `NULL` |
+| `sDeletedBy` | 落 `NULL` |
+
+**索引利用**：
+- `uk_procedure_name` UNIQUE：唯一性约束触发并发兜底
+- `idx_parent`：父模块查询场景（FK 校验时按 `iParentId` 查 `tModule`）
+
+**外键**：本 REQ 利用 `fk_module_parent` 作为 DB 层兜底；应用层在写入前先查父模块存在性，提前返回 `40411`，避免直接抛 SQL 完整性异常。
+
+## 依赖的接口
+
+无（本接口是 module_mod 的入口接口，不依赖其他业务接口）。
+
+后续在 REQ-USR-004 完成后，需要回归补齐本接口的 `@PreAuthorize("hasAuthority('MOD:CREATE')")`，并要求请求携带有效 JWT。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 根模块**：提交完整字段、`iParentId=null`，返回 200 + `data.iIncrement` 非空；DB 中查询新记录字段与入参一致；`bDeleted=0` / `tCreateDate` 已写入。
+2. **正向 — 子模块**：先创建 root 再以其 `iIncrement` 作为 `iParentId` 创建子模块，返回 200。
+3. **唯一性冲突**：用相同 `sProcedureName` 二次提交，返回 `code=40911` + 中文 message；DB 不产生重复记录。
+4. **父模块不存在**：传入 `iParentId=999999`，返回 `code=40411`。
+5. **必填缺失 / 枚举非法 / 长度超限**：返回 `code=40010` + 错误字段名定位。
+6. **可选默认值**：不传 `bShowPermission` / `iSortOrder` → DB 落 `false / 0`。
+
+### 接口契约一致性
+
+- 响应格式严格符合 `{code, message, data, timestamp}`（docs/05 § 全局约定）。
+- 错误码段位与 docs/05 一致：`200` / `40010` / `40911` / `40411` / `500xx`。
+- 异常堆栈不出现在响应里（GlobalExceptionHandler 拦截并映射为友好错误，docs/04 § 1.4）。
+
+### 测试覆盖（feature-tdd 阶段）
+
+- **单元测试**：`ModuleServiceImpl#create` 覆盖 6 类正/反路径（含唯一冲突的 `DuplicateKeyException` 映射）。
+- **集成测试（MockMvc + 真实 MySQL test schema）**：
+  - 正向：根模块、子模块创建后查 DB 验证字段
+  - 反向：唯一冲突、父模块不存在、必填缺失、枚举非法、长度超限 ≥ 5 个 case
+  - 并发：两线程同时插入同 `sProcedureName`，断言一条成功 + 一条 40911（可选，若 CI 跑得动）
+- **测试数据隔离**：每个测试方法 `@Transactional` 自动回滚；不污染其他测试。
+
+### 代码与文档
+
+- `// REQ-MOD-001` 注释贴在 Controller / Service / Mapper / DTO / VO 关键类。
+- 提交按 `feat(mod): add module create endpoint REQ-MOD-001` 规范。
+- 不引入 docs/04 § 零 技术栈外的依赖（如需，按软规则 S1 经 AskUserQuestion）。
+---
+req_id: REQ-MOD-002
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-002 — 模块修改
+
+## 目标
+
+实现后端 `PUT /api/modules/{id}` 接口：在不破坏唯一性 / 树结构完整性的前提下，更新已有模块的可编辑字段，返回最新模块 VO。
+
+## 输入 / 触发
+
+**接口**：`PUT /api/modules/{id}`，Content-Type `application/json`。`{id}` = `tModule.iIncrement`。
+
+**Request body**（`ModuleUpdateDTO`）字段——与 REQ-MOD-001 输入相比**剥除 `sProcedureName`**（不可改，contract 约束）；其余 7 个业务字段含义和校验规则保持一致：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 | 落库列 |
+|---|---|---|---|---|
+| `sDisplayType` | String | 是 | 枚举：`手机端` / `前端业务` / `系统配置` / `接口` | `tModule.sDisplayType` |
+| `sModuleType` | String | 是 | 长度 1-50 | `tModule.sModuleType` |
+| `sManageDeptEn` | String | 是 | 长度 1-50 | `tModule.sManageDeptEn` |
+| `bShowPermission` | Boolean | 否 | 默认保持原值；显式传 `null` 视为不变 | `tModule.bShowPermission` |
+| `sModuleNameZh` | String | 是 | 长度 1-100 | `tModule.sModuleNameZh` |
+| `iParentId` | Integer | 否 | 可空（设为根模块）；非空必须存在且未软删除；不能等于 `{id}` 自身或其后代 | `tModule.iParentId` |
+| `iSortOrder` | Integer | 否 | 默认保持原值；非负整数 | `tModule.iSortOrder` |
+
+> **`sProcedureName` 不在 DTO 中**：Jackson 反序列化时若客户端误传将被忽略（`@JsonIgnoreProperties(ignoreUnknown = true)` 由 Jackson 默认行为兜底；不抛错）。前端 UI 应把该字段渲染为只读。
+>
+> **PUT 语义**：本接口采用全量替换语义。请求体中显式存在的字段均落库；若未提供（JSON 中 key 缺失或值为 `null`），按字段下方"必填"列：必填字段缺失 → `40010`；可选字段缺失 → 保持数据库原值。
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:UPDATE`。本 REQ 沿用 REQ-MOD-001 的 SecurityConfig permitAll 占位（REQ-USR-004 后回头收紧）；Controller 写注释 `// REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:UPDATE')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**（统一响应格式）：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "sDisplayType": "前端业务",
+    "sProcedureName": "sp_audit_user_module",
+    "sModuleType": "USR",
+    "sManageDeptEn": "IT",
+    "bShowPermission": true,
+    "sModuleNameZh": "用户管理（修订）",
+    "iParentId": 3,
+    "iSortOrder": 5,
+    "tCreateDate": "2026-05-06T10:30:00",
+    "bDeleted": false
+  },
+  "timestamp": 1746528600000
+}
+```
+
+VO 复用 REQ-MOD-001 的 `ModuleVO`（11 个字段）。
+
+## 业务规则
+
+1. **目标模块必须存在且未软删除**：`SELECT ... WHERE iIncrement = {id} AND bDeleted = 0`。不存在或已删 → `40421`。
+2. **`sProcedureName` 不可改**：DTO 不接受该字段；后端读取目标记录后保留原 `sProcedureName` 不变。
+3. **`iParentId` 自引用校验**：
+   - 若 `iParentId` 等于路径参数 `{id}`（自引用）→ `40921`。
+   - 若 `iParentId` 在 `tModule` 中不存在或已软删除 → `40411`。
+   - 若 `iParentId` 是 `{id}` 的后代（沿 `iParentId` 链向下走，深度上限 5 层与 docs/03 § tModule 业务注记一致）→ `40921`。
+4. **保留字段**：`iIncrement` / `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `sCreatedBy` / `bDeleted` / `tDeletedDate` / `sDeletedBy` 在本接口**不被修改**。
+5. **`bShowPermission` / `iSortOrder` 部分更新**：DTO 中为 `null` → 保持原值；显式传值 → 覆盖。
+6. **审计**：本 REQ 暂不维护"最近修改时间"和"修改人"列（schema 未规划相关字段，docs/03 也未要求）。后续若需，按 V_n migration 加列同步更新 docs/03。
+7. **多租户字段不写入**：与 REQ-MOD-001 一致，本接口不动 `sBrandsId / sSubsidiaryId`。
+
+## 边界与约束
+
+### 鉴权策略（本 REQ 限定）
+
+沿用 REQ-MOD-001：SecurityConfig permitAll；Controller 上写说明性注释 `// REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:UPDATE')")`。
+
+### 事务
+
+- Service 方法标 `@Transactional(rollbackFor = Exception.class)`。读取目标模块 → 校验 → 更新 全在同一事务。
+- 父模块校验 + 后代环路检查需多次 `selectById`，事务内可能产生几次小查询；本期数据量低，不做缓存优化。
+
+### 并发
+
+- 用 `moduleMapper.updateById(entity)` 走 PK 更新；不引入乐观锁版本号（schema 没规划 `version` 列）。
+- 并发同时更新同一模块时遵循"后写覆盖"语义，可接受。需要更强一致性时另开 REQ。
+
+### 性能
+
+- 后代环路检查用迭代 BFS（队列），每次查 `selectList(eq("iParentId", ...))` 拿子节点；深度上限 5 层 + 单层节点数受限于业务，不做递归 SQL。
+
+### 错误码映射（与 docs/05 对齐）
+
+| 场景 | 错误码 |
+|---|---|
+| 必填字段缺失 / 类型错误 / 长度超限 / 枚举非法 | `40010` |
+| `{id}` 模块不存在或已软删除 | `40421` |
+| `iParentId` 指向不存在 / 已删模块 | `40411` |
+| `iParentId == {id}` 或为 `{id}` 的后代 | `40921` |
+| 服务端兜底 | `50000` |
+
+> docs/05 列出的 `40911`（sProcedureName 冲突）在本实现里不会触发（DTO 不接受 sProcedureName）；保留契约文档不变即可。
+> 新增错误码 `40921` 需补到 `ErrorCode` 枚举（命名 `MOD_PARENT_LOOP`）；`40421` 命名 `MOD_NOT_FOUND`。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tModule`（详见 docs/03 § tModule）
+
+| 字段 | 行为 |
+|---|---|
+| `iIncrement` | 路径参数 `{id}` 定位行，**不修改** |
+| `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `sCreatedBy` | **不修改** |
+| `sDisplayType` | 入参覆盖 |
+| `sProcedureName` | **不修改**（保留原值） |
+| `sModuleType` | 入参覆盖 |
+| `sManageDeptEn` | 入参覆盖 |
+| `bShowPermission` | 入参非 null 覆盖；null 保留 |
+| `sModuleNameZh` | 入参覆盖 |
+| `iParentId` | 入参覆盖（含 null 设根） |
+| `iSortOrder` | 入参非 null 覆盖；null 保留 |
+| `bDeleted` / `tDeletedDate` / `sDeletedBy` | **不修改** |
+
+**索引利用**：
+- 主键定位 `{id}`
+- `idx_parent` / `fk_module_parent`：iParentId 校验时按父链 / 子链查询
+
+**外键**：`fk_module_parent` 仍兜底；应用层环路检查在写入前显式拦截。
+
+## 依赖的接口
+
+无（本接口独立工作；与 REQ-MOD-001 并列同模块同 schema）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 全量更新非父字段**：传入合法的 7 个字段（不含 `iParentId` 自引用），返回 200 + 最新 VO；DB 中查询新值与入参一致；`sProcedureName` / `tCreateDate` 与原值相同。
+2. **正向 — 设置父模块**：先建 root + child，再 `PUT /api/modules/{child_id}` 把 `iParentId` 改到另一个 sibling；返回 200，DB 中 `iParentId` 更新成功。
+3. **正向 — 清空父模块（设为根）**：`PUT` 时显式传 `"iParentId": null`，DB 中 `iParentId` 变 NULL。
+4. **正向 — 部分字段保留原值**：DTO 中 `bShowPermission` / `iSortOrder` 传 null，DB 中保留原值。
+5. **目标不存在**：`PUT /api/modules/999999`，返回 200 + `code=40421`。
+6. **目标已软删除**：先把模块 `bDeleted` 置 1（直接 DB UPDATE 模拟），再 `PUT`，返回 `40421`。
+7. **必填缺失**：DTO 缺 `sModuleNameZh`，返回 `40010`。
+8. **枚举非法**：`sDisplayType="X"`，返回 `40010`。
+9. **长度超限**：`sModuleType` = 51 字符，返回 `40010`。
+10. **iParentId 自引用**：`PUT /api/modules/{id}` 把 `iParentId` 设为 `{id}` 本身，返回 `40921`。
+11. **iParentId 不存在**：`PUT` 时 `iParentId=999999`，返回 `40411`。
+12. **iParentId 是后代**：祖父→父→子三层结构，`PUT` 祖父把 `iParentId` 设为子的 id，返回 `40921`。
+13. **sProcedureName 字段被忽略**：客户端误传 `sProcedureName="other"`，DB 中该字段保持原值。
+
+### 接口契约一致性
+
+- 响应格式严格符合 `{code, message, data, timestamp}`（docs/05 § 全局约定）。
+- 错误码段位与 docs/05 一致：`40010` / `40411` / `40421` / `40921` / `50000`。
+- 异常堆栈不出现在响应里。
+
+### 测试覆盖
+
+- **单元测试** `ModuleServiceImplTest`（继续 mock ModuleMapper）：
+  - update_targetNotFound_throws40421
+  - update_targetSoftDeleted_throws40421
+  - update_parentSelfReference_throws40921
+  - update_parentNotFound_throws40411
+  - update_parentIsDescendant_throws40921
+  - update_full_returnsVOWithUpdatedFields（断言传给 mapper.updateById 的 entity 字段值，包括 sProcedureName 保留）
+  - update_partialNullFields_keepsOriginalValues
+  - update_clearParent_setsParentToNull
+
+- **集成测试** `ModuleControllerIT` 追加（`@Transactional` 自动回滚；用 ModuleMapper 直接预置数据）：
+  - put_validUpdate_returns200
+  - put_setParentToNull_clearsParent
+  - put_targetNotFound_returns40421
+  - put_parentNotFound_returns40411
+  - put_parentSelfRef_returns40921
+  - put_parentIsDescendant_returns40921
+  - put_missingRequired_returns40010
+  - put_ignoresProcedureNameField_doesNotChange
+
+### 代码与文档
+
+- `// REQ-MOD-002` 注释贴在 Controller 方法、Service 方法、新增 ErrorCode 枚举常量上。
+- 提交按 `feat(mod): <subject> REQ-MOD-002` 规范，每 Task 一个 commit。
+- 不引入 docs/04 § 零 技术栈外的依赖。
+---
+req_id: REQ-MOD-003
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-003 — 模块删除
+
+## 目标
+
+实现后端 `DELETE /api/modules/{id}` 接口：对指定模块做**软删除**（写入 `bDeleted=1` / `tDeletedDate=now` / `sDeletedBy=NULL`），并在删除前校验子模块引用，避免破坏树结构完整性。
+
+## 输入 / 触发
+
+**接口**：`DELETE /api/modules/{id}`，无请求体。`{id}` = `tModule.iIncrement`。
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:DELETE`。本 REQ 沿用 SecurityConfig permitAll；Controller 上写 Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:DELETE')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "bDeleted": true
+  },
+  "timestamp": 1746528600000
+}
+```
+
+返回精简 VO：仅 `iIncrement` + `bDeleted`，足以让前端在表格里直接更新该行的删除标记。新增 `ModuleDeleteResultVO` 单独承载该结构（避免复用 `ModuleVO` 暴露不必要字段）。
+
+## 业务规则
+
+1. **目标存在且未被软删除**：`SELECT iIncrement, bDeleted FROM tModule WHERE iIncrement = {id}`。`null` 或 `bDeleted = 1` → `BizException(MOD_NOT_FOUND)` (40421)。
+2. **子模块引用检查**：`SELECT COUNT(*) FROM tModule WHERE iParentId = {id} AND bDeleted = 0`。`> 0` → `BizException(MOD_HAS_REFERENCES)` (40912)。
+3. **外部业务引用**：本期 schema 无其他业务表通过 FK 引用 `tModule`（V1 SQL 中无外部 FK 指向 tModule）。本 REQ 仅检查子模块；后续若新增模块引用 tModule（如菜单 / 权限分配），需在该模块的 service 层追加引用检查并复用 `MOD_HAS_REFERENCES`。
+4. **软删除字段写入**：
+   - `bDeleted = 1`
+   - `tDeletedDate = LocalDateTime.now()`
+   - `sDeletedBy = NULL`（REQ-USR-004 后由登录上下文回填）
+   - 其他字段保持原值
+5. **已删除模块不可再删**：bDeleted=1 直接走 40421（与 #1 等效）。
+6. **重复请求语义**：连续两次 DELETE 同一 id，第一次成功（200 + bDeleted=true），第二次 40421。**非幂等**——但响应可预测，不会破坏数据。
+7. **事务边界**：service 方法 `@Transactional`，校验 + 软删除单事务内完成。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 REQ-MOD-001/002 SecurityConfig permitAll。
+
+### 错误码映射
+
+| 场景 | 错误码 | ErrorCode 枚举常量 |
+|---|---|---|
+| `{id}` 不存在或已软删除 | 40421 | `MOD_NOT_FOUND`（已存在） |
+| 存在未软删除子模块 | 40912 | `MOD_HAS_REFERENCES`（**新增**） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+### 并发
+
+- 用 `moduleMapper.update(entity, wrapper)` 加 `bDeleted = 0` 条件，让"两个并发删除"中只有一个能写成功（影响行数 1），另一个影响 0 行。Service 检查影响行数：`= 0` → 返回 40421（视为已被并发删除）。
+- 不引入乐观锁版本号。
+
+### 性能
+
+- 子模块计数走 `idx_parent` 索引，O(1)。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tModule`
+
+| 字段 | 行为 |
+|---|---|
+| `iIncrement` | 路径参数 `{id}` 定位行，**不修改** |
+| `bDeleted` | 0 → 1 |
+| `tDeletedDate` | 写入 `LocalDateTime.now()` |
+| `sDeletedBy` | 写入 `NULL`（REQ-USR-004 后回填） |
+| 其他全部字段 | **不修改** |
+
+**索引利用**：
+- `pk_module`：定位 `{id}`
+- `idx_parent`：子模块计数
+
+**外键**：本期无其他表 FK 指向 tModule，无需额外检查。
+
+## 依赖的接口
+
+无（独立接口）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 叶子模块删除**：先建一个无子模块的 root，DELETE，返回 200 + `data.iIncrement` + `data.bDeleted=true`。DB 中 `bDeleted=1` / `tDeletedDate` 非空 / `sDeletedBy=NULL` / 其他字段保持原值。
+2. **正向 — 删除后再 GET 列表（REQ-MOD-004）跳过该模块**：本 REQ 不实现 GET，但通过 `selectById` 后断言查询接口的过滤效果。
+3. **目标不存在**：DELETE `/api/modules/999999`，返回 `40421`。
+4. **目标已软删除**：手工 update bDeleted=1 后 DELETE，返回 `40421`。
+5. **存在未删除子模块**：先建 parent + child，DELETE parent，返回 `40912`；DB 中 parent.bDeleted 仍为 0。
+6. **存在已删除子模块（不阻塞）**：先建 parent + child，DELETE child（成功），再 DELETE parent，应成功（已删子模块不计入引用）。
+7. **重复 DELETE**：第二次返回 40421。
+8. **响应 VO 字段精简**：仅含 iIncrement + bDeleted（断言 sDisplayType / sProcedureName 等不在响应里）。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`。
+- 错误码：200 / 40421 / 40912 / 50000。
+- 不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `ModuleServiceImplTest` 追加（mock ModuleMapper）：
+  - delete_targetNotFound_throws40421
+  - delete_targetAlreadyDeleted_throws40421
+  - delete_hasUndeletedChildren_throws40912
+  - delete_leafModule_writesSoftDeleteFields_returnsResult
+  - delete_softDeletedChildren_doesNotBlock
+  - delete_concurrentRace_throws40421（mock update 影响 0 行）
+
+- **集成测试** `ModuleControllerIT` 追加：
+  - delete_validLeaf_returns200WithBDeletedTrue（先 mapper.insert，再 DELETE，再 selectById 验证 bDeleted=true / tDeletedDate 非空）
+  - delete_targetNotFound_returns40421
+  - delete_targetAlreadyDeleted_returns40421
+  - delete_hasUndeletedChildren_returns40912
+  - delete_softDeletedChildren_doesNotBlock_returns200
+  - delete_responseVOContainsOnlyIIncrementAndBDeleted
+
+### 代码与文档
+
+- `// REQ-MOD-003 模块删除` 注释贴在 Controller 方法、Service 方法、新增 ErrorCode 枚举常量上。
+- 提交按 `feat(mod): <subject> REQ-MOD-003` 规范。
+- 不引入 docs/04 § 零 技术栈外的依赖。
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-004 — 模块查询
+
+## 目标
+
+实现后端 `GET /api/modules` 接口：以**树形结构**返回所有未软删除的模块，可选按 `sModuleNameZh` 模糊匹配过滤；过滤命中时同时保留命中节点的所有**祖先路径**以便定位上下文。
+
+## 输入 / 触发
+
+**接口**：`GET /api/modules`，无请求体。
+
+**Query parameters**：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 |
+|---|---|---|---|
+| `keyword` | String | 否 | 长度 ≤ 50；非空时对 `sModuleNameZh` 做 `LIKE '%keyword%'`（不区分大小写——MySQL `utf8mb4_unicode_ci` 默认行为） |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:READ`。沿用 SecurityConfig permitAll；Controller Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:READ')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": [
+    {
+      "iIncrement": 1,
+      "sModuleNameZh": "系统配置",
+      "sDisplayType": "系统配置",
+      "sManageDeptEn": "IT",
+      "iParentId": null,
+      "iSortOrder": 0,
+      "children": [
+        {
+          "iIncrement": 2,
+          "sModuleNameZh": "用户管理",
+          "sDisplayType": "前端业务",
+          "sManageDeptEn": "IT",
+          "iParentId": 1,
+          "iSortOrder": 1,
+          "children": []
+        }
+      ]
+    }
+  ],
+  "timestamp": 1746528600000
+}
+```
+
+`data` 是根节点数组（`iParentId == null` 的节点）；每个节点带 `children` 数组（同结构递归）。
+
+新增 VO `ModuleTreeNodeVO`：字段 `iIncrement` / `sModuleNameZh` / `sDisplayType` / `sManageDeptEn` / `iParentId` / `iSortOrder` / `children: List<ModuleTreeNodeVO>`。
+
+> **不返回的字段**（避免泄露内部）：`sProcedureName` / `sModuleType` / `bShowPermission` / `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `sCreatedBy` / `bDeleted` / `tDeletedDate` / `sDeletedBy`。如未来 REQ 需要其中字段，再扩 VO。
+
+## 业务规则
+
+1. **范围过滤**：`bDeleted = 0`（默认仅返回未软删除）。
+2. **空 keyword**：返回所有未软删除模块构成的完整树。
+3. **非空 keyword**：
+   - 步骤 a：在所有未软删除模块中找出 `sModuleNameZh LIKE '%keyword%'` 的命中集合 `hits`。
+   - 步骤 b：对每个 `hit`，沿 `iParentId` 链向上收集所有未软删除祖先（深度上限 5 与 docs/03 § tModule 一致），并入结果集合。
+   - 步骤 c：用结果集合在内存中按 `iParentId` 组装树。
+   - 命中节点本身的子孙不会被强制纳入（除非也命中）；这样避免一次过滤拉出整棵子树。
+4. **排序**：同级节点按 `iSortOrder ASC` 升序，`iSortOrder` 相同则按 `iIncrement ASC`（确定性排序）。
+5. **`children` 字段**：叶子节点为 `[]`，不为 `null`（确保前端可直接 `.map`）。
+6. **空结果**：keyword 无匹配 → `data = []`，**HTTP 200 + code=200**，不返回 404 类错误。
+7. **只读**：本接口不写库，无事务要求；标 `@Transactional(readOnly = true)`。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 REQ-MOD-001/002/003 SecurityConfig permitAll。
+
+### 错误码
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| `keyword` 长度 > 50 | 40010 | `PARAM_INVALID`（已存在） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+### 性能
+
+- 单次 `selectList(LambdaQueryWrapper.eq(bDeleted, false))` 拉取所有未删除模块；spec § 性能上限 docs/03 注明"单次返回不超过 500 项 / 树深度上限 5 层"，本期数据量低不分页。
+- 在内存里 O(N) 建索引（id → entity）+ O(N) 建子节点列表 + O(N) 排序 + O(K * D) 沿祖先链向上（K=hits 数，D=深度上限 5）。
+- 不引入 SQL 递归 CTE / 自连接；保持 mapper 层轻量。
+
+### 大小写敏感
+
+`utf8mb4_unicode_ci` collation 默认不区分大小写。MyBatis-Plus `LambdaQueryWrapper.like(...)` 走 SQL `LIKE`，行为与 collation 一致。无需额外处理。
+
+### keyword 中的特殊字符
+
+`%` / `_` 在 SQL `LIKE` 模式里是通配符。简化处理：本期不做转义（业务模块名通常不含这些字符）；如未来需要，service 层先把 keyword 中的 `%` / `_` / `\` 替换为转义形式（`MyBatis-Plus 5.x` 的 `like` 已自带 escape，本期 3.5.7 需手动）。**本 REQ 暂不处理转义**，作为已知边界记录。
+
+## 依赖的 schema 表 / 字段
+
+**读表**：`tModule`
+
+| 字段 | 用途 |
+|---|---|
+| `iIncrement` | 节点 id；输出 |
+| `sModuleNameZh` | 模糊匹配列；输出 |
+| `sDisplayType` | 输出 |
+| `sManageDeptEn` | 输出 |
+| `iParentId` | 父子关系；输出 |
+| `iSortOrder` | 排序；输出 |
+| `bDeleted` | 过滤未删除（=0） |
+
+**索引利用**：
+- `idx_module_name_zh`：`LIKE '%keyword%'` 实际不走索引（左模糊），但本期数据量低可接受。
+- `idx_parent`：祖先链查询时按 iIncrement PK 走 selectById，不用 idx_parent。
+- `idx_module_deleted`（未单独建，但 bDeleted 在多个 idx 中已有）：bDeleted 过滤时 MySQL 优化器自行选择。
+
+**外键**：本接口只读，不触发 FK 检查。
+
+## 依赖的接口
+
+无（独立查询接口）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 空 keyword 返回完整树**：DB 中 5 棵根 + 多层子模块；GET 返回 5 个根节点，子孙完整嵌套；同级按 iSortOrder 升序。
+2. **正向 — keyword 模糊匹配 + 祖先**：DB 有 root("系统配置") → 子("用户管理") → 孙("登录")；GET `?keyword=登录` 返回 root → 子 → 孙 三层（即命中节点 + 全部祖先）。
+3. **正向 — keyword 部分匹配**：keyword="管理"，匹配多个节点；返回它们各自完整祖先链合并的树。
+4. **正向 — 软删除模块过滤**：DELETE 一个模块后再查，结果不含该模块。
+5. **正向 — 空结果**：keyword="不存在的关键词"，返回 `data=[]` + code=200。
+6. **正向 — keyword 含中英混合**：keyword="user 用户" 也走 LIKE '%user 用户%'（与 spec § 业务规则 3 一致；不拆词）。
+7. **同级排序**：两根 iSortOrder=2/1，返回顺序 1 在前。
+8. **children 字段**：叶子节点 children 是 `[]` 而非 null（jsonPath 断言）。
+9. **keyword 长度超限**：keyword=51 字符，返回 `code=40010`。
+10. **无登录也可访问**（permitAll 阶段）：直接 GET 不带 Authorization 返回 200。
+11. **响应字段精简**：响应不含 sProcedureName / sModuleType / bShowPermission / 标准列等内部字段（jsonPath 断言）。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`。
+- 错误码 200 / 40010 / 50000。
+- 不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `ModuleServiceImplTest` 追加（mock ModuleMapper）：
+  - tree_emptyDb_returnsEmptyList
+  - tree_singleRoot_returnsOneNodeWithEmptyChildren
+  - tree_multiLevel_buildsNestedStructureSortedByISortOrder
+  - tree_keywordHit_includesAncestorChain
+  - tree_keywordNoMatch_returnsEmptyList
+  - tree_softDeletedExcluded（mapper 已过滤；service 不重复过滤）
+
+- **集成测试** `ModuleControllerIT` 追加：
+  - get_emptyKeyword_returnsAllUndeletedAsTree
+  - get_keyword_filtersByModuleNameZhWithAncestors
+  - get_keywordNoMatch_returnsEmptyArray
+  - get_keywordTooLong_returns40010
+  - get_softDeletedNotInResult
+  - get_responseExcludesInternalFields
+  - get_leafNodeChildrenIsEmptyArrayNotNull
+
+### 代码与文档
+
+- `// REQ-MOD-004` 注释贴在 Controller / Service / VO。
+- 提交按 `feat(mod): <subject> REQ-MOD-004` 规范。
+---
+req_id: REQ-USR-001
+date: 2026-05-06
+module: module_usr
+---
+
+# Spec: REQ-USR-001 — 用户新增
+
+## 目标
+
+实现后端 `POST /api/users` 接口：录入新用户基本信息 + 员工关联（可选）+ 权限组关联，密码默认 `666666` 经 BCrypt 哈希后落库；返回 `iIncrement` + 用户 VO（不含密码哈希）。
+
+## 输入 / 触发
+
+**接口**：`POST /api/users`，Content-Type `application/json`。
+
+**Request body**（`UserCreateDTO`）字段：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 | 落库列 |
+|---|---|---|---|---|
+| `sUserNo` | String | 是 | 长度 1-50；`bDeleted=0` 范围内系统内唯一 | `tUser.sUserNo` |
+| `sUserName` | String | 是 | 长度 1-50；`bDeleted=0` 范围内系统内唯一（登录账号） | `tUser.sUserName` |
+| `iStaffId` | Integer | 否 | 必须指向存在且未软删除的 `tStaff.iIncrement` | `tUser.iStaffId` |
+| `sUserType` | String | 是 | 枚举：`普通用户` / `超级管理员` | `tUser.sUserType` |
+| `sLanguage` | String | 是 | 枚举：`zh` / `en` / `zh-TW` | `tUser.sLanguage` |
+| `bCanModifyDocs` | Boolean | 否 | 默认 `false` | `tUser.bCanModifyDocs` |
+| `permissionCategoryIds` | List<Integer> | 否 | 每个元素须指向存在且未软删除的 `tPermissionCategory.iIncrement`；可空数组（无授权） | 写入 `tUserPermission` 关联表 |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + `USR:CREATE`。沿用 module_mod 的 SecurityConfig permitAll；Controller Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:CREATE')")`。
+
+> **密码不在 DTO 里**：默认 `666666` 经 `org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder` 哈希后落库。BCrypt 已经在 spring-boot-starter-security 中包含，无需新增依赖。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "sUserNo": "u001",
+    "sUserName": "alice",
+    "iStaffId": 7,
+    "sUserType": "普通用户",
+    "sLanguage": "zh",
+    "bCanModifyDocs": false,
+    "tCreateDate": "2026-05-06T10:30:00",
+    "bDeleted": false,
+    "permissionCategoryIds": [1, 2, 3]
+  },
+  "timestamp": 1746528600000
+}
+```
+
+新建 VO `UserVO`：字段 `iIncrement` / `sUserNo` / `sUserName` / `iStaffId` / `sUserType` / `sLanguage` / `bCanModifyDocs` / `tCreateDate` / `bDeleted` / `permissionCategoryIds`（聚合自 tUserPermission）。
+
+**不返回**：`sPasswordHash` / `sId` / `sBrandsId` / `sSubsidiaryId` / `sCreatedBy` / `tLastLoginDate` / `tDeletedDate` / `sDeletedBy`。
+
+## 业务规则
+
+1. **唯一性**：`sUserNo` 与 `sUserName` 在 `bDeleted=0` 范围内系统内全局唯一。冲突 → `BizException(USR_USER_NAME_OR_NO_DUP)` (40921)。
+2. **职员校验**：若 `iStaffId` 非空，必须 `selectById(iStaffId)` 存在且 `bDeleted=0`；不存在或已删 → `BizException(STAFF_NOT_FOUND)` (40421)。
+3. **权限分类校验**：若 `permissionCategoryIds` 非空，每个 id 都要存在且未软删除（一次 `selectBatchIds` 一次性校验）；任一不存在 → `BizException(PERM_CATEGORY_NOT_FOUND)` (40422)。
+4. **密码哈希**：固定初始密码字符串 `"666666"` → `BCryptPasswordEncoder().encode("666666")` → 落 `tUser.sPasswordHash`。`BCryptPasswordEncoder` 注册为 Spring Bean（`PasswordConfig`）便于 REQ-USR-004 复用。
+5. **关联表写入**：`tUserPermission` 按 `permissionCategoryIds` 逐条 `insert`（每条 `iUserId=新用户 id` / `iCategoryId=对应分类 id` / `tCreateDate=now`；docs/03 修订版无 bSelected 列，**关联记录存在即「已选」**）。
+6. **新建记录初始状态**：`bDeleted=0`、`tDeletedDate=NULL`、`sDeletedBy=NULL`、`tCreateDate=LocalDateTime.now()`、`tLastLoginDate=NULL`、`sCreatedBy=NULL`（多租户/登录上下文未引入）、`sBrandsId=NULL`、`sSubsidiaryId=NULL`、`sId=NULL`。
+7. **事务边界**：`@Transactional(rollbackFor = Exception.class)` 包住 用户校验 + 用户 insert + 权限关联批量 insert 三步；任一失败整体回滚。
+8. **并发兜底**：DB 唯一索引 `uk_user_no` / `uk_user_name` 兜底唯一性；service 捕 `DuplicateKeyException` 映射为 `USR_USER_NAME_OR_NO_DUP`。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 module_mod 的 SecurityConfig permitAll。注释 `// REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:CREATE')")`。
+
+### 错误码映射
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| 必填缺失 / 类型 / 长度 / 枚举非法 | 40010 | `PARAM_INVALID`（已存在） |
+| `iStaffId` 不存在 / 已删除 | 40421 | `STAFF_NOT_FOUND`（**新增**） |
+| `permissionCategoryIds` 任一不存在 / 已删除 | 40422 | `PERM_CATEGORY_NOT_FOUND`（**新增**） |
+| `sUserNo` / `sUserName` 唯一冲突 | 40921 | `USR_USER_NAME_OR_NO_DUP`（**新增**） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+> docs/05 § REQ-USR-001 中列的错误码 `40020` / `40921` / `40421` / `40422` —— 段位约定 `40020` 是 USR 模块的参数错（非 MOD 模块的 `40010`）。本 spec **统一沿用 `40010` 作为参数错（与 GlobalExceptionHandler 现有映射一致）**，避免在两套段位里折腾。docs/05 后续 sweep 时再统一对齐。
+
+### 性能 / 并发
+
+- 单条用户 + 至多 N 条权限关联 insert，预期低并发。`uk_user_no` / `uk_user_name` 唯一约束兜底。
+- `permissionCategoryIds` 批量校验用 `selectBatchIds` 单次 SQL，O(1) round-trip。
+
+### 字符集 / 长度
+
+- utf8mb4，允许中文姓名 / 用户名（虽然多数业务侧用英文）。
+- 长度超 schema 上限 → 视为参数错 40010。
+
+### 与 docs/04 § 1.4 / 3.5 一致性
+
+- 异常走 GlobalExceptionHandler。
+- BCryptPasswordEncoder bean 不硬编码 strength（默认 10），从 application.yml 读取 strength（暂留默认）。
+
+### 已知技术债
+
+- **`sCreatedBy=NULL`**：REQ-USR-004 引入登录上下文后回填。
+- **多租户字段 NULL**：与 module_mod 一致，REQ-USR-004 后由拦截器注入。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tUser`、`tUserPermission`
+
+**读表**：`tStaff`（关联校验 / 后续 REQ-USR-003 列表 join）、`tPermissionCategory`（关联校验 / 列表只读字典）
+
+| `tUser` 字段 | 落库逻辑 |
+|---|---|
+| `iIncrement` | DB AUTO_INCREMENT |
+| `sUserNo` / `sUserName` | 入参（必填，唯一） |
+| `iStaffId` | 入参（可选；FK 校验通过的 `tStaff.iIncrement`） |
+| `sUserType` / `sLanguage` | 入参（必填，枚举） |
+| `bCanModifyDocs` | 入参（可选，默认 false） |
+| `sPasswordHash` | BCrypt("666666") |
+| `tCreateDate` | LocalDateTime.now() |
+| `tLastLoginDate` / `sCreatedBy` / 多租户 / `sId` / `bDeleted` 三件套 | 见 § 业务规则 6 |
+
+| `tUserPermission` 字段 | 落库逻辑 |
+|---|---|
+| `iIncrement` | DB AUTO_INCREMENT |
+| `iUserId` | 新用户 iIncrement |
+| `iCategoryId` | dto.permissionCategoryIds[i] |
+| `tCreateDate` | LocalDateTime.now() |
+| `sCreatedBy` | NULL（REQ-USR-004 后回填） |
+| 多租户 / `sId` | NULL |
+
+**索引利用**：
+- `uk_user_no` / `uk_user_name`（UNIQUE）：用户唯一性预检 + 兜底
+- `uk_user_perm` (UNIQUE iUserId+iCategoryId)：防重复授权（应用层不会触发，DB 兜底）
+
+**外键**：
+- `fk_user_staff`（tUser.iStaffId → tStaff.iIncrement）：应用层先查再 insert，避免直接抛 SQL 完整性异常
+- `fk_up_user`（tUserPermission.iUserId → tUser.iIncrement）：CASCADE，本接口无需关心
+- `fk_up_category`（tUserPermission.iCategoryId → tPermissionCategory.iIncrement）：应用层先 selectBatchIds 再 insert
+
+## 依赖的接口
+
+无（本接口独立工作）。
+
+REQ-USR-002 / 003 / 004 都会读 tUser，但不依赖本接口运行时 — 仅依赖本接口建立的数据。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 最小字段（无 staff、无权限）**：传入 sUserNo / sUserName / sUserType / sLanguage 必填，返回 200 + `data.iIncrement` + 默认 bCanModifyDocs=false / permissionCategoryIds=[]；DB 中 sPasswordHash 为 BCrypt 哈希（不等于 "666666" 明文）。
+2. **正向 — 含 staff + 权限**：传入合法 iStaffId + 3 个 permissionCategoryIds，返回 200；DB tUser.iStaffId 等于入参；tUserPermission 中存在 3 条关联（iUserId=新用户）。
+3. **唯一性冲突 — sUserName**：先建一个 sUserName=alice 的用户，再用同 sUserName 提交，返回 40921。
+4. **唯一性冲突 — sUserNo**：同上，sUserNo 冲突。
+5. **iStaffId 不存在**：传入 iStaffId=999999，返回 40421。
+6. **iStaffId 已软删除**：先建 staff 后置 bDeleted=1，再 POST，返回 40421。
+7. **permissionCategoryIds 任一不存在**：传入 [1, 999999]，返回 40422，且 DB 中 tUser 与 tUserPermission 都未写入（事务回滚）。
+8. **必填缺失 / 枚举非法 / 长度超限**：返回 40010。
+9. **空 permissionCategoryIds**：传 `[]` 或不传该字段，正向通过（无关联记录）。
+10. **密码哈希不可逆**：直接读 DB sPasswordHash，断言以 `$2a$` 或 `$2b$` 开头（BCrypt 标准前缀），且不含 "666666" 明文。
+11. **响应不暴露 sPasswordHash**：jsonPath `$.data.sPasswordHash` doesNotExist。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`。
+- 不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `UserServiceImplTest`：mock UserMapper / StaffMapper / PermissionCategoryMapper / UserPermissionMapper / BCryptPasswordEncoder
+  - create_minimalFields_returnsVOWithBCryptHash
+  - create_withStaffAndPermissions_writesAssociation
+  - create_duplicateUserName_throws40921
+  - create_duplicateUserNo_throws40921
+  - create_staffNotFound_throws40421
+  - create_staffSoftDeleted_throws40421
+  - create_permissionCategoryNotFound_throws40422
+  - create_emptyPermissionCategoryIds_doesNotInsertAssociation
+  - create_concurrentDuplicate_dupKeyException_mappedTo40921
+- **集成测试** `UserControllerIT`：
+  - post_minimalFields_returns200
+  - post_withStaffAndPermissions_returns200_andDbAssociated
+  - post_duplicateUserName_returns40921
+  - post_staffNotFound_returns40421
+  - post_permissionCategoryNotFound_returns40422
+  - post_passwordHashedInDb_notPlaintext
+  - post_responseExcludesSPasswordHash
+
+### 代码与文档
+
+- `// REQ-USR-001` 注释贴在 Controller / Service / 新增 ErrorCode / DTO / VO。
+- 提交按 `feat(usr): <subject> REQ-USR-001` 规范。
+- 不引入 docs/04 § 零 技术栈外的依赖（BCryptPasswordEncoder 已在 spring-boot-starter-security 中）。
+---
+req_id: REQ-USR-002
+date: 2026-05-06
+module: module_usr
+---
+
+# Spec: REQ-USR-002 — 用户修改
+
+## 目标
+
+实现后端 `PUT /api/users/{id}` 接口：在不破坏唯一性的前提下，更新已有用户的可编辑字段（含权限组关联），返回最新 UserVO（不含 sPasswordHash）。
+
+## 输入 / 触发
+
+**接口**：`PUT /api/users/{id}`，Content-Type `application/json`。`{id}` = `tUser.iIncrement`。
+
+**Request body**（`UserUpdateDTO`）字段——与 REQ-USR-001 输入相比**剥除 `sUserNo` / `sUserName`**（不可改，登录身份固定）；其余字段均可修改：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 | 行为 |
+|---|---|---|---|---|
+| `iStaffId` | Integer | 否 | 必须指向存在且未软删除的 `tStaff.iIncrement`；显式 `null` 表示清空员工关联 | 覆盖 |
+| `sUserType` | String | 是 | 枚举：`普通用户` / `超级管理员` | 覆盖 |
+| `sLanguage` | String | 是 | 枚举：`zh` / `en` / `zh-TW` | 覆盖 |
+| `bCanModifyDocs` | Boolean | 否 | `null` 保持原值；显式覆盖 | 部分更新 |
+| `permissionCategoryIds` | List<Integer> | 否 | 每元素必须存在且未软删除；可空数组（清空所有授权） | 重建关联（先删后插，幂等） |
+
+> **不在 DTO 中**：`sUserNo`（用户号唯一不可改）、`sUserName`（登录账号唯一不可改）、`sPasswordHash`（密码不通过本接口修改）。Jackson 默认忽略未知字段。
+> 前端 UI 应把这些字段渲染为只读。
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + `USR:UPDATE`。沿用 SecurityConfig permitAll；Controller Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:UPDATE')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**复用 REQ-USR-001 的 `UserVO`（10 个字段含 `permissionCategoryIds`），不暴露 sPasswordHash。
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "sUserNo": "u001",
+    "sUserName": "alice",
+    "iStaffId": 7,
+    "sUserType": "超级管理员",
+    "sLanguage": "en",
+    "bCanModifyDocs": true,
+    "tCreateDate": "2026-05-06T10:30:00",
+    "bDeleted": false,
+    "permissionCategoryIds": [1, 2]
+  },
+  "timestamp": 1746528600000
+}
+```
+
+## 业务规则
+
+1. **目标用户必须存在且未软删除**：`selectById(id)` 返回 null 或 `bDeleted=1` → `BizException(USR_NOT_FOUND)` (40431)。
+2. **`sUserNo` / `sUserName` / `sPasswordHash` 不可改**：DTO 不接受这些字段；service 层读取目标行后保留这三个字段不变。
+3. **iStaffId 校验**（仅当 dto.iStaffId 非空）：`staffMapper.selectById(...)` 不存在或 `bDeleted=true` → `BizException(STAFF_NOT_FOUND)` (40421)；显式 `null` 表示清空员工关联，不校验。
+4. **权限分类校验**（仅当 dto.permissionCategoryIds 非空）：每元素必须存在且未软删除（`selectBatchIds` 一次性查）；任一不存在 → `BizException(PERM_CATEGORY_NOT_FOUND)` (40422)。
+5. **权限组重建语义**：service 内**先删后插**——先 `userPermissionMapper.delete(eq(iUserId, {id}))` 清空目标用户所有现有关联，再按 `permissionCategoryIds` 顺序插入。空数组 / 不传则只删不插（清空授权）。
+6. **`bCanModifyDocs` / `iStaffId` 部分更新**：DTO 中 `null` 时——
+   - `bCanModifyDocs == null` → 保持原值；
+   - `iStaffId == null` → **显式清空**为 NULL（与"未传"语义一致；DTO 字段语义本就是"目标值"）。
+7. **保留字段**：`iIncrement` / `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `sCreatedBy` / `tLastLoginDate` / `bDeleted` / `tDeletedDate` / `sDeletedBy` 在本接口**不被修改**。
+8. **审计**：本期 schema 未规划"最近修改时间 / 修改人"列，不维护。
+9. **事务**：`@Transactional(rollbackFor = Exception.class)`，覆盖目标校验 → 父校验 → 权限校验 → user update → tUserPermission delete → tUserPermission insert，整体回滚。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 module_mod / REQ-USR-001 SecurityConfig permitAll。
+
+### 错误码映射
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| 必填缺失 / 类型 / 长度 / 枚举非法 | 40010 | `PARAM_INVALID`（已存在） |
+| `{id}` 用户不存在或已软删除 | 40431 | `USR_NOT_FOUND`（**新增**） |
+| `iStaffId` 不存在 / 已删除 | 40421 | `STAFF_NOT_FOUND`（已存在） |
+| `permissionCategoryIds` 任一不存在 / 已删除 | 40422 | `PERM_CATEGORY_NOT_FOUND`（已存在） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+> docs/05 § REQ-USR-002 中列的 40331（角色变更权限）涉及操作员角色权限模型，需要 SecurityContext + RBAC 才能落地，**REQ-USR-004 后再补**；本 REQ 不实施。
+
+### iStaffId 的 NULL 写入
+
+借鉴 REQ-MOD-002 经验：MyBatis-Plus 默认 update 跳过 null 字段，需让 `iStaffId` 字段加 `FieldStrategy.IGNORED` 才能把 NULL 写入 SQL。本期在 `UserEntity#iStaffId` 上加 `@TableField(value="iStaffId", updateStrategy=FieldStrategy.IGNORED)`。
+
+> 风险与 REQ-MOD-002 相同：未来 partial update 路径会埋雷。本 REQ 走 load-then-modify 全量回填，安全。
+
+### 权限组重建的并发
+
+- "先删后插"在事务内是原子的；`uk_user_perm` 唯一约束兜底。
+- 同一用户并发修改权限：MySQL 默认行级锁 + 事务隔离 → 后写覆盖（与 REQ-MOD-002 一致）。
+
+### 性能
+
+- `selectBatchIds` 单次 round-trip 校验 N 个权限分类。
+- `delete + insert` 为 N+1 次 SQL，本期不优化。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tUser`（主体字段更新）、`tUserPermission`（先删后插）
+
+**读表**：`tStaff`（iStaffId 校验）、`tPermissionCategory`（权限分类校验）
+
+| `tUser` 字段 | 行为 |
+|---|---|
+| `iIncrement` / `sUserNo` / `sUserName` / `sPasswordHash` / `tCreateDate` / `sCreatedBy` / `tLastLoginDate` / `sId` / 多租户 / `bDeleted` 三件套 | **不修改** |
+| `iStaffId` | 入参覆盖（含 null 设根；需 `FieldStrategy.IGNORED`） |
+| `sUserType` / `sLanguage` | 入参覆盖（必填） |
+| `bCanModifyDocs` | 入参非 null 覆盖；null 保留 |
+
+`tUserPermission` 操作：先 `delete(eq(iUserId, {id}))`，再按 `permissionCategoryIds` 顺序 `insert`（每条 `iUserId={id}` / `iCategoryId=...` / `tCreateDate=now`，无 bSelected）。
+
+**索引利用**：`uk_user_no` / `uk_user_name`（不会触发，因为本接口不改这两列）；`uk_user_perm`（兜底重复授权）。
+
+## 依赖的接口
+
+无（独立接口；REQ-USR-001 建立的体系完全复用）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 全字段更新**：先建一个用户（带 staff + 3 个权限），PUT 改 iStaffId（另一个 staff）+ sUserType + sLanguage + bCanModifyDocs + permissionCategoryIds（2 个新分类），返回 200；DB 中 user 字段更新；tUserPermission 替换为 2 条新关联（原 3 条已删）。
+2. **正向 — 清空 iStaffId**：PUT 时显式 `iStaffId=null`，DB user.iStaffId 变 NULL（验证 IGNORED 策略生效）。
+3. **正向 — 清空权限组**：PUT permissionCategoryIds=[]，DB tUserPermission 清空（按 iUserId）；返回 VO permissionCategoryIds=[]。
+4. **正向 — 保留字段**：先记录原 sUserNo / sUserName / sPasswordHash / tCreateDate；PUT 后查 DB 这 4 个字段保持原值。
+5. **正向 — 部分字段保留原值**：DTO 中 `bCanModifyDocs=null`，DB 保留原值（验证 NOT_NULL 策略生效）。
+6. **目标不存在**：`PUT /api/users/999999`，返回 40431。
+7. **目标已软删除**：先建 user 后置 bDeleted=1，PUT 返回 40431。
+8. **必填缺失 / 枚举非法 / 长度超限**：返回 40010。
+9. **iStaffId 不存在**：iStaffId=999999，返回 40421。
+10. **iStaffId 已软删除**：返回 40421。
+11. **permissionCategoryIds 任一不存在**：返回 40422；DB user 与 tUserPermission 都不变（事务回滚）。
+12. **sUserNo / sUserName / sPasswordHash 字段被忽略**：客户端误传 `sUserNo="hijack"` / `sUserName="hijack"` / `sPasswordHash="$2a$10$xxx"`，DB 中这 3 个字段保持原值。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`。
+- 错误码 200 / 40010 / 40421 / 40422 / 40431 / 50000。
+- 不暴露 sPasswordHash；不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `UserServiceImplTest` 追加（mock 5 个 mapper + PasswordEncoder）：
+  - update_targetNotFound_throws40431
+  - update_targetSoftDeleted_throws40431
+  - update_staffNotFound_throws40421
+  - update_staffSoftDeleted_throws40421
+  - update_permissionCategoryNotFound_throws40422
+  - update_full_returnsVOWithUpdatedFields_andRebuildsPermissions（捕 ArgumentCaptor，断言 user 字段保留 sUserNo/sUserName/sPasswordHash + 新值字段；断言 userPermissionMapper.delete 调一次 + insert 调 N 次）
+  - update_partialNullBCanModifyDocs_keepsOriginal
+  - update_clearStaffId_setsToNull
+  - update_emptyPermissionCategoryIds_clearsAllAssociations（delete 调一次 + insert 不调）
+
+- **集成测试** `UserControllerIT` 追加：
+  - put_validUpdate_returns200_andDbReflects
+  - put_clearStaffId_setsNull
+  - put_emptyPermissionCategoryIds_clearsAssociations
+  - put_targetNotFound_returns40431
+  - put_staffNotFound_returns40421
+  - put_permissionCategoryNotFound_returns40422
+  - put_missingRequired_returns40010
+  - put_ignoresProtectedFields_doesNotChangeUserNoOrName（body 含 sUserNo / sUserName / sPasswordHash 但 DB 中这三列保持原值）
+
+### 代码与文档
+
+- `// REQ-USR-002` 注释贴在 Controller 方法、Service 方法、新增 ErrorCode `USR_NOT_FOUND`。
+- 提交按 `feat(usr): <subject> REQ-USR-002`。
+---
+req_id: REQ-USR-003
+date: 2026-05-06
+module: module_usr
+---
+
+# Spec: REQ-USR-003 — 用户查询
+
+## 目标
+
+实现后端 `GET /api/users` 接口：按 `queryField` + `matchType` + `queryValue` 三件套对 `tUser` 进行过滤（含跨表 JOIN `tStaff` 取员工名 / 部门），分页返回精简 VO 列表。
+
+## 输入 / 触发
+
+**接口**：`GET /api/users`，无请求体。
+
+**Query parameters**（`UserQueryDTO`）：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 |
+|---|---|---|---|
+| `pageNum` | Integer | 否 | ≥1，默认 1 |
+| `pageSize` | Integer | 否 | 1-100，默认 20 |
+| `queryField` | String | 否 | 枚举：`username` / `staffname` / `userno` / `department` / `usertype` / `language` / `deleted` / `lastLoginDate` / `createdBy`；缺省视为不过滤 |
+| `matchType` | String | 否 | 枚举：`contains` / `notContains` / `equals`；默认 `contains` |
+| `queryValue` | String | 否 | 长度 ≤ 100；缺省视为不过滤；`deleted` 字段下视为 `'true' / 'false'` 字符串 |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + `USR:READ`。沿用 SecurityConfig permitAll；Controller Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('USR:READ')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "total": 42,
+    "list": [
+      {
+        "iIncrement": 12,
+        "sUserName": "alice",
+        "sStaffName": "张三",
+        "sUserNo": "u001",
+        "sDepartment": "研发部",
+        "sUserType": "普通用户",
+        "sLanguage": "zh",
+        "bDeleted": false,
+        "tLastLoginDate": "2026-05-06T09:00:00",
+        "sCreatedBy": "admin",
+        "tCreateDate": "2026-05-06T08:00:00"
+      }
+    ],
+    "pageNum": 1,
+    "pageSize": 20
+  },
+  "timestamp": 1746528600000
+}
+```
+
+新建 `UserListItemVO`（11 字段）+ 复用项目通用 `PageResult<T>`（4 字段：total / list / pageNum / pageSize；本期首次引入，作为 module_usr 横切组件）。
+
+> **不返回**：`sPasswordHash` / `sId` / `sBrandsId` / `sSubsidiaryId` / `iStaffId` / `bCanModifyDocs` / `tDeletedDate` / `sDeletedBy`。
+
+## 业务规则
+
+1. **范围过滤**：默认仅返回 `bDeleted=0` 用户**除非** `queryField=deleted` 且 `queryValue` 显式过滤——见规则 6。
+2. **跨表 JOIN**：`tUser LEFT JOIN tStaff ON tUser.iStaffId = tStaff.iIncrement AND tStaff.bDeleted = 0`；空关联字段（无 staff）展示为空字符串 `""`（VO 字段为 null）。
+3. **queryField 列映射**：
+
+   | queryField 值 | SQL 实际列 |
+   |---|---|
+   | `username` | `tUser.sUserName` |
+   | `staffname` | `tStaff.sStaffName` |
+   | `userno` | `tUser.sUserNo` |
+   | `department` | `tStaff.sDepartment` |
+   | `usertype` | `tUser.sUserType` |
+   | `language` | `tUser.sLanguage` |
+   | `deleted` | `tUser.bDeleted` |
+   | `lastLoginDate` | `tUser.tLastLoginDate` |
+   | `createdBy` | `tUser.sCreatedBy` |
+
+4. **matchType 映射**：
+
+   | matchType 值 | SQL 片段 |
+   |---|---|
+   | `contains`（默认） | `<col> LIKE '%' || queryValue || '%'` |
+   | `notContains` | `<col> NOT LIKE '%' || queryValue || '%'` |
+   | `equals` | `<col> = queryValue` |
+
+5. **空过滤值语义**：`queryField` 或 `queryValue` 缺省 / 空串 → 不附加该 WHERE 条件。
+6. **deleted 字段特殊处理**：当 `queryField=deleted` 时，`bDeleted=0` 的默认过滤不应用（让 `queryValue` 直接控制——`'false'` / `'0'` → bDeleted=0；`'true'` / `'1'` → bDeleted=1）。
+7. **排序**：按 `tUser.tCreateDate DESC, tUser.iIncrement DESC` 稳定排序。
+8. **分页**：MyBatis-Plus `Page<T>` + `selectPage` 标准分页；total 由 MP 自动计数。
+9. **只读**：`@Transactional(readOnly = true)`；不写库。
+10. **空结果**：`data.list = []` + `data.total = 0` + `code=200`，不返回 404。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 SecurityConfig permitAll。
+
+### 错误码映射
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| `pageSize` 超 1-100 / `queryField` / `matchType` 非枚举 / `queryValue` 长度超限 | 40010 | `PARAM_INVALID`（已存在） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+### 实现路径选择
+
+引入**自定义 XML SQL**（`UserMapper.xml`）：本期首次需要跨表 JOIN，纯 LambdaQueryWrapper 难以表达 LEFT JOIN + 动态 WHERE。在 `mapper/usr/UserMapper.xml` 添加 `searchUsers(IPage<UserListItemVO> page, @Param("query") UserQueryDTO query)` 方法，对应 ResultMap 映射到 `UserListItemVO`。
+
+XML SQL 草稿（写入 plan 锁定）：
+
+```xml
+<select id="searchUsers" resultType="com.xly.erp.module.usr.vo.UserListItemVO">
+  SELECT
+    u.iIncrement, u.sUserName, s.sStaffName, u.sUserNo,
+    s.sDepartment, u.sUserType, u.sLanguage, u.bDeleted,
+    u.tLastLoginDate, u.sCreatedBy, u.tCreateDate
+  FROM tUser u
+  LEFT JOIN tStaff s ON u.iStaffId = s.iIncrement AND s.bDeleted = 0
+  <where>
+    <if test="query.queryField != 'deleted'">
+      u.bDeleted = 0
+    </if>
+    <if test="query.queryField != null and query.queryField != '' and query.queryValue != null and query.queryValue != ''">
+      AND
+      <choose>
+        <when test="query.matchType == 'equals'">
+          ${col} = #{query.queryValue}
+        </when>
+        <when test="query.matchType == 'notContains'">
+          ${col} NOT LIKE CONCAT('%', #{query.queryValue}, '%')
+        </when>
+        <otherwise>
+          ${col} LIKE CONCAT('%', #{query.queryValue}, '%')
+        </otherwise>
+      </choose>
+    </if>
+  </where>
+  ORDER BY u.tCreateDate DESC, u.iIncrement DESC
+</select>
+```
+
+> `${col}` 由 service 层通过 enum 映射成实际列名后传入参数（**不是直接拼用户输入**——避免 SQL 注入）；queryField 不在白名单 → 抛 PARAM_INVALID。
+
+实际实现可能要把 `${col}` 替换逻辑放到 service：service 把 queryField 翻译为列字符串放进 query 对象的临时字段（如 `query.setColumn(...)`），XML 用 `${query.column}` 渲染——XMl `${...}` 直接拼接字符串，服务层先白名单校验。
+
+### 性能
+
+- LEFT JOIN tStaff 走 `tUser.iStaffId` 上的索引（`fk_user_staff`）。
+- `LIKE '%X%'` 左模糊不走索引；本期数据量低可接受。
+- MP `Page<T>` 走 PaginationInnerInterceptor，需要在 `MybatisPlusConfig` 注册（如已存在跳过；如未引入，本 REQ 引入）。
+
+### Bean Validation
+
+`UserQueryDTO` 用 `@Min(1) Integer pageNum`、`@Min(1) @Max(100) Integer pageSize`、`@Pattern` 校验枚举字段。Controller 用 `@Valid`（query 参数 bean 绑定）。
+
+## 依赖的 schema 表 / 字段
+
+**读表**：`tUser`（主体）+ `tStaff`（LEFT JOIN）
+
+| `tUser` 字段 | 用途 |
+|---|---|
+| 全部 11 个输出字段 + `bDeleted` 过滤 | SELECT + WHERE |
+| `iStaffId` | LEFT JOIN 键 |
+
+| `tStaff` 字段 | 用途 |
+|---|---|
+| `iIncrement` | LEFT JOIN 键 |
+| `sStaffName` / `sDepartment` | SELECT + 可选 WHERE |
+| `bDeleted` | LEFT JOIN 时附加条件 (s.bDeleted=0) |
+
+**索引利用**：
+- `pk_user`：分页 ORDER BY iIncrement
+- `fk_user_staff`（隐式 BTREE on `iStaffId`）：JOIN
+- `uk_user_no` / `uk_user_name`：equals 匹配能走索引
+
+## 依赖的接口
+
+无（独立查询接口）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **空查询返回所有未删除用户**：DB 有 5 个 user（含 1 个 bDeleted=1），GET 不带 queryField 返回 4 个未删除（含 LEFT JOIN 出来的 staff 名 / 部门）。
+2. **按用户名 contains 过滤**：DB 有 alice / alex / bob，`queryField=username&matchType=contains&queryValue=al` 返回 alice + alex。
+3. **按员工名 contains 过滤**：通过 LEFT JOIN，匹配 tStaff.sStaffName。
+4. **按部门 equals 过滤**：matchType=equals，命中精确部门。
+5. **deleted=false 过滤**：返回未删除集合。
+6. **deleted=true 过滤**：仅返回已软删除（验证规则 6）。
+7. **notContains 排除**：matchType=notContains，排除指定关键字。
+8. **分页**：pageSize=2，pageNum=1 / 2，断言 list.size + total。
+9. **空结果**：queryValue 完全不匹配，返回 list=[] + total=0。
+10. **响应字段精简**：jsonPath 验证 sPasswordHash / sId / sBrandsId / iStaffId 不出现。
+11. **未关联 staff 用户**：DB 中有 user.iStaffId=null，列表 sStaffName / sDepartment 应为 null。
+12. **pageSize 超限**：pageSize=101，返回 40010。
+13. **queryField 非枚举**：queryField=invalid，返回 40010。
+14. **matchType 非枚举**：返回 40010。
+15. **排序**：tCreateDate DESC，新建在前。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`；data 嵌套 `{total, list, pageNum, pageSize}`。
+- 错误码 200 / 40010 / 50000。
+- 不暴露 sPasswordHash 等内部字段。
+
+### 测试覆盖
+
+- **单元测试** `UserServiceImplTest` 追加（mock UserMapper.searchUsers）：
+  - search_emptyDb_returnsEmptyPage
+  - search_invalidQueryField_throws40010（service 内白名单校验）
+  - search_invalidMatchType_throws40010
+  - search_passesColumnAndValue_toMapper（ArgumentCaptor 验 query.column 由白名单映射）
+
+- **集成测试** `UserControllerIT` 追加：
+  - get_emptyKeyword_returnsAllUndeleted
+  - get_filterByUsernameContains_returnsMatchedSubset
+  - get_filterByStaffnameContains_returnsJoinedResults
+  - get_filterByDeletedTrue_returnsOnlyDeleted
+  - get_pagination_returnsCorrectSlice
+  - get_responseExcludesInternalFields
+  - get_pageSizeTooLarge_returns40010
+  - get_invalidQueryField_returns40010
+  - get_userWithoutStaff_listItemHasNullStaffFields
+
+### 代码与文档
+
+- `// REQ-USR-003` 注释贴在 Controller / Service 方法 / Mapper.xml 顶部。
+- 提交按 `feat(usr): <subject> REQ-USR-003`。
+- **新增** `MybatisPlusConfig`（如不存在）：`PaginationInnerInterceptor` bean 启用 MP 分页。
+- **新增** 通用 `PageResult<T>` VO（horizontal scope；本 REQ 首次引入但属于 common 命名空间）。
+---
+req_id: REQ-USR-004
+date: 2026-05-06
+module: module_usr
+---
+
+# Spec: REQ-USR-004 — 用户登录
+
+## 目标
+
+实现后端 `POST /api/auth/login` 接口：用户凭用户名 + 密码（+ 版本）完成身份认证，签发限时 JWT access token + 返回用户基本信息；连续失败时临时锁定账号；登录成功回写 `tLastLoginDate`。
+
+## 范围说明
+
+本 REQ 是 module_usr 的最后一个 REQ，落地 JWT 签发 + 内存锁定计数 + tLastLoginDate 回写。**契约层面**，docs/02 § 三 与既有各 REQ Controller 注释提到「REQ-USR-004 完成后追加 @PreAuthorize + 切换 SecurityConfig 到 authenticated」。**本 REQ 仅签发 token**，SecurityConfig 保持 permitAll；将所有既有端点切换到强制鉴权 + 给每个 Controller 方法加 `@PreAuthorize` + 让现有 IT 携带 token 是另一个体量较大的清算工作（module_mod 4 端点 + module_usr 3 端点 + 全部 IT），作为已知技术债登记到模块完成报告 § ⑩，留给下一个 REQ 或独立 sweep 处理。
+
+> 锁定失败计数：spec 写明用**内存** `ConcurrentHashMap` 保管；docs/03 § tUser 业务注记声明走 Redis，但本仓库 .env.local 未配 Redis 凭据、pom 也未引 spring-boot-starter-data-redis。本期保留内存实现并在 javadoc / 业务注记中注明"REQ-USR-XXX 引入 Redis 后替换"。
+
+## 输入 / 触发
+
+**接口**：`POST /api/auth/login`，Content-Type `application/json`。**不需鉴权**（white-list in SecurityConfig）。
+
+**Request body**（`LoginDTO`）：
+
+| 字段 | 类型 | 必填 | 校验 |
+|---|---|---|---|
+| `sUserName` | String | 是 | 长度 1-50 |
+| `sPassword` | String | 是 | 长度 1-100（明文 HTTPS 传输；线下 prod 必须 HTTPS） |
+| `sVersion` | String | 是 | 枚举：`standard`（仅一个值；REQ 卡片表 1 写"标准版"，spec 用 ASCII `standard` 作 SQL/code 友好） |
+
+## 输出 / 结果
+
+**HTTP 200，响应体**（成功）：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhbGljZSIsImlhdCI6MTc0NjUyODYwMCwiZXhwIjoxNzQ2NTM1ODAwfQ...",
+    "expiresIn": 7200,
+    "user": {
+      "iIncrement": 12,
+      "sUserNo": "u001",
+      "sUserName": "alice",
+      "sUserType": "普通用户",
+      "sLanguage": "zh"
+    }
+  },
+  "timestamp": 1746528600000
+}
+```
+
+新建 VO `LoginResultVO`：字段 `accessToken` / `expiresIn`（秒）/ `user`（嵌套 `LoginUserInfo`：iIncrement / sUserNo / sUserName / sUserType / sLanguage 5 字段）。
+
+**不返回**：`sPasswordHash` / `iStaffId` / `bCanModifyDocs` / `tLastLoginDate` / 多租户字段 / 软删除三件套。`refreshToken` 暂不签发（spec § 范围说明，留作后续）。
+
+## 业务规则
+
+1. **JWT 签发**：HS256，secret 来自 `.env.local` `JWT_SECRET`（已配置）；`expiresIn = 7200`（2 小时）；claims：`sub = sUserName`、`iat`、`exp`、`uid = iIncrement`、`type = sUserType`。
+2. **密码校验**：`BCryptPasswordEncoder.matches(sPassword, user.sPasswordHash)`。复用 REQ-USR-001 引入的 PasswordConfig bean。
+3. **目标用户存在 + 未软删**：`SELECT iIncrement, sUserName, sPasswordHash, sUserType, sLanguage, sUserNo, bDeleted FROM tUser WHERE sUserName = ? AND bDeleted = 0`。null → 失败计数 + `40101`（用户名或密码错误，不区分原因避免账号枚举）；`bDeleted=1` 同样 40101。
+4. **失败计数 + 锁定**：内存 `Map<String, FailRecord>`（key=sUserName）。`FailRecord{count, firstFailAt, lockUntil}`。
+   - 每次密码错误 → `count++`，记 `firstFailAt`（首次失败时间，每个统计窗口）。
+   - `count >= 5` 且未锁定 → 设 `lockUntil = now + 15min`。
+   - 已锁定（`now < lockUntil`）→ 返回 `40301`（账号锁定）+ `data.cooldownSeconds = (lockUntil - now)`。
+   - 锁定到期（`now >= lockUntil`）→ reset `count=0`，正常进入校验流程。
+   - 登录成功 → `cache.remove(sUserName)`（清失败计数）。
+5. **`sVersion` 校验**：当前仅支持 `standard`（DTO @Pattern + service 层防御）。其他值返回 `40010`。
+6. **`tLastLoginDate` 回写**：成功签发 token 后用 `LambdaUpdateWrapper.set(tLastLoginDate, now)` 显式更新，避免 entity-driven update 触发 iStaffId.IGNORED 副作用。
+7. **审计 / 日志**：登录失败 / 锁定 / 成功均 `log.info` 一条（含 sUserName + 客户端 IP，IP 由 controller 通过 `HttpServletRequest.getRemoteAddr()` 获取并传给 service；REQ 卡片 § 验收提到"防暴力破解"以日志为最低抑制）。
+8. **响应格式**：成功 / 失败统一 `{code, message, data, timestamp}`；data 在失败时为 null（除 40301 外，含 `cooldownSeconds`）。
+
+## 边界与约束
+
+### 鉴权策略
+
+- **本接口** `/api/auth/login`：white-list，permitAll（任何人可调）。
+- **其他既有接口**：本 REQ 不切换为 authenticated，仍保留 permitAll。技术债登记在模块完成报告 § ⑩。
+
+### 错误码映射
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| 必填缺失 / 长度超限 / sVersion 非枚举 | 40010 | `PARAM_INVALID`（已存在） |
+| 用户名不存在 / 密码错误 / 用户已软删 | 40101 | `LOGIN_INVALID_CREDENTIALS`（**新增**） |
+| 账号被临时锁定 | 40301 | `LOGIN_ACCOUNT_LOCKED`（**新增**） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+### Redis 缺位的妥协
+
+`InMemoryLoginAttemptStore`（service 层 bean）实现 `LoginAttemptStore` 接口，提供 `recordFailure / clear / isLocked / cooldownSeconds`。后续 REQ 引入 Redis 时新增 `RedisLoginAttemptStore` impl，替换 bean，service 不变。
+
+### JWT 库选择
+
+引入 `io.jsonwebtoken:jjwt-api / jjwt-impl / jjwt-jackson` 0.12.x（最新稳定）。这属 docs/04 § 零 已列「权限认证 Spring Security / JWT」的具体实现，不触发软规则 S1。
+
+### SecurityConfig 改动
+
+`SecurityConfig` 在白名单中显式加 `requestMatchers("/api/auth/login").permitAll()`；其他 `anyRequest().permitAll()` 维持原状（与 module_mod / module_usr 已有端点兼容）。
+
+### 防暴力破解
+
+仅做基础锁定（5 次错误 → 15 分钟锁定）。docs/04 § 1.6 提到 token 生命周期 / 刷新机制 / 密钥管理；本期完成 expires-in、未实施 refreshToken 流转，记入已知 gap。
+
+## 依赖的 schema 表 / 字段
+
+**读表**：`tUser`（按 sUserName 查 + 校验密码）
+
+**写表**：`tUser`（仅写 `tLastLoginDate`；其他字段不动）
+
+| 字段 | 用途 |
+|---|---|
+| `sUserName` | 主索引（uk_user_name） |
+| `sPasswordHash` | BCrypt 校验 |
+| `bDeleted` | 过滤 |
+| `iIncrement` / `sUserNo` / `sUserType` / `sLanguage` | LoginUserInfo / JWT claims |
+| `tLastLoginDate` | 成功登录回写 |
+
+**索引利用**：`uk_user_name`（UNIQUE，单字段查询 O(1)）。
+
+**外键 / 关联表**：本接口不用。
+
+## 依赖的接口
+
+无（独立鉴权入口）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 凭据正确**：先用 REQ-USR-001 创建用户（默认密码 666666），POST /api/auth/login，返回 200 + accessToken（非空）+ expiresIn=7200 + user 含 5 字段；DB 中 tLastLoginDate 已写入。
+2. **JWT 解析**：解析 accessToken（用 JWT_SECRET），断言 claims 含 `sub == sUserName`、`uid == iIncrement`、`type == sUserType`、`exp - iat == 7200`。
+3. **凭据错误 — 用户名不存在**：返回 40101。
+4. **凭据错误 — 密码错误**：返回 40101；DB tLastLoginDate 不更新；内存计数 +1。
+5. **用户已软删**：先创建用户后置 bDeleted=1，登录返回 40101（不区分原因防账号枚举）。
+6. **必填缺失 / sVersion 非枚举**：返回 40010。
+7. **5 次密码错误后锁定**：连续 5 次错误密码登录同一用户名，第 5 次（含）开始返回 40301 + `data.cooldownSeconds > 0`；正确密码也返回 40301（锁定期内一律锁定）。
+8. **锁定后正确密码仍 40301**：锁定状态下传正确密码也拒绝；登录失败和成功都不重置锁定到期时间。
+9. **锁定到期后可登录**：直接修改内存 store 的 lockUntil 至过去，再用正确密码登录，返回 200。
+10. **响应不含 sPasswordHash**：jsonPath 验证 `$.data.user.sPasswordHash` doesNotExist。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`；data 嵌套 `{accessToken, expiresIn, user}`。
+- 错误码 200 / 40010 / 40101 / 40301 / 50000。
+- 不暴露 sPasswordHash；不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `LoginServiceImplTest`（mock UserMapper / PasswordEncoder / LoginAttemptStore / JwtTokenProvider）：
+  - login_validCredentials_returnsTokenAndClearsFailCount
+  - login_userNotFound_returns40101_recordsFailure
+  - login_userSoftDeleted_returns40101
+  - login_passwordMismatch_returns40101_recordsFailure
+  - login_accountLocked_returns40301_withCooldown
+  - login_5thFailureTriggersLock
+  - login_successUpdatesTLastLoginDate
+  - jwtTokenProvider_signAndParse_returnsClaims（独立 JwtTokenProvider 单元测试）
+
+- **集成测试** `LoginControllerIT`（@SpringBootTest @Transactional + 真实 PasswordEncoder + 真实 InMemoryLoginAttemptStore，用 @BeforeEach 重置 store）：
+  - login_validCredentials_returns200WithToken
+  - login_jwtClaimsAreCorrect
+  - login_invalidUsername_returns40101
+  - login_wrongPassword_returns40101
+  - login_softDeletedUser_returns40101
+  - login_missingPassword_returns40010
+  - login_invalidVersion_returns40010
+  - login_5thFailureLocks_returns40301
+  - login_responseExcludesSPasswordHash
+
+### 代码与文档
+
+- `// REQ-USR-004` 注释贴在 LoginController / LoginService / JwtTokenProvider / LoginAttemptStore / 新增 ErrorCode。
+- 提交按 `feat(usr): <subject> REQ-USR-004` 规范。
+- pom.xml 新增 jjwt 三件套（api/impl/jackson 0.12.x）。
@@ -8,6 +8,19 @@ set -euo pipefail
 PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$PROJECT_ROOT"
+# 让 .env.local 注入 JAVA_HOME / DB_* / JWT_SECRET 等运行期变量
+# 由 .githooks/pre-push 触发本脚本时也能拿到
+ENV_FILE="${PROJECT_ROOT}/.env.local"
+if [ -f "$ENV_FILE" ]; then
+  set -a; . "$ENV_FILE"; set +a
+fi
+if [ -n "${JAVA_HOME:-}" ] && [ -d "$JAVA_HOME" ]; then
+  export PATH="$JAVA_HOME/bin:$PATH"
+fi
+if [ -n "${EXTRA_PATH:-}" ]; then
+  export PATH="$EXTRA_PATH:$PATH"
+fi
+
 # Stack detection (runtime, mode-agnostic)
 HAS_BACKEND=0; [ -d backend ] && HAS_BACKEND=1
 HAS_FRONTEND=0; [ -d frontend ] && HAS_FRONTEND=1