diff --git a/CLAUDE.md b/CLAUDE.md index cbd9440..f8d9566 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -132,7 +132,7 @@ B 阶段分两段，**全部固化到 skills**。入口：`/erp-workflow:coding- ### 你禁止做的 🚫 -1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约 +1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试 / A4 `db-init` 首次 apply V1 验证除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约。**A4 例外**：`db-init` 在 A 阶段 setup-test-db 后会一次性手工 `mysql < V1__initial_schema.sql` 把 V1 灌入测试库，并校验 `SHOW TABLES` 行数 = docs/03 表数量，用于 DDL 自检；B 阶段（Spring Boot 启动后）Flyway 会重建 schema 并 apply 全部 migration（包括 V1），手工 apply 不会污染 Flyway 历史。 2. **手动 Edit `docs/08 § 二/§ 三` 的 `MR:` / `整体 MR:` 字段**，必须要由 `mr-create` 自动回写 ### Schema 演化规约（Flyway migration） diff --git a/backend/pom.xml b/backend/pom.xml new file mode 100644 index 0000000..a19dcac --- /dev/null +++ b/backend/pom.xml @@ -0,0 +1,141 @@ + + + 4.0.0 + + + org.springframework.boot + spring-boot-starter-parent + 3.3.4 + + + + com.xly.erp + xly-erp-backend + 0.0.1-SNAPSHOT + jar + xly-erp-backend + 小羚羊 ERP 后端 + + + 17 + 17 + 17 + UTF-8 + 3.5.7 + 0.12.5 + 1.18.40 + + + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-validation + + + org.springframework.security + spring-security-crypto + + + + com.baomidou + mybatis-plus-spring-boot3-starter + ${mybatis-plus.version} + + + + com.mysql + mysql-connector-j + runtime + + + + org.flywaydb + flyway-core + + + org.flywaydb + flyway-mysql + + + + io.jsonwebtoken + jjwt-api + ${jjwt.version} + + + io.jsonwebtoken + jjwt-impl + ${jjwt.version} + runtime + + + io.jsonwebtoken + jjwt-jackson + ${jjwt.version} + runtime + + + + org.projectlombok + lombok + ${lombok.version} + true + + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + + + + org.projectlombok + lombok + ${lombok.version} + + + + + + org.springframework.boot + spring-boot-maven-plugin + + + + org.projectlombok + lombok + + + + + + org.apache.maven.plugins + maven-surefire-plugin + + + ${env.DB_HOST} + ${env.DB_PORT} + ${env.DB_USER} + ${env.DB_PASSWORD} + ${env.DB_SCHEMA} + ${env.JWT_SECRET} + + + + + + diff --git a/backend/src/main/java/com/xly/erp/Application.java b/backend/src/main/java/com/xly/erp/Application.java new file mode 100644 index 0000000..87b3550 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/Application.java @@ -0,0 +1,13 @@ +package com.xly.erp; + +import org.mybatis.spring.annotation.MapperScan; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +@SpringBootApplication +@MapperScan("com.xly.erp.module.*.mapper") +public class Application { + public static void main(String[] args) { + SpringApplication.run(Application.class, args); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java b/backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java new file mode 100644 index 0000000..26131c8 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java @@ -0,0 +1,18 @@ +package com.xly.erp.common.config; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; + +/** + * BCrypt 密码编码器 Bean。strength=10（Spring Security 默认）。 + * docs/03 sys_user.sPasswordHash + docs/04 § 1.6。 + */ +@Configuration +public class PasswordEncoderConfig { + + @Bean + public BCryptPasswordEncoder passwordEncoder() { + return new BCryptPasswordEncoder(10); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java b/backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java new file mode 100644 index 0000000..98fee6d --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java @@ -0,0 +1,21 @@ +package com.xly.erp.common.config; + +import com.xly.erp.common.security.JwtHandlerInterceptor; +import lombok.RequiredArgsConstructor; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.servlet.config.annotation.InterceptorRegistry; +import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; + +@Configuration +@RequiredArgsConstructor +public class WebMvcConfig implements WebMvcConfigurer { + + private final JwtHandlerInterceptor jwtInterceptor; + + @Override + public void addInterceptors(InterceptorRegistry registry) { + registry.addInterceptor(jwtInterceptor) + .addPathPatterns("/api/v1/**") + .excludePathPatterns("/api/v1/auth/login"); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/exception/BizException.java b/backend/src/main/java/com/xly/erp/common/exception/BizException.java new file mode 100644 index 0000000..cf7fa22 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/exception/BizException.java @@ -0,0 +1,30 @@ +package com.xly.erp.common.exception; + +import lombok.Getter; + +/** + * 业务异常 — 由 service 层抛出，由 GlobalExceptionHandler 统一转 Result.fail。 + * docs/04 § 1.4。 + */ +@Getter +public class BizException extends RuntimeException { + private final int code; + /** 可选附带的响应数据（例如 42301 锁定返 lockUntil）。null 表示无 data 字段。 */ + private final Object data; + + public BizException(int code, String message) { + this(code, message, (Object) null); + } + + public BizException(int code, String message, Object data) { + super(message); + this.code = code; + this.data = data; + } + + public BizException(int code, String message, Throwable cause) { + super(message, cause); + this.code = code; + this.data = null; + } +} diff --git a/backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java b/backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java new file mode 100644 index 0000000..7523765 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java @@ -0,0 +1,66 @@ +package com.xly.erp.common.exception; + +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.response.Result; +import jakarta.validation.ConstraintViolationException; +import lombok.extern.slf4j.Slf4j; +import org.springframework.http.ResponseEntity; +import org.springframework.http.converter.HttpMessageNotReadableException; +import org.springframework.web.bind.MethodArgumentNotValidException; +import org.springframework.web.bind.annotation.ExceptionHandler; +import org.springframework.web.bind.annotation.RestControllerAdvice; + +/** + * 全局异常处理器。 + * 把 BizException / 参数校验异常 / 兜底异常转 Result.fail 统一响应。 + * docs/04 § 1.4。 + */ +@RestControllerAdvice +@Slf4j +public class GlobalExceptionHandler { + + @ExceptionHandler(BizException.class) + public ResponseEntity> handleBiz(BizException e) { + log.warn("[BizException] code={} message={} hasData={}", e.getCode(), e.getMessage(), e.getData() != null); + Result body = e.getData() != null + ? Result.fail(e.getCode(), e.getMessage(), e.getData()) + : Result.fail(e.getCode(), e.getMessage()); + return ResponseEntity + .status(ErrorCode.toHttpStatus(e.getCode())) + .body(body); + } + + @ExceptionHandler(MethodArgumentNotValidException.class) + public ResponseEntity> handleValidation(MethodArgumentNotValidException e) { + String msg = e.getBindingResult().getFieldErrors().stream() + .findFirst() + .map(fe -> fe.getField() + " " + fe.getDefaultMessage()) + .orElse("参数校验失败"); + return ResponseEntity + .status(400) + .body(Result.fail(ErrorCode.BAD_REQUEST, msg)); + } + + @ExceptionHandler(ConstraintViolationException.class) + public ResponseEntity> handleConstraint(ConstraintViolationException e) { + return ResponseEntity + .status(400) + .body(Result.fail(ErrorCode.BAD_REQUEST, e.getMessage())); + } + + @ExceptionHandler(HttpMessageNotReadableException.class) + public ResponseEntity> handleNotReadable(HttpMessageNotReadableException e) { + log.warn("[HttpMessageNotReadable] {}", e.getMessage()); + return ResponseEntity + .status(400) + .body(Result.fail(ErrorCode.BAD_REQUEST, "请求体格式不合法或包含未知字段")); + } + + @ExceptionHandler(Exception.class) + public ResponseEntity> handleFallback(Exception e) { + log.error("[Unhandled] {}", e.getMessage(), e); + return ResponseEntity + .status(500) + .body(Result.fail(ErrorCode.INTERNAL_ERROR, "服务器内部错误")); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/response/ErrorCode.java b/backend/src/main/java/com/xly/erp/common/response/ErrorCode.java new file mode 100644 index 0000000..c344f44 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/response/ErrorCode.java @@ -0,0 +1,48 @@ +package com.xly.erp.common.response; + +/** + * 全局错误码定义。 + * 段位约定见 docs/04 § 1.3。 + */ +public final class ErrorCode { + + private ErrorCode() {} + + public static final int OK = 200; + + public static final int BAD_REQUEST = 40001; + public static final int INVALID_ENUM_PARAM = 40003; + public static final int COMPANY_NOT_FOUND = 40004; + + public static final int BAD_CREDENTIALS = 40101; + public static final int ACCOUNT_DELETED = 40103; + + public static final int FORBIDDEN = 40301; + public static final int USER_FORBIDDEN_SELF_DEACTIVATE = 40302; + + public static final int USER_NOT_FOUND = 40401; + + public static final int ACCOUNT_LOCKED = 42301; + + public static final int CONFLICT_USERNAME = 40901; + public static final int CONFLICT_USERCODE = 40902; + + public static final int INTERNAL_ERROR = 50000; + + /** + * 业务 code → HTTP 状态码映射。 + */ + public static int toHttpStatus(int code) { + if (code == OK) return 200; + if (code == ACCOUNT_LOCKED) return 423; + int hundreds = code / 100; + if (hundreds == 400) return 400; + if (hundreds == 401) return 401; + if (hundreds == 403) return 403; + if (hundreds == 404) return 404; + if (hundreds == 409) return 409; + if (hundreds == 423) return 423; + if (hundreds == 500) return 500; + return 500; + } +} diff --git a/backend/src/main/java/com/xly/erp/common/response/PageResult.java b/backend/src/main/java/com/xly/erp/common/response/PageResult.java new file mode 100644 index 0000000..075bb98 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/response/PageResult.java @@ -0,0 +1,18 @@ +package com.xly.erp.common.response; + +import lombok.Builder; +import lombok.Data; + +import java.util.List; + +/** + * 通用分页响应包装。docs/04 § 3.2。 + */ +@Data +@Builder +public class PageResult { + private List records; + private long total; + private int page; + private int size; +} diff --git a/backend/src/main/java/com/xly/erp/common/response/Result.java b/backend/src/main/java/com/xly/erp/common/response/Result.java new file mode 100644 index 0000000..c7b2869 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/response/Result.java @@ -0,0 +1,39 @@ +package com.xly.erp.common.response; + +import lombok.Getter; + +/** + * 统一响应包装。 + * docs/04 § 1.3。 + */ +@Getter +public class Result { + private final int code; + private final String message; + private final T data; + private final long timestamp; + + private Result(int code, String message, T data) { + this.code = code; + this.message = message; + this.data = data; + this.timestamp = System.currentTimeMillis(); + } + + public static Result ok(T data) { + return new Result<>(ErrorCode.OK, "操作成功", data); + } + + public static Result ok() { + return new Result<>(ErrorCode.OK, "操作成功", null); + } + + public static Result fail(int code, String message) { + return new Result<>(code, message, null); + } + + @SuppressWarnings("unchecked") + public static Result fail(int code, String message, T data) { + return new Result<>(code, message, data); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java b/backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java new file mode 100644 index 0000000..263e363 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java @@ -0,0 +1,80 @@ +package com.xly.erp.common.security; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import org.springframework.web.method.HandlerMethod; +import org.springframework.web.servlet.HandlerInterceptor; + +import java.time.LocalDateTime; +import java.util.Map; + +/** + * REQ-USR-002 鉴权与角色守卫拦截器。 + * - 解析 Authorization Bearer → 校验 user 状态 → set LoginContext + * - 若 handler 标注 @RequireSuperAdmin，强制 userType == SUPER_ADMIN + * - afterCompletion 清理 ThreadLocal + */ +@Component +@RequiredArgsConstructor +@Slf4j +public class JwtHandlerInterceptor implements HandlerInterceptor { + + private static final String BEARER_PREFIX = "Bearer "; + + private final JwtUtil jwtUtil; + private final SysUserMapper userMapper; + + @Override + public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { + String authHeader = request.getHeader("Authorization"); + if (authHeader == null || !authHeader.startsWith(BEARER_PREFIX)) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "未携带 token"); + } + String token = authHeader.substring(BEARER_PREFIX.length()); + + Map claims = jwtUtil.parse(token); + String username = (String) claims.get("username"); + if (username == null || username.isBlank()) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 缺 username claim"); + } + + SysUser user = userMapper.selectByUsername(username); + if (user == null) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户不存在"); + } + if (Integer.valueOf(1).equals(user.getIIsDeleted())) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户已作废"); + } + if (user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now())) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 关联用户已锁定"); + } + + String companyCode = (String) claims.get("companyCode"); + LoginContext.set(new LoginContext.LoginUser( + user.getIIncrement(), + user.getSUsername(), + user.getSUserType(), + companyCode)); + + if (handler instanceof HandlerMethod hm) { + if (hm.getMethodAnnotation(RequireSuperAdmin.class) != null + && !"SUPER_ADMIN".equals(user.getSUserType())) { + throw new BizException(ErrorCode.FORBIDDEN, "权限不足，仅超级管理员可调用"); + } + } + return true; + } + + @Override + public void afterCompletion(HttpServletRequest request, HttpServletResponse response, + Object handler, Exception ex) { + LoginContext.clear(); + } +} diff --git a/backend/src/main/java/com/xly/erp/common/security/JwtUtil.java b/backend/src/main/java/com/xly/erp/common/security/JwtUtil.java new file mode 100644 index 0000000..266d843 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/security/JwtUtil.java @@ -0,0 +1,75 @@ +package com.xly.erp.common.security; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import io.jsonwebtoken.Claims; +import io.jsonwebtoken.JwtException; +import io.jsonwebtoken.Jwts; +import io.jsonwebtoken.security.Keys; +import jakarta.annotation.PostConstruct; +import org.springframework.beans.factory.annotation.Value; +import org.springframework.stereotype.Component; + +import javax.crypto.SecretKey; +import java.nio.charset.StandardCharsets; +import java.util.Date; +import java.util.HashMap; +import java.util.Map; +import java.util.UUID; + +/** + * JWT 签发与验证工具。HS256，密钥来自 ${JWT_SECRET}。 + * docs/04 § 1.6。 + */ +@Component +public class JwtUtil { + + @Value("${jwt.secret}") + private String secret; + + private SecretKey key; + + @PostConstruct + void init() { + byte[] bytes = secret.getBytes(StandardCharsets.UTF_8); + if (bytes.length < 32) { + throw new IllegalStateException( + "JWT_SECRET 长度不足 32 字节（HS256 要求），实际 " + bytes.length + + " 字节。请在 .env.local 配置至少 256 位的随机字符串。"); + } + this.key = Keys.hmacShaKeyFor(bytes); + } + + public String issue(Map claims, long ttlSec) { + long now = System.currentTimeMillis(); + Map all = new HashMap<>(claims); + String sub = String.valueOf(all.remove("sub")); + String jti = UUID.randomUUID().toString(); + return Jwts.builder() + .subject(sub) + .claims(all) + .id(jti) + .issuedAt(new Date(now)) + .expiration(new Date(now + ttlSec * 1000L)) + .signWith(key) + .compact(); + } + + public Map parse(String token) { + try { + Claims claims = Jwts.parser() + .verifyWith(key) + .build() + .parseSignedClaims(token) + .getPayload(); + Map out = new HashMap<>(claims); + out.put("sub", claims.getSubject()); + out.put("jti", claims.getId()); + out.put("iat", claims.getIssuedAt() != null ? claims.getIssuedAt().getTime() / 1000 : null); + out.put("exp", claims.getExpiration() != null ? claims.getExpiration().getTime() / 1000 : null); + return out; + } catch (JwtException e) { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "token 无效或已过期"); + } + } +} diff --git a/backend/src/main/java/com/xly/erp/common/security/LoginContext.java b/backend/src/main/java/com/xly/erp/common/security/LoginContext.java new file mode 100644 index 0000000..916482e --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/security/LoginContext.java @@ -0,0 +1,27 @@ +package com.xly.erp.common.security; + +/** + * 请求级登录上下文 — JwtHandlerInterceptor 在 preHandle 时 set，afterCompletion 时 clear。 + * 用普通 ThreadLocal（不用 InheritableThreadLocal）避免子线程意外继承。 + */ +public final class LoginContext { + + private static final ThreadLocal HOLDER = new ThreadLocal<>(); + + private LoginContext() {} + + public static void set(LoginUser user) { + HOLDER.set(user); + } + + public static LoginUser current() { + return HOLDER.get(); + } + + public static void clear() { + HOLDER.remove(); + } + + /** 当前登录用户上下文。userType 取值 NORMAL / SUPER_ADMIN。 */ + public record LoginUser(Integer userId, String username, String userType, String companyCode) {} +} diff --git a/backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java b/backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java new file mode 100644 index 0000000..3f90aac --- /dev/null +++ b/backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java @@ -0,0 +1,15 @@ +package com.xly.erp.common.security; + +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * 标注在 controller 方法上，要求当前登录用户 userType == SUPER_ADMIN。 + * 由 JwtHandlerInterceptor 在 preHandle 时校验。 + */ +@Target(ElementType.METHOD) +@Retention(RetentionPolicy.RUNTIME) +public @interface RequireSuperAdmin { +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java b/backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java new file mode 100644 index 0000000..6640cb8 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java @@ -0,0 +1,29 @@ +package com.xly.erp.module.usr.controller; + +import com.xly.erp.common.response.Result; +import com.xly.erp.module.usr.dto.LoginReq; +import com.xly.erp.module.usr.service.LoginService; +import com.xly.erp.module.usr.vo.LoginVo; +import jakarta.validation.Valid; +import lombok.RequiredArgsConstructor; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +/** + * 认证入口。REQ-USR-001：POST /api/v1/auth/login。 + */ +@RestController +@RequestMapping("/api/v1/auth") +@RequiredArgsConstructor +public class AuthController { + + private final LoginService loginService; + + @PostMapping("/login") + public Result login(@RequestBody @Valid LoginReq req) { + LoginVo vo = loginService.login(req.getUsername(), req.getPassword(), req.getCompanyCode()); + return Result.ok(vo); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java b/backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java new file mode 100644 index 0000000..5837029 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java @@ -0,0 +1,67 @@ +package com.xly.erp.module.usr.controller; + +import com.xly.erp.common.response.PageResult; +import com.xly.erp.common.response.Result; +import com.xly.erp.common.security.LoginContext; +import com.xly.erp.common.security.RequireSuperAdmin; +import com.xly.erp.module.usr.dto.CreateUserReq; +import com.xly.erp.module.usr.dto.UpdateUserReq; +import com.xly.erp.module.usr.dto.UserQueryReq; +import com.xly.erp.module.usr.service.UserCreateService; +import com.xly.erp.module.usr.service.UserDetailService; +import com.xly.erp.module.usr.service.UserListService; +import com.xly.erp.module.usr.service.UserUpdateService; +import com.xly.erp.module.usr.vo.CreateUserVo; +import com.xly.erp.module.usr.vo.UserDetailVo; +import com.xly.erp.module.usr.vo.UserListItemVo; +import jakarta.validation.Valid; +import lombok.RequiredArgsConstructor; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.PutMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +@RestController +@RequestMapping("/api/v1/users") +@RequiredArgsConstructor +public class UserController { + + private final UserCreateService userCreateService; + private final UserDetailService userDetailService; + private final UserUpdateService userUpdateService; + private final UserListService userListService; + + @PostMapping + @RequireSuperAdmin + public ResponseEntity> create(@RequestBody @Valid CreateUserReq req) { + String operator = LoginContext.current().username(); + CreateUserVo vo = userCreateService.create(req, operator); + return ResponseEntity.status(HttpStatus.CREATED).body(Result.ok(vo)); + } + + @GetMapping + @RequireSuperAdmin + public Result> list(@Valid UserQueryReq req) { + return Result.ok(userListService.list(req)); + } + + @GetMapping("/{userId}") + @RequireSuperAdmin + public Result getById(@PathVariable Integer userId) { + return Result.ok(userDetailService.getById(userId)); + } + + @PutMapping("/{userId}") + @RequireSuperAdmin + public Result update(@PathVariable Integer userId, + @RequestBody @Valid UpdateUserReq req) { + LoginContext.LoginUser cur = LoginContext.current(); + UserDetailVo vo = userUpdateService.update(userId, req, cur.userId(), cur.username()); + return Result.ok(vo); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java b/backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java new file mode 100644 index 0000000..6322e88 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java @@ -0,0 +1,41 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.NotNull; +import jakarta.validation.constraints.Pattern; +import jakarta.validation.constraints.Size; +import lombok.Data; + +import java.util.List; + +@Data +public class CreateUserReq { + + @NotBlank + @Pattern(regexp = "^[A-Za-z0-9_]{3,20}$", + message = "用户名必须为 3-20 位字母数字下划线") + private String username; + + @NotBlank + @Size(max = 50) + private String userCode; + + @NotBlank + @Pattern(regexp = "NORMAL|SUPER_ADMIN", + message = "userType 必须为 NORMAL 或 SUPER_ADMIN") + private String userType; + + @NotBlank + @Pattern(regexp = "zh-CN|en-US|zh-TW", + message = "language 必须为 zh-CN / en-US / zh-TW") + private String language; + + @NotNull + private Boolean canEditDocument; + + /** 可选；非空则必须命中 sys_employee.iIncrement 且 iIsDeleted=0 */ + private Integer employeeId; + + /** 可选；空数组 / null 都允许；非空时每个 ID 必须命中 sys_permission_category */ + private List permissionCategoryIds; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java b/backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java new file mode 100644 index 0000000..2bc2af4 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java @@ -0,0 +1,21 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.constraints.NotBlank; +import jakarta.validation.constraints.Size; +import lombok.Data; + +@Data +public class LoginReq { + + @NotBlank + @Size(max = 50) + private String username; + + @NotBlank + @Size(max = 128) + private String password; + + @NotBlank + @Size(max = 50) + private String companyCode; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java b/backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java new file mode 100644 index 0000000..8ca932b --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java @@ -0,0 +1,37 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.constraints.Min; +import jakarta.validation.constraints.Pattern; +import jakarta.validation.constraints.Size; +import lombok.Data; + +import java.util.List; + +/** + * PATCH 语义：所有字段都可选；缺省 / 显式 null 视为不变。 + * 特例：employeeId == 0 视为解除关联（DB 写 NULL）。 + */ +@Data +public class UpdateUserReq { + + @Size(max = 50) + @Pattern(regexp = "^\\S+$", message = "userCode 不可为空白") + private String userCode; + + @Pattern(regexp = "NORMAL|SUPER_ADMIN", + message = "userType 必须为 NORMAL 或 SUPER_ADMIN") + private String userType; + + @Pattern(regexp = "zh-CN|en-US|zh-TW", + message = "language 必须为 zh-CN / en-US / zh-TW") + private String language; + + private Boolean canEditDocument; + + @Min(value = 0, message = "employeeId 必须 >= 0；0 表示解除关联") + private Integer employeeId; + + private Boolean isDeleted; + + private List permissionCategoryIds; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java b/backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java new file mode 100644 index 0000000..8b7f6c4 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java @@ -0,0 +1,28 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.constraints.Max; +import jakarta.validation.constraints.Min; +import lombok.Data; + +/** + * 用户列表查询请求。所有字段可选；枚举值白名单由 service 层校验。 + * REQ-USR-004。 + */ +@Data +public class UserQueryReq { + + @Min(value = 1, message = "page 必须 >= 1") + private Integer page; + + @Min(value = 1, message = "size 必须 >= 1") + @Max(value = 100, message = "size 不能超过 100") + private Integer size; + + private String sortField; + private String sortOrder; + private String queryField; + private String matchMode; + private String queryValue; + private String userType; + private Boolean isDeleted; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java b/backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java new file mode 100644 index 0000000..f68005e --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java @@ -0,0 +1,29 @@ +package com.xly.erp.module.usr.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * 公司表实体（只需登录用到的字段）。docs/03 § sys_company。 + */ +@Data +@TableName("sys_company") +public class SysCompany { + + @TableId(value = "iIncrement", type = IdType.AUTO) + private Integer iIncrement; + + private String sId; + private String sBrandsId; + private String sSubsidiaryId; + private LocalDateTime tCreateDate; + + private String sCompanyName; + private String sCompanyCode; + private Integer iSortOrder; + private Integer iIsDeleted; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java b/backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java new file mode 100644 index 0000000..07d1179 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java @@ -0,0 +1,32 @@ +package com.xly.erp.module.usr.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * 职员表实体（只读 join，含登录返回 employeeName 所需的最小字段）。 + * docs/03 § sys_employee。 + */ +@Data +@TableName("sys_employee") +public class SysEmployee { + + @TableId(value = "iIncrement", type = IdType.AUTO) + private Integer iIncrement; + + private String sId; + private String sBrandsId; + private String sSubsidiaryId; + private LocalDateTime tCreateDate; + + private String sEmployeeName; + private String sEmployeeCode; + private Integer iDepartmentId; + private String sPhone; + private String sEmail; + private Integer iIsDeleted; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java b/backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java new file mode 100644 index 0000000..a033449 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java @@ -0,0 +1,27 @@ +package com.xly.erp.module.usr.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +@Data +@TableName("sys_permission_category") +public class SysPermissionCategory { + + @TableId(value = "iIncrement", type = IdType.AUTO) + private Integer iIncrement; + + private String sId; + private String sBrandsId; + private String sSubsidiaryId; + private LocalDateTime tCreateDate; + + private String sCategoryName; + private String sCategoryCode; + private String sCategoryDesc; + private Integer iSortOrder; + private Integer iIsDeleted; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java b/backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java new file mode 100644 index 0000000..07b408f --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java @@ -0,0 +1,40 @@ +package com.xly.erp.module.usr.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * 用户表实体。docs/03 § sys_user。 + */ +@Data +@TableName("sys_user") +public class SysUser { + + @TableId(value = "iIncrement", type = IdType.AUTO) + private Integer iIncrement; + + private String sId; + private String sBrandsId; + private String sSubsidiaryId; + private LocalDateTime tCreateDate; + + private String sUsername; + private String sUserCode; + private String sPasswordHash; + + private Integer iEmployeeId; + private String sUserType; + private String sLanguage; + private Integer iCanEditDocument; + private Integer iIsDeleted; + private Integer iFailedLoginCount; + private LocalDateTime tLockUntil; + private LocalDateTime tLastLoginDate; + private String sCreatedBy; + private String sUpdatedBy; + private LocalDateTime tUpdatedDate; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java b/backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java new file mode 100644 index 0000000..3b0e523 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java @@ -0,0 +1,25 @@ +package com.xly.erp.module.usr.entity; + +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +@Data +@TableName("sys_user_permission_category") +public class SysUserPermissionCategory { + + @TableId(value = "iIncrement", type = IdType.AUTO) + private Integer iIncrement; + + private String sId; + private String sBrandsId; + private String sSubsidiaryId; + private LocalDateTime tCreateDate; + + private Integer iUserId; + private Integer iPermissionCategoryId; + private String sGrantedBy; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java new file mode 100644 index 0000000..45fa5c0 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java @@ -0,0 +1,14 @@ +package com.xly.erp.module.usr.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.xly.erp.module.usr.entity.SysCompany; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Select; + +@Mapper +public interface SysCompanyMapper extends BaseMapper { + + @Select("SELECT iIncrement, sCompanyCode, sCompanyName, iIsDeleted " + + "FROM sys_company WHERE sCompanyCode = #{code} LIMIT 1") + SysCompany selectByCode(String code); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java new file mode 100644 index 0000000..3e0b638 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java @@ -0,0 +1,9 @@ +package com.xly.erp.module.usr.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.xly.erp.module.usr.entity.SysEmployee; +import org.apache.ibatis.annotations.Mapper; + +@Mapper +public interface SysEmployeeMapper extends BaseMapper { +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java new file mode 100644 index 0000000..1c8c1a8 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java @@ -0,0 +1,26 @@ +package com.xly.erp.module.usr.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.xly.erp.module.usr.entity.SysPermissionCategory; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Select; + +import java.util.List; + +@Mapper +public interface SysPermissionCategoryMapper extends BaseMapper { + + /** + * 计算给定 ID 集合中有多少行未删除（iIsDeleted=0）。 + * 用于 REQ-USR-002 批量校验 permissionCategoryIds 是否全部存在。 + */ + @Select({ + "" + }) + int countActiveByIds(@Param("ids") List ids); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java new file mode 100644 index 0000000..b99eca5 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java @@ -0,0 +1,64 @@ +package com.xly.erp.module.usr.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.vo.UserListItemVo; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Select; +import org.apache.ibatis.annotations.Update; + +import java.util.List; + +@Mapper +public interface SysUserMapper extends BaseMapper { + + String LOGIN_COLUMNS = "iIncrement, sUsername, sUserCode, sPasswordHash, iEmployeeId, " + + "sUserType, sLanguage, iCanEditDocument, iIsDeleted, iFailedLoginCount, " + + "tLockUntil, tLastLoginDate"; + + @Select("SELECT " + LOGIN_COLUMNS + " FROM sys_user WHERE sUsername = #{username} LIMIT 1") + SysUser selectByUsername(String username); + + /** + * 原子累加失败登录次数；达到阈值 maxCount 时同步写 tLockUntil = NOW() + lockMinutes 分钟。 + * 单 SQL，DB 层保证并发安全。返回受影响行数（应为 1）。 + * MySQL 按 SET 子句从左到右求值，所以放在 +1 之后的引用看到的是新值。 + */ + @Update("UPDATE sys_user " + + "SET iFailedLoginCount = iFailedLoginCount + 1, " + + " tLockUntil = IF(iFailedLoginCount >= #{maxCount}, " + + " DATE_ADD(NOW(), INTERVAL #{lockMinutes} MINUTE), " + + " tLockUntil) " + + "WHERE iIncrement = #{userId}") + int incrementFailedLoginCountAtomic(@Param("userId") Integer userId, + @Param("maxCount") int maxCount, + @Param("lockMinutes") long lockMinutes); + + /** + * 成功登录写入：清零计数 + 清空锁定 + 更新登录时间。一次 UPDATE。 + */ + @Update("UPDATE sys_user " + + "SET iFailedLoginCount = 0, tLockUntil = NULL, tLastLoginDate = NOW() " + + "WHERE iIncrement = #{userId}") + int markLoginSuccess(@Param("userId") Integer userId); + + @Select("SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUsername = #{username})") + boolean existsByUsername(@Param("username") String username); + + @Select("SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUserCode = #{userCode})") + boolean existsByUserCode(@Param("userCode") String userCode); + + @Select("SELECT EXISTS(SELECT 1 FROM sys_user " + + "WHERE sUserCode = #{userCode} AND iIncrement <> #{excludedUserId})") + boolean existsByUserCodeExcludingId(@Param("userCode") String userCode, + @Param("excludedUserId") Integer excludedUserId); + + /** + * REQ-USR-004 动态查询。SQL 在 SysUserMapper.xml 定义。 + * QueryParams 必须已通过 service 层白名单校验。 + */ + List selectByQuery(@Param("p") UserQueryParams p); + + long countByQuery(@Param("p") UserQueryParams p); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java new file mode 100644 index 0000000..e8fbaea --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java @@ -0,0 +1,26 @@ +package com.xly.erp.module.usr.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import org.apache.ibatis.annotations.Delete; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Select; + +import java.util.List; + +@Mapper +public interface SysUserPermissionCategoryMapper extends BaseMapper { + + @Select("SELECT iPermissionCategoryId FROM sys_user_permission_category WHERE iUserId = #{userId}") + List selectPermissionCategoryIdsByUserId(@Param("userId") Integer userId); + + @Delete({ + "" + }) + int deleteByUserAndCategoryIds(@Param("userId") Integer userId, + @Param("ids") List categoryIds); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/mapper/UserQueryParams.java b/backend/src/main/java/com/xly/erp/module/usr/mapper/UserQueryParams.java new file mode 100644 index 0000000..1c20854 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/mapper/UserQueryParams.java @@ -0,0 +1,18 @@ +package com.xly.erp.module.usr.mapper; + +/** + * SysUserMapper.selectByQuery / countByQuery 入参（service 层规范化白名单后填入）。 + * sqlSortField / sqlSortOrder / sqlQueryColumn 必须已通过白名单校验； + * mapper XML 直接用 ${} 拼接到 SQL。 + */ +public class UserQueryParams { + public String sqlSortField; + public String sqlSortOrder; + public String sqlQueryColumn; // null 表示无 queryField 条件 + public String matchMode; // contains / notContains / equals + public String queryValue; // null/"" 表示跳过该条件 + public String userType; // null 表示不过滤 + public Integer isDeleted; // null 不过滤；0 / 1 过滤 + public Integer offset; + public Integer limit; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java b/backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java new file mode 100644 index 0000000..ef17b5c --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java @@ -0,0 +1,14 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.module.usr.vo.LoginVo; + +public interface LoginService { + /** + * 校验用户名 + 密码 + 公司编码并签发 access token。 + * REQ-USR-001。 + * + * @throws com.xly.erp.common.exception.BizException + * 40004 公司不存在 / 40101 凭据错误 / 40103 账号作废 / 42301 账号锁定 + */ + LoginVo login(String username, String password, String companyCode); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java b/backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java new file mode 100644 index 0000000..9c55cdf --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java @@ -0,0 +1,17 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.module.usr.dto.CreateUserReq; +import com.xly.erp.module.usr.vo.CreateUserVo; + +public interface UserCreateService { + /** + * 新建用户 + 权限分类授权。 + * REQ-USR-002。 + * + * @param req 已通过 jakarta 校验的请求体 + * @param operatorUsername 当前登录用户（写入 sCreatedBy / sGrantedBy） + * @throws com.xly.erp.common.exception.BizException + * 40004 employee / permissionCategory 不存在 / 40901 用户名重复 / 40902 用户号重复 + */ + CreateUserVo create(CreateUserReq req, String operatorUsername); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java b/backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java new file mode 100644 index 0000000..a69a3e7 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java @@ -0,0 +1,13 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.module.usr.vo.UserDetailVo; + +public interface UserDetailService { + /** + * REQ-USR-003 GET /api/v1/users/{userId} 详情。 + * 包含作废用户（不过滤 iIsDeleted）。 + * + * @throws com.xly.erp.common.exception.BizException 40401 用户不存在 + */ + UserDetailVo getById(Integer userId); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java b/backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java new file mode 100644 index 0000000..486664e --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java @@ -0,0 +1,13 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.response.PageResult; +import com.xly.erp.module.usr.dto.UserQueryReq; +import com.xly.erp.module.usr.vo.UserListItemVo; + +public interface UserListService { + /** + * REQ-USR-004 GET /api/v1/users — 分页 + 多字段筛选 + 排序。 + * 白名单校验、越界矫正均由实现层完成。 + */ + PageResult list(UserQueryReq req); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java b/backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java new file mode 100644 index 0000000..faa6175 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java @@ -0,0 +1,15 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.module.usr.dto.UpdateUserReq; +import com.xly.erp.module.usr.vo.UserDetailVo; + +public interface UserUpdateService { + /** + * REQ-USR-003 PUT /api/v1/users/{userId}：部分字段更新 + 权限分类增量差集。 + * + * @throws com.xly.erp.common.exception.BizException + * 40004 employee/permissionCategory 不存在 / 40302 自我停用 / 40401 用户不存在 / 40902 用户号冲突 + */ + UserDetailVo update(Integer userId, UpdateUserReq req, + Integer operatorUserId, String operatorUsername); +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java b/backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java new file mode 100644 index 0000000..dbdc8fe --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java @@ -0,0 +1,119 @@ +package com.xly.erp.module.usr.service.impl; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.security.JwtUtil; +import com.xly.erp.module.usr.entity.SysCompany; +import com.xly.erp.module.usr.entity.SysEmployee; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.mapper.SysCompanyMapper; +import com.xly.erp.module.usr.mapper.SysEmployeeMapper; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.service.LoginService; +import com.xly.erp.module.usr.vo.LoginVo; +import com.xly.erp.module.usr.vo.UserInfoVo; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; +import org.springframework.stereotype.Service; + +import java.time.LocalDateTime; +import java.time.format.DateTimeFormatter; +import java.util.HashMap; +import java.util.Map; + +@Service +@RequiredArgsConstructor +@Slf4j +public class LoginServiceImpl implements LoginService { + + static final int MAX_FAILED_LOGIN_COUNT = 5; + static final long LOCK_DURATION_MINUTES = 30L; + static final long TOKEN_TTL_SEC = 7200L; + + private final SysUserMapper userMapper; + private final SysCompanyMapper companyMapper; + private final SysEmployeeMapper employeeMapper; + private final BCryptPasswordEncoder passwordEncoder; + private final JwtUtil jwtUtil; + + @Override + public LoginVo login(String username, String password, String companyCode) { + // 1. 公司校验（只读，不需事务） + SysCompany company = companyMapper.selectByCode(companyCode); + if (company == null || Integer.valueOf(1).equals(company.getIIsDeleted())) { + log.warn("[login] companyCode={} 不存在或已删除", companyCode); + throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "公司不存在或已删除"); + } + + // 2. 用户查找 + SysUser user = userMapper.selectByUsername(username); + if (user == null) { + log.warn("[login] username={} 不存在（统一返 40101）", username); + throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误"); + } + + // 3. 作废校验（不计入失败次数） + if (Integer.valueOf(1).equals(user.getIIsDeleted())) { + log.warn("[login] username={} 已作废", username); + throw new BizException(ErrorCode.ACCOUNT_DELETED, "账号已被作废，禁止登录"); + } + + // 4. 锁定校验（不计入失败次数；过期锁定视为已解锁） + if (user.getTLockUntil() != null && user.getTLockUntil().isAfter(LocalDateTime.now())) { + log.warn("[login] username={} 锁定中，lockUntil={}", username, user.getTLockUntil()); + Map data = new HashMap<>(); + data.put("lockUntil", user.getTLockUntil() + .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)); + throw new BizException(ErrorCode.ACCOUNT_LOCKED, "账号已锁定，请稍后再试", data); + } + + // 5. 密码校验 + if (!passwordEncoder.matches(password, user.getSPasswordHash())) { + int rows = userMapper.incrementFailedLoginCountAtomic( + user.getIIncrement(), MAX_FAILED_LOGIN_COUNT, LOCK_DURATION_MINUTES); + log.warn("[login] username={} 密码错误，原子累加失败次数 rows={}", username, rows); + throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误"); + } + + // 6. 成功路径 + return loginSuccess(user, companyCode); + } + + private LoginVo loginSuccess(SysUser user, String companyCode) { + userMapper.markLoginSuccess(user.getIIncrement()); + + String employeeName = null; + if (user.getIEmployeeId() != null) { + SysEmployee emp = employeeMapper.selectById(user.getIEmployeeId()); + if (emp != null) { + employeeName = emp.getSEmployeeName(); + } + } + + Map claims = new HashMap<>(); + claims.put("sub", user.getIIncrement()); + claims.put("username", user.getSUsername()); + claims.put("userType", user.getSUserType()); + claims.put("companyCode", companyCode); + claims.put("language", user.getSLanguage()); + + String token = jwtUtil.issue(claims, TOKEN_TTL_SEC); + + log.info("[login] username={} 登录成功", user.getSUsername()); + + return LoginVo.builder() + .accessToken(token) + .tokenType("Bearer") + .expiresInSec(TOKEN_TTL_SEC) + .userInfo(UserInfoVo.builder() + .userId(user.getIIncrement()) + .username(user.getSUsername()) + .userType(user.getSUserType()) + .language(user.getSLanguage()) + .companyCode(companyCode) + .employeeName(employeeName) + .build()) + .build(); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java new file mode 100644 index 0000000..69b3f4a --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java @@ -0,0 +1,112 @@ +package com.xly.erp.module.usr.service.impl; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.dto.CreateUserReq; +import com.xly.erp.module.usr.entity.SysEmployee; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysEmployeeMapper; +import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.service.UserCreateService; +import com.xly.erp.module.usr.vo.CreateUserVo; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.dao.DataIntegrityViolationException; +import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; + +import java.util.List; + +@Service +@RequiredArgsConstructor +@Slf4j +public class UserCreateServiceImpl implements UserCreateService { + + static final String INITIAL_PASSWORD = "666666"; + + private final SysUserMapper userMapper; + private final SysEmployeeMapper employeeMapper; + private final SysPermissionCategoryMapper permissionCategoryMapper; + private final SysUserPermissionCategoryMapper userPermissionCategoryMapper; + private final BCryptPasswordEncoder passwordEncoder; + + @Override + @Transactional + public CreateUserVo create(CreateUserReq req, String operatorUsername) { + // 1. 唯一性预检（返友好错误码；DB 唯一索引兜底并发场景） + if (userMapper.existsByUsername(req.getUsername())) { + throw new BizException(ErrorCode.CONFLICT_USERNAME, "用户名已存在"); + } + if (userMapper.existsByUserCode(req.getUserCode())) { + throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已存在"); + } + + // 2. employee 外键校验 + if (req.getEmployeeId() != null) { + SysEmployee emp = employeeMapper.selectById(req.getEmployeeId()); + if (emp == null || Integer.valueOf(1).equals(emp.getIIsDeleted())) { + throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "指定的员工不存在或已删除"); + } + } + + // 3. permissionCategory 外键校验（批量） + List pcIds = req.getPermissionCategoryIds(); + if (pcIds != null && !pcIds.isEmpty()) { + int active = permissionCategoryMapper.countActiveByIds(pcIds); + if (active != pcIds.size()) { + throw new BizException(ErrorCode.COMPANY_NOT_FOUND, + "指定的权限分类含不存在或已删除项"); + } + } + + // 4. 写入 sys_user + SysUser user = new SysUser(); + user.setSUsername(req.getUsername()); + user.setSUserCode(req.getUserCode()); + user.setSPasswordHash(passwordEncoder.encode(INITIAL_PASSWORD)); + user.setIEmployeeId(req.getEmployeeId()); + user.setSUserType(req.getUserType()); + user.setSLanguage(req.getLanguage()); + user.setICanEditDocument(Boolean.TRUE.equals(req.getCanEditDocument()) ? 1 : 0); + user.setIIsDeleted(0); + user.setIFailedLoginCount(0); + user.setSCreatedBy(operatorUsername); + try { + userMapper.insert(user); + } catch (DataIntegrityViolationException e) { + String msg = e.getMessage() == null ? "" : e.getMessage(); + if (msg.contains("uk_sys_user_username")) { + throw new BizException(ErrorCode.CONFLICT_USERNAME, "用户名已存在"); + } + if (msg.contains("uk_sys_user_code")) { + throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已存在"); + } + throw e; + } + + // 5. 写入 sys_user_permission_category（如有） + if (pcIds != null && !pcIds.isEmpty()) { + for (Integer pcId : pcIds) { + SysUserPermissionCategory link = new SysUserPermissionCategory(); + link.setIUserId(user.getIIncrement()); + link.setIPermissionCategoryId(pcId); + link.setSGrantedBy(operatorUsername); + userPermissionCategoryMapper.insert(link); + } + } + + log.info("[user-create] username={} userCode={} byOperator={} permissionCount={}", + user.getSUsername(), user.getSUserCode(), operatorUsername, + pcIds == null ? 0 : pcIds.size()); + + return CreateUserVo.builder() + .userId(user.getIIncrement()) + .username(user.getSUsername()) + .userCode(user.getSUserCode()) + .build(); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java new file mode 100644 index 0000000..7dcc409 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java @@ -0,0 +1,57 @@ +package com.xly.erp.module.usr.service.impl; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.entity.SysEmployee; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.mapper.SysEmployeeMapper; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.service.UserDetailService; +import com.xly.erp.module.usr.vo.UserDetailVo; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; + +import java.util.List; + +@Service +@RequiredArgsConstructor +public class UserDetailServiceImpl implements UserDetailService { + + private final SysUserMapper userMapper; + private final SysEmployeeMapper employeeMapper; + private final SysUserPermissionCategoryMapper upcMapper; + + @Override + public UserDetailVo getById(Integer userId) { + SysUser user = userMapper.selectById(userId); + if (user == null) { + throw new BizException(ErrorCode.USER_NOT_FOUND, "用户不存在"); + } + + String employeeName = null; + if (user.getIEmployeeId() != null) { + SysEmployee emp = employeeMapper.selectById(user.getIEmployeeId()); + if (emp != null) { + employeeName = emp.getSEmployeeName(); + } + } + + List pcIds = upcMapper.selectPermissionCategoryIdsByUserId(userId); + + return UserDetailVo.builder() + .userId(user.getIIncrement()) + .username(user.getSUsername()) + .userCode(user.getSUserCode()) + .userType(user.getSUserType()) + .language(user.getSLanguage()) + .canEditDocument(Integer.valueOf(1).equals(user.getICanEditDocument())) + .isDeleted(Integer.valueOf(1).equals(user.getIIsDeleted())) + .employeeId(user.getIEmployeeId()) + .employeeName(employeeName) + .permissionCategoryIds(pcIds) + .updatedBy(user.getSUpdatedBy()) + .updatedDate(user.getTUpdatedDate()) + .build(); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java new file mode 100644 index 0000000..e227566 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java @@ -0,0 +1,158 @@ +package com.xly.erp.module.usr.service.impl; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.response.PageResult; +import com.xly.erp.module.usr.dto.UserQueryReq; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.UserQueryParams; +import com.xly.erp.module.usr.service.UserListService; +import com.xly.erp.module.usr.vo.UserListItemVo; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; + +import java.time.LocalDateTime; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.List; +import java.util.Map; +import java.util.Set; + +@Service +@RequiredArgsConstructor +public class UserListServiceImpl implements UserListService { + + static final int DEFAULT_PAGE = 1; + static final int DEFAULT_SIZE = 20; + static final String DEFAULT_SORT_FIELD = "tCreateDate"; + static final String DEFAULT_SORT_ORDER = "desc"; + static final String DEFAULT_MATCH_MODE = "contains"; + + static final Set SORT_FIELDS = Set.of( + "tCreateDate", "tLastLoginDate", "sUsername", "sUserCode"); + + static final Set SORT_ORDERS = Set.of("asc", "desc"); + + static final Set MATCH_MODES = Set.of("contains", "notContains", "equals"); + + /** spec § 业务规则 3：非字符串列（int/datetime）一律按 equals 处理。 */ + static final Set EQUALS_ONLY_FIELDS = Set.of("isDeleted", "lastLoginDate"); + + static final Set USER_TYPES = Set.of("NORMAL", "SUPER_ADMIN"); + + static final Map QUERY_FIELD_TO_SQL = Map.ofEntries( + Map.entry("username", "u.sUsername"), + Map.entry("employeeName", "e.sEmployeeName"), + Map.entry("userCode", "u.sUserCode"), + Map.entry("departmentName", "d.sDepartmentName"), + Map.entry("userType", "u.sUserType"), + Map.entry("isDeleted", "u.iIsDeleted"), + Map.entry("lastLoginDate", "u.tLastLoginDate"), + Map.entry("createdBy", "u.sCreatedBy")); + + private final SysUserMapper userMapper; + + @Override + public PageResult list(UserQueryReq req) { + // 应用默认值 + int page = req.getPage() == null ? DEFAULT_PAGE : req.getPage(); + int size = req.getSize() == null ? DEFAULT_SIZE : req.getSize(); + String sortField = req.getSortField() == null ? DEFAULT_SORT_FIELD : req.getSortField(); + String sortOrder = req.getSortOrder() == null ? DEFAULT_SORT_ORDER : req.getSortOrder(); + String matchMode = req.getMatchMode() == null ? DEFAULT_MATCH_MODE : req.getMatchMode(); + + // 白名单校验 + if (!SORT_FIELDS.contains(sortField)) { + throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "sortField 不在白名单"); + } + if (!SORT_ORDERS.contains(sortOrder)) { + throw new BizException(ErrorCode.BAD_REQUEST, "sortOrder 必须为 asc 或 desc"); + } + if (!MATCH_MODES.contains(matchMode)) { + throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "matchMode 不在白名单"); + } + + String sqlQueryColumn = null; + String normalizedQueryValue = null; + if (req.getQueryField() != null && !req.getQueryField().isBlank()) { + sqlQueryColumn = QUERY_FIELD_TO_SQL.get(req.getQueryField()); + if (sqlQueryColumn == null) { + throw new BizException(ErrorCode.INVALID_ENUM_PARAM, "queryField 不在白名单"); + } + // 只有 queryField + queryValue 都提供且非空才应用条件 + if (req.getQueryValue() != null && !req.getQueryValue().isBlank()) { + normalizedQueryValue = normalizeQueryValue(req.getQueryField(), req.getQueryValue()); + // spec § 业务规则 3：非字符串列一律强制 equals + if (EQUALS_ONLY_FIELDS.contains(req.getQueryField())) { + matchMode = "equals"; + } + } else { + sqlQueryColumn = null; // 缺 queryValue 跳过条件 + } + } + + if (req.getUserType() != null && !USER_TYPES.contains(req.getUserType())) { + throw new BizException(ErrorCode.BAD_REQUEST, "userType 必须为 NORMAL 或 SUPER_ADMIN"); + } + + UserQueryParams p = new UserQueryParams(); + p.sqlSortField = sortField; + p.sqlSortOrder = sortOrder; + p.sqlQueryColumn = sqlQueryColumn; + p.matchMode = matchMode; + p.queryValue = normalizedQueryValue; + p.userType = req.getUserType(); + p.isDeleted = req.getIsDeleted() == null ? null : (req.getIsDeleted() ? 1 : 0); + p.limit = size; + p.offset = (page - 1) * size; + + long total = userMapper.countByQuery(p); + List records = userMapper.selectByQuery(p); + + // 越界矫正：当前页空但 total>0 → 重算最后一页 + int actualPage = page; + if (records.isEmpty() && total > 0) { + int lastPage = (int) ((total + size - 1) / size); + p.offset = (lastPage - 1) * size; + records = userMapper.selectByQuery(p); + actualPage = lastPage; + } + + return PageResult.builder() + .records(records) + .total(total) + .page(actualPage) + .size(size) + .build(); + } + + /** + * 对非字符串列做规范化（spec § 业务规则 3）： + * - isDeleted: true/1 → "1"；false/0 → "0"；其他抛 40001 + * - lastLoginDate: 解析 ISO LOCAL_DATE_TIME 或 ISO LOCAL_DATE，统一格式为 'yyyy-MM-dd HH:mm:ss'；非法抛 40001 + * - 其他列返回原值 + */ + private String normalizeQueryValue(String queryField, String raw) { + if ("isDeleted".equals(queryField)) { + if ("true".equalsIgnoreCase(raw) || "1".equals(raw)) return "1"; + if ("false".equalsIgnoreCase(raw) || "0".equals(raw)) return "0"; + throw new BizException(ErrorCode.BAD_REQUEST, + "queryField=isDeleted 时 queryValue 必须为 true / false / 0 / 1"); + } + if ("lastLoginDate".equals(queryField)) { + try { + LocalDateTime dt; + if (raw.contains("T") || raw.contains(" ")) { + dt = LocalDateTime.parse(raw.replace(' ', 'T')); + } else { + dt = java.time.LocalDate.parse(raw).atStartOfDay(); + } + return dt.format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); + } catch (DateTimeParseException e) { + throw new BizException(ErrorCode.BAD_REQUEST, + "queryField=lastLoginDate 时 queryValue 必须为 ISO 日期或日期时间"); + } + } + return raw; + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java new file mode 100644 index 0000000..88420c7 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java @@ -0,0 +1,135 @@ +package com.xly.erp.module.usr.service.impl; + +import com.baomidou.mybatisplus.core.conditions.update.UpdateWrapper; +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.dto.UpdateUserReq; +import com.xly.erp.module.usr.entity.SysEmployee; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysEmployeeMapper; +import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.service.UserDetailService; +import com.xly.erp.module.usr.service.UserUpdateService; +import com.xly.erp.module.usr.vo.UserDetailVo; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; + +import java.time.LocalDateTime; +import java.util.HashSet; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Set; + +@Service +@RequiredArgsConstructor +@Slf4j +public class UserUpdateServiceImpl implements UserUpdateService { + + private final SysUserMapper userMapper; + private final SysEmployeeMapper employeeMapper; + private final SysPermissionCategoryMapper permissionCategoryMapper; + private final SysUserPermissionCategoryMapper upcMapper; + private final UserDetailService userDetailService; + + @Override + @Transactional + public UserDetailVo update(Integer userId, UpdateUserReq req, + Integer operatorUserId, String operatorUsername) { + // 1. 存在性 + SysUser existing = userMapper.selectById(userId); + if (existing == null) { + throw new BizException(ErrorCode.USER_NOT_FOUND, "用户不存在"); + } + + // 2. 自我停用守卫 + if (Boolean.TRUE.equals(req.getIsDeleted()) && userId.equals(operatorUserId)) { + throw new BizException(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE, + "不允许停用当前登录用户自己"); + } + + // 3. userCode 唯一（排除自身） + if (req.getUserCode() != null + && !req.getUserCode().equals(existing.getSUserCode()) + && userMapper.existsByUserCodeExcludingId(req.getUserCode(), userId)) { + throw new BizException(ErrorCode.CONFLICT_USERCODE, "用户号已被占用"); + } + + // 4. employeeId 外键（仅正整数才查） + if (req.getEmployeeId() != null && req.getEmployeeId() > 0) { + SysEmployee emp = employeeMapper.selectById(req.getEmployeeId()); + if (emp == null || Integer.valueOf(1).equals(emp.getIIsDeleted())) { + throw new BizException(ErrorCode.COMPANY_NOT_FOUND, "指定的员工不存在或已删除"); + } + } + + // 5. permissionCategoryIds 外键（dedup 后校验） + Set targetPcSet = null; + if (req.getPermissionCategoryIds() != null) { + targetPcSet = new LinkedHashSet<>(req.getPermissionCategoryIds()); + if (!targetPcSet.isEmpty()) { + int active = permissionCategoryMapper.countActiveByIds( + new java.util.ArrayList<>(targetPcSet)); + if (active != targetPcSet.size()) { + throw new BizException(ErrorCode.COMPANY_NOT_FOUND, + "指定的权限分类含不存在或已删除项"); + } + } + } + + // 6. 写 sys_user 字段 + UpdateWrapper uw = new UpdateWrapper<>(); + uw.eq("iIncrement", userId); + + if (req.getUserCode() != null) uw.set("sUserCode", req.getUserCode()); + if (req.getUserType() != null) uw.set("sUserType", req.getUserType()); + if (req.getLanguage() != null) uw.set("sLanguage", req.getLanguage()); + if (req.getCanEditDocument() != null) + uw.set("iCanEditDocument", req.getCanEditDocument() ? 1 : 0); + if (req.getIsDeleted() != null) + uw.set("iIsDeleted", req.getIsDeleted() ? 1 : 0); + if (req.getEmployeeId() != null) { + if (req.getEmployeeId() == 0) { + uw.set("iEmployeeId", null); // 解除关联 + } else { + uw.set("iEmployeeId", req.getEmployeeId()); + } + } + uw.set("sUpdatedBy", operatorUsername); + uw.set("tUpdatedDate", LocalDateTime.now()); + + userMapper.update(null, uw); + + // 7. 权限分类增量差集 + if (targetPcSet != null) { + List currentList = upcMapper.selectPermissionCategoryIdsByUserId(userId); + Set currentSet = new HashSet<>(currentList); + + Set toRemove = new HashSet<>(currentSet); + toRemove.removeAll(targetPcSet); + + Set toAdd = new LinkedHashSet<>(targetPcSet); + toAdd.removeAll(currentSet); + + if (!toRemove.isEmpty()) { + upcMapper.deleteByUserAndCategoryIds(userId, new java.util.ArrayList<>(toRemove)); + } + for (Integer pcId : toAdd) { + SysUserPermissionCategory link = new SysUserPermissionCategory(); + link.setIUserId(userId); + link.setIPermissionCategoryId(pcId); + link.setSGrantedBy(operatorUsername); + upcMapper.insert(link); + } + log.info("[user-update] userId={} pc.toRemove={} pc.toAdd={}", + userId, toRemove.size(), toAdd.size()); + } + + log.info("[user-update] userId={} byOperator={} 完成", userId, operatorUsername); + return userDetailService.getById(userId); + } +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java b/backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java new file mode 100644 index 0000000..2365edc --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java @@ -0,0 +1,12 @@ +package com.xly.erp.module.usr.vo; + +import lombok.Builder; +import lombok.Data; + +@Data +@Builder +public class CreateUserVo { + private Integer userId; + private String username; + private String userCode; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java b/backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java new file mode 100644 index 0000000..5e8f933 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java @@ -0,0 +1,13 @@ +package com.xly.erp.module.usr.vo; + +import lombok.Builder; +import lombok.Data; + +@Data +@Builder +public class LoginVo { + private String accessToken; + private String tokenType; + private long expiresInSec; + private UserInfoVo userInfo; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java b/backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java new file mode 100644 index 0000000..7ebb395 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java @@ -0,0 +1,26 @@ +package com.xly.erp.module.usr.vo; + +import com.fasterxml.jackson.annotation.JsonInclude; +import lombok.Builder; +import lombok.Data; + +import java.time.LocalDateTime; +import java.util.List; + +@Data +@Builder +@JsonInclude(JsonInclude.Include.NON_NULL) +public class UserDetailVo { + private Integer userId; + private String username; + private String userCode; + private String userType; + private String language; + private Boolean canEditDocument; + private Boolean isDeleted; + private Integer employeeId; + private String employeeName; + private List permissionCategoryIds; + private String updatedBy; + private LocalDateTime updatedDate; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java b/backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java new file mode 100644 index 0000000..5fe001e --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java @@ -0,0 +1,17 @@ +package com.xly.erp.module.usr.vo; + +import com.fasterxml.jackson.annotation.JsonInclude; +import lombok.Builder; +import lombok.Data; + +@Data +@Builder +@JsonInclude(JsonInclude.Include.NON_NULL) +public class UserInfoVo { + private Integer userId; + private String username; + private String userType; + private String language; + private String employeeName; + private String companyCode; +} diff --git a/backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java b/backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java new file mode 100644 index 0000000..6f61277 --- /dev/null +++ b/backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java @@ -0,0 +1,28 @@ +package com.xly.erp.module.usr.vo; + +import com.fasterxml.jackson.annotation.JsonInclude; +import lombok.Builder; +import lombok.Data; +import lombok.NoArgsConstructor; +import lombok.AllArgsConstructor; + +import java.time.LocalDateTime; + +@Data +@Builder +@NoArgsConstructor +@AllArgsConstructor +@JsonInclude(JsonInclude.Include.ALWAYS) +public class UserListItemVo { + private Integer userId; + private String username; + private String employeeName; + private String userCode; + private String departmentName; + private String userType; + private String language; + private Boolean isDeleted; + private LocalDateTime lastLoginDate; + private String createdBy; + private LocalDateTime createdDate; +} diff --git a/backend/src/main/resources/application-test.yml b/backend/src/main/resources/application-test.yml new file mode 100644 index 0000000..7917780 --- /dev/null +++ b/backend/src/main/resources/application-test.yml @@ -0,0 +1,21 @@ +spring: + jackson: + deserialization: + fail-on-unknown-properties: true + datasource: + url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true + username: ${DB_USER} + password: ${DB_PASSWORD} + flyway: + enabled: true + locations: filesystem:../sql/migrations + +jwt: + secret: ${JWT_SECRET:test-secret-please-replace-with-256bit-random-string-xxxxxxx} + ttl-sec: 7200 + +logging: + level: + root: WARN + com.xly.erp: DEBUG + com.zaxxer.hikari: WARN diff --git a/backend/src/main/resources/application.yml b/backend/src/main/resources/application.yml new file mode 100644 index 0000000..52707cc --- /dev/null +++ b/backend/src/main/resources/application.yml @@ -0,0 +1,38 @@ +server: + port: 9090 + +spring: + application: + name: xly-erp-backend + jackson: + deserialization: + fail-on-unknown-properties: true + datasource: + driver-class-name: com.mysql.cj.jdbc.Driver + url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true + username: ${DB_USER} + password: ${DB_PASSWORD} + flyway: + enabled: true + locations: filesystem:../sql/migrations + baseline-on-migrate: true + baseline-version: 0 + validate-on-migrate: true + +mybatis-plus: + mapper-locations: classpath*:/mapper/**/*.xml + configuration: + map-underscore-to-camel-case: false + log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl + global-config: + db-config: + id-type: auto + +jwt: + secret: ${JWT_SECRET} + ttl-sec: 7200 + +logging: + level: + root: INFO + com.xly.erp: DEBUG diff --git a/backend/src/main/resources/logback-spring.xml b/backend/src/main/resources/logback-spring.xml new file mode 100644 index 0000000..7c2338d --- /dev/null +++ b/backend/src/main/resources/logback-spring.xml @@ -0,0 +1,14 @@ + + + + + %d{HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n + + + + + + + + + diff --git a/backend/src/main/resources/mapper/usr/SysUserMapper.xml b/backend/src/main/resources/mapper/usr/SysUserMapper.xml new file mode 100644 index 0000000..5bad4dc --- /dev/null +++ b/backend/src/main/resources/mapper/usr/SysUserMapper.xml @@ -0,0 +1,74 @@ + + + + + + FROM sys_user u + LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId + LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId + + + + + + + + AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%') + + + AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%') + OR ${p.sqlQueryColumn} IS NULL) + + + AND ${p.sqlQueryColumn} = #{p.queryValue} + + + + + AND u.sUserType = #{p.userType} + + + AND u.iIsDeleted = #{p.isDeleted} + + + + + + + + + + + + + + + + + + + + + + + diff --git a/backend/src/test/java/com/xly/erp/ApplicationContextTest.java b/backend/src/test/java/com/xly/erp/ApplicationContextTest.java new file mode 100644 index 0000000..cc7d10b --- /dev/null +++ b/backend/src/test/java/com/xly/erp/ApplicationContextTest.java @@ -0,0 +1,26 @@ +package com.xly.erp; + +import org.junit.jupiter.api.Test; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.context.ApplicationContext; +import org.springframework.beans.factory.annotation.Autowired; + +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * REQ-USR-001 — Boot smoke test: + * verifies Spring Boot context starts and Flyway has applied V1 against the + * MySQL schema configured via .env.local (DB_HOST/DB_PORT/DB_USER/DB_PASSWORD/DB_SCHEMA). + */ +@SpringBootTest +@org.springframework.test.context.ActiveProfiles("test") +class ApplicationContextTest { + + @Autowired + private ApplicationContext ctx; + + @Test + void contextLoads() { + assertNotNull(ctx, "Spring ApplicationContext should be initialised"); + } +} diff --git a/backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java b/backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java new file mode 100644 index 0000000..3f4c461 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java @@ -0,0 +1,69 @@ +package com.xly.erp.common.exception; + +import com.xly.erp.common.response.ErrorCode; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RestController; + +import static org.hamcrest.Matchers.containsString; +import static org.hamcrest.Matchers.not; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +@org.springframework.context.annotation.Import(GlobalExceptionHandlerTest.ThrowingTestController.class) +class GlobalExceptionHandlerTest { + + @Autowired + private MockMvc mockMvc; + + @Test + void bizException_locked_returns423_withCode42301() throws Exception { + mockMvc.perform(get("/_test/throw/locked")) + .andExpect(status().isLocked()) + .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_LOCKED)) + .andExpect(jsonPath("$.data").doesNotExist()); + } + + @Test + void bizException_badCredentials_returns401_withCode40101() throws Exception { + mockMvc.perform(get("/_test/throw/bad-credentials")) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void unexpectedException_returns500_doesNotLeakStackTrace() throws Exception { + mockMvc.perform(get("/_test/throw/runtime")) + .andExpect(status().isInternalServerError()) + .andExpect(jsonPath("$.code").value(ErrorCode.INTERNAL_ERROR)) + .andExpect(jsonPath("$.message").value(not(containsString("java.")))) + .andExpect(jsonPath("$.message").value(not(containsString("Exception")))); + } + + @RestController + static class ThrowingTestController { + @GetMapping("/_test/throw/locked") + public void locked() { + throw new BizException(ErrorCode.ACCOUNT_LOCKED, "账号已锁定，请稍后再试"); + } + + @GetMapping("/_test/throw/bad-credentials") + public void badCredentials() { + throw new BizException(ErrorCode.BAD_CREDENTIALS, "用户名或密码错误"); + } + + @GetMapping("/_test/throw/runtime") + public void runtime() { + throw new RuntimeException("internal boom java.lang.NullPointerException"); + } + } +} diff --git a/backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java b/backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java new file mode 100644 index 0000000..d83b32e --- /dev/null +++ b/backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java @@ -0,0 +1,43 @@ +package com.xly.erp.common.response; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +class ErrorCodeTest { + + @Test + void httpMappings_coverNewCodes() { + assertEquals(403, ErrorCode.toHttpStatus(ErrorCode.FORBIDDEN)); + assertEquals(409, ErrorCode.toHttpStatus(ErrorCode.CONFLICT_USERNAME)); + assertEquals(409, ErrorCode.toHttpStatus(ErrorCode.CONFLICT_USERCODE)); + assertEquals(40301, ErrorCode.FORBIDDEN); + assertEquals(40901, ErrorCode.CONFLICT_USERNAME); + assertEquals(40902, ErrorCode.CONFLICT_USERCODE); + } + + @Test + void httpMappings_coverNewCodes_v004() { + assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.INVALID_ENUM_PARAM)); + assertEquals(40003, ErrorCode.INVALID_ENUM_PARAM); + } + + @Test + void httpMappings_coverNewCodes_v003() { + assertEquals(403, ErrorCode.toHttpStatus(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE)); + assertEquals(404, ErrorCode.toHttpStatus(ErrorCode.USER_NOT_FOUND)); + assertEquals(40302, ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE); + assertEquals(40401, ErrorCode.USER_NOT_FOUND); + } + + @Test + void httpMappings_existingCodes_unchanged() { + assertEquals(200, ErrorCode.toHttpStatus(ErrorCode.OK)); + assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.BAD_REQUEST)); + assertEquals(400, ErrorCode.toHttpStatus(ErrorCode.COMPANY_NOT_FOUND)); + assertEquals(401, ErrorCode.toHttpStatus(ErrorCode.BAD_CREDENTIALS)); + assertEquals(401, ErrorCode.toHttpStatus(ErrorCode.ACCOUNT_DELETED)); + assertEquals(423, ErrorCode.toHttpStatus(ErrorCode.ACCOUNT_LOCKED)); + assertEquals(500, ErrorCode.toHttpStatus(ErrorCode.INTERNAL_ERROR)); + } +} diff --git a/backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java b/backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java new file mode 100644 index 0000000..0e2c51a --- /dev/null +++ b/backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java @@ -0,0 +1,148 @@ +package com.xly.erp.common.security; + +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +import java.util.HashMap; +import java.util.Map; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +@org.springframework.context.annotation.Import(JwtHandlerInterceptorTest.GuardedTestController.class) +class JwtHandlerInterceptorTest { + + @Autowired private MockMvc mvc; + @Autowired private JwtUtil jwtUtil; + @Autowired private LoginTestSeeder seeder; + @Autowired private org.springframework.jdbc.core.JdbcTemplate jdbc; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + private String issueToken(String username, String userType, String companyCode) { + Map claims = new HashMap<>(); + claims.put("sub", 1); + claims.put("username", username); + claims.put("userType", userType); + claims.put("companyCode", companyCode); + claims.put("language", "zh-CN"); + return jwtUtil.issue(claims, 7200); + } + + // ===== 鉴权基础 ===== + + @Test + void noAuthHeader_returns401_40101() throws Exception { + mvc.perform(get("/api/v1/_test/any-auth")) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void invalidToken_returns401_40101() throws Exception { + mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer bogus.jwt.token")) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void tokenForUnknownUser_returns401_40101() throws Exception { + String token = issueToken("nobody", "NORMAL", "HQ"); + mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token)) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void tokenForDeletedUser_returns401_40101() throws Exception { + String token = issueToken(LoginTestSeeder.USER_DELETED, "NORMAL", "HQ"); + mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token)) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void tokenForLockedUser_returns401_40101() throws Exception { + jdbc.update("UPDATE sys_user SET tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?", + LoginTestSeeder.USER_OK); + String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ"); + mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token)) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void validToken_normalUser_canAccessAnyAuthEndpoint() throws Exception { + String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ"); + mvc.perform(get("/api/v1/_test/any-auth").header("Authorization", "Bearer " + token)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data").value("ok-" + LoginTestSeeder.USER_OK)); + } + + // ===== @RequireSuperAdmin ===== + + @Test + void validToken_normalUser_cannotAccessAdminOnly_returns403_40301() throws Exception { + String token = issueToken(LoginTestSeeder.USER_OK, "NORMAL", "HQ"); + mvc.perform(get("/api/v1/_test/admin-only").header("Authorization", "Bearer " + token)) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN)); + } + + @Test + void validToken_superAdmin_canAccessAdminOnly() throws Exception { + // 把 alice 升级为 SUPER_ADMIN + jdbc.update("UPDATE sys_user SET sUserType='SUPER_ADMIN' WHERE sUsername=?", LoginTestSeeder.USER_OK); + String token = issueToken(LoginTestSeeder.USER_OK, "SUPER_ADMIN", "HQ"); + mvc.perform(get("/api/v1/_test/admin-only").header("Authorization", "Bearer " + token)) + .andExpect(status().isOk()); + } + + // ===== 放行 /api/v1/auth/login ===== + + @Test + void loginEndpointPath_skipsInterceptor() throws Exception { + // 不带 auth 头调登录接口；应进入 controller 并返参数校验错（不是 40101） + mvc.perform(post("/api/v1/auth/login").contentType("application/json").content("{}")) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @RestController + @RequestMapping("/api/v1/_test") + static class GuardedTestController { + + @GetMapping("/any-auth") + public com.xly.erp.common.response.Result anyAuth() { + LoginContext.LoginUser u = LoginContext.current(); + return com.xly.erp.common.response.Result.ok("ok-" + (u == null ? "null" : u.username())); + } + + @GetMapping("/admin-only") + @RequireSuperAdmin + public com.xly.erp.common.response.Result adminOnly() { + return com.xly.erp.common.response.Result.ok("admin"); + } + } +} diff --git a/backend/src/test/java/com/xly/erp/common/security/JwtUtilTest.java b/backend/src/test/java/com/xly/erp/common/security/JwtUtilTest.java new file mode 100644 index 0000000..6b2211b --- /dev/null +++ b/backend/src/test/java/com/xly/erp/common/security/JwtUtilTest.java @@ -0,0 +1,68 @@ +package com.xly.erp.common.security; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import java.util.HashMap; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class JwtUtilTest { + + @Autowired + private JwtUtil jwtUtil; + + private Map sampleClaims() { + Map claims = new HashMap<>(); + claims.put("sub", "42"); + claims.put("username", "alice"); + claims.put("userType", "NORMAL"); + claims.put("companyCode", "HQ"); + claims.put("language", "zh-CN"); + return claims; + } + + @Test + void issuedToken_canBeParsedBackToClaims() { + String token = jwtUtil.issue(sampleClaims(), 7200); + assertNotNull(token); + assertFalse(token.isEmpty()); + + Map parsed = jwtUtil.parse(token); + assertEquals("42", parsed.get("sub")); + assertEquals("alice", parsed.get("username")); + assertEquals("NORMAL", parsed.get("userType")); + assertEquals("HQ", parsed.get("companyCode")); + assertEquals("zh-CN", parsed.get("language")); + assertNotNull(parsed.get("jti")); + assertNotNull(parsed.get("iat")); + assertNotNull(parsed.get("exp")); + + long iat = ((Number) parsed.get("iat")).longValue(); + long exp = ((Number) parsed.get("exp")).longValue(); + assertEquals(7200L, exp - iat, "exp - iat 必须严格等于 ttlSec（spec § 验收 § 2）"); + } + + @Test + void tamperedToken_throwsBizException() { + String token = jwtUtil.issue(sampleClaims(), 7200); + String tampered = token.substring(0, token.length() - 4) + "XXXX"; + BizException e = assertThrows(BizException.class, () -> jwtUtil.parse(tampered)); + assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode()); + } + + @Test + void expiredToken_throwsBizException() { + String token = jwtUtil.issue(sampleClaims(), 0L); + try { Thread.sleep(1100); } catch (InterruptedException ignored) {} + BizException e = assertThrows(BizException.class, () -> jwtUtil.parse(token)); + assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode()); + } +} diff --git a/backend/src/test/java/com/xly/erp/common/security/LoginContextTest.java b/backend/src/test/java/com/xly/erp/common/security/LoginContextTest.java new file mode 100644 index 0000000..0fdd7e3 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/common/security/LoginContextTest.java @@ -0,0 +1,51 @@ +package com.xly.erp.common.security; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.Test; + +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.jupiter.api.Assertions.*; + +class LoginContextTest { + + @AfterEach + void tearDown() { + LoginContext.clear(); + } + + @Test + void setAndCurrent_returnsSameUser() { + LoginContext.LoginUser u = new LoginContext.LoginUser(42, "alice", "NORMAL", "HQ"); + LoginContext.set(u); + assertSame(u, LoginContext.current()); + } + + @Test + void clear_returnsNullForCurrent() { + LoginContext.set(new LoginContext.LoginUser(1, "x", "NORMAL", "HQ")); + LoginContext.clear(); + assertNull(LoginContext.current()); + } + + @Test + void setAndCurrent_isolatedPerThread() throws InterruptedException { + LoginContext.set(new LoginContext.LoginUser(1, "main", "NORMAL", "HQ")); + + AtomicReference seen = new AtomicReference<>(); + CountDownLatch latch = new CountDownLatch(1); + Thread t = new Thread(() -> { + seen.set(LoginContext.current()); + LoginContext.set(new LoginContext.LoginUser(2, "child", "SUPER_ADMIN", "HQ")); + latch.countDown(); + }); + t.start(); + latch.await(); + t.join(); + + assertNull(seen.get(), "子线程不应继承父线程 ThreadLocal"); + assertEquals("main", LoginContext.current().username(), + "父线程上下文不应被子线程改动影响"); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java b/backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java new file mode 100644 index 0000000..efecf83 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java @@ -0,0 +1,116 @@ +package com.xly.erp.module.usr.controller; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.dto.LoginReq; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.http.MediaType; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +class AuthControllerTest { + + @Autowired private MockMvc mvc; + @Autowired private ObjectMapper json; + @Autowired private LoginTestSeeder seeder; + @Autowired private JdbcTemplate jdbc; + + @BeforeEach + void setUp() { + seeder.reset(); + } + + private String body(String username, String password, String companyCode) throws Exception { + LoginReq r = new LoginReq(); + r.setUsername(username); + r.setPassword(password); + r.setCompanyCode(companyCode); + return json.writeValueAsString(r); + } + + @Test + void post_login_success_returns200_andLoginVo() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data.accessToken").isNotEmpty()) + .andExpect(jsonPath("$.data.tokenType").value("Bearer")) + .andExpect(jsonPath("$.data.expiresInSec").value(7200)) + .andExpect(jsonPath("$.data.userInfo.username").value(LoginTestSeeder.USER_OK)) + .andExpect(jsonPath("$.data.userInfo.companyCode").value(LoginTestSeeder.COMPANY_OK)); + } + + @Test + void post_login_badCredentials_returns401_code40101() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void post_login_unknownUser_returns401_code40101() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body("nobody", "any", LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void post_login_lockedAccount_returns423_code42301_withLockUntil() throws Exception { + jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?", + LoginTestSeeder.USER_OK); + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isLocked()) + .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_LOCKED)) + .andExpect(jsonPath("$.data.lockUntil").isNotEmpty()); + } + + @Test + void post_login_deletedAccount_returns401_code40103() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(LoginTestSeeder.USER_DELETED, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.ACCOUNT_DELETED)); + } + + @Test + void post_login_unknownCompany_returns400_code40004() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, "NOPE"))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND)); + } + + @Test + void post_login_blankUsername_returns400_code40001() throws Exception { + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body("", LoginTestSeeder.DEFAULT_PASSWORD, LoginTestSeeder.COMPANY_OK))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java new file mode 100644 index 0000000..d70187b --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java @@ -0,0 +1,254 @@ +package com.xly.erp.module.usr.controller; + +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.security.JwtUtil; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; + +import java.util.HashMap; +import java.util.Map; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +class UserControllerListTest { + + @Autowired private MockMvc mvc; + @Autowired private LoginTestSeeder seeder; + @Autowired private JwtUtil jwtUtil; + @Autowired private JdbcTemplate jdbc; + + private LoginTestSeeder.Fixture fx; + private String adminToken; + private String normalToken; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN", fx.adminId()); + normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL", fx.aliceId()); + } + + private String issue(String username, String userType, Integer userId) { + Map c = new HashMap<>(); + c.put("sub", userId); + c.put("username", username); + c.put("userType", userType); + c.put("companyCode", LoginTestSeeder.COMPANY_OK); + c.put("language", "zh-CN"); + return jwtUtil.issue(c, 7200); + } + + @Test + void list_default_returnsAllUsers() throws Exception { + mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data.total").value(3)) + .andExpect(jsonPath("$.data.records.length()").value(3)) + .andExpect(jsonPath("$.data.page").value(1)) + .andExpect(jsonPath("$.data.size").value(20)); + } + + @Test + void list_sizeOver100_returns400_40001() throws Exception { + mvc.perform(get("/api/v1/users") + .param("size", "200") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void list_pageZero_returns400_40001() throws Exception { + mvc.perform(get("/api/v1/users") + .param("page", "0") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void list_sortByUsernameAsc() throws Exception { + mvc.perform(get("/api/v1/users") + .param("sortField", "sUsername") + .param("sortOrder", "asc") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_ADMIN)); + } + + @Test + void list_sortFieldInvalid_returns400_40003() throws Exception { + mvc.perform(get("/api/v1/users") + .param("sortField", "badField") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM)); + } + + @Test + void list_sortOrderInvalid_returns400_40001() throws Exception { + mvc.perform(get("/api/v1/users") + .param("sortOrder", "foo") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void list_queryByUsernameContains() throws Exception { + mvc.perform(get("/api/v1/users") + .param("queryField", "username") + .param("matchMode", "contains") + .param("queryValue", "ali") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(1)) + .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_OK)); + } + + @Test + void list_queryByDepartmentName_multiJoin() throws Exception { + mvc.perform(get("/api/v1/users") + .param("queryField", "departmentName") + .param("matchMode", "equals") + .param("queryValue", "技术部") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(1)) + .andExpect(jsonPath("$.data.records[0].departmentName").value("技术部")); + } + + @Test + void list_queryByIsDeletedTrue() throws Exception { + mvc.perform(get("/api/v1/users") + .param("queryField", "isDeleted") + .param("matchMode", "equals") + .param("queryValue", "true") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(1)) + .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_DELETED)); + } + + @Test + void list_queryFieldInvalid_returns400_40003() throws Exception { + mvc.perform(get("/api/v1/users") + .param("queryField", "badField") + .param("queryValue", "x") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM)); + } + + @Test + void list_matchModeInvalid_returns400_40003() throws Exception { + mvc.perform(get("/api/v1/users") + .param("matchMode", "startsWith") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.INVALID_ENUM_PARAM)); + } + + @Test + void list_explicitUserTypeFilter() throws Exception { + mvc.perform(get("/api/v1/users") + .param("userType", "NORMAL") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(2)); // alice + bob_deleted + } + + @Test + void list_explicitUserTypeInvalid_returns400_40001() throws Exception { + mvc.perform(get("/api/v1/users") + .param("userType", "HACKER") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void list_explicitIsDeletedFalse_filtersActive() throws Exception { + mvc.perform(get("/api/v1/users") + .param("isDeleted", "false") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(2)); // alice + admin + } + + @Test + void list_composedFilters_andSemantics() throws Exception { + mvc.perform(get("/api/v1/users") + .param("queryField", "username") + .param("queryValue", "a") + .param("userType", "NORMAL") + .param("isDeleted", "false") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(1)) + .andExpect(jsonPath("$.data.records[0].username").value(LoginTestSeeder.USER_OK)); + } + + @Test + void list_pageBeyondTotal_returnsLastPage() throws Exception { + mvc.perform(get("/api/v1/users") + .param("page", "999") + .param("size", "10") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(3)) + .andExpect(jsonPath("$.data.page").value(1)) + .andExpect(jsonPath("$.data.records.length()").value(3)); + } + + @Test + void list_normalUserToken_returns403_40301() throws Exception { + mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + normalToken)) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN)); + } + + @Test + void list_noAuthHeader_returns401_40101() throws Exception { + mvc.perform(get("/api/v1/users")) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void list_responseRecordDoesNotIncludePasswordField() throws Exception { + mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.records[0].password").doesNotExist()) + .andExpect(jsonPath("$.data.records[0].passwordHash").doesNotExist()) + .andExpect(jsonPath("$.data.records[0].sPasswordHash").doesNotExist()); + } + + @Test + void list_emptyTable_returnsZeroTotal() throws Exception { + jdbc.update("DELETE FROM sys_user_permission_category"); + jdbc.update("DELETE FROM sys_user"); + // 但鉴权需要 token 关联用户存在，所以保留 admin 用户即可 + // 重做：只删 alice / bob + // 重置后用一个独立 seed + seeder.reset(); + jdbc.update("DELETE FROM sys_user WHERE sUsername IN (?, ?)", + LoginTestSeeder.USER_OK, LoginTestSeeder.USER_DELETED); + + mvc.perform(get("/api/v1/users").header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.total").value(1)); // 只剩 admin + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java new file mode 100644 index 0000000..c87a408 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java @@ -0,0 +1,220 @@ +package com.xly.erp.module.usr.controller; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.security.JwtUtil; +import com.xly.erp.module.usr.dto.CreateUserReq; +import com.xly.erp.module.usr.dto.LoginReq; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.http.MediaType; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +class UserControllerTest { + + @Autowired private MockMvc mvc; + @Autowired private ObjectMapper json; + @Autowired private LoginTestSeeder seeder; + @Autowired private JwtUtil jwtUtil; + + private LoginTestSeeder.Fixture fx; + private String adminToken; + private String normalToken; + private String deletedToken; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN"); + normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL"); + deletedToken = issue(LoginTestSeeder.USER_DELETED, "NORMAL"); + } + + private String issue(String username, String userType) { + Map claims = new HashMap<>(); + claims.put("sub", 1); + claims.put("username", username); + claims.put("userType", userType); + claims.put("companyCode", LoginTestSeeder.COMPANY_OK); + claims.put("language", "zh-CN"); + return jwtUtil.issue(claims, 7200); + } + + private CreateUserReq buildReq() { + CreateUserReq r = new CreateUserReq(); + r.setUsername("newbie"); + r.setUserCode("U010"); + r.setUserType("NORMAL"); + r.setLanguage("zh-CN"); + r.setCanEditDocument(false); + return r; + } + + private String body(Object o) throws Exception { + return json.writeValueAsString(o); + } + + @Test + void post_users_success_returns201_andCreatedVo() throws Exception { + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(buildReq()))) + .andExpect(status().isCreated()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data.userId").isNumber()) + .andExpect(jsonPath("$.data.username").value("newbie")) + .andExpect(jsonPath("$.data.userCode").value("U010")); + } + + @Test + void post_users_blankUsername_returns400_40001() throws Exception { + CreateUserReq r = buildReq(); + r.setUsername(""); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void post_users_invalidUserType_returns400_40001() throws Exception { + CreateUserReq r = buildReq(); + r.setUserType("ROOT"); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void post_users_unknownPropertyPassword_returns400_40001() throws Exception { + ObjectNode body = json.valueToTree(buildReq()); + body.put("password", "Password1!"); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body.toString())) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void post_users_noAuthHeader_returns401_40101() throws Exception { + mvc.perform(post("/api/v1/users") + .contentType(MediaType.APPLICATION_JSON) + .content(body(buildReq()))) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void post_users_normalUserToken_returns403_40301() throws Exception { + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + normalToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(buildReq()))) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN)); + } + + @Test + void post_users_deletedUserToken_returns401_40101() throws Exception { + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + deletedToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(buildReq()))) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void post_users_duplicateUsername_returns409_40901() throws Exception { + CreateUserReq r = buildReq(); + r.setUsername(LoginTestSeeder.USER_OK); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isConflict()) + .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERNAME)); + } + + @Test + void post_users_duplicateUserCode_returns409_40902() throws Exception { + CreateUserReq r = buildReq(); + r.setUserCode("U001"); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isConflict()) + .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERCODE)); + } + + @Test + void post_users_unknownEmployee_returns400_40004() throws Exception { + CreateUserReq r = buildReq(); + r.setEmployeeId(99999); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND)); + } + + @Test + void post_users_unknownPermissionCategory_returns400_40004() throws Exception { + CreateUserReq r = buildReq(); + r.setPermissionCategoryIds(List.of(99999)); + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND)); + } + + @Test + void post_users_success_canLoginWithInitialPassword() throws Exception { + // 1) admin 创建用户 + mvc.perform(post("/api/v1/users") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(buildReq()))) + .andExpect(status().isCreated()); + + // 2) 新用户用初始密码 666666 登录应成功 + LoginReq login = new LoginReq(); + login.setUsername("newbie"); + login.setPassword("666666"); + login.setCompanyCode(LoginTestSeeder.COMPANY_OK); + mvc.perform(post("/api/v1/auth/login") + .contentType(MediaType.APPLICATION_JSON) + .content(body(login))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data.accessToken").isNotEmpty()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java new file mode 100644 index 0000000..45c3a01 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java @@ -0,0 +1,332 @@ +package com.xly.erp.module.usr.controller; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.security.JwtUtil; +import com.xly.erp.module.usr.dto.UpdateUserReq; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.http.MediaType; +import org.springframework.test.context.ActiveProfiles; +import org.springframework.test.web.servlet.MockMvc; + +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; + +@SpringBootTest +@AutoConfigureMockMvc +@ActiveProfiles("test") +class UserControllerUpdateTest { + + @Autowired private MockMvc mvc; + @Autowired private ObjectMapper json; + @Autowired private LoginTestSeeder seeder; + @Autowired private JwtUtil jwtUtil; + @Autowired private SysUserPermissionCategoryMapper upcMapper; + @Autowired private com.xly.erp.module.usr.mapper.SysUserMapper userMapper; + + private LoginTestSeeder.Fixture fx; + private String adminToken; + private String normalToken; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + adminToken = issue(LoginTestSeeder.USER_ADMIN, "SUPER_ADMIN", fx.adminId()); + normalToken = issue(LoginTestSeeder.USER_OK, "NORMAL", fx.aliceId()); + } + + private String issue(String username, String userType, Integer userId) { + Map c = new HashMap<>(); + c.put("sub", userId); + c.put("username", username); + c.put("userType", userType); + c.put("companyCode", LoginTestSeeder.COMPANY_OK); + c.put("language", "zh-CN"); + return jwtUtil.issue(c, 7200); + } + + // ===== GET ===== + + @Test + void get_existingUser_returns200_andFullVo() throws Exception { + mvc.perform(get("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.code").value(ErrorCode.OK)) + .andExpect(jsonPath("$.data.userId").value(fx.aliceId())) + .andExpect(jsonPath("$.data.username").value(LoginTestSeeder.USER_OK)) + .andExpect(jsonPath("$.data.employeeName").value("张三")); + } + + @Test + void get_unknownUser_returns404_40401() throws Exception { + mvc.perform(get("/api/v1/users/99999") + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isNotFound()) + .andExpect(jsonPath("$.code").value(ErrorCode.USER_NOT_FOUND)); + } + + @Test + void get_normalUser_returns403_40301() throws Exception { + mvc.perform(get("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + normalToken)) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN)); + } + + @Test + void get_noAuthHeader_returns401_40101() throws Exception { + mvc.perform(get("/api/v1/users/" + fx.aliceId())) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void get_deletedUser_stillReturns200() throws Exception { + mvc.perform(get("/api/v1/users/" + fx.bobDeletedId()) + .header("Authorization", "Bearer " + adminToken)) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.isDeleted").value(true)); + } + + // ===== PUT ===== + + private String body(Object o) throws Exception { + return json.writeValueAsString(o); + } + + private UpdateUserReq req() { + return new UpdateUserReq(); + } + + @Test + void put_updateUserCodeAndType_returns200() throws Exception { + UpdateUserReq r = req(); + r.setUserCode("U_NEW"); + r.setUserType("SUPER_ADMIN"); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.userCode").value("U_NEW")) + .andExpect(jsonPath("$.data.userType").value("SUPER_ADMIN")); + } + + @Test + void put_updateEmployeeId_toAnotherEmployee_setsValue() throws Exception { + UpdateUserReq r = req(); + r.setEmployeeId(fx.employeeId()); + mvc.perform(put("/api/v1/users/" + fx.adminId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.employeeId").value(fx.employeeId())); + } + + @Test + void put_updateEmployeeId_zero_clearsRelation() throws Exception { + UpdateUserReq r = req(); + r.setEmployeeId(0); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.employeeId").doesNotExist()); + } + + @Test + void put_updateEmployeeId_unknown_returns400_40004() throws Exception { + UpdateUserReq r = req(); + r.setEmployeeId(99999); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND)); + } + + @Test + void put_isDeletedTrue_marksAndOriginalTokenRejectedNextCall() throws Exception { + // 把 alice 设为作废 + UpdateUserReq r = req(); + r.setIsDeleted(true); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()); + + // 用 alice 的 token 调任何 /api/v1/** 接口应 40101 + // 但 alice 是 NORMAL，连 admin 路径都会先 401（用户已作废），不是 403 + mvc.perform(get("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + normalToken)) + .andExpect(status().isUnauthorized()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_CREDENTIALS)); + } + + @Test + void put_permissionCategories_subsetDelta() throws Exception { + Integer pur = fx.activePermissionCategoryIds().get(0); + Integer sal = fx.activePermissionCategoryIds().get(1); + // 预置 alice 有 {pur, sal} + for (Integer pcId : List.of(pur, sal)) { + SysUserPermissionCategory l = new SysUserPermissionCategory(); + l.setIUserId(fx.aliceId()); + l.setIPermissionCategoryId(pcId); + l.setSGrantedBy("system"); + upcMapper.insert(l); + } + + UpdateUserReq r = req(); + r.setPermissionCategoryIds(List.of(sal)); // 只保留 sal + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.permissionCategoryIds.length()").value(1)) + .andExpect(jsonPath("$.data.permissionCategoryIds[0]").value(sal)); + } + + @Test + void put_permissionCategories_emptyArray_clearsAll() throws Exception { + Integer pur = fx.activePermissionCategoryIds().get(0); + SysUserPermissionCategory l = new SysUserPermissionCategory(); + l.setIUserId(fx.aliceId()); + l.setIPermissionCategoryId(pur); + l.setSGrantedBy("system"); + upcMapper.insert(l); + + UpdateUserReq r = req(); + r.setPermissionCategoryIds(List.of()); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.permissionCategoryIds.length()").value(0)); + } + + @Test + void put_permissionCategories_unknownId_returns400_40004_andRollsBack() throws Exception { + UpdateUserReq r = req(); + r.setUserCode("U_NEW"); + r.setPermissionCategoryIds(List.of(99999)); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.COMPANY_NOT_FOUND)); + + // 验证回滚：alice 的 userCode 仍是 U001 + com.xly.erp.module.usr.entity.SysUser db = userMapper.selectById(fx.aliceId()); + org.junit.jupiter.api.Assertions.assertEquals("U001", db.getSUserCode()); + } + + @Test + void put_duplicateUserCode_returns409_40902() throws Exception { + UpdateUserReq r = req(); + r.setUserCode("U001"); // alice 的 userCode + mvc.perform(put("/api/v1/users/" + fx.adminId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isConflict()) + .andExpect(jsonPath("$.code").value(ErrorCode.CONFLICT_USERCODE)); + } + + @Test + void put_userCodeUnchangedSameAsSelf_returns200() throws Exception { + UpdateUserReq r = req(); + r.setUserCode("U001"); // alice 的当前 userCode + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isOk()); + } + + @Test + void put_selfDeactivate_returns403_40302() throws Exception { + UpdateUserReq r = req(); + r.setIsDeleted(true); + mvc.perform(put("/api/v1/users/" + fx.adminId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(r))) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE)); + } + + @Test + void put_unknownProperty_username_returns400_40001() throws Exception { + ObjectNode b = json.createObjectNode(); + b.put("username", "hacker"); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(b.toString())) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void put_unknownProperty_password_returns400_40001() throws Exception { + ObjectNode b = json.createObjectNode(); + b.put("password", "newpass"); + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(b.toString())) + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.code").value(ErrorCode.BAD_REQUEST)); + } + + @Test + void put_unknownUserId_returns404_40401() throws Exception { + mvc.perform(put("/api/v1/users/99999") + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(req()))) + .andExpect(status().isNotFound()) + .andExpect(jsonPath("$.code").value(ErrorCode.USER_NOT_FOUND)); + } + + @Test + void put_normalUser_returns403_40301() throws Exception { + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + normalToken) + .contentType(MediaType.APPLICATION_JSON) + .content(body(req()))) + .andExpect(status().isForbidden()) + .andExpect(jsonPath("$.code").value(ErrorCode.FORBIDDEN)); + } + + @Test + void put_emptyBody_only_updates_audit_fields() throws Exception { + mvc.perform(put("/api/v1/users/" + fx.aliceId()) + .header("Authorization", "Bearer " + adminToken) + .contentType(MediaType.APPLICATION_JSON) + .content("{}")) + .andExpect(status().isOk()) + .andExpect(jsonPath("$.data.updatedBy").value(LoginTestSeeder.USER_ADMIN)); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/dto/CreateUserReqValidationTest.java b/backend/src/test/java/com/xly/erp/module/usr/dto/CreateUserReqValidationTest.java new file mode 100644 index 0000000..7b11be2 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/dto/CreateUserReqValidationTest.java @@ -0,0 +1,96 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.ConstraintViolation; +import jakarta.validation.Validation; +import jakarta.validation.Validator; +import org.junit.jupiter.api.Test; + +import java.util.List; +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.*; + +class CreateUserReqValidationTest { + + private static final Validator VALIDATOR = + Validation.buildDefaultValidatorFactory().getValidator(); + + private CreateUserReq build() { + CreateUserReq r = new CreateUserReq(); + r.setUsername("alice2"); + r.setUserCode("U010"); + r.setUserType("NORMAL"); + r.setLanguage("zh-CN"); + r.setCanEditDocument(false); + return r; + } + + @Test + void allRequired_passes() { + Set> v = VALIDATOR.validate(build()); + assertTrue(v.isEmpty()); + } + + @Test + void blankUsername_fails() { + CreateUserReq r = build(); + r.setUsername(""); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void usernameTooShort_fails() { + CreateUserReq r = build(); + r.setUsername("ab"); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void usernameWithIllegalChar_fails() { + CreateUserReq r = build(); + r.setUsername("al ice"); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void userCodeTooLong_fails() { + CreateUserReq r = build(); + r.setUserCode("X".repeat(51)); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void userTypeNotEnum_fails() { + CreateUserReq r = build(); + r.setUserType("ROOT"); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void languageNotEnum_fails() { + CreateUserReq r = build(); + r.setLanguage("ja-JP"); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void canEditDocumentMissing_fails() { + CreateUserReq r = build(); + r.setCanEditDocument(null); + assertFalse(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void employeeIdNull_isAllowed() { + CreateUserReq r = build(); + r.setEmployeeId(null); + assertTrue(VALIDATOR.validate(r).isEmpty()); + } + + @Test + void permissionCategoryIdsEmpty_isAllowed() { + CreateUserReq r = build(); + r.setPermissionCategoryIds(List.of()); + assertTrue(VALIDATOR.validate(r).isEmpty()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/dto/LoginReqValidationTest.java b/backend/src/test/java/com/xly/erp/module/usr/dto/LoginReqValidationTest.java new file mode 100644 index 0000000..d300140 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/dto/LoginReqValidationTest.java @@ -0,0 +1,66 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.ConstraintViolation; +import jakarta.validation.Validation; +import jakarta.validation.Validator; +import jakarta.validation.ValidatorFactory; +import org.junit.jupiter.api.Test; + +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.*; + +class LoginReqValidationTest { + + private static final Validator VALIDATOR = + Validation.buildDefaultValidatorFactory().getValidator(); + + private LoginReq build(String u, String p, String c) { + LoginReq r = new LoginReq(); + r.setUsername(u); + r.setPassword(p); + r.setCompanyCode(c); + return r; + } + + @Test + void blankUsername_fails() { + Set> v = VALIDATOR.validate(build("", "Password1!", "HQ")); + assertFalse(v.isEmpty()); + assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("username"))); + } + + @Test + void blankPassword_fails() { + Set> v = VALIDATOR.validate(build("alice", "", "HQ")); + assertFalse(v.isEmpty()); + assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("password"))); + } + + @Test + void blankCompanyCode_fails() { + Set> v = VALIDATOR.validate(build("alice", "Password1!", "")); + assertFalse(v.isEmpty()); + assertTrue(v.stream().anyMatch(c -> c.getPropertyPath().toString().equals("companyCode"))); + } + + @Test + void tooLongUsername_fails() { + String tooLong = "a".repeat(51); + Set> v = VALIDATOR.validate(build(tooLong, "Password1!", "HQ")); + assertFalse(v.isEmpty()); + } + + @Test + void tooLongPassword_fails() { + String tooLong = "a".repeat(129); + Set> v = VALIDATOR.validate(build("alice", tooLong, "HQ")); + assertFalse(v.isEmpty()); + } + + @Test + void allFieldsPresent_passes() { + Set> v = VALIDATOR.validate(build("alice", "Password1!", "HQ")); + assertTrue(v.isEmpty()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/dto/UpdateUserReqValidationTest.java b/backend/src/test/java/com/xly/erp/module/usr/dto/UpdateUserReqValidationTest.java new file mode 100644 index 0000000..8e421f4 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/dto/UpdateUserReqValidationTest.java @@ -0,0 +1,77 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.ConstraintViolation; +import jakarta.validation.Validation; +import jakarta.validation.Validator; +import org.junit.jupiter.api.Test; + +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.*; + +class UpdateUserReqValidationTest { + + private static final Validator V = + Validation.buildDefaultValidatorFactory().getValidator(); + + @Test + void emptyBody_isValid() { + assertTrue(V.validate(new UpdateUserReq()).isEmpty()); + } + + @Test + void invalidUserType_fails() { + UpdateUserReq r = new UpdateUserReq(); + r.setUserType("ROOT"); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void invalidLanguage_fails() { + UpdateUserReq r = new UpdateUserReq(); + r.setLanguage("ja-JP"); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void userCodeTooLong_fails() { + UpdateUserReq r = new UpdateUserReq(); + r.setUserCode("X".repeat(51)); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void userCodeBlank_fails() { + UpdateUserReq r = new UpdateUserReq(); + r.setUserCode(" "); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void employeeIdNegative_fails() { + UpdateUserReq r = new UpdateUserReq(); + r.setEmployeeId(-1); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void employeeIdZero_isValid_meansUnsetRelation() { + UpdateUserReq r = new UpdateUserReq(); + r.setEmployeeId(0); + assertTrue(V.validate(r).isEmpty()); + } + + @Test + void allValidFields_passes() { + UpdateUserReq r = new UpdateUserReq(); + r.setUserCode("U999"); + r.setUserType("NORMAL"); + r.setLanguage("zh-CN"); + r.setCanEditDocument(true); + r.setEmployeeId(7); + r.setIsDeleted(false); + r.setPermissionCategoryIds(java.util.List.of(1, 2)); + Set> v = V.validate(r); + assertTrue(v.isEmpty(), () -> "should be empty but got: " + v); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java b/backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java new file mode 100644 index 0000000..4407c00 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java @@ -0,0 +1,55 @@ +package com.xly.erp.module.usr.dto; + +import jakarta.validation.Validation; +import jakarta.validation.Validator; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class UserQueryReqValidationTest { + + private static final Validator V = + Validation.buildDefaultValidatorFactory().getValidator(); + + @Test + void emptyReq_isValid() { + assertTrue(V.validate(new UserQueryReq()).isEmpty()); + } + + @Test + void pageZero_fails() { + UserQueryReq r = new UserQueryReq(); + r.setPage(0); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void sizeOver100_fails() { + UserQueryReq r = new UserQueryReq(); + r.setSize(101); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void sizeZero_fails() { + UserQueryReq r = new UserQueryReq(); + r.setSize(0); + assertFalse(V.validate(r).isEmpty()); + } + + @Test + void allValidFields_passes() { + UserQueryReq r = new UserQueryReq(); + r.setPage(2); + r.setSize(50); + r.setSortField("tCreateDate"); + r.setSortOrder("asc"); + r.setQueryField("username"); + r.setMatchMode("contains"); + r.setQueryValue("ali"); + r.setUserType("NORMAL"); + r.setIsDeleted(false); + assertTrue(V.validate(r).isEmpty()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapperTest.java b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapperTest.java new file mode 100644 index 0000000..044983d --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapperTest.java @@ -0,0 +1,51 @@ +package com.xly.erp.module.usr.mapper; + +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +@SpringBootTest +@ActiveProfiles("test") +class SysPermissionCategoryMapperTest { + + @Autowired private SysPermissionCategoryMapper mapper; + @Autowired private LoginTestSeeder seeder; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + @Test + void countActiveByIds_returnsAllActive() { + int n = mapper.countActiveByIds(fx.activePermissionCategoryIds()); + assertEquals(fx.activePermissionCategoryIds().size(), n); + } + + @Test + void countActiveByIds_excludesDeleted() { + List mixed = new ArrayList<>(fx.activePermissionCategoryIds()); + mixed.add(fx.deletedPermissionCategoryId()); + int n = mapper.countActiveByIds(mixed); + assertEquals(fx.activePermissionCategoryIds().size(), n, + "已软删的分类不应计入"); + } + + @Test + void countActiveByIds_excludesUnknown() { + List mixed = new ArrayList<>(fx.activePermissionCategoryIds()); + mixed.add(99999); + int n = mapper.countActiveByIds(mixed); + assertEquals(fx.activePermissionCategoryIds().size(), n); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperQueryTest.java b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperQueryTest.java new file mode 100644 index 0000000..86fbc01 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperQueryTest.java @@ -0,0 +1,105 @@ +package com.xly.erp.module.usr.mapper; + +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.UserListItemVo; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class SysUserMapperQueryTest { + + @Autowired private SysUserMapper mapper; + @Autowired private LoginTestSeeder seeder; + + @BeforeEach + void setUp() { + seeder.reset(); + } + + private UserQueryParams baseParams() { + UserQueryParams p = new UserQueryParams(); + p.sqlSortField = "tCreateDate"; + p.sqlSortOrder = "desc"; + p.matchMode = "contains"; + p.offset = 0; + p.limit = 100; + return p; + } + + @Test + void count_noFilters_returnsAllRows() { + long total = mapper.countByQuery(baseParams()); + // seeder 插入 alice + admin + bob_deleted = 3 行 + assertEquals(3, total); + } + + @Test + void select_withSortByUsername_ascending() { + UserQueryParams p = baseParams(); + p.sqlSortField = "sUsername"; + p.sqlSortOrder = "asc"; + List rows = mapper.selectByQuery(p); + assertEquals(3, rows.size()); + // 期望升序：admin / alice / bob_deleted + assertEquals(LoginTestSeeder.USER_ADMIN, rows.get(0).getUsername()); + assertEquals(LoginTestSeeder.USER_OK, rows.get(1).getUsername()); + assertEquals(LoginTestSeeder.USER_DELETED, rows.get(2).getUsername()); + } + + @Test + void select_withQueryFieldUsername_contains() { + UserQueryParams p = baseParams(); + p.sqlQueryColumn = "u.sUsername"; + p.matchMode = "contains"; + p.queryValue = "ali"; + List rows = mapper.selectByQuery(p); + assertEquals(1, rows.size()); + assertEquals(LoginTestSeeder.USER_OK, rows.get(0).getUsername()); + } + + @Test + void select_joinsEmployeeAndDepartment_returnsBothNames() { + UserQueryParams p = baseParams(); + p.sqlQueryColumn = "u.sUsername"; + p.matchMode = "equals"; + p.queryValue = LoginTestSeeder.USER_OK; + List rows = mapper.selectByQuery(p); + assertEquals(1, rows.size()); + assertEquals("张三", rows.get(0).getEmployeeName()); + assertEquals("技术部", rows.get(0).getDepartmentName()); + } + + @Test + void select_withIsDeletedFilter_returnsOnlyMatching() { + UserQueryParams p = baseParams(); + p.isDeleted = 1; + List rows = mapper.selectByQuery(p); + assertEquals(1, rows.size()); + assertEquals(LoginTestSeeder.USER_DELETED, rows.get(0).getUsername()); + } + + @Test + void select_withUserTypeFilter_returnsOnlyAdmin() { + UserQueryParams p = baseParams(); + p.userType = "SUPER_ADMIN"; + List rows = mapper.selectByQuery(p); + assertEquals(1, rows.size()); + assertEquals(LoginTestSeeder.USER_ADMIN, rows.get(0).getUsername()); + } + + @Test + void select_pagination_limitsResults() { + UserQueryParams p = baseParams(); + p.limit = 2; + List rows = mapper.selectByQuery(p); + assertEquals(2, rows.size()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java new file mode 100644 index 0000000..d4efb2f --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java @@ -0,0 +1,85 @@ +package com.xly.erp.module.usr.mapper; + +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class SysUserMapperTest { + + @Autowired + private SysUserMapper userMapper; + + @Autowired + private LoginTestSeeder seeder; + + @BeforeEach + void setUp() { + seeder.reset(); + } + + @Test + void selectByUsername_returnsUserWithAllFields() { + SysUser user = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertNotNull(user); + assertEquals(LoginTestSeeder.USER_OK, user.getSUsername()); + assertEquals("U001", user.getSUserCode()); + assertNotNull(user.getSPasswordHash()); + assertEquals("NORMAL", user.getSUserType()); + assertEquals("zh-CN", user.getSLanguage()); + assertEquals(0, user.getIIsDeleted()); + assertEquals(0, user.getIFailedLoginCount()); + } + + @Test + void selectByUsername_returnsNullWhenNotFound() { + SysUser user = userMapper.selectByUsername("nobody"); + assertNull(user); + } + + @Test + void existsByUsername_trueForExisting() { + assertTrue(userMapper.existsByUsername(LoginTestSeeder.USER_OK)); + } + + @Test + void existsByUsername_falseForUnknown() { + assertFalse(userMapper.existsByUsername("nobody")); + } + + @Test + void existsByUserCode_trueForExisting() { + assertTrue(userMapper.existsByUserCode("U001")); + } + + @Test + void existsByUserCode_falseForUnknown() { + assertFalse(userMapper.existsByUserCode("UXXX")); + } + + @Test + void existsByUserCodeExcludingId_otherUserHasCode_returnsTrue() { + // alice has U001 / admin has U000；查 U001 排除 admin → 找到 alice → true + assertTrue(userMapper.existsByUserCodeExcludingId("U001", + seeder.reset().adminId())); + } + + @Test + void existsByUserCodeExcludingId_selfHasCode_returnsFalse() { + LoginTestSeeder.Fixture f = seeder.reset(); + // 查 alice 的 userCode 排除 alice 本身 → false + assertFalse(userMapper.existsByUserCodeExcludingId("U001", f.aliceId())); + } + + @Test + void existsByUserCodeExcludingId_unknownCode_returnsFalse() { + assertFalse(userMapper.existsByUserCodeExcludingId("UXXX", 1)); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapperTest.java b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapperTest.java new file mode 100644 index 0000000..d33cdf2 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapperTest.java @@ -0,0 +1,82 @@ +package com.xly.erp.module.usr.mapper; + +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class SysUserPermissionCategoryMapperTest { + + @Autowired private SysUserPermissionCategoryMapper mapper; + @Autowired private LoginTestSeeder seeder; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + // 给 alice 授权两个活跃分类 + for (Integer pcId : fx.activePermissionCategoryIds()) { + SysUserPermissionCategory link = new SysUserPermissionCategory(); + link.setIUserId(fx.aliceId()); + link.setIPermissionCategoryId(pcId); + link.setSGrantedBy("system"); + mapper.insert(link); + } + } + + @Test + void selectPermissionCategoryIdsByUserId_returnsAllCurrent() { + List ids = mapper.selectPermissionCategoryIdsByUserId(fx.aliceId()); + assertEquals(fx.activePermissionCategoryIds().size(), ids.size()); + assertTrue(ids.containsAll(fx.activePermissionCategoryIds())); + } + + @Test + void selectPermissionCategoryIdsByUserId_emptyForNoGrants() { + List ids = mapper.selectPermissionCategoryIdsByUserId(fx.adminId()); + assertTrue(ids.isEmpty()); + } + + @Test + void deleteByUserAndCategoryIds_onlyDeletesGivenSubset() { + Integer pur = fx.activePermissionCategoryIds().get(0); + int rows = mapper.deleteByUserAndCategoryIds(fx.aliceId(), List.of(pur)); + assertEquals(1, rows); + + List remaining = mapper.selectPermissionCategoryIdsByUserId(fx.aliceId()); + assertEquals(fx.activePermissionCategoryIds().size() - 1, remaining.size()); + assertFalse(remaining.contains(pur)); + } + + @Test + void deleteByUserAndCategoryIds_nonMatchingIds_returns0() { + int rows = mapper.deleteByUserAndCategoryIds(fx.aliceId(), List.of(99999)); + assertEquals(0, rows); + } + + @Test + void deleteByUserAndCategoryIds_doesNotAffectOtherUser() { + // 给 admin 也授权一条 + SysUserPermissionCategory link = new SysUserPermissionCategory(); + link.setIUserId(fx.adminId()); + link.setIPermissionCategoryId(fx.activePermissionCategoryIds().get(0)); + link.setSGrantedBy("system"); + mapper.insert(link); + + // 删 alice 的某个分类不应影响 admin + mapper.deleteByUserAndCategoryIds(fx.aliceId(), + List.of(fx.activePermissionCategoryIds().get(0))); + + assertEquals(1, mapper.selectPermissionCategoryIdsByUserId(fx.adminId()).size()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java b/backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java new file mode 100644 index 0000000..a24490f --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java @@ -0,0 +1,214 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.security.JwtUtil; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.LoginVo; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.test.context.ActiveProfiles; + +import java.time.LocalDateTime; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class LoginServiceImplTest { + + @Autowired private LoginService loginService; + @Autowired private SysUserMapper userMapper; + @Autowired private JdbcTemplate jdbc; + @Autowired private LoginTestSeeder seeder; + @Autowired private JwtUtil jwtUtil; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + @Test + void contextLoads_loginServiceBean() { + assertNotNull(loginService); + } + + // ===== Task 7: company validation ===== + + @Test + void login_unknownCompany_throws40004() { + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, "NOPE")); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(0, u.getIFailedLoginCount(), "公司校验失败不应累加用户失败次数"); + } + + @Test + void login_softDeletedCompany_throws40004() { + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_DELETED)); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + } + + // ===== Task 8: bad credentials ===== + + @Test + void login_unknownUser_throws40101_noDbWrite() { + BizException e = assertThrows(BizException.class, + () -> loginService.login("nobody", "any", LoginTestSeeder.COMPANY_OK)); + assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode()); + } + + @Test + void login_badPassword_throws40101_andIncrementsFailCount() { + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK)); + assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode()); + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(1, u.getIFailedLoginCount()); + } + + // ===== Task 9: locking ===== + + @Test + void login_5thBadPassword_setsLockUntil_andStillReturns40101() { + for (int i = 0; i < 4; i++) { + assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK)); + } + SysUser before5 = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(4, before5.getIFailedLoginCount()); + assertNull(before5.getTLockUntil()); + + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK)); + assertEquals(ErrorCode.BAD_CREDENTIALS, e.getCode(), + "第 5 次错误仍返 40101（不暴露阈值）"); + + SysUser after5 = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(5, after5.getIFailedLoginCount()); + assertNotNull(after5.getTLockUntil(), "第 5 次错误应设置锁定截止"); + assertTrue(after5.getTLockUntil().isAfter(LocalDateTime.now().plusMinutes(29)), + "锁定时长应 ~30 分钟"); + } + + @Test + void login_duringLockWindow_throws42301_noCountIncrement() { + jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_ADD(NOW(), INTERVAL 30 MINUTE) WHERE sUsername=?", + LoginTestSeeder.USER_OK); + + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK)); + assertEquals(ErrorCode.ACCOUNT_LOCKED, e.getCode()); + + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(5, u.getIFailedLoginCount(), "锁定期间任何登录尝试不应改变计数"); + } + + @Test + void login_afterLockExpired_allowsNewAttempt() { + jdbc.update("UPDATE sys_user SET iFailedLoginCount=5, tLockUntil=DATE_SUB(NOW(), INTERVAL 1 MINUTE) WHERE sUsername=?", + LoginTestSeeder.USER_OK); + + LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK); + assertNotNull(vo.getAccessToken()); + + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(0, u.getIFailedLoginCount(), "锁定过期 + 成功登录应清零"); + assertNull(u.getTLockUntil(), "成功登录应清空 tLockUntil"); + } + + // ===== Task 10: deleted + success ===== + + @Test + void login_deletedUser_throws40103_noCountIncrement() { + BizException e = assertThrows(BizException.class, + () -> loginService.login(LoginTestSeeder.USER_DELETED, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK)); + assertEquals(ErrorCode.ACCOUNT_DELETED, e.getCode()); + + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_DELETED); + assertEquals(0, u.getIFailedLoginCount()); + } + + @Test + void login_success_returnsTokenAndClearsFailCount_andUpdatesLastLogin() { + jdbc.update("UPDATE sys_user SET iFailedLoginCount=2 WHERE sUsername=?", LoginTestSeeder.USER_OK); + + LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK); + + assertNotNull(vo); + assertNotNull(vo.getAccessToken()); + assertEquals("Bearer", vo.getTokenType()); + assertEquals(7200L, vo.getExpiresInSec()); + assertNotNull(vo.getUserInfo()); + assertEquals(LoginTestSeeder.USER_OK, vo.getUserInfo().getUsername()); + assertEquals("NORMAL", vo.getUserInfo().getUserType()); + assertEquals("zh-CN", vo.getUserInfo().getLanguage()); + assertEquals(LoginTestSeeder.COMPANY_OK, vo.getUserInfo().getCompanyCode()); + assertEquals("张三", vo.getUserInfo().getEmployeeName()); + + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(0, u.getIFailedLoginCount()); + assertNull(u.getTLockUntil()); + assertNotNull(u.getTLastLoginDate()); + } + + @Test + void login_concurrentBadPassword_atomicallyIncrementsCount() throws Exception { + // 2 线程并发各跑 2 次错误密码 → 计数累加必须 == 4（低于 5 不触发锁定， + // 专注验证原子性。锁定路径在 login_5thBadPassword_* 单线程测试中验证） + int perThread = 2; + int threadCount = 2; + Thread t1 = new Thread(() -> { + for (int i = 0; i < perThread; i++) { + try { + loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK); + } catch (BizException ignored) {} + } + }); + Thread t2 = new Thread(() -> { + for (int i = 0; i < perThread; i++) { + try { + loginService.login(LoginTestSeeder.USER_OK, "WrongPass1!", LoginTestSeeder.COMPANY_OK); + } catch (BizException ignored) {} + } + }); + t1.start(); t2.start(); + t1.join(); t2.join(); + + SysUser u = userMapper.selectByUsername(LoginTestSeeder.USER_OK); + assertEquals(perThread * threadCount, u.getIFailedLoginCount(), + "并发失败累加必须 == 总次数（原子 UPDATE 保证；非原子实现会丢失累加）"); + assertNull(u.getTLockUntil(), "总次数低于阈值不应触发锁定"); + } + + @Test + void login_success_jwtParsesBack_with_sub_username_companyCode() { + LoginVo vo = loginService.login(LoginTestSeeder.USER_OK, LoginTestSeeder.DEFAULT_PASSWORD, + LoginTestSeeder.COMPANY_OK); + Map claims = jwtUtil.parse(vo.getAccessToken()); + assertEquals(String.valueOf(fx.aliceId()), claims.get("sub")); + assertEquals(LoginTestSeeder.USER_OK, claims.get("username")); + assertEquals(LoginTestSeeder.COMPANY_OK, claims.get("companyCode")); + assertEquals("NORMAL", claims.get("userType")); + assertEquals("zh-CN", claims.get("language")); + assertNotNull(claims.get("jti")); + long iat = ((Number) claims.get("iat")).longValue(); + long exp = ((Number) claims.get("exp")).longValue(); + assertEquals(7200L, exp - iat, "exp - iat 必须 == TOKEN_TTL_SEC"); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java b/backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java new file mode 100644 index 0000000..2ba9a6b --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java @@ -0,0 +1,156 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.dto.CreateUserReq; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.CreateUserVo; +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; +import org.springframework.test.context.ActiveProfiles; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class UserCreateServiceImplTest { + + @Autowired private UserCreateService service; + @Autowired private SysUserMapper userMapper; + @Autowired private SysUserPermissionCategoryMapper upcMapper; + @Autowired private BCryptPasswordEncoder encoder; + @Autowired private LoginTestSeeder seeder; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + private CreateUserReq buildReq(String username, String userCode) { + CreateUserReq r = new CreateUserReq(); + r.setUsername(username); + r.setUserCode(userCode); + r.setUserType("NORMAL"); + r.setLanguage("zh-CN"); + r.setCanEditDocument(false); + return r; + } + + // ===== 唯一性 / 外键校验（Task 7） ===== + + @Test + void create_usernameExists_throws40901() { + CreateUserReq r = buildReq(LoginTestSeeder.USER_OK, "U999"); + BizException e = assertThrows(BizException.class, () -> service.create(r, "admin")); + assertEquals(ErrorCode.CONFLICT_USERNAME, e.getCode()); + } + + @Test + void create_userCodeExists_throws40902() { + CreateUserReq r = buildReq("brandnew", "U001"); + BizException e = assertThrows(BizException.class, () -> service.create(r, "admin")); + assertEquals(ErrorCode.CONFLICT_USERCODE, e.getCode()); + } + + @Test + void create_employeeIdNotFound_throws40004() { + CreateUserReq r = buildReq("brandnew", "U999"); + r.setEmployeeId(99999); + BizException e = assertThrows(BizException.class, () -> service.create(r, "admin")); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + } + + @Test + void create_permissionCategoryNotFound_throws40004() { + CreateUserReq r = buildReq("brandnew", "U999"); + List bad = new java.util.ArrayList<>(fx.activePermissionCategoryIds()); + bad.add(99999); + r.setPermissionCategoryIds(bad); + BizException e = assertThrows(BizException.class, () -> service.create(r, "admin")); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + } + + @Test + void create_permissionCategorySoftDeleted_throws40004() { + CreateUserReq r = buildReq("brandnew", "U999"); + r.setPermissionCategoryIds(List.of(fx.deletedPermissionCategoryId())); + BizException e = assertThrows(BizException.class, () -> service.create(r, "admin")); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + } + + // ===== 写入路径（Task 8） ===== + + @Test + void create_minimalFields_persistsUserWithInitialPassword() { + CreateUserReq r = buildReq("newbie", "U010"); + CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN); + + assertNotNull(vo.getUserId()); + assertEquals("newbie", vo.getUsername()); + assertEquals("U010", vo.getUserCode()); + + SysUser db = userMapper.selectByUsername("newbie"); + assertNotNull(db); + assertEquals("NORMAL", db.getSUserType()); + assertEquals("zh-CN", db.getSLanguage()); + assertEquals(0, db.getICanEditDocument()); + assertEquals(0, db.getIIsDeleted()); + assertEquals(0, db.getIFailedLoginCount()); + assertTrue(encoder.matches("666666", db.getSPasswordHash()), + "初始密码必须 BCrypt 哈希为 666666"); + } + + @Test + void create_fullFields_persistsUserAndPermissionMappings() { + CreateUserReq r = buildReq("manager", "U020"); + r.setUserType("SUPER_ADMIN"); + r.setLanguage("en-US"); + r.setCanEditDocument(true); + r.setEmployeeId(fx.employeeId()); + r.setPermissionCategoryIds(fx.activePermissionCategoryIds()); + + CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN); + + SysUser db = userMapper.selectByUsername("manager"); + assertNotNull(db); + assertEquals("SUPER_ADMIN", db.getSUserType()); + assertEquals("en-US", db.getSLanguage()); + assertEquals(1, db.getICanEditDocument()); + assertEquals(fx.employeeId(), db.getIEmployeeId()); + + List links = upcMapper.selectList( + new LambdaQueryWrapper() + .eq(SysUserPermissionCategory::getIUserId, vo.getUserId())); + assertEquals(fx.activePermissionCategoryIds().size(), links.size()); + for (SysUserPermissionCategory link : links) { + assertEquals(LoginTestSeeder.USER_ADMIN, link.getSGrantedBy()); + } + } + + @Test + void create_emptyPermissionCategories_persistsUserOnly() { + CreateUserReq r = buildReq("solo", "U030"); + r.setPermissionCategoryIds(List.of()); + CreateUserVo vo = service.create(r, LoginTestSeeder.USER_ADMIN); + + SysUser db = userMapper.selectByUsername("solo"); + assertNotNull(db); + + List links = upcMapper.selectList( + new LambdaQueryWrapper() + .eq(SysUserPermissionCategory::getIUserId, vo.getUserId())); + assertTrue(links.isEmpty()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java b/backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java new file mode 100644 index 0000000..9dbd546 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java @@ -0,0 +1,82 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.UserDetailVo; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class UserDetailServiceImplTest { + + @Autowired private UserDetailService service; + @Autowired private LoginTestSeeder seeder; + @Autowired private SysUserPermissionCategoryMapper upcMapper; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + @Test + void getById_existingActiveUser_returnsFullVo() { + // 给 alice 加 2 个权限分类授权 + for (Integer pcId : fx.activePermissionCategoryIds()) { + SysUserPermissionCategory link = new SysUserPermissionCategory(); + link.setIUserId(fx.aliceId()); + link.setIPermissionCategoryId(pcId); + link.setSGrantedBy("system"); + upcMapper.insert(link); + } + + UserDetailVo vo = service.getById(fx.aliceId()); + assertEquals(fx.aliceId(), vo.getUserId()); + assertEquals(LoginTestSeeder.USER_OK, vo.getUsername()); + assertEquals("U001", vo.getUserCode()); + assertEquals("NORMAL", vo.getUserType()); + assertEquals("zh-CN", vo.getLanguage()); + assertEquals(false, vo.getCanEditDocument()); + assertEquals(false, vo.getIsDeleted()); + assertEquals(fx.employeeId(), vo.getEmployeeId()); + assertEquals("张三", vo.getEmployeeName()); + assertEquals(2, vo.getPermissionCategoryIds().size()); + } + + @Test + void getById_userWithoutEmployee_employeeNameIsNull() { + UserDetailVo vo = service.getById(fx.adminId()); + assertNull(vo.getEmployeeId()); + assertNull(vo.getEmployeeName()); + } + + @Test + void getById_userWithoutPermissions_emptyList() { + UserDetailVo vo = service.getById(fx.aliceId()); + assertNotNull(vo.getPermissionCategoryIds()); + assertTrue(vo.getPermissionCategoryIds().isEmpty()); + } + + @Test + void getById_deletedUser_stillReturned() { + UserDetailVo vo = service.getById(fx.bobDeletedId()); + assertEquals(LoginTestSeeder.USER_DELETED, vo.getUsername()); + assertEquals(true, vo.getIsDeleted()); + } + + @Test + void getById_unknownId_throws40401() { + BizException e = assertThrows(BizException.class, () -> service.getById(99999)); + assertEquals(ErrorCode.USER_NOT_FOUND, e.getCode()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java b/backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java new file mode 100644 index 0000000..cca052d --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java @@ -0,0 +1,246 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.common.response.PageResult; +import com.xly.erp.module.usr.dto.UserQueryReq; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.UserListItemVo; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class UserListServiceImplTest { + + @Autowired private UserListService service; + @Autowired private LoginTestSeeder seeder; + + @BeforeEach + void setUp() { + seeder.reset(); + } + + private UserQueryReq req() { + return new UserQueryReq(); + } + + @Test + void list_default_returnsAllUsers() { + PageResult result = service.list(req()); + assertEquals(3, result.getTotal()); + assertEquals(3, result.getRecords().size()); + assertEquals(1, result.getPage()); + assertEquals(20, result.getSize()); + } + + @Test + void list_sortByUsernameAsc() { + UserQueryReq r = req(); + r.setSortField("sUsername"); + r.setSortOrder("asc"); + PageResult result = service.list(r); + assertEquals(LoginTestSeeder.USER_ADMIN, result.getRecords().get(0).getUsername()); + } + + @Test + void list_sortFieldInvalid_throws40003() { + UserQueryReq r = req(); + r.setSortField("badField"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode()); + } + + @Test + void list_sortOrderInvalid_throws40001() { + UserQueryReq r = req(); + r.setSortOrder("foo"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.BAD_REQUEST, e.getCode()); + } + + @Test + void list_queryFieldInvalid_throws40003() { + UserQueryReq r = req(); + r.setQueryField("badField"); + r.setQueryValue("x"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode()); + } + + @Test + void list_matchModeInvalid_throws40003() { + UserQueryReq r = req(); + r.setMatchMode("startsWith"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.INVALID_ENUM_PARAM, e.getCode()); + } + + @Test + void list_queryByUsernameContains() { + UserQueryReq r = req(); + r.setQueryField("username"); + r.setMatchMode("contains"); + r.setQueryValue("ali"); + PageResult result = service.list(r); + assertEquals(1, result.getTotal()); + assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername()); + } + + @Test + void list_queryByEmployeeName_joinsCorrectly() { + UserQueryReq r = req(); + r.setQueryField("employeeName"); + r.setMatchMode("contains"); + r.setQueryValue("张"); + PageResult result = service.list(r); + assertEquals(1, result.getTotal()); + assertEquals("张三", result.getRecords().get(0).getEmployeeName()); + } + + @Test + void list_queryByDepartmentName_multiLevelJoin() { + UserQueryReq r = req(); + r.setQueryField("departmentName"); + r.setMatchMode("equals"); + r.setQueryValue("技术部"); + PageResult result = service.list(r); + assertEquals(1, result.getTotal()); + assertEquals("技术部", result.getRecords().get(0).getDepartmentName()); + } + + @Test + void list_queryByIsDeleted_true_returnsDeleted() { + UserQueryReq r = req(); + r.setQueryField("isDeleted"); + r.setMatchMode("equals"); + r.setQueryValue("true"); + PageResult result = service.list(r); + assertEquals(1, result.getTotal()); + assertEquals(LoginTestSeeder.USER_DELETED, result.getRecords().get(0).getUsername()); + } + + @Test + void list_queryByIsDeleted_invalidValue_throws40001() { + UserQueryReq r = req(); + r.setQueryField("isDeleted"); + r.setQueryValue("maybe"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.BAD_REQUEST, e.getCode()); + } + + @Test + void list_queryFieldWithoutValue_skipsCondition() { + UserQueryReq r = req(); + r.setQueryField("username"); + // no queryValue + PageResult result = service.list(r); + assertEquals(3, result.getTotal()); + } + + @Test + void list_explicitUserTypeFilter() { + UserQueryReq r = req(); + r.setUserType("NORMAL"); + PageResult result = service.list(r); + // alice (NORMAL active) + bob_deleted (NORMAL deleted) = 2 + assertEquals(2, result.getTotal()); + } + + @Test + void list_explicitUserTypeInvalid_throws40001() { + UserQueryReq r = req(); + r.setUserType("HACKER"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.BAD_REQUEST, e.getCode()); + } + + @Test + void list_explicitIsDeletedFalse_filtersActive() { + UserQueryReq r = req(); + r.setIsDeleted(false); + PageResult result = service.list(r); + // alice + admin + assertEquals(2, result.getTotal()); + } + + @Test + void list_composedFilters_andSemantics() { + UserQueryReq r = req(); + r.setQueryField("username"); + r.setQueryValue("a"); + r.setUserType("NORMAL"); + r.setIsDeleted(false); + PageResult result = service.list(r); + // alice 是唯一 NORMAL + 启用 + 名字含 a 的 + assertEquals(1, result.getTotal()); + assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername()); + } + + @Test + void list_pageBeyondTotal_returnsLastPage() { + UserQueryReq r = req(); + r.setPage(999); + r.setSize(10); + PageResult result = service.list(r); + assertEquals(3, result.getTotal()); + assertFalse(result.getRecords().isEmpty(), "越界应返回最后一页数据"); + assertEquals(1, result.getPage(), "actualPage 应矫正为最后一页 (3/10 → 1)"); + } + + @Test + void list_queryByIsDeleted_matchModeContains_isForcedToEquals() { + // spec § 业务规则 3：isDeleted matchMode 强制 equals + UserQueryReq r = req(); + r.setQueryField("isDeleted"); + r.setMatchMode("contains"); + r.setQueryValue("true"); + PageResult result = service.list(r); + // 应该等同于 equals true → 仅 bob_deleted + assertEquals(1, result.getTotal()); + assertEquals(LoginTestSeeder.USER_DELETED, result.getRecords().get(0).getUsername()); + } + + @Test + void list_queryByLastLoginDate_matchModeContains_isForcedToEquals_andDateNormalized() { + // 给 alice 写一个明确的 lastLoginDate + jdbc.update("UPDATE sys_user SET tLastLoginDate='2026-05-15 10:00:00' WHERE sUsername=?", + LoginTestSeeder.USER_OK); + + UserQueryReq r = req(); + r.setQueryField("lastLoginDate"); + r.setMatchMode("contains"); + r.setQueryValue("2026-05-15 10:00:00"); + PageResult result = service.list(r); + assertEquals(1, result.getTotal()); + assertEquals(LoginTestSeeder.USER_OK, result.getRecords().get(0).getUsername()); + } + + @Test + void list_queryByLastLoginDate_invalidValue_throws40001() { + UserQueryReq r = req(); + r.setQueryField("lastLoginDate"); + r.setQueryValue("not-a-date"); + BizException e = assertThrows(BizException.class, () -> service.list(r)); + assertEquals(ErrorCode.BAD_REQUEST, e.getCode()); + } + + @org.springframework.beans.factory.annotation.Autowired + private org.springframework.jdbc.core.JdbcTemplate jdbc; + + @Test + void list_responseDoesNotIncludePasswordField() { + PageResult result = service.list(req()); + UserListItemVo vo = result.getRecords().get(0); + // UserListItemVo 不应有 password 相关字段——通过反射验证 + for (java.lang.reflect.Field f : vo.getClass().getDeclaredFields()) { + assertFalse(f.getName().toLowerCase().contains("password"), + "VO 字段不应含 password: " + f.getName()); + } + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java b/backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java new file mode 100644 index 0000000..2c0ad5b --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java @@ -0,0 +1,296 @@ +package com.xly.erp.module.usr.service; + +import com.xly.erp.common.exception.BizException; +import com.xly.erp.common.response.ErrorCode; +import com.xly.erp.module.usr.dto.UpdateUserReq; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.entity.SysUserPermissionCategory; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import com.xly.erp.module.usr.mapper.SysUserPermissionCategoryMapper; +import com.xly.erp.module.usr.support.LoginTestSeeder; +import com.xly.erp.module.usr.vo.UserDetailVo; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.ActiveProfiles; + +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.*; + +@SpringBootTest +@ActiveProfiles("test") +class UserUpdateServiceImplTest { + + @Autowired private UserUpdateService service; + @Autowired private SysUserMapper userMapper; + @Autowired private SysUserPermissionCategoryMapper upcMapper; + @Autowired private LoginTestSeeder seeder; + + private LoginTestSeeder.Fixture fx; + + @BeforeEach + void setUp() { + fx = seeder.reset(); + } + + private UpdateUserReq req() { + return new UpdateUserReq(); + } + + // ===== 校验路径（Task 6） ===== + + @Test + void update_unknownUserId_throws40401() { + BizException e = assertThrows(BizException.class, + () -> service.update(99999, req(), fx.adminId(), LoginTestSeeder.USER_ADMIN)); + assertEquals(ErrorCode.USER_NOT_FOUND, e.getCode()); + } + + @Test + void update_selfDeactivate_throws40302() { + UpdateUserReq r = req(); + r.setIsDeleted(true); + BizException e = assertThrows(BizException.class, + () -> service.update(fx.adminId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN)); + assertEquals(ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE, e.getCode()); + } + + @Test + void update_userCodeConflict_throws40902() { + UpdateUserReq r = req(); + r.setUserCode("U001"); // alice's code + BizException e = assertThrows(BizException.class, + () -> service.update(fx.adminId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN)); + assertEquals(ErrorCode.CONFLICT_USERCODE, e.getCode()); + } + + @Test + void update_employeeIdNotFound_throws40004() { + UpdateUserReq r = req(); + r.setEmployeeId(99999); + BizException e = assertThrows(BizException.class, + () -> service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN)); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + } + + @Test + void update_permissionCategoryNotFound_throws40004_rollsBack() { + UpdateUserReq r = req(); + r.setUserCode("U_NEW"); + r.setPermissionCategoryIds(List.of(99999)); + BizException e = assertThrows(BizException.class, + () -> service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN)); + assertEquals(ErrorCode.COMPANY_NOT_FOUND, e.getCode()); + // 回滚：sys_user.sUserCode 不应被改 + SysUser after = userMapper.selectById(fx.aliceId()); + assertEquals("U001", after.getSUserCode()); + } + + // ===== 字段写入（Task 7） ===== + + @Test + void update_userCode_only_persisted_otherFieldsUnchanged() { + UpdateUserReq r = req(); + r.setUserCode("U_NEW"); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + SysUser db = userMapper.selectById(fx.aliceId()); + assertEquals("U_NEW", db.getSUserCode()); + assertEquals(LoginTestSeeder.USER_OK, db.getSUsername(), "用户名不变"); + assertEquals(LoginTestSeeder.USER_ADMIN, db.getSUpdatedBy()); + assertNotNull(db.getTUpdatedDate()); + } + + @Test + void update_userType_language_canEditDocument() { + UpdateUserReq r = req(); + r.setUserType("SUPER_ADMIN"); + r.setLanguage("en-US"); + r.setCanEditDocument(true); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + SysUser db = userMapper.selectById(fx.aliceId()); + assertEquals("SUPER_ADMIN", db.getSUserType()); + assertEquals("en-US", db.getSLanguage()); + assertEquals(1, db.getICanEditDocument()); + } + + @Test + void update_employeeId_positiveInteger_setsToValue() { + UpdateUserReq r = req(); + r.setEmployeeId(fx.employeeId()); + service.update(fx.adminId(), r, fx.adminId() + 1000, LoginTestSeeder.USER_ADMIN); + // operatorUserId 不等于 adminId 才能避开自我停用守卫（本测试未触发，但保持参数有效） + SysUser db = userMapper.selectById(fx.adminId()); + assertEquals(fx.employeeId(), db.getIEmployeeId()); + } + + @Test + void update_employeeId_zero_setsToNull() { + UpdateUserReq r = req(); + r.setEmployeeId(0); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + SysUser db = userMapper.selectById(fx.aliceId()); + assertNull(db.getIEmployeeId()); + } + + @Test + void update_employeeId_unchanged_preservesOriginalValue() { + UpdateUserReq r = req(); + // 不设 employeeId + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + SysUser db = userMapper.selectById(fx.aliceId()); + assertEquals(fx.employeeId(), db.getIEmployeeId()); + } + + @Test + void update_isDeleted_true_marksUserDeleted() { + UpdateUserReq r = req(); + r.setIsDeleted(true); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + SysUser db = userMapper.selectById(fx.aliceId()); + assertEquals(1, db.getIIsDeleted()); + } + + @Test + void update_isDeleted_false_revivesUser() { + UpdateUserReq r = req(); + r.setIsDeleted(false); + service.update(fx.bobDeletedId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + SysUser db = userMapper.selectById(fx.bobDeletedId()); + assertEquals(0, db.getIIsDeleted()); + } + + @Test + void update_emptyRequest_onlyUpdatesAuditFields() { + service.update(fx.aliceId(), req(), fx.adminId(), LoginTestSeeder.USER_ADMIN); + SysUser db = userMapper.selectById(fx.aliceId()); + assertEquals(LoginTestSeeder.USER_ADMIN, db.getSUpdatedBy()); + assertNotNull(db.getTUpdatedDate()); + // 其他字段不变 + assertEquals("U001", db.getSUserCode()); + assertEquals("NORMAL", db.getSUserType()); + } + + @Test + void update_userCodeUnchangedSameAsSelf_returns200() { + UpdateUserReq r = req(); + r.setUserCode("U001"); // alice 自己当前的 userCode + UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + assertEquals("U001", vo.getUserCode()); + } + + // ===== 权限分类增量差集（Task 8） ===== + + @Test + void update_permissionCategories_emptyList_clearsAll() { + // 先给 alice 加 2 个 + for (Integer pcId : fx.activePermissionCategoryIds()) { + SysUserPermissionCategory l = new SysUserPermissionCategory(); + l.setIUserId(fx.aliceId()); + l.setIPermissionCategoryId(pcId); + l.setSGrantedBy("system"); + upcMapper.insert(l); + } + UpdateUserReq r = req(); + r.setPermissionCategoryIds(List.of()); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + assertTrue(upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()).isEmpty()); + } + + @org.springframework.beans.factory.annotation.Autowired + private com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper permissionCategoryMapper; + + @Test + void update_permissionCategories_subsetDelta_addsAndRemoves() { + Integer pur = fx.activePermissionCategoryIds().get(0); + Integer sal = fx.activePermissionCategoryIds().get(1); + // 初始：alice = {PUR, SAL} + for (Integer pcId : List.of(pur, sal)) { + SysUserPermissionCategory l = new SysUserPermissionCategory(); + l.setIUserId(fx.aliceId()); + l.setIPermissionCategoryId(pcId); + l.setSGrantedBy("system"); + upcMapper.insert(l); + } + Integer salRowId = upcMapper.selectList( + new com.baomidou.mybatisplus.core.conditions.query.QueryWrapper() + .eq("iUserId", fx.aliceId()) + .eq("iPermissionCategoryId", sal)) + .get(0).getIIncrement(); + + // 新增分类 X（活跃） + com.xly.erp.module.usr.entity.SysPermissionCategory x = + new com.xly.erp.module.usr.entity.SysPermissionCategory(); + x.setSCategoryName("X"); + x.setSCategoryCode("X"); + x.setISortOrder(99); + x.setIIsDeleted(0); + permissionCategoryMapper.insert(x); + + UpdateUserReq r = req(); + r.setPermissionCategoryIds(List.of(sal, x.getIIncrement())); + UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + // 最终 alice 应有 {SAL, X} + Set finalSet = new HashSet<>( + upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId())); + assertEquals(Set.of(sal, x.getIIncrement()), finalSet); + + // SAL 行 iIncrement 不变（差集而非全量替换） + Integer salRowIdAfter = upcMapper.selectList( + new com.baomidou.mybatisplus.core.conditions.query.QueryWrapper() + .eq("iUserId", fx.aliceId()) + .eq("iPermissionCategoryId", sal)) + .get(0).getIIncrement(); + assertEquals(salRowId, salRowIdAfter, "保留项的 iIncrement 应不变"); + } + + @Test + void update_permissionCategories_omitted_preservesExisting() { + Integer pur = fx.activePermissionCategoryIds().get(0); + SysUserPermissionCategory l = new SysUserPermissionCategory(); + l.setIUserId(fx.aliceId()); + l.setIPermissionCategoryId(pur); + l.setSGrantedBy("system"); + upcMapper.insert(l); + + // 请求不含 permissionCategoryIds + UpdateUserReq r = req(); + r.setUserCode("U_NEW"); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + assertEquals(1, upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId()).size()); + } + + @Test + void update_permissionCategories_duplicateInRequest_deduped() { + Integer pur = fx.activePermissionCategoryIds().get(0); + Integer sal = fx.activePermissionCategoryIds().get(1); + UpdateUserReq r = req(); + r.setPermissionCategoryIds(new ArrayList<>(List.of(pur, pur, sal))); + service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + + Set finalSet = new HashSet<>( + upcMapper.selectPermissionCategoryIdsByUserId(fx.aliceId())); + assertEquals(Set.of(pur, sal), finalSet); + } + + @Test + void update_returnsUserDetailVoReflectingFinalState() { + UpdateUserReq r = req(); + r.setUserType("SUPER_ADMIN"); + r.setLanguage("en-US"); + UserDetailVo vo = service.update(fx.aliceId(), r, fx.adminId(), LoginTestSeeder.USER_ADMIN); + assertEquals("SUPER_ADMIN", vo.getUserType()); + assertEquals("en-US", vo.getLanguage()); + assertEquals(LoginTestSeeder.USER_ADMIN, vo.getUpdatedBy()); + assertNotNull(vo.getUpdatedDate()); + } +} diff --git a/backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java b/backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java new file mode 100644 index 0000000..4f1e355 --- /dev/null +++ b/backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java @@ -0,0 +1,175 @@ +package com.xly.erp.module.usr.support; + +import com.xly.erp.module.usr.entity.SysCompany; +import com.xly.erp.module.usr.entity.SysEmployee; +import com.xly.erp.module.usr.entity.SysPermissionCategory; +import com.xly.erp.module.usr.entity.SysUser; +import com.xly.erp.module.usr.mapper.SysCompanyMapper; +import com.xly.erp.module.usr.mapper.SysEmployeeMapper; +import com.xly.erp.module.usr.mapper.SysPermissionCategoryMapper; +import com.xly.erp.module.usr.mapper.SysUserMapper; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.jdbc.core.JdbcTemplate; +import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; +import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; + +import java.util.List; + +/** + * 测试数据种子。在每个集成测试 @BeforeEach 调用 reset()。 + * + * 默认账号： + * - alice / Password1! / 启用 / NORMAL / 关联员工"张三" + * - admin / Password1! / 启用 / SUPER_ADMIN + * - bob_deleted / Password1! / 作废（iIsDeleted=1） + * + * 默认公司：HQ（启用）/ DEL_CO（软删）。 + * 默认权限分类：PUR-采购管理 / SAL-销售管理（启用）/ HR-人事（软删）。 + */ +@Component +public class LoginTestSeeder { + + public static final String DEFAULT_PASSWORD = "Password1!"; + public static final String COMPANY_OK = "HQ"; + public static final String COMPANY_DELETED = "DEL_CO"; + public static final String USER_OK = "alice"; + public static final String USER_ADMIN = "admin"; + public static final String USER_DELETED = "bob_deleted"; + public static final String PERMISSION_CATEGORY_PUR = "PUR"; + public static final String PERMISSION_CATEGORY_SAL = "SAL"; + public static final String PERMISSION_CATEGORY_HR_DELETED = "HR"; + + private final JdbcTemplate jdbc; + private final SysCompanyMapper companyMapper; + private final SysEmployeeMapper employeeMapper; + private final SysUserMapper userMapper; + private final SysPermissionCategoryMapper permissionCategoryMapper; + private final BCryptPasswordEncoder encoder; + + @Autowired + public LoginTestSeeder(JdbcTemplate jdbc, + SysCompanyMapper companyMapper, + SysEmployeeMapper employeeMapper, + SysUserMapper userMapper, + SysPermissionCategoryMapper permissionCategoryMapper, + BCryptPasswordEncoder encoder) { + this.jdbc = jdbc; + this.companyMapper = companyMapper; + this.employeeMapper = employeeMapper; + this.userMapper = userMapper; + this.permissionCategoryMapper = permissionCategoryMapper; + this.encoder = encoder; + } + + @Transactional + public Fixture reset() { + jdbc.update("DELETE FROM sys_user_permission_category"); + jdbc.update("DELETE FROM sys_user"); + jdbc.update("DELETE FROM sys_permission_category"); + jdbc.update("DELETE FROM sys_employee"); + jdbc.update("DELETE FROM sys_department"); + jdbc.update("DELETE FROM sys_company"); + + SysCompany hq = new SysCompany(); + hq.setSCompanyCode(COMPANY_OK); + hq.setSCompanyName("总部"); + hq.setIIsDeleted(0); + companyMapper.insert(hq); + + SysCompany del = new SysCompany(); + del.setSCompanyCode(COMPANY_DELETED); + del.setSCompanyName("已删公司"); + del.setIIsDeleted(1); + companyMapper.insert(del); + + jdbc.update("INSERT INTO sys_department (sDepartmentName, sDepartmentCode, iIsDeleted) VALUES (?,?,0)", + "技术部", "TECH"); + Integer deptId = jdbc.queryForObject( + "SELECT iIncrement FROM sys_department WHERE sDepartmentCode='TECH'", + Integer.class); + + SysEmployee emp = new SysEmployee(); + emp.setSEmployeeName("张三"); + emp.setSEmployeeCode("E001"); + emp.setIDepartmentId(deptId); + emp.setIIsDeleted(0); + employeeMapper.insert(emp); + + String hash = encoder.encode(DEFAULT_PASSWORD); + + SysUser alice = new SysUser(); + alice.setSUsername(USER_OK); + alice.setSUserCode("U001"); + alice.setSPasswordHash(hash); + alice.setIEmployeeId(emp.getIIncrement()); + alice.setSUserType("NORMAL"); + alice.setSLanguage("zh-CN"); + alice.setICanEditDocument(0); + alice.setIIsDeleted(0); + alice.setIFailedLoginCount(0); + alice.setSCreatedBy("system"); + userMapper.insert(alice); + + SysUser admin = new SysUser(); + admin.setSUsername(USER_ADMIN); + admin.setSUserCode("U000"); + admin.setSPasswordHash(hash); + admin.setSUserType("SUPER_ADMIN"); + admin.setSLanguage("zh-CN"); + admin.setICanEditDocument(1); + admin.setIIsDeleted(0); + admin.setIFailedLoginCount(0); + admin.setSCreatedBy("system"); + userMapper.insert(admin); + + SysUser bob = new SysUser(); + bob.setSUsername(USER_DELETED); + bob.setSUserCode("U002"); + bob.setSPasswordHash(hash); + bob.setSUserType("NORMAL"); + bob.setSLanguage("zh-CN"); + bob.setICanEditDocument(0); + bob.setIIsDeleted(1); + bob.setIFailedLoginCount(0); + bob.setSCreatedBy("system"); + userMapper.insert(bob); + + SysPermissionCategory pur = new SysPermissionCategory(); + pur.setSCategoryCode(PERMISSION_CATEGORY_PUR); + pur.setSCategoryName("采购管理"); + pur.setISortOrder(1); + pur.setIIsDeleted(0); + permissionCategoryMapper.insert(pur); + + SysPermissionCategory sal = new SysPermissionCategory(); + sal.setSCategoryCode(PERMISSION_CATEGORY_SAL); + sal.setSCategoryName("销售管理"); + sal.setISortOrder(2); + sal.setIIsDeleted(0); + permissionCategoryMapper.insert(sal); + + SysPermissionCategory hrDel = new SysPermissionCategory(); + hrDel.setSCategoryCode(PERMISSION_CATEGORY_HR_DELETED); + hrDel.setSCategoryName("人事（已删）"); + hrDel.setISortOrder(3); + hrDel.setIIsDeleted(1); + permissionCategoryMapper.insert(hrDel); + + return new Fixture( + alice.getIIncrement(), + admin.getIIncrement(), + bob.getIIncrement(), + emp.getIIncrement(), + List.of(pur.getIIncrement(), sal.getIIncrement()), + hrDel.getIIncrement()); + } + + public record Fixture( + Integer aliceId, + Integer adminId, + Integer bobDeletedId, + Integer employeeId, + List activePermissionCategoryIds, + Integer deletedPermissionCategoryId) {} +} diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-001.md b/docs/01-需求清单/USR-用户管理/REQ-USR-001.md index efd0fec..9f2457f 100644 --- a/docs/01-需求清单/USR-用户管理/REQ-USR-001.md +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-001.md @@ -1,6 +1,5 @@ ### REQ-USR-001 用户登录 - **目标**: 用户通过用户名+密码完成身份认证，获取 JWT Token 用于后续接口鉴权 - **输入**: @@ -11,12 +10,12 @@ | --- | ---- | --- | ---- | ------- | ----- | --- | ----------- | | 用户名 | 文本 | 是 | 手工输入 | — | — | — | — | | 密码 | 文本 | 是 | 手工输入 | — | — | — | 输入显示星号 | - | 版本 | 文本 | 是 | 下拉单选 | `公司表` | 页面加载时 | 标准版 | | + | 版本 | 文本 | 是 | 下拉单选 | `公司表` | 页面加载时 | — | | - **输出**: 成功/失败 - **跨字段规则**: 校验用户名 + 密码哈希；连续失败达到阈值临时锁定账号；登录成功签发限时 token 并返回基本用户信息 - **边界**: token 设置合理过期时间；接口需具备防暴力破解保护 - **验收**: 正确凭据返回 Token 且可通过鉴权接口验证；错误密码返回通用错误消息（不区分用户名或密码错误）；锁定账号返回锁定提示 -- **依赖表**: `t_user`（认证主体 + 失败计数 + 锁定时间 + 登录时间）/ `t_company`（「版本」下拉数据源） -- **依赖接口**: `POST /api/usr/auth/login`（本 REQ 提供）；后续配套 `POST /api/usr/auth/refresh`、`POST /api/usr/auth/logout` 由同模块衍生接口（不另立 REQ） +- **依赖表**: `sys_user`(读: 校验账号 / 写: 更新 `iFailedLoginCount`、`tLockUntil`、`tLastLoginDate`), `sys_company`(读: 登录页"版本"下拉) +- **依赖接口**: `POST /api/v1/auth/login`（本 REQ 提供）；`GET /api/v1/companies`（登录页公司下拉，后续运营模块提供） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-002.md b/docs/01-需求清单/USR-用户管理/REQ-USR-002.md index 41fed2e..9be554c 100644 --- a/docs/01-需求清单/USR-用户管理/REQ-USR-002.md +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-002.md @@ -37,5 +37,5 @@ - **跨字段规则**: 用户名在系统内全局唯一；角色取值受系统配置约束 - **边界**: 密码以哈希形式存储 - **验收**: 提交合法数据后用户记录出现在列表；重复用户名返回错误提示；普通账号无权访问此功能 -- **依赖表**: `t_user`（新建主记录）/ `t_employee`（员工名下拉 + 关联）/ `t_permission`（权限分类下拉）/ `t_user_permission`（写入权限组关联） -- **依赖接口**: `POST /api/usr/users`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001）获取 JWT +- **依赖表**: `sys_user`(写: 新增账号), `sys_employee`(读: 关联职员下拉), `sys_permission_category`(读: 权限分类列表), `sys_user_permission_category`(写: 写入勾选授权) +- **依赖接口**: `POST /api/v1/users`（本 REQ 提供）；下游调用：`GET /api/v1/employees`（员工下拉，后续 HR 模块提供）；`GET /api/v1/permission-categories`（权限分类下拉，后续运营模块提供） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-003.md b/docs/01-需求清单/USR-用户管理/REQ-USR-003.md index 0ad6f89..9bfb006 100644 --- a/docs/01-需求清单/USR-用户管理/REQ-USR-003.md +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-003.md @@ -36,5 +36,5 @@ - **跨字段规则**: 密码不在该接口修改；角色变更需具备相应权限 - **边界**: 必须传入有效用户 id；字段格式与新增一致 - **验收**: 修改角色或状态后立即反映在用户列表；被禁用账号无法登录并收到明确提示 -- **依赖表**: `t_user`（更新主记录）/ `t_employee`（员工名下拉 + 关联）/ `t_permission`（权限分类下拉）/ `t_user_permission`（删旧 + 写新权限组关联） -- **依赖接口**: `PUT /api/usr/users/{iIncrement}`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001）+ 数据来源 `POST /api/usr/users`（REQ-USR-002） +- **依赖表**: `sys_user`(读 + 写: 更新非密码字段), `sys_employee`(读: 关联职员下拉), `sys_permission_category`(读: 权限分类列表), `sys_user_permission_category`(读 + 写: 增量增删授权差集) +- **依赖接口**: `PUT /api/v1/users/{userId}`（本 REQ 提供）；`GET /api/v1/users/{userId}`（详情回显，可在本 REQ 实现或复用 REQ-USR-004 列表点击进入）；下游调用：`GET /api/v1/employees`、`GET /api/v1/permission-categories`（同 REQ-USR-002） diff --git a/docs/01-需求清单/USR-用户管理/REQ-USR-004.md b/docs/01-需求清单/USR-用户管理/REQ-USR-004.md index 5bd10cb..1c3e229 100644 --- a/docs/01-需求清单/USR-用户管理/REQ-USR-004.md +++ b/docs/01-需求清单/USR-用户管理/REQ-USR-004.md @@ -33,5 +33,5 @@ - **跨字段规则**: - - **边界**: 单页最大条数受限（默认 100）；密码与敏感字段不返回；查询为只读，不产生写副作用 - **验收**: 按条件筛选返回正确结果集；无匹配时返回空列表而非报错；分页参数越界时返回最后一页 -- **依赖表**: `t_user`（列表主表 + 类型 / 作废 / 登录日期 / 制单人）/ `t_employee`（员工名）/ `t_department`（部门） -- **依赖接口**: `GET /api/usr/users`（本 REQ 提供）；前置 `POST /api/usr/auth/login`（REQ-USR-001） +- **依赖表**: `sys_user`(读: 分页 + 筛选), `sys_employee`(读: JOIN 取员工名), `sys_department`(读: JOIN 经 employee 取部门名) +- **依赖接口**: `GET /api/v1/users`（本 REQ 提供） diff --git a/docs/01-需求清单/USR-用户管理/_module.md b/docs/01-需求清单/USR-用户管理/_module.md index a1e1c19..6c6c32f 100644 --- a/docs/01-需求清单/USR-用户管理/_module.md +++ b/docs/01-需求清单/USR-用户管理/_module.md @@ -1,5 +1,5 @@ # USR-用户管理 -- **模块简述**: 提供用户全生命周期管理，含登录认证、新增、修改、查询等业务操作 -- **依赖模块**: —（基础模块） -- **涉及表**: `t_user` / `t_employee` / `t_department` / `t_permission` / `t_user_permission` / `t_company` +- **模块简述**: 用户管理模块负责用户账号的全生命周期管理，包括登录认证、新增 / 修改 / 查询用户、角色分配与账号启停 +- **依赖模块**: —（无） +- **涉及表**: `sys_user`, `sys_employee`, `sys_department`, `sys_company`, `sys_permission_category`, `sys_user_permission_category` diff --git a/docs/02-开发计划.md b/docs/02-开发计划.md index b01308a..09ba58c 100644 --- a/docs/02-开发计划.md +++ b/docs/02-开发计划.md @@ -4,7 +4,7 @@ | 模块 ID | 模块名 | 依赖模块 | 依赖表 | |---|---|---|---| -| module_usr | USR-用户管理 | — | `t_user` / `t_employee` / `t_department` / `t_permission` / `t_user_permission` / `t_company` | +| module_usr | 用户管理 | — | `sys_user`, `sys_employee`, `sys_department`, `sys_company`, `sys_permission_category`, `sys_user_permission_category` | ## 二、开发顺序清单（CC 分发权威） @@ -14,15 +14,16 @@ | # | REQ | 所属模块 | 选中理由 | 备注 | |---|-----|---------|---------|------| -| 1 | **REQ-USR-001** | module_usr | 所属模块无依赖，认证接口为基础设施（其余 REQ 接口需 JWT 鉴权） | — | -| 2 | **REQ-USR-002** | module_usr | 依赖 REQ-USR-001 已在前；新增用户为后续修改 / 查询提供数据 | — | -| 3 | **REQ-USR-003** | module_usr | 依赖 REQ-USR-002 已在前（先有用户才能修改） | — | -| 4 | **REQ-USR-004** | module_usr | 依赖 REQ-USR-002 已在前（先有用户才能查询） | — | +| 1 | **REQ-USR-001** | module_usr | 所属模块无依赖，登录是后续接口鉴权的基础 | — | +| 2 | **REQ-USR-002** | module_usr | 同模块，无前置 REQ 依赖；用户创建是 003/004 的数据源 | — | +| 3 | **REQ-USR-003** | module_usr | 同模块，逻辑上依赖 REQ-USR-002 已在前（修改基于已存在用户） | — | +| 4 | **REQ-USR-004** | module_usr | 同模块，无前置 REQ 依赖；列表查询用 002/003 产生的数据更易自测 | — | > **后端模块全部 merged 后**：用户重跑 `/erp-workflow:coding-start` → coding-start 检测到 `backend_done=true && frontend_done=false` → 派发 `frontend-start`。`frontend-start` 步骤 1 自带 prototype/ 门禁（≥ 1 个 `*.html` mockup，缺失则 AskUserQuestion 提示用户补齐）。前端阶段以业务功能（不是 HTML 文件数）为粒度拆分 FE，每个 FE 跑一次 feature 循环（fe-feature-*），最后整个阶段合 1 个 MR（分支 `frontend-phase`，记录在 `docs/08 § 三 整体 MR`）。 ## 三、关键说明 -- 本期需求只覆盖 USR 用户管理一个模块；后续若新增 PUR / SAL / FIN 等模块，需重新跑 `/erp-workflow:plan-start` 让 A5 重算依赖与顺序。 -- REQ-USR-001 排第一是「基础设施先行」策略：JWT 鉴权机制建好后，其余 REQ 才能复用 `@PreAuthorize` 与统一异常处理；初始管理员账号由 V1 后续的种子 migration 注入（或人工 SQL 直插）。 -- `t_employee` / `t_department` / `t_permission` / `t_company` 四张维表在 module_usr 内部按需访问，不另起模块；后续如演化出独立的 HR / 组织架构模块，再单独拆分。 +- 当前仅有 1 个业务模块 `module_usr`，无跨模块依赖，模块级 DAG 退化为单节点，无环。 +- REQ 内部依赖只有 003 → 002 一条边，按数字序天然满足，无需破环。 +- `sys_employee` / `sys_department` / `sys_company` / `sys_permission_category` 4 张参考字典已由 V1 建好但本模块**只读使用**，初始化数据由 B 阶段开发时通过 V2/V3 seed migration 或测试 fixture 补全（不在当前 4 个 REQ 范围内）。 +- 后端阶段所有任务限定在 `backend/module/usr/` 路径下；前端实现推迟到 `frontend-start` 派发的前端阶段，按 `prototype/*.html` 拆 FE。 diff --git a/docs/03-数据库设计文档.md b/docs/03-数据库设计文档.md index f838262..4384424 100644 --- a/docs/03-数据库设计文档.md +++ b/docs/03-数据库设计文档.md @@ -12,7 +12,7 @@ |---|---|---|---|---| | `iIncrement` | int | 否 | 是 | 整数主键 ID（自增方式由实现决定：DB `AUTO_INCREMENT` 或应用 / 触发器分配） | | `sId` | varchar(100) | 是 | — | 业务 ID（对外暴露的字符串标识，如 UUID / 人类可读编号） | -| `sBrandsId` | varchar(100) | 是 | — | 品牌 ID（多租户隔离） | +| `sBrandsId` | varchar(100) | 是 | — | 母公司 ID（多租户隔离） | | `sSubsidiaryId` | varchar(100) | 是 | — | 子公司 ID（组织层级隔离） | | `tCreateDate` | datetime | 否 | — | 记录创建时间 | @@ -20,24 +20,37 @@ ## ER 关系概览 -USR 用户管理模块共 6 张表，围绕「用户」为核心： +``` +sys_department ◄──┐ sys_company（独立，登录页"版本"下拉） + │ + │ N:1 +sys_employee ─────┘ + ▲ + │ N:1 (可选, ON DELETE SET NULL) + │ +sys_user ────────► sys_user_permission_category ◄──── sys_permission_category + (用户 × 权限分类多对多, ON DELETE CASCADE) +``` + +- `sys_company`：登录页"版本"下拉来源；目前独立存在，不与 user 直接 FK，登录上下文记录公司选择即可。 +- `sys_department`：部门字典；被 `sys_employee` 引用。 +- `sys_employee`：职员档案；被 `sys_user` 通过 `iEmployeeId` 可选引用（员工先存在，用户后绑定）。 +- `sys_user`：用户账号（登录、权限、状态、登录追踪一体）。 +- `sys_permission_category`：权限分类字典（USR-002/003 表 2 "权限组"的来源）。 +- `sys_user_permission_category`：用户 × 权限分类多对多授权表，记录每个用户被授予哪些权限分类。 -- `t_user`（用户主表）通过 `iEmployeeId` 关联 `t_employee`（职员），实现「用户号 / 员工名」一对一联动。 -- `t_employee`（职员表）通过 `iDepartmentId` 关联 `t_department`（部门表），支撑 REQ-USR-004 按部门筛选。 -- `t_user` 与 `t_permission`（权限分类字典）通过 `t_user_permission`（用户-权限关联表）建立多对多关系，实现 REQ-USR-002 / 003 的「权限组」分配。 -- `t_company`（公司版本字典）独立于 `t_user`，仅为 REQ-USR-001 登录入参「版本」下拉提供可选项，不与用户产生强引用。 +## 表清单 -依赖方向：`t_user → t_employee → t_department`、`t_user ↔ t_permission`（多对多）、`t_company` 独立。 +- `sys_company` — 公司 / 版本字典，登录页下拉选择来源 +- `sys_department` — 部门字典，职员归属 +- `sys_employee` — 职员档案，员工基础信息 +- `sys_user` — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪） +- `sys_permission_category` — 权限分类字典 +- `sys_user_permission_category` — 用户 × 权限分类授权关系 -## 表清单 -- `t_user` — 系统用户主表，承载登录认证、用户类型、语言偏好、单据权限等基础属性 -- `t_employee` — 公司职员主档，与用户表通过 `iEmployeeId` 关联，提供姓名 / 工号 / 部门归属 -- `t_department` — 部门组织树，支撑职员归属与按部门筛选 -- `t_permission` — 权限分类字典，定义系统可分配的权限项 -- `t_user_permission` — 用户-权限分类多对多关联表 -- `t_company` — 公司 / 版本字典（标准版 / 专业版 / 旗舰版），登录时「版本」下拉数据源 +--- -## `t_user` — 系统用户主表，承载登录认证与基础属性 +## `sys_company` — 公司 / 版本字典，登录页下拉选择来源 ### 字段 @@ -48,38 +61,28 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `sUserNo` | varchar(50) | 否 | — | 用户号；关联职员后自动同步员工号；系统内唯一 | -| `sUserName` | varchar(50) | 否 | — | 登录用户名；系统内唯一；3-50 位 | -| `iEmployeeId` | int | 是 | NULL | 关联职员 `t_employee.iIncrement`；可空（非员工账号如系统管理员） | -| `sPasswordHash` | varchar(255) | 否 | — | 密码哈希（BCrypt / Argon2）；禁止明文；初始密码 `666666` 哈希后存入 | -| `sUserType` | varchar(20) | 否 | `NORMAL` | 用户类型枚举：`NORMAL`（普通用户）/ `SUPER_ADMIN`（超级管理员） | -| `sLanguage` | varchar(10) | 否 | `zh-CN` | 语言枚举：`zh-CN`（中文）/ `en-US`（英文）/ `zh-TW`（繁体） | -| `bModifyDoc` | tinyint(1) | 否 | 0 | 单据修改权限：0 否 / 1 是 | -| `bVoid` | tinyint(1) | 否 | 0 | 作废标记（软删除）：0 启用 / 1 已作废 | -| `iLoginFailCount` | int | 否 | 0 | 连续登录失败次数；达到阈值触发临时锁定；登录成功后清零 | -| `tLockUntil` | datetime | 是 | NULL | 锁定截止时间；NULL 表示未锁定 | -| `tLastLoginDate` | datetime | 是 | NULL | 最近一次登录时间 | -| `sCreator` | varchar(100) | 是 | NULL | 制单人（创建该账号的操作员用户名） | +| `sCompanyName` | varchar(100) | 否 | — | 公司 / 版本名称（登录页下拉显示文本） | +| `sCompanyCode` | varchar(50) | 否 | — | 公司编码（前端唯一识别） | +| `iSortOrder` | int | 否 | 0 | 下拉列表排序权重，升序 | +| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记，0=正常 1=已删 | ### 索引 -- `uk_user_username` (UNIQUE): `sUserName` -- `uk_user_userno` (UNIQUE): `sUserNo` -- `idx_user_employee` (BTREE): `iEmployeeId` -- `idx_user_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId` -- `idx_user_void` (BTREE): `bVoid` +- `pk_sys_company` (PRIMARY): `iIncrement` +- `uk_sys_company_code` (UNIQUE): `sCompanyCode` +- `idx_sys_company_is_deleted` (BTREE): `iIsDeleted, iSortOrder` ### 外键 -- `fk_user_employee`: `iEmployeeId` → `t_employee.iIncrement` (ON DELETE SET NULL / ON UPDATE RESTRICT) +（无） ### 业务注记 -- 登录认证主体表；密码以哈希形式存储，登录失败计数与锁定时间均落库以保证服务重启不丢；亦可由 Redis 镜像加速，但 DB 字段为权威。 -- `bVoid = 1` 视为已作废账号，不可登录、不出现在默认查询结果中（REQ-USR-004 列表默认隐藏作废）。 -- 用户名 / 用户号唯一性由 `uk_user_username` / `uk_user_userno` 保证；新增 / 修改时若冲突由 DB 抛唯一约束错误，Service 转译为 `40001 用户名已存在`。 +REQ-USR-001 登录页 "版本" 字段下拉来源。当前与 `sys_user` 不直接 FK，登录会话记录用户选择的公司即可（避免单用户跨公司绑定的复杂度）。新增公司由后续运营模块管理；本模块阶段只读使用。 + +--- -## `t_employee` — 公司职员主档 +## `sys_department` — 部门字典，职员归属 ### 字段 @@ -90,30 +93,26 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `sEmployeeNo` | varchar(50) | 否 | — | 员工号；系统内唯一 | -| `sName` | varchar(100) | 否 | — | 姓名 | -| `iDepartmentId` | int | 是 | NULL | 部门 ID，关联 `t_department.iIncrement` | -| `sPhone` | varchar(20) | 是 | NULL | 手机号 | -| `sEmail` | varchar(100) | 是 | NULL | 邮箱 | -| `bDisabled` | tinyint(1) | 否 | 0 | 是否离职：0 在职 / 1 离职 | +| `sDepartmentName` | varchar(100) | 否 | — | 部门名称 | +| `sDepartmentCode` | varchar(50) | 否 | — | 部门编码 | +| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 | ### 索引 -- `uk_employee_no` (UNIQUE): `sEmployeeNo` -- `idx_employee_dept` (BTREE): `iDepartmentId` -- `idx_employee_name` (BTREE): `sName` -- `idx_employee_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId` +- `pk_sys_department` (PRIMARY): `iIncrement` +- `uk_sys_department_code` (UNIQUE): `sDepartmentCode` ### 外键 -- `fk_employee_department`: `iDepartmentId` → `t_department.iIncrement` (ON DELETE SET NULL / ON UPDATE RESTRICT) +（无） ### 业务注记 -- 用户表通过 `iEmployeeId` 关联本表；REQ-USR-002 / 003 选择员工时下拉数据源；REQ-USR-004 查询字段「员工名 / 部门」均联表本表。 -- 离职员工保留记录（`bDisabled = 1`），其关联用户应被自动作废（应用层逻辑，未做 DB 触发器）。 +REQ-USR-004 查询输出 "部门" 字段来源（经 `sys_employee` 关联）。本阶段是扁平字典，未来 HR 模块扩展时可加 `iParentId` 形成树状结构。 + +--- -## `t_department` — 部门组织树 +## `sys_employee` — 职员档案，员工基础信息 ### 字段 @@ -124,27 +123,31 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `sName` | varchar(100) | 否 | — | 部门名称 | -| `sCode` | varchar(50) | 否 | — | 部门编码；系统内唯一 | -| `iParentId` | int | 是 | NULL | 上级部门 ID，NULL 表示根部门 | -| `iSortOrder` | int | 否 | 0 | 排序值，小者靠前 | +| `sEmployeeName` | varchar(50) | 否 | — | 员工姓名（2-50 字符） | +| `sEmployeeCode` | varchar(50) | 否 | — | 员工工号（系统内唯一） | +| `iDepartmentId` | int | 否 | — | 所属部门 ID（FK → sys_department.iIncrement） | +| `sPhone` | varchar(20) | 是 | NULL | 手机号 | +| `sEmail` | varchar(100) | 是 | NULL | 邮箱 | +| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 | ### 索引 -- `uk_department_code` (UNIQUE): `sCode` -- `idx_department_parent` (BTREE): `iParentId` -- `idx_department_tenant` (BTREE): `sBrandsId`, `sSubsidiaryId` +- `pk_sys_employee` (PRIMARY): `iIncrement` +- `uk_sys_employee_code` (UNIQUE): `sEmployeeCode` +- `idx_sys_employee_department` (BTREE): `iDepartmentId` +- `idx_sys_employee_name` (BTREE): `sEmployeeName` ### 外键 -- `fk_department_parent`: `iParentId` → `t_department.iIncrement` (ON DELETE RESTRICT / ON UPDATE RESTRICT) +- `fk_sys_employee_department`: `iDepartmentId` → `sys_department.iIncrement` (ON DELETE RESTRICT, ON UPDATE CASCADE) ### 业务注记 -- 自引用形成部门树，根部门 `iParentId IS NULL`。 -- 部门删除采用「拒绝删除有下级 / 有员工的部门」策略（应用层校验）；DB 外键 RESTRICT 兜底。 +REQ-USR-002 / 003 "员工名" 下拉来源；REQ-USR-004 "员工名" / "部门" 输出来源。`iDepartmentId` 用 RESTRICT 防止删除还有员工的部门。员工先于用户存在；同一员工可对应 0 或 1 个用户账号。 + +--- -## `t_permission` — 权限分类字典 +## `sys_user` — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪） ### 字段 @@ -155,24 +158,46 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `sCode` | varchar(50) | 否 | — | 权限码，例如 `USR:ADD` / `USR:EDIT`；系统内唯一 | -| `sName` | varchar(100) | 否 | — | 权限分类名称（展示用） | -| `iSortOrder` | int | 否 | 0 | 同分类内排序 | +| `sUsername` | varchar(50) | 否 | — | 用户名（登录凭据，系统内全局唯一，3-20 位字母数字下划线） | +| `sUserCode` | varchar(50) | 否 | — | 用户号（业务展示用编码，系统内唯一） | +| `sPasswordHash` | varchar(255) | 否 | — | 密码哈希（BCrypt / Argon2，禁明文） | +| `iEmployeeId` | int | 是 | NULL | 关联职员 ID（可选；FK → sys_employee.iIncrement） | +| `sUserType` | varchar(20) | 否 | `NORMAL` | 用户类型枚举：`NORMAL`=普通用户 / `SUPER_ADMIN`=超级管理员 | +| `sLanguage` | varchar(10) | 否 | `zh-CN` | 语言：`zh-CN`=中文 / `en-US`=英文 / `zh-TW`=繁体 | +| `iCanEditDocument` | tinyint(1) | 否 | 0 | 单据修改权限：0=否 1=是 | +| `iIsDeleted` | tinyint(1) | 否 | 0 | 是否作废：0=启用 1=作废（停用） | +| `iFailedLoginCount` | int | 否 | 0 | 累计登录失败次数，达阈值锁定，登录成功清零 | +| `tLockUntil` | datetime | 是 | NULL | 锁定截止时间，NULL=未锁定，过期自动解锁 | +| `tLastLoginDate` | datetime | 是 | NULL | 最后一次成功登录时间，REQ-USR-004 "登录日期" 来源 | +| `sCreatedBy` | varchar(50) | 是 | NULL | 制单人（创建该用户的用户名），REQ-USR-002 "制单人" | +| `sUpdatedBy` | varchar(50) | 是 | NULL | 最后修改人用户名 | +| `tUpdatedDate` | datetime | 是 | NULL | 最后修改时间 | ### 索引 -- `uk_permission_code` (UNIQUE): `sCode` +- `pk_sys_user` (PRIMARY): `iIncrement` +- `uk_sys_user_username` (UNIQUE): `sUsername` +- `uk_sys_user_code` (UNIQUE): `sUserCode` +- `idx_sys_user_employee` (BTREE): `iEmployeeId` +- `idx_sys_user_type` (BTREE): `sUserType` +- `idx_sys_user_is_deleted` (BTREE): `iIsDeleted` +- `idx_sys_user_created_by` (BTREE): `sCreatedBy` ### 外键 -- 无 +- `fk_sys_user_employee`: `iEmployeeId` → `sys_employee.iIncrement` (ON DELETE SET NULL, ON UPDATE CASCADE) ### 业务注记 -- 字典表，启动时由初始化脚本灌入；不允许业务删除，禁用通过软标记（暂未引入 `bVoid`，由 docs/01 补充时再加）。 -- 权限码格式 `<模块代码>:<动作>`，与后端 `@PreAuthorize('hasAuthority(...)')` 一一对应（docs/06 § 1.3）。 +USR 模块核心表。 +- **登录认证**（REQ-USR-001）：`sUsername` + `sPasswordHash` 验证；连续失败累加 `iFailedLoginCount`，达 5 次写 `tLockUntil = now() + 30 分钟`；登录成功清零 + 更新 `tLastLoginDate`。 +- **作废**（`iIsDeleted = 1`）：等价业务"停用"，登录直接拒绝。删除用户不物理删，避免 FK 联动；`uk_sys_user_username` 与作废态共存的可能由应用层处理（作废后用户名释放或保留按运营决定，本阶段保留唯一）。 +- **职员关联**（`iEmployeeId`）：可选；删除职员时此字段置 NULL（`ON DELETE SET NULL`），用户记录不丢。 +- **密码不在本接口修改**（REQ-USR-003 边界）：修改用户走非密码字段；密码重置走独立流程（后续 REQ 扩展）。 -## `t_user_permission` — 用户-权限分类关联表 +--- + +## `sys_permission_category` — 权限分类字典 ### 字段 @@ -183,26 +208,29 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `iUserId` | int | 否 | — | 用户 ID，关联 `t_user.iIncrement` | -| `iPermissionId` | int | 否 | — | 权限分类 ID，关联 `t_permission.iIncrement` | +| `sCategoryName` | varchar(100) | 否 | — | 权限分类名称（如 "采购管理" / "销售管理"） | +| `sCategoryCode` | varchar(50) | 否 | — | 权限分类编码（系统内唯一，代码层引用） | +| `sCategoryDesc` | varchar(255) | 是 | NULL | 分类说明 | +| `iSortOrder` | int | 否 | 0 | 列表展示顺序 | +| `iIsDeleted` | tinyint(1) | 否 | 0 | 软删除标记 | ### 索引 -- `uk_user_perm` (UNIQUE): `iUserId`, `iPermissionId` -- `idx_user_perm_perm` (BTREE): `iPermissionId` +- `pk_sys_permission_category` (PRIMARY): `iIncrement` +- `uk_sys_permission_category_code` (UNIQUE): `sCategoryCode` +- `idx_sys_permission_category_sort` (BTREE): `iIsDeleted, iSortOrder` ### 外键 -- `fk_userperm_user`: `iUserId` → `t_user.iIncrement` (ON DELETE CASCADE / ON UPDATE RESTRICT) -- `fk_userperm_perm`: `iPermissionId` → `t_permission.iIncrement` (ON DELETE RESTRICT / ON UPDATE RESTRICT) +（无） ### 业务注记 -- 关联表豁免 `sBrandsId` / `sSubsidiaryId` 的业务语义但保留列以遵守项目标准；写入时复用 `t_user` 的对应租户标识。 -- 删除用户时级联清理本表行（`ON DELETE CASCADE`）；删除字典项保护已分配数据（`ON DELETE RESTRICT`）。 -- 唯一约束 `(iUserId, iPermissionId)` 确保同一用户对同一权限分类不重复授权。 +REQ-USR-002 / 003 表 2 "权限组" 的"权限分类"来源。本表是字典，分类条目由系统初始化或运营维护，**用户管理模块只读使用**。 + +--- -## `t_company` — 公司 / 版本字典 +## `sys_user_permission_category` — 用户 × 权限分类授权关系 ### 字段 @@ -213,18 +241,25 @@ USR 用户管理模块共 6 张表，围绕「用户」为核心： | `sBrandsId` | varchar(100) | 是 | `1111111111` | 品牌 ID（多租户隔离，标准列） | | `sSubsidiaryId` | varchar(100) | 是 | `1111111111` | 子公司 ID（组织层级隔离，标准列） | | `tCreateDate` | datetime | 否 | 当前时间 | 创建时间（标准列） | -| `sCode` | varchar(50) | 否 | — | 公司 / 版本编码；系统内唯一 | -| `sName` | varchar(100) | 否 | — | 显示名称 | +| `iUserId` | int | 否 | — | 用户 ID（FK → sys_user.iIncrement） | +| `iPermissionCategoryId` | int | 否 | — | 权限分类 ID（FK → sys_permission_category.iIncrement） | +| `sGrantedBy` | varchar(50) | 是 | NULL | 授予人用户名 | ### 索引 -- `uk_company_code` (UNIQUE): `sCode` +- `pk_sys_user_permission_category` (PRIMARY): `iIncrement` +- `uk_sys_user_permission_category` (UNIQUE): `iUserId, iPermissionCategoryId` +- `idx_sys_user_permission_category_category` (BTREE): `iPermissionCategoryId` ### 外键 -- 无 +- `fk_sys_upc_user`: `iUserId` → `sys_user.iIncrement` (ON DELETE CASCADE, ON UPDATE CASCADE) +- `fk_sys_upc_permission_category`: `iPermissionCategoryId` → `sys_permission_category.iIncrement` (ON DELETE CASCADE, ON UPDATE CASCADE) ### 业务注记 -- REQ-USR-001 登录入参「版本」下拉数据源；启动时由初始化脚本插入至少一行默认公司数据；具体「版本」字段语义待后续业务确认后再补列。 -- 当前 REQ 描述不足以确认与 `t_user` 是否需要强关联，故先做独立字典；后续如需「用户绑定公司 / 版本」再于 `t_user` 增列。 +记录每个用户被授予的权限分类清单。 +- REQ-USR-002 新增用户时，根据表 2 勾选生成本表对应行。 +- REQ-USR-003 修改用户时，重新计算差集做增量增删。 +- `ON DELETE CASCADE`：用户被物理删除时联动清理（注意：业务上用户作废不会物理删除，所以联动主要面向极端场景）；权限分类被物理删除时联动清理用户授权关系，避免悬挂。 +- 复合唯一键 `(iUserId, iPermissionCategoryId)` 保证同一用户同一分类只授权一次。 diff --git a/docs/04-技术规范.md b/docs/04-技术规范.md index ad1239b..6eb1114 100644 --- a/docs/04-技术规范.md +++ b/docs/04-技术规范.md @@ -35,117 +35,138 @@ ### 1.1 分层结构 +按 Spring Boot 3 + MyBatis-Plus 惯例分四层，每层职责单一： + | 层 | 职责 | |---|---| -| `controller/` | 接收 HTTP 请求、参数校验（`@Valid`）、调用 Service、组装响应；不写业务逻辑 | -| `service/` | 业务编排、事务边界、跨 Mapper 调用；接口 + `impl/` 实现 | -| `mapper/` | MyBatis-Plus 数据访问（Java 接口 + XML），仅做单表 CRUD 与简单关联查询 | -| `entity/` | 与数据库表 1:1 的实体类，字段名/类型严格对齐 docs/03 | -| `dto/` | 入参对象（前端 → 后端），含 `@NotNull` / `@Pattern` 等校验注解 | -| `vo/` | 出参对象（后端 → 前端），由 MapStruct 从 Entity 转换 | -| `config/` | Spring 配置类（Security / Redis / MyBatis-Plus / Swagger / Activiti） | -| `common/` | 全局响应包装、统一异常处理器、拦截器、工具类 | -| `security/` | JWT 生成 / 验证、`UserDetailsService` 实现、权限注解 | +| `controller` | HTTP 入口；参数校验（`@Valid`）；调用 service；返回统一响应；**不写业务逻辑** | +| `service` + `service/impl` | 业务编排；事务边界；调用一个或多个 mapper；DTO ↔ Entity 转换走 converter | +| `mapper` + `resources/mapper/*.xml` | 单表 CRUD 走 MyBatis-Plus；复杂 SQL 写 XML；**不写业务逻辑** | +| `entity` / `dto` / `vo` / `converter` | 数据传输层；converter 用 MapStruct 自动生成实现 | ### 1.2 命名约定 -- **包名**：全小写，单数。根包 `com.example.erp`。业务模块包 `.module.<模块代码小写>`（示例：`com.example.erp.module.usr`）。 -- **类名**：大驼峰；按层级加后缀（`UserController` / `UserServiceImpl` / `UserMapper` / `UserCreateDTO` / `UserListVO`）。 -- **方法名**：小驼峰；动词开头（`createUser` / `listUsers` / `disableUser`），与 REST 动作语义对齐。 -- **常量**：全大写下划线（`MAX_LOGIN_FAILS = 5`），放对应业务模块的 `constant/` 子包或公共 `common/constant/`。 -- **示例 1**：`com.example.erp.module.usr.controller.UserController#listUsers(UserQueryDTO)` 返回 `PageVO`。 -- **示例 2**：`com.example.erp.module.usr.service.impl.UserServiceImpl#disableUser(Long id)` 写入 `t_user_audit_log` 审计。 +- **Java 包**：全小写。根包：`com.xly.erp`。业务模块：`module.`（与 docs/01 模块代码对齐）。 +- **类名**：大驼峰；后缀清晰标识层（`UserController` / `UserServiceImpl` / `UserMapper` / `UserEntity` / `CreateUserReq` / `UserVo` / `UserConverter`）。 +- **方法 / 字段**：小驼峰（`createUser` / `userName`）。 +- **常量**：全大写下划线（`MAX_LOGIN_ATTEMPTS`）。 +- **数据库表名**：小写下划线（`sys_user`）；字段名同样小写下划线（`created_at`）。 + +**示例**： +```java +package com.xly.erp.module.usr.controller; + +@RestController +@RequestMapping("/api/v1/users") +public class UserController { + public Result createUser(@RequestBody @Valid CreateUserReq req) { ... } +} +``` ### 1.3 统一响应格式 -后端所有 HTTP 接口返回 `Result` 包装： +所有 HTTP 接口返回 `Result` / `PageResult`： ```json // 成功 { "code": 0, "message": "ok", "data": { ... } } + // 失败 { "code": 40001, "message": "用户名已存在", "data": null } ``` 错误码段位： - -| 段位 | 含义 | -|---|---| -| `0` | 成功 | -| `1xxxx` | 系统级（参数校验、未授权、未登录） | -| `2xxxx` | 通用业务错误（资源不存在、状态非法） | -| `4xxxx` | 模块业务错误（按模块再分子段：USR=`40xxx`，PUR=`41xxx`...） | -| `5xxxx` | 第三方 / 基础设施错误（DB / Redis / 外部服务） | +- `0`：成功 +- `10xxx`：参数 / 校验类错误 +- `20xxx`：业务规则错误 +- `30xxx`：权限类错误 +- `40xxx`：资源类错误（找不到、冲突） +- `50xxx`：服务器内部错误 +- `60xxx`：第三方依赖错误 ### 1.4 异常处理 -- **全局异常处理器**：`@RestControllerAdvice` 统一捕获，转换为 `Result` 失败结构。 -- **必须 catch**：`MethodArgumentNotValidException`（参数校验）/ `BindException` / 业务自定义 `BizException` / `AccessDeniedException`。 -- **禁止 catch**：泛 `Exception` 在业务代码中吞掉；必须让全局处理器接管。 -- **接口响应禁止回显后端异常堆栈**：返回用户友好错误码 + 文案；堆栈仅写入 logback。 +- 全局异常处理器 `GlobalExceptionHandler`（`@RestControllerAdvice`）统一捕获并转 `Result.fail(...)`。 +- 业务异常用 `BizException(int code, String message)`，service 层抛出，全局处理器捕获后转响应。 +- **禁止**在 controller / service 里 `catch (Exception e) { e.printStackTrace(); }` 后吞掉。 +- **接口响应禁止回显后端异常堆栈**：仅返回 `code` + 用户友好 `message`；堆栈写日志（含 traceId）。 ### 1.5 事务 -- **事务边界**：放在 Service 层方法上（`@Transactional`），Controller / Mapper 禁止开事务。 -- **传播策略**：默认 `REQUIRED`；只读查询用 `@Transactional(readOnly = true)`。 -- **跨服务调用禁止开新事务嵌套**：跨进程 / 跨服务的一致性走「最终一致 + 补偿」或 Activiti 工作流，不要用分布式事务。 +- 事务边界统一在 **service 实现层**，使用 `@Transactional(rollbackFor = Exception.class)`。 +- controller / mapper 层**禁止**写 `@Transactional`。 +- 跨服务（跨进程）调用**禁止**使用本地事务跨边界；改用最终一致性（消息队列 / 补偿任务），本项目当前无跨服务场景。 ### 1.6 认证 -- **协议**：JWT（HS256），头 `Authorization: Bearer `。 -- **生命周期**：access token 8 小时，refresh token 7 天；登录返回两枚 token；access 过期前端凭 refresh 刷新一次。 -- **刷新机制**：refresh token 只能用于换 access，不能直接调业务接口；服务端可吊销（Redis 存吊销名单）。 -- **密钥管理**：JWT 签名密钥放 `.env.local` 的 `JWT_SECRET`，至少 32 字节；生产环境必须更换默认值。 -- **登录失败锁定**：连续 5 次失败锁账户 30 分钟，Redis 计数器 key `login:fail:`。 +- 使用 Spring Security + JWT。 +- **Access Token**：HS256，TTL 2 小时；签发后写 Redis（key=`auth:token::`，value=用户摘要）。 +- **Refresh Token**：TTL 7 天，单独签发；刷新时旋转 token 并使旧 token 失效。 +- 密钥（HMAC secret）放 `.env.local` 的 `JWT_SECRET`，**禁止**写入 application.yml 或代码。 +- 登出 / 改密 / 停用：把对应 `jti` 加入 Redis 黑名单直至原 TTL 过期。 ## 二、前端规范 ### 2.1 目录约定 +按 Vite + React 18 + Redux Toolkit 惯例分层（详见 docs/09 § 三）： + | 目录 | 职责 | |---|---| -| `src/api/` | Axios 实例 + 每模块一个 API 文件；**所有 HTTP 调用唯一入口** | -| `src/components/` | 跨页面通用组件（`AuthButton` / `AppTable` / `PageHeader`） | -| `src/pages/` | 业务页面，按模块组织子目录 | -| `src/store/` | Redux Toolkit slice，仅放真正的全局状态 | -| `src/hooks/` | 自定义 hook（`useAuth` / `usePagination` / `useDebounce`） | -| `src/utils/` | 纯函数工具（格式化、校验、正则） | -| `src/styles/` | `tokens.css` + 全局样式 | -| `src/router/` | 路由表 + 路由守卫 | - -> **前端禁止直接写 SQL / 操作 DB**，所有数据访问走 `api/` 层统一封装。 +| `src/api/` | Axios 实例 + 各模块接口调用函数；**所有数据访问唯一入口** | +| `src/store/` | Redux Toolkit slices；全局态（认证 / 用户信息 / 字典） | +| `src/router/` | React Router 配置 + 路由守卫 | +| `src/pages//` | 业务页面（按模块分目录） | +| `src/components/` | 跨页面通用组件（含 `Permission` 等） | +| `src/layouts/` | 框架布局 | +| `src/hooks/` | 自定义 hook | +| `src/utils/` | 工具方法（日期 / 金额 / 校验等） | +| `src/styles/` | 全局样式 + Design Tokens | +| `src/types/` | 全局 TypeScript 类型 | + +**前端禁止直接写 SQL / 操作 DB**；所有数据访问走 `api/` 层封装的 HTTP 调用。 ### 2.2 状态管理 -- **Redux 存什么**：全局共享 + 跨页面持久（当前用户信息、权限码列表、菜单树、字典）。 -- **Redux 不存什么**：单个页面的表单值、Modal 开关、表格分页参数 → 放组件 `useState` / `useReducer`。 -- **服务端数据**：业务数据（列表、明细）不要塞 Redux，每次进入页面走 `api/` 取最新；只有字典 / 全局枚举做内存缓存（`store/slices/dictSlice`）。 +- **全局态**（用户身份 / 权限 / 全局字典 / 主题）：Redux Toolkit。 +- **页面级态**（表单值 / 列表参数）：组件本地 `useState` / `useReducer`。 +- **服务端数据**（列表 / 详情）：直接调 `api/` 函数，配合 `useEffect` + 本地 state；**不放**全局 store，避免缓存一致性问题。 +- 跨页面共享但**非全局**的态用 React Context（如 Modal Provider）。 ### 2.3 请求封装 -- **Axios 实例**：`src/api/http.ts` 统一创建，`baseURL` 取 `import.meta.env.VITE_API_BASE`。 -- **请求拦截器**：自动注入 `Authorization: Bearer `；token 临期则先刷新再发起原请求。 -- **响应拦截器**：剥 `Result.data` 给业务；`code !== 0` 时 `message.error(message)` 并 reject。 -- **超时**：默认 15s；上传 / 导出接口单独 60s。 -- **错误重试**：仅对幂等 GET 重试 1 次，POST / PUT / DELETE 禁止重试。 +`src/api/client.ts` 统一 Axios 实例： + +- baseURL 从 `import.meta.env.VITE_API_BASE_URL` 读取。 +- **请求拦截**：自动注入 `Authorization: Bearer `；附带 `X-Request-Id` 用于链路追踪。 +- **响应拦截**： + - HTTP 200 + `code === 0` → 返回 `data`。 + - HTTP 200 + `code !== 0` → 抛业务错误（含 message 和 code）。 + - HTTP 401 → 触发 refresh token；refresh 失败 → 清登录态 + 跳登录页。 + - HTTP 5xx → 抛网络错误。 +- 超时：默认 10s；上传 / 导出接口 60s。 +- 不做自动重试（重试由业务调用处显式控制）。 ### 2.4 错误处理 -- **网络错误**：Axios `error.code === 'ERR_NETWORK'` → 全局 `message.error('网络异常，请检查连接')`。 -- **业务错误**：`code !== 0` 在响应拦截器统一弹 message；页面只需处理 `try/catch` 中的 reject。 -- **页面级错误**：路由级 `ErrorBoundary` 包顶层，组件 throw 时显示统一错误页（docs/06 § 1.2）。 +| 错误类型 | 处理方式 | +|---|---| +| 网络错误（断网 / 5xx） | 顶层 `message.error('网络异常，请重试')`，业务调用处可自定义重试按钮 | +| 业务错误（code !== 0） | 默认 `message.error(err.message)`，业务调用处可拦截做特殊提示 | +| 表单校验失败 | 字段下方红字（Ant Design `Form` 自带） | +| 路由级未授权 | `RequireAuth` 守卫重定向到 `/login` | +| 页面级崩溃 | 顶层 `ErrorBoundary` 显示 `Result status="500"` + 重新加载按钮 | ### 2.5 样式与主题 - **CSS 变量命名**：`--color---` - - `scope` = `form` / `table-row` / `btn` / `link` / ... - - `role` = `bg` / `fg` / `border` - - `state` = `edit` / `readonly` / `hover` / `selected` -- **文件位置**：`src/styles/tokens.css`，由 skeleton-gen 生成空骨架，色值由 docs/06 § 二锁定后填入。 -- **组件样式**：只用 `var(--color-xxx)`，禁止硬编码 hex / rgba。 -- **Ant Design 主题对接**：`` 把 tokens 注入 antd 主题。 - -具体 token 表见 docs/06 § 二。 + - `scope`：`form` / `table-row` / `tag` / `btn` 等；通用全局色无 scope（如 `--color-primary`） + - `role`：`bg` / `fg` / `border` + - `state`：`edit` / `readonly` / `hover` / `selected` / `disabled`；常态省略 +- **文件位置**：`frontend/src/styles/tokens.css`（由 skeleton-gen 生成骨架，色值由 docs/06 § 二锁定）。 +- **组件样式中只用 `var(--color-xxx)`**，禁止硬编码 hex / rgba。 +- **与 Ant Design 主题对接**：`App.tsx` 顶层包 ``；Ant Design 5 接受 token 对象映射，确保组件库色值与 tokens.css 单一来源。 +- 具体 token 表见 `docs/06 § 二`。 ## 三、共同约定 @@ -153,35 +174,40 @@ `(): REQ-XXX-NNN` -- `type` ∈ `feat` / `fix` / `refactor` / `test` / `docs` / `chore` / `style` -- `scope` 为模块代码小写（`usr` / `pur` / `sal`）或 `infra` -- `subject` 50 字以内动词开头 -- 末尾必须挂 `REQ-XXX-NNN`（如 `REQ-USR-001`），CI 用此挂关联 +- type：见 CLAUDE.md § 🗂️ Git 提交规范。 +- scope：模块代码小写（`usr` / `pur` / `sal`）或 `infra` / `docs`。 +- subject：祈使句，中文，<= 50 字。 +- REQ tag：业务类提交（feat / fix / test）必带。 + +**示例**：`feat(usr): 实现用户登录接口 REQ-USR-001` ### 3.2 分页查询 -- **后端入参**：`PageQuery { pageNum: int = 1, pageSize: int = 20 }`（`pageSize` 上限 100）+ 业务过滤字段；继承基类避免重复声明。 -- **后端出参**：`PageVO { records: List, total: long, pageNum: int, pageSize: int }`。 -- **前端组件**：统一封装 `` 内置 antd `Table` + `Pagination`，受控 `current` / `pageSize` / `total`。 -- **默认排序**：按创建时间倒序；可按列点击切换。 +- **后端**：请求入参 `PageReq { page=1, size=20 }`（兜底默认值；size 上限 100）；返回 `PageResult { records: List, total: long, page: int, size: int }`。 +- **前端**：使用 Ant Design `Table` + `Pagination`；统一组件包装在 `components/PagedTable`，对接 `PageResult`。 +- 排序参数走 `sortField` / `sortOrder`，白名单字段，禁止任意字段排序。 ### 3.3 日期与金额 -- **后端类型**：日期 `LocalDate`，时间 `LocalDateTime`，金额 `BigDecimal`（scale=2，HALF_UP）。 -- **序列化**：Jackson 全局配置 `LocalDateTime` ↔ `yyyy-MM-dd HH:mm:ss`；`BigDecimal` 序列化为字符串避免精度丢失。 -- **前端展示**：`utils/format.ts` 提供 `formatDate(d)` / `formatMoney(n)`；金额展示固定 2 位小数 + 千分位（`￥1,234.56`）。 +- **后端类型**：日期用 `LocalDateTime` / `LocalDate`；金额用 `BigDecimal`（精度 2 位）。 +- **后端 → 前端**：日期统一序列化为 `YYYY-MM-DD HH:mm:ss` 字符串；金额序列化为 `string`（避免精度丢失）。 +- **前端展示**：日期使用 `dayjs` 格式化（`YYYY-MM-DD HH:mm`）；金额使用 `utils/money.ts` 格式化为千分位。 +- **金额精度**：内部全部 `BigDecimal`，4 舍 6 入 5 成双（`HALF_EVEN`）；展示截断到 2 位。 ### 3.4 数据访问规约 -- **SELECT 字段显式列举**，禁止 `SELECT *`；Mapper XML 用 `` 集中维护。 -- **禁止 N+1**：循环中不得执行 DB 查询；改用批量查（`IN (?,?,?)`）/ JOIN / ``。 -- **表名 / 字段名**：Mapper XML 中通过 `` 片段或常量引用，禁止字符串拼接（防 SQL 注入 + 利于改名）。 -- **分页**：统一用 MyBatis-Plus `Page` + `selectPage(...)`，禁止 LIMIT 字符串拼接。 +- **SELECT 字段显式列举**：禁止 `SELECT *`；MyBatis-Plus 用 `select(User::getId, User::getUsername)` 或 XML 显式列名。 +- **禁止 N+1 反模式**：循环中不得执行 DB 查询；改用 `selectBatchIds` / `IN` 子句 / `JOIN`。 +- **Mapper XML**：表名 / 字段名用常量或引用，禁止字符串拼接 SQL（防注入）。 +- **复杂查询走 XML**，简单 CRUD 走 LambdaQueryWrapper。 +- **写操作**：单表批量写用 `saveBatch` / `updateBatchById`；超大批量（>1000）分批 commit。 ### 3.5 配置与安全 -- **配置**：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`，代码里**禁止硬编码**；`application.yml` 用 `${VAR_NAME:default}` 引用环境变量。 +- **后端配置**：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 `application.yml` + `.env.local`。代码中**禁止硬编码**（用 `@Value` / `@ConfigurationProperties` 注入）。 +- **多环境**：`application-dev.yml` / `application-test.yml` / `application-prod.yml`，通过 `SPRING_PROFILES_ACTIVE` 切换。 - **前端安全**： - - `localStorage` **不存敏感信息**（token / 身份 / 个人数据）；推荐 HttpOnly Cookie 或 「内存 access token + HttpOnly refresh cookie」组合。 - - 接口响应禁止回显后端异常堆栈（与 § 1.4 一致）。 - - XSS：所有用户输入展示走 React JSX 自动转义；`dangerouslySetInnerHTML` 禁用，除非内容来源已白名单化。 + - `localStorage` **禁止**存敏感信息（token / 身份 / 个人数据）。 + - Token 推荐**内存 + HttpOnly Cookie**（refresh）或纯内存（access），Redux store 持有 access；刷新页面通过 refresh cookie 重新换取。 + - **接口响应禁止回显后端异常堆栈**（与 § 1.4 一致）。 +- **密钥来源**：所有密钥（JWT / DB 密码 / 第三方 API key）从 `.env.local` 加载；`.env.local` 在 `.gitignore`，永不入库。 diff --git a/docs/05-API接口契约.md b/docs/05-API接口契约.md index 17659fe..6b0f52c 100644 --- a/docs/05-API接口契约.md +++ b/docs/05-API接口契约.md @@ -1,7 +1,7 @@ # 05-API接口契约 -BasePath: `/api` -端口: `8080` +BasePath: `/api/v1` +端口: `9090` ## 全局约定 @@ -22,186 +22,109 @@ BasePath: `/api` ### 鉴权 -所有业务接口走 JWT Bearer。客户端在 `Authorization: Bearer ` 头中携带访问令牌。 - -- 登录 `POST /api/usr/auth/login` 返回 `accessToken`（8 小时）+ `refreshToken`（7 天） -- 临期前端用 refresh token 换新 access token：`POST /api/usr/auth/refresh` -- 注销 `POST /api/usr/auth/logout` 服务端把 token 加入 Redis 吊销名单 -- 未携带 / 过期 / 已吊销 → 401，对应错误码 `40101 未登录` / `40102 Token 已过期` / `40103 Token 已吊销` +除 `POST /api/v1/auth/login` 和 `GET /api/v1/companies`（登录页"版本"下拉）之外的全部接口需在请求头携带 `Authorization: Bearer `。Token 由 `/auth/login` 签发，TTL 2 小时，HS256 签名（密钥 `JWT_SECRET` 来自 `.env.local`）。鉴权失败统一返回 `40101 token 无效或已过期` / `40102 用户已被作废或锁定`。详见 docs/04 § 1.6。 ### 分页参数 -统一查询入参： +请求入参： -| 字段 | 类型 | 必填 | 默认 | 说明 | +| 参数 | 类型 | 必填 | 默认 | 说明 | |---|---|---|---|---| -| `pageNum` | int | 否 | 1 | 当前页码，从 1 开始 | -| `pageSize` | int | 否 | 20 | 每页条数；上限 100 | -| `orderBy` | string | 否 | `tCreateDate DESC` | 排序表达式，列名 + 方向 | +| `page` | int | 否 | 1 | 页码，从 1 开始 | +| `size` | int | 否 | 20 | 每页条数，上限 100 | +| `sortField` | string | 否 | — | 排序字段，白名单内 | +| `sortOrder` | string | 否 | `desc` | `asc` / `desc` | -响应包装： +响应 `data` 结构 `PageResult`： ```json { - "code": 200, "message": "ok", - "data": { - "records": [ ... ], - "total": 1234, - "pageNum": 1, - "pageSize": 20 - }, - "timestamp": 1700000000000 + "records": [], + "total": 0, + "page": 1, + "size": 20 } ``` ## 接口清单 （各模块接口段落见下方，由 `downstream-gen` 按 REQ 填入） -## module_usr — USR 用户管理 +## module_usr 用户管理 ### REQ-USR-001 用户登录 - **Method**: POST -- **Path**: `/api/usr/auth/login` -- **Auth**: 公开（无需 JWT） -- **请求**: - ```json - { - "userName": "admin", - "password": "P@ssw0rd", - "companyVersion": "STANDARD" - } - ``` - - `userName` (string, 必填, 3-50 位) - - `password` (string, 必填, 明文传输，由 TLS 保证机密性；后端用 BCrypt/Argon2 比对哈希) - - `companyVersion` (string, 必填, 枚举 `STANDARD` / `PRO` / `FLAGSHIP`) -- **响应**: - ```json - { - "code": 200, "message": "ok", - "data": { - "accessToken": "eyJ...", - "refreshToken": "eyJ...", - "expiresIn": 28800, - "user": { - "iIncrement": 1, - "sUserName": "admin", - "sUserType": "SUPER_ADMIN", - "sLanguage": "zh-CN", - "permissionCodes": ["USR:ADD", "USR:EDIT", "USR:DELETE", "USR:VIEW"] - } - }, - "timestamp": 1700000000000 - } - ``` +- **Path**: `/api/v1/auth/login` +- **Auth**: 无需（公开接口） +- **请求**: JSON body `LoginReq { username: string (3-20), password: string (8-20, 明文，HTTPS 传输), companyCode: string (sys_company.sCompanyCode) }` +- **响应**: JSON `LoginVo { accessToken: string (JWT), tokenType: "Bearer", expiresInSec: 7200, userInfo: { userId: int, username: string, userType: "NORMAL"|"SUPER_ADMIN", language: string, employeeName?: string, companyCode: string } }` #### 错误码 -- `40001` — 用户名或密码错误（不区分两者，防爆破） -- `40301` — 账号已锁定，请稍后再试 -- `40302` — 账号已作废 -- `40010` — 参数校验失败（用户名 / 密码 / 版本字段为空或格式不合法） - ---- +- `40001` — 用户名或密码格式错误 +- `40101` — 用户名或密码错误（统一文案，不区分两者） +- `40103` — 账号已被作废，禁止登录 +- `42301` — 账号已锁定，请稍后再试（HTTP 423；锁定剩余时间见 `data.lockUntil`） +- `40004` — 公司不存在或已删除 ### REQ-USR-002 新增用户 - **Method**: POST -- **Path**: `/api/usr/users` -- **Auth**: JWT；要求权限码 `USR:ADD` -- **请求**: - ```json - { - "userNo": "U10001", - "userName": "zhangsan", - "employeeId": 12, - "userType": "NORMAL", - "language": "zh-CN", - "modifyDoc": false, - "permissionIds": [3, 5, 8] - } - ``` - - `userNo` / `userName` 必填且系统内唯一 - - `employeeId` 可空（非员工账号） - - `userType` 枚举 `NORMAL` / `SUPER_ADMIN`（仅超级管理员可创建超级管理员） - - `language` 枚举 `zh-CN` / `en-US` / `zh-TW` - - `permissionIds` 权限分类 ID 数组，可为空 - - 初始密码后端固定生成（`666666`），不在请求体中 -- **响应**: - ```json - { "code": 200, "message": "ok", "data": { "userNo": "U10001", "iIncrement": 42 }, "timestamp": 1700000000000 } - ``` +- **Path**: `/api/v1/users` +- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用 +- **请求**: JSON body `CreateUserReq { username: string (3-20，正则 ^[A-Za-z0-9_]{3,20}$), userCode: string (max 50), userType: "NORMAL"|"SUPER_ADMIN", language: "zh-CN"|"en-US"|"zh-TW", canEditDocument: boolean, employeeId?: int, permissionCategoryIds?: int[] }`。**初始密码由系统统一设为 `"666666"`（BCrypt 哈希后入库），请求体不接受 `password` 字段（出现即返 40001）。** +- **响应**: JSON `CreateUserVo { userId: int, username: string, userCode: string }`（HTTP 201） #### 错误码 -- `40001` — 用户名 / 用户号已存在 -- `40010` — 参数校验失败 -- `40310` — 普通用户无权创建超级管理员 -- `40411` — 关联职员不存在 -- `40412` — 关联权限分类不存在 +- `40001` — 必填字段缺失或格式错误（含携带未知字段如 `password`） +- `40004` — 指定的员工 / 权限分类不存在 +- `40101` — 未携带或无效 Token +- `40301` — 当前用户非超级管理员，无权调用 +- `40901` — 用户名已存在 +- `40902` — 用户号已存在 ---- +### REQ-USR-003 GET 用户详情 + +- **Method**: GET +- **Path**: `/api/v1/users/{userId}` +- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用 +- **请求**: Path `userId: int` +- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds: int[], updatedBy, updatedDate }` + +#### 错误码 +- `40101` — 未携带或无效 Token +- `40301` — 当前用户非超级管理员，无权调用 +- `40401` — 用户不存在 ### REQ-USR-003 修改用户 - **Method**: PUT -- **Path**: `/api/usr/users/{iIncrement}` -- **Auth**: JWT；要求权限码 `USR:EDIT` -- **请求**: - ```json - { - "employeeId": 12, - "userType": "NORMAL", - "language": "en-US", - "modifyDoc": true, - "void": false, - "permissionIds": [3, 5] - } - ``` - - `userName` 不可修改，故请求体不包含 - - `void = true` 等价于禁用（软删除） - - `permissionIds` 全量覆盖（先 DELETE 后 INSERT，事务内） -- **响应**: - ```json - { "code": 200, "message": "ok", "data": { "iIncrement": 42 }, "timestamp": 1700000000000 } - ``` +- **Path**: `/api/v1/users/{userId}` +- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用 +- **请求**: Path `userId: int`；JSON body `UpdateUserReq { userCode?: string, userType?: "NORMAL"|"SUPER_ADMIN", language?: "zh-CN"|"en-US"|"zh-TW", canEditDocument?: boolean, employeeId?: int|null, isDeleted?: boolean, permissionCategoryIds?: int[] }`（username 与 password 字段不接受） +- **响应**: JSON `UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds, updatedBy, updatedDate }` #### 错误码 -- `40404` — 目标用户不存在 -- `40310` — 不可修改超级管理员（非超级管理员调用） -- `40311` — 不可禁用 / 修改自己 -- `40411` — 关联职员不存在 -- `40412` — 关联权限分类不存在 -- `40010` — 参数校验失败 - ---- +- `40001` — 字段格式错误或试图修改 username / password +- `40004` — 指定的员工 / 权限分类不存在 +- `40101` — 未携带或无效 Token +- `40301` — 当前用户非超级管理员，无权调用 +- `40302` — 试图停用当前登录用户自己 +- `40401` — 用户不存在 +- `40902` — 用户号已被占用 ### REQ-USR-004 查询用户 - **Method**: GET -- **Path**: `/api/usr/users` -- **Auth**: JWT；要求权限码 `USR:VIEW` -- **请求**: query string - - `searchField` 枚举 `userName` / `employeeName` / `userNo` / `departmentName` / `userType` / `void` / `lastLoginDate` / `creator` - - `matchMode` 枚举 `CONTAINS` / `NOT_CONTAINS` / `EQUALS` - - `searchValue` 字符串，空则不过滤 - - `includeVoid` 布尔，默认 false（不返回已作废用户） - - `pageNum` / `pageSize` / `orderBy` 通用分页参数 -- **响应**: 分页结构，`records[]` 元素： - ```json - { - "iIncrement": 42, - "sUserName": "zhangsan", - "employeeName": "张三", - "sUserNo": "U10001", - "departmentName": "技术部", - "sUserType": "NORMAL", - "sLanguage": "zh-CN", - "bVoid": false, - "tLastLoginDate": "2026-05-13 09:12:33", - "sCreator": "admin", - "tCreateDate": "2025-12-01 10:00:00" - } - ``` - - 不返回 `sPasswordHash` / `iLoginFailCount` / `tLockUntil` +- **Path**: `/api/v1/users` +- **Auth**: Bearer Token；仅 `userType=SUPER_ADMIN` 可调用 +- **请求**: Query 参数 `page=1&size=20&sortField=tCreateDate&sortOrder=desc&queryField=username&matchMode=contains&queryValue=张&userType=NORMAL&isDeleted=false` + - `queryField`: 枚举 `username|employeeName|userCode|departmentName|userType|isDeleted|lastLoginDate|createdBy` + - `matchMode`: 枚举 `contains|notContains|equals`，缺省 `contains` + - `queryValue`: 字符串，空字符串表示不限 +- **响应**: `PageResult`，`UserListItemVo { userId, username, employeeName, userCode, departmentName, userType, language, isDeleted, lastLoginDate, createdBy, createdDate }`（密码字段不返回） #### 错误码 -- `40010` — 参数校验失败（`pageSize > 100` / `matchMode` 不合法 / `searchField` 不合法） +- `40001` — 分页参数越界或类型错误（page<1 / size 越界 / sortOrder 非 asc-desc / userType 非枚举 / lastLoginDate 入参非法日期 / isDeleted 入参非布尔） +- `40003` — `sortField` / `queryField` / `matchMode` 不在白名单 +- `40101` — 未携带或无效 Token +- `40301` — 当前用户非超级管理员，无权调用 diff --git a/docs/06-UI交互规范.md b/docs/06-UI交互规范.md index 2c16448..70e8409 100644 --- a/docs/06-UI交互规范.md +++ b/docs/06-UI交互规范.md @@ -6,88 +6,95 @@ ### 1.1 操作反馈 -- **成功提示**：使用 Ant Design `message.success()`，默认 3s 自动消失；新增 / 修改 / 删除等写操作必须给反馈。 -- **失败提示**：使用 `message.error()` 显示后端返回的 `message` 字段；表单字段级错误用 Form 的 `validateStatus="error"` + `help` 同步显示。 -- **危险操作二次确认**：删除 / 禁用 / 重置密码等不可逆操作必须用 `Modal.confirm({ okType: 'danger' })` 二次确认，按钮文案使用业务动词（如「确认禁用」），不用「确定」。 -- **长耗时按钮 loading**：提交类按钮在请求未返回前必须置为 `loading=true` 并禁用，避免重复提交；查询类操作在表格组件上启用 `loading` 属性即可。 +- **成功提示**：使用 Ant Design `message.success`，3 秒自动消失；不阻塞操作。 +- **失败提示**：使用 `message.error` 显示后端 `Result.message`；4.5 秒消失；保留可复制。 +- **危险操作**（删除 / 停用 / 重置密码）：必须 `Modal.confirm` 二次确认，标题写明动作，正文写明影响对象 + 不可逆性。 +- **长耗时按钮**（>300ms）：按钮 `loading` 态 + 禁用，避免重复提交；提交完成后恢复。 +- **表单校验失败**：字段下方红字提示；首个错误字段自动聚焦并滚入视口。 ### 1.2 数据展示 -- **空状态**：列表 / 表格无数据时使用 ``，明细页无数据时附加「返回列表」按钮。 -- **加载状态**：页面级加载用 `` 包裹主区域；表格 / 卡片局部加载用组件自带 `loading` 属性。 -- **异常状态**：接口 5xx 或网络异常时显示 `重试} />`；403 时显示「无权限」并提供「返回首页」按钮。 +- **空状态**：使用 `Empty` 组件，图标 + 一句话说明（如 `暂无用户`）+ 主操作按钮（如 `新增用户`）。 +- **加载中**：列表用 `Skeleton`；单组件用 `Spin`；全屏首次加载允许使用 `Spin` 覆盖。 +- **异常态**：网络 / 5xx 错误使用 `Result status="error"` 显示，附 `重试` 按钮。 +- **分页**：默认 20 条 / 页，可选 10 / 20 / 50 / 100；显示总数 + 当前页 / 总页数。 +- **表格列**：必显列固定在左侧；操作列固定在右侧；时间列统一格式 `YYYY-MM-DD HH:mm`。 ### 1.3 权限控制（前端） -- **菜单级**：登录后由后端返回菜单权限码列表，前端 Layout 按权限码过滤后渲染左侧菜单。 -- **按钮级**：包装 `新增`，权限码不在用户列表时直接不渲染（避免显示再禁用）。 -- **路由级**：在 React Router 外层包 ``，路由元数据声明 `meta.code`，无权限重定向 403 页面。 -- **关联后端 RBAC**：权限码格式 `<模块代码>:<动作>`（如 `USR:ADD` / `USR:EDIT` / `USR:DELETE`），与后端 Spring Security `@PreAuthorize("hasAuthority('USR:ADD')")` 一一对应。 +- **菜单级**：Redux `auth.user.permissions` 驱动；菜单项无权限直接不渲染。 +- **路由级**：`router/index.tsx` 用 `RequireAuth` + `RequireRole` 高阶守卫；未授权重定向到登录或 403 页。 +- **按钮级**：`` 包裹按钮，无权限时不渲染（不显示 disabled 灰按钮）。 +- **后端 RBAC 同源**：前端权限码与后端 `Permission` 表严格对齐（codename 一致）；前端只做展示控制，最终鉴权由后端兜底。 ## 二、Design Tokens -> 所有色值统一以 CSS 变量定义于 `src/styles/tokens.css`；命名规范见 docs/04 § 2.5。 +> 所有色值统一以 CSS 变量定义于 `frontend/src/styles/tokens.css`；命名规范见 docs/04 § 2.5。组件样式只引用 `var(--color-xxx)`，禁止硬编码 hex / rgba。 ### 2.1 全局调色板 -与 Ant Design 5 主题对齐，统一通过 `` 注入。 +与 Ant Design 5 默认主题对齐，按语义分组。 | 语义 | 变量名 | 默认值 | 用途 | |---|---|---|---| -| 主色 | `--color-primary` | `#1677ff` | 主操作按钮 / 链接 / 选中态 | -| 成功 | `--color-success` | `#52c41a` | 成功消息 / 启用状态标签 | -| 警告 | `--color-warning` | `#faad14` | 警告消息 / 待处理状态 | -| 错误 | `--color-error` | `#ff4d4f` | 错误消息 / 危险按钮 / 禁用状态 | -| 主文字 | `--color-text-primary` | `rgba(0, 0, 0, 0.88)` | 正文 / 表格内容 | -| 次文字 | `--color-text-secondary` | `rgba(0, 0, 0, 0.65)` | 辅助说明 / 占位 | -| 边框 | `--color-border` | `#d9d9d9` | 表单输入 / 卡片边界 | -| 背景 | `--color-bg-base` | `#ffffff` | 页面主背景 | -| 弱背景 | `--color-bg-layout` | `#f5f5f5` | 页面 layout 间隙 / 灰底 | +| 主色 | `--color-primary` | `#1677ff` | 主按钮、链接、激活态边框 | +| 主色-悬浮 | `--color-primary-hover` | `#4096ff` | 主色控件 hover | +| 主色-激活 | `--color-primary-active` | `#0958d9` | 主色控件 active / pressed | +| 成功 | `--color-success` | `#52c41a` | 成功提示、积极状态标签 | +| 警告 | `--color-warning` | `#faad14` | 警告提示、需注意状态 | +| 错误 | `--color-error` | `#ff4d4f` | 错误提示、危险按钮 | +| 信息 | `--color-info` | `#1677ff` | 普通信息提示 | +| 主文字 | `--color-text` | `rgba(0,0,0,0.88)` | 标题、正文 | +| 次文字 | `--color-text-secondary` | `rgba(0,0,0,0.65)` | 辅助说明 | +| 禁用文字 | `--color-text-disabled` | `rgba(0,0,0,0.25)` | 禁用态 | +| 边框 | `--color-border` | `#d9d9d9` | 输入框 / 卡片边框 | +| 分割线 | `--color-split` | `#f0f0f0` | 列表分割线 | +| 背景-页面 | `--color-bg-page` | `#f5f5f5` | 页面底色 | +| 背景-容器 | `--color-bg-container` | `#ffffff` | 卡片 / 表单 / Modal | +| 背景-禁用 | `--color-bg-disabled` | `#f5f5f5` | 禁用控件 | ### 2.2 组件级状态色 -| 序号 | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 | -|---|---|---|---|---|---|---|---|---| -| 1 | 表单输入框 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | 只读态边框使用 `transparent` | -| 2 | 下拉单选 | `var(--color-bg-base)` | `var(--color-bg-layout)` | `var(--color-bg-base)` | `var(--color-text-primary)` | `var(--color-text-secondary)` | `var(--color-text-primary)` | — | -| 3 | 表格行 | — | `var(--color-bg-base)` | `var(--color-bg-row-hover)` | — | `var(--color-text-primary)` | `var(--color-text-primary)` | 编辑态走 Modal，行内不编辑 | -| 4 | 主按钮 | `var(--color-primary)` | `var(--color-bg-layout)` | `var(--color-primary-hover)` | `#ffffff` | `var(--color-text-secondary)` | `#ffffff` | 危险按钮替换 `--color-error` | -| 5 | 链接 | — | — | `var(--color-primary-hover)` | `var(--color-primary)` | — | `var(--color-primary-hover)` | — | +按场景 × 状态映射，单元格写 token 引用形式（`var(--color-xxx)`）。`—` 表示该状态不适用。 -**Token 默认值**： +| # | 组件 | 编辑bg | 只读bg | 悬浮bg | 编辑fg | 只读fg | 悬浮fg | 备注 | +|---|---|---|---|---|---|---|---|---| +| 1 | Input | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 只读用 `readOnly`，禁用用 `disabled` | +| 2 | Select | `var(--color-bg-container)` | `var(--color-bg-disabled)` | `var(--color-bg-container)` | `var(--color-text)` | `var(--color-text-secondary)` | `var(--color-text)` | 同 Input | +| 3 | Button-Primary | `var(--color-primary)` | — | `var(--color-primary-hover)` | `#fff` | — | `#fff` | 主操作 | +| 4 | Button-Default | `var(--color-bg-container)` | — | `var(--color-bg-container)` | `var(--color-text)` | — | `var(--color-primary)` | 次操作 | +| 5 | Button-Danger | `var(--color-error)` | — | `#ff7875` | `#fff` | — | `#fff` | 删除 / 停用 | +| 6 | Table-Row | `var(--color-bg-container)` | — | `#fafafa` | `var(--color-text)` | — | `var(--color-text)` | 斑马纹关闭 | +| 7 | Tag-Success | `#f6ffed` | — | — | `var(--color-success)` | — | — | 正常 / 启用状态 | +| 8 | Tag-Error | `#fff2f0` | — | — | `var(--color-error)` | — | — | 停用 / 失败状态 | -| Token | 默认值 | -|---|---| -| `--color-primary-hover` | `#4096ff` | -| `--color-bg-row-hover` | `#fafafa` | +**Token 默认值**（与 § 2.1 完整一致；新增 token 时此表与 tokens.css 同步更新）。 ### 2.3 引用约定 -- 组件样式只用 `var(--color-xxx)`，禁止硬编码 hex / rgba。 -- 新增 token 须先登记到 § 2.1 / 2.2 再补 `tokens.css`。 -- 修改色值只改 `tokens.css` 一处，不允许组件覆盖。 +- 组件样式只用 `var(--color-xxx)`，**禁止**直接写 hex / rgb / rgba。 +- 新增 token 必须先登记到 § 2.1 / 2.2，再写入 `tokens.css`。 +- 修改色值只改 `tokens.css` 一处；组件层不允许覆盖（如 `.ant-btn-primary { background: ... }` 之类禁止）。 ## 三、页面清单 +（由 `downstream-gen` 按模块追加段落） -### module_usr USR-用户管理 +### module_usr 用户管理 - **登录页** (`/login`) - 类型: 表单页 - 对应 REQ: REQ-USR-001 - - 入口菜单: 无（未登录态唯一可达页面） - - 主要交互: 表单输入 用户名 / 密码 / 版本 → 提交 → 成功跳首页 / 失败留页并显示通用错误消息；账号锁定时显示锁定提示 -- **用户列表页** (`/usr/users`) + - 入口菜单: 未登录访问任何路径均重定向至此 + - 主要交互: 公司/版本下拉（页面加载时拉取 `GET /api/v1/companies`）→ 输入用户名 / 密码（密码星号显示）→ 提交按钮带 loading 态防重复提交；连续 5 次失败显示锁定剩余时间；成功后写 access token 到内存并跳转默认主页 + +- **用户列表** (`/users`) - 类型: 列表页 - - 对应 REQ: REQ-USR-004 - - 入口菜单: 系统管理 → 用户管理 → 用户列表 - - 主要交互: 查询字段 + 匹配方式 + 查询值 三段筛选 → 表格分页展示 → 行内「编辑」「禁用 / 启用」按钮（权限码 `USR:EDIT`）；顶部「新增用户」按钮（权限码 `USR:ADD`）跳新增表单 -- **用户新增页** (`/usr/users/new`) - - 类型: 表单页 - - 对应 REQ: REQ-USR-002 - - 入口菜单: 系统管理 → 用户管理 → 用户列表 → 新增按钮 - - 主要交互: 员工名（下拉单选）选择后自动回填用户号 / 用户名；类型 / 语言下拉；权限组表格（多选）；提交校验失败显示字段级 `validateStatus="error"`；成功 message.success 后回列表页 -- **用户编辑页** (`/usr/users/:id/edit`) - - 类型: 表单页 - - 对应 REQ: REQ-USR-003 - - 入口菜单: 用户列表 → 行内「编辑」按钮 - - 主要交互: 复用新增表单组件；用户名只读；提供「重置密码」按钮（二次确认）；提供「禁用 / 启用」开关；禁用自己时按钮置灰 + - 对应 REQ: REQ-USR-002（"新增"入口）、REQ-USR-003（"编辑"行内按钮）、REQ-USR-004（列表分页 + 筛选） + - 入口菜单: 系统管理 → 用户管理 + - 主要交互: 顶部筛选区（查询字段下拉 / 匹配方式下拉 / 查询值输入框 / 查询按钮）+ 右上"新增用户"按钮 + Ant Design Table（含序号 / 用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 语言 / 作废标签 / 登录日期 / 制单人 / 制单日期 / 操作列）+ 分页器（10/20/50/100）；编辑按钮打开 Modal 复用新增表单组件（按 REQ-USR-003 字段差异置只读 / 禁用）；不允许停用当前登录账号自己（按钮 disabled + tooltip 解释） + +- **用户表单**（嵌入式 Modal，无独立路由） + - 类型: 表单页（Modal） + - 对应 REQ: REQ-USR-002 / REQ-USR-003 + - 入口菜单: 由用户列表的"新增" / "编辑"按钮触发 + - 主要交互: 左侧基础信息区（员工名下拉 / 用户号 / 用户名 / 类型下拉 / 语言下拉 / 单据修改权限复选框 / 作废复选框（仅编辑））+ 右侧权限组区（按 `sys_permission_category` 渲染勾选列表）+ 底部"保存"/"取消"；保存调 `POST /api/v1/users`（新增）或 `PUT /api/v1/users/{userId}`（编辑），成功后关闭 Modal 并刷新列表 diff --git a/docs/07-环境配置.md b/docs/07-环境配置.md index fbcc21b..2daa34b 100644 --- a/docs/07-环境配置.md +++ b/docs/07-环境配置.md @@ -4,43 +4,46 @@ | 层 | 依赖 | 版本 | 说明 | |---|---|---|---| -| 运行时 | Java (JDK) | 17 / 21 | Spring Boot 3 推荐版本 | -| 运行时 | MySQL | 8.x | 关系数据库 | -| 运行时 | Redis | 最新稳定版 | 缓存 / 会话 | -| 运行时 | Node.js | 20.x LTS | 前端构建 + 本地 dev server | -| 构建（后端） | Maven | 3.9.x | Java 依赖与构建工具 | -| 构建（前端） | pnpm | 8.x（或 npm 10.x） | 前端依赖管理 | -| 构建（前端） | Vite | 最新稳定版 | 前端开发与打包 | -| 容器 | Docker | 最新稳定版 | 容器化部署 | -| 容器 | Docker Compose | 最新稳定版 | 本地一键启依赖（MySQL + Redis） | -| 反向代理 | Nginx | 最新稳定版 | 前端静态托管 / 反向代理 | -| CLI 工具 | git | 2.30+ | 代码版本控制 | -| CLI 工具 | mysql client | 8.x | 本地执行 SQL / 验证 migration | -| CLI 工具 | glab（可选） | 最新稳定版 | GitLab MR 创建（亦可直接走 Web） | +| 运行时 | Java JDK | 17 或 21 | Spring Boot 3.x 运行环境 | +| 运行时 | Node.js | 20.x LTS | Vite 5 / React 18 构建运行 | +| 运行时 | MySQL | 8.x | 关系型数据库 | +| 运行时 | Redis | 最新稳定 | 缓存 / 会话 | +| 运行时 | Nginx | 最新稳定 | 反向代理、前端静态托管（生产） | +| 构建 | Maven | 3.9.x | 后端依赖管理与构建 | +| 构建 | npm（或 pnpm） | 与 Node 配套 | 前端包管理器 | +| 构建 | Flyway core + mysql | 10.x | Spring Boot 启动时自动 apply migration | +| 构建 | Vite | 最新稳定 | 前端打包 | +| 容器 | Docker | 最新稳定 | 镜像构建与本地编排 | +| 容器 | docker-compose | 最新稳定 | 本地 mysql / redis 编排 | +| CLI 工具 | git | ≥ 2.40 | 版本控制 | +| CLI 工具 | mysql client | 8.x | `scripts/setup-test-db.sh` 调用 | +| CLI 工具 | curl / jq | 最新稳定 | API 调试、脚本辅助 | ## 二、端口约定 | 服务 | 端口 | 说明 | |---|---|---| -| 后端 HTTP | 8080 | Spring Boot 默认端口（`server.port`） | -| 前端 dev server | 5173 | Vite 默认端口（`vite --port`） | -| MySQL | 3306 | 默认端口，本地开发可用 Docker Compose 暴露 | -| Redis | 6379 | 默认端口 | -| Nginx | 80 / 443 | 生产部署反向代理入口 | +| 后端 HTTP | 9090 | 项目锁定（避开常见 8080 冲突） | +| 前端 dev server | 5173 | Vite 默认 | +| MySQL | 3306 | 主库 | +| MySQL（测试） | 3307 | 本地独立测试库（避免与开发库冲突，可选） | +| Redis | 6379 | 默认 | +| Nginx | 80 / 443 | 生产反代 | ## 三、环境变量 -运行时凭据（数据库连接、JWT 密钥等）全部放在仓库根的 `.env.local`，不入 git。 -字段清单与占位符见该文件，真实值由开发者本地填写。 +运行时凭据（数据库连接、JWT 密钥、Redis 密码等）全部放在仓库根的 `.env.local`，**不入 git**（由 `.gitignore` 强制忽略）。 + +字段清单与占位符见 `.env.local`，真实值由开发者本地填写。CC 不读取 `.env.local` 的真实值；任何引用都用 `${VAR_NAME}` 形式。 ## 四、常用命令 | 命令 | 说明 | |---|---| -| `./mvnw spring-boot:run` | 本地启动后端（含 Flyway 自动 apply migration） | -| `pnpm dev` | 本地启动前端 dev server（默认 5173） | -| `./mvnw clean package -DskipTests` | 后端打包生成 jar | -| `pnpm build` | 前端打包到 `dist/` | -| `bash scripts/test.sh` | 执行后端 + 前端测试组合（lint / unit / e2e） | -| `bash scripts/setup-test-db.sh` | 重置本地测试数据库（DROP + CREATE + apply V1） | -| `glab mr create` | 推送当前分支并创建 GitLab MR（亦可走 Web 端） | +| `cd backend && ./mvnw spring-boot:run` | 启动后端服务（监听 8080） | +| `cd frontend && npm run dev` | 启动前端 dev server（监听 5173） | +| `cd backend && ./mvnw clean package` | 后端打包（生成 jar） | +| `cd frontend && npm run build` | 前端打包（生成 dist/） | +| `bash scripts/test.sh` | 跑后端 + 前端全部测试（test-gate 入口） | +| `bash scripts/setup-test-db.sh` | DROP+CREATE 测试库（Flyway V1 会在测试启动时 apply） | +| `glab mr create` 或 `gh pr create` | 创建 MR / PR（mr-create skill 调用） | diff --git a/docs/08-模块任务管理.md b/docs/08-模块任务管理.md index 6f0416a..6b309db 100644 --- a/docs/08-模块任务管理.md +++ b/docs/08-模块任务管理.md @@ -55,15 +55,15 @@ - [ ] REQ-SYS-002 用户注册 --> -- module_usr USR-用户管理 +- module_usr 用户管理 - 依赖: — - - 路径: backend/src/main/java/com/example/erp/module/usr/ - - MR: — + - 路径: backend/module/usr/ + - MR: !1 - 功能: - - [ ] REQ-USR-001 用户登录 - - [ ] REQ-USR-002 新增用户 - - [ ] REQ-USR-003 修改用户 - - [ ] REQ-USR-004 查询用户 + - [x] REQ-USR-001 用户登录 + - [x] REQ-USR-002 新增用户 + - [x] REQ-USR-003 修改用户 + - [x] REQ-USR-004 查询用户 ## 三、Coding 阶段（前端整体） diff --git a/docs/09-项目目录结构.md b/docs/09-项目目录结构.md index 4845ea9..210b8cf 100644 --- a/docs/09-项目目录结构.md +++ b/docs/09-项目目录结构.md @@ -4,93 +4,108 @@ ``` . -├── CLAUDE.md # 项目级规范与流程指令 -├── README.md # 项目说明（可选） -├── .env.local # 本地凭据（不入 git） +├── CLAUDE.md # Claude Code 主指令 +├── README.md # 项目说明 +├── .env.local # 本地凭据（不入 git） ├── .gitignore -├── .githooks/ -│ └── pre-push # 推送前自动跑 scripts/test.sh -├── scripts/ -│ ├── test.sh # 后端 + 前端测试组合入口 -│ └── setup-test-db.sh # 重置本地测试数据库 +├── .githooks/ # 仓库级 git hooks（core.hooksPath 指向） +│ └── pre-push +├── scripts/ # 项目脚本（test.sh / setup-test-db.sh 等） +├── docs/ # 全部规划与设计文档 +├── prototype/ # 前端 HTML mockup（前端阶段的布局权威） ├── sql/ -│ └── migrations/ # Flyway V*__*.sql 文件 -├── docs/ # 全量项目文档（见 § 四） -├── prototype/ # 静态 HTML mockup（前端实现权威） -├── backend/ # 后端工程（Spring Boot + Maven） -└── frontend/ # 前端工程（Vite + React） +│ └── migrations/ # Flyway V_n__*.sql +├── backend/ # Spring Boot 服务 +│ ├── pom.xml +│ └── src/ +└── frontend/ # Vite + React 应用 + ├── package.json + ├── vite.config.ts + └── src/ ``` ## 二、后端目录 +后端按 Spring Boot 3 + MyBatis-Plus 的惯例组织；业务代码按 docs/01 模块索引落到 `module//`。 + ``` backend/ ├── pom.xml -└── src/ - ├── main/ - │ ├── java/ - │ │ └── com.example.erp/ - │ │ ├── ErpApplication.java - │ │ ├── common/ # 全局响应 / 异常 / 拦截器 / 工具 - │ │ │ ├── result/ - │ │ │ ├── exception/ - │ │ │ ├── interceptor/ - │ │ │ └── util/ - │ │ ├── config/ # Spring 配置类（Security / Redis / MyBatis-Plus / Swagger / Activiti） - │ │ ├── module/ # 业务模块（按 docs/01 索引拆分） - │ │ │ └── usr/ # USR 用户管理 - │ │ │ ├── controller/ - │ │ │ ├── service/ - │ │ │ │ └── impl/ - │ │ │ ├── mapper/ - │ │ │ ├── entity/ - │ │ │ ├── dto/ - │ │ │ └── vo/ - │ │ └── security/ # 认证 / 鉴权 / JWT - │ └── resources/ - │ ├── application.yml - │ ├── application-dev.yml - │ ├── application-prod.yml - │ ├── mapper/ # MyBatis XML（按模块再分子目录） - │ └── logback-spring.xml - └── test/ - └── java/ - └── com.example.erp/ - └── module/ - └── usr/ # 与 main/ 镜像 +├── src/ +│ ├── main/ +│ │ ├── java/ +│ │ │ └── com/xly/erp/ +│ │ │ ├── Application.java # Spring Boot 启动类 +│ │ │ ├── common/ # 跨模块基础组件 +│ │ │ │ ├── response/ # 统一响应包装（Result / PageResult） +│ │ │ │ ├── exception/ # 全局异常处理 + 业务异常 +│ │ │ │ ├── security/ # Spring Security / JWT 配置 +│ │ │ │ ├── config/ # 通用配置（CORS / Swagger / MyBatis-Plus 等） +│ │ │ │ └── util/ # 工具类 +│ │ │ └── module/ +│ │ │ └── usr/ # 用户管理（REQ-USR-*） +│ │ │ ├── controller/ +│ │ │ ├── service/ +│ │ │ ├── service/impl/ +│ │ │ ├── mapper/ +│ │ │ ├── entity/ +│ │ │ ├── dto/ # Request DTO +│ │ │ ├── vo/ # Response VO +│ │ │ └── converter/ # MapStruct DTO/VO/Entity 转换 +│ │ └── resources/ +│ │ ├── application.yml # 主配置 +│ │ ├── application-dev.yml # 开发环境 +│ │ ├── application-test.yml # 测试环境 +│ │ ├── mapper/ # MyBatis XML（与 module 子目录对应） +│ │ │ └── usr/ +│ │ └── logback-spring.xml +│ └── test/ +│ └── java/ +│ └── com/xly/erp/ +│ └── module/ +│ └── usr/ # 单元测试 + 集成测试 +└── target/ # Maven 构建产物（gitignore） ``` +> Flyway migration 不在 backend/ 下，统一在仓库根 `sql/migrations/`，由 Spring Boot 启动时自动 apply（见 docs/04 § Schema 演化规约）。 + ## 三、前端目录 +前端按 Vite + React 18 + Ant Design 5 + Redux Toolkit + React Router v6 的惯例组织；业务页面按模块分组放在 `pages//`。 + ``` frontend/ ├── package.json ├── vite.config.ts ├── tsconfig.json ├── index.html -└── src/ - ├── main.tsx # 入口（挂载 React + Router + Store + ConfigProvider） - ├── App.tsx # 顶层路由 + 全局 Layout - ├── api/ # Axios 实例 + 各模块 API（数据访问统一入口） - │ └── usr.ts # USR 用户管理 API - ├── components/ # 跨页面通用组件（AuthButton / AppTable / PageHeader 等） - ├── pages/ # 按业务模块组织页面 - │ └── usr/ # USR 用户管理 - │ ├── UserList.tsx - │ ├── UserEdit.tsx - │ └── Login.tsx - ├── store/ # Redux Toolkit slices（全局状态） - │ └── slices/ - ├── hooks/ # 自定义 hook（useAuth / usePagination 等） - ├── utils/ # 工具函数（formatDate / formatMoney / regex 等） - ├── styles/ - │ ├── tokens.css # Design Tokens（docs/06 § 二） - │ └── global.css # 全局样式 reset / typography - ├── router/ # 路由表（含 meta.code 权限码） - └── assets/ # 静态资源（图片 / 字体） +├── src/ +│ ├── main.tsx # 入口 +│ ├── App.tsx # 根组件 + 路由 +│ ├── api/ # Axios 实例 + 接口调用层 +│ │ ├── client.ts # axios 实例 + 拦截器（401 / 错误统一处理） +│ │ └── usr.ts # 用户管理接口（按模块拆分） +│ ├── store/ # Redux Toolkit +│ │ ├── index.ts # configureStore +│ │ └── slices/ +│ │ └── auth.ts # 登录态 slice +│ ├── router/ # React Router 配置 +│ │ └── index.tsx +│ ├── pages/ # 页面（按模块分组） +│ │ ├── login/ # FE-NN 登录页 +│ │ └── usr/ # 用户管理页面 +│ ├── components/ # 跨页面通用组件 +│ ├── layouts/ # 框架布局（侧栏 / 顶栏 / 内容区） +│ ├── hooks/ # 自定义 hook +│ ├── utils/ # 工具方法 +│ ├── styles/ +│ │ └── tokens.css # Design Tokens（docs/06 § 二） +│ └── types/ # 全局 TypeScript 类型 +├── tests/ # Playwright E2E +└── dist/ # Vite 构建产物（gitignore） ``` -> 注：仓库根 `src/styles/tokens.css` 由 skeleton-gen 创建，作为 Design Tokens 的「上游」源；前端工程化前可先保留在根 `src/styles/` 下，前端工程初始化时迁入 `frontend/src/styles/`（同名同内容）。 +> Vitest 组件测试与对应源码同级（`*.test.tsx`）。 ## 四、docs/ 结构 @@ -111,14 +126,37 @@ docs/ ## 五、命名与放置约定 -- **后端根包**：`com.example.erp`，下文统称 ``；新增业务模块时落到 `.module.<模块代码小写>`（如 `.module.usr`）。 -- **Controller**：`.module..controller.Controller`，文件名首字母大写驼峰，URI 前缀 `/api/<模块代码小写>`。 -- **Service**：接口 `Service` + 实现 `ServiceImpl`，实现类放 `service/impl/`。 -- **Mapper**：`Mapper`（Java 接口）+ `resources/mapper//Mapper.xml`（XML 同名）。 -- **Entity / DTO / VO**： - - `entity/` 数据库实体（与表 1:1，字段类型同 docs/03） - - `dto/` 入参（前端 → 后端的请求体） - - `vo/` 出参（后端 → 前端的响应体） -- **前端组件**：通用组件放 `frontend/src/components/`，文件名首字母大写驼峰（`AuthButton.tsx`）；样式同名 `.module.css`（启用 CSS Modules）。 -- **前端页面**：放 `frontend/src/pages/<模块代码小写>/`，文件名按业务功能命名（`UserList.tsx` / `UserEdit.tsx`），路由 path 前缀 `/<模块代码小写>`。 -- **API 客户端**：每个模块一个文件 `frontend/src/api/<模块代码小写>.ts`，导出该模块所有接口函数；禁止在组件里直接 `axios.xxx`。 +### 5.1 根包 / 命名空间 + +- **Java 根包**: `com.xly.erp` +- **前端 npm 包名**: `xly-erp-frontend` + +### 5.2 后端文件放置 + +| 类型 | 路径 | 命名 | +|---|---|---| +| Controller | `module//controller/Controller.java` | 大驼峰 + `Controller` 后缀 | +| Service 接口 | `module//service/Service.java` | 大驼峰 + `Service` 后缀 | +| Service 实现 | `module//service/impl/ServiceImpl.java` | 大驼峰 + `ServiceImpl` 后缀 | +| Mapper 接口 | `module//mapper/Mapper.java` | 大驼峰 + `Mapper` 后缀 | +| Mapper XML | `resources/mapper//Mapper.xml` | 与接口同名 | +| Entity | `module//entity/.java` | 大驼峰，业务实体名 | +| DTO（请求） | `module//dto/Req.java` | 动词 + 实体 + `Req`，如 `CreateUserReq` | +| VO（响应） | `module//vo/Vo.java` 或 `DetailVo.java` | 大驼峰 + `Vo` 后缀 | +| Converter | `module//converter/Converter.java` | MapStruct 接口 | + +### 5.3 前端文件放置 + +| 类型 | 路径 | 命名 | +|---|---|---| +| 页面 | `pages//.tsx` | 大驼峰，与路由对齐 | +| 通用组件 | `components//index.tsx` | 大驼峰 | +| 接口调用 | `api/.ts` | 小写模块名 | +| Redux slice | `store/slices/.ts` | 小驼峰 | +| 测试 | 与源文件同级 `.test.tsx`（组件） / `tests/.spec.ts`（E2E） | 与被测对象对齐 | + +### 5.4 通用规则 + +- 所有 Java 包名小写；类名大驼峰；方法 / 字段小驼峰；常量全大写下划线。 +- TypeScript / TSX 文件用大驼峰命名组件，其他用小驼峰。 +- 业务模块代码与 docs/01 模块代码（USR / PUR / ...）保持一致，小写下划线作为目录名（`module/usr/`）。 diff --git a/docs/superpowers/module-reports/2026-05-15-module_usr.md b/docs/superpowers/module-reports/2026-05-15-module_usr.md new file mode 100644 index 0000000..b9f8dee --- /dev/null +++ b/docs/superpowers/module-reports/2026-05-15-module_usr.md @@ -0,0 +1,123 @@ +--- +module_id: module_usr +date: 2026-05-15 +git_range: 76218f3 (bootstrap spring boot 后端骨架) ↔ 4d58768 (test-gate evidence) +--- + +# 模块完成报告 — module_usr 用户管理 + +## ① 模块信息 +- 模块 ID: module_usr +- 模块名: 用户管理 +- 开发区间: 2026-05-15 单日（REQ-USR-001 → 002 → 003 → 004） +- 分支: module-module_usr + +## ② REQ 完成清单 + +- [x] REQ-USR-001 — 用户登录 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-001.md + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-001.md + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-001.md +- [x] REQ-USR-002 — 新增用户 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-002.md + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-002.md + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-002.md +- [x] REQ-USR-003 — 修改用户（含 GET 详情） + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-003.md + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-003.md + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-003.md +- [x] REQ-USR-004 — 查询用户 + - spec: docs/superpowers/specs/2026-05-15-REQ-USR-004.md + - plan: docs/superpowers/plans/2026-05-15-REQ-USR-004.md + - review: docs/superpowers/reviews/2026-05-15-REQ-USR-004.md + +## ③ 文件变更表 + +| 文件 | 操作 | 说明 | +|---|---|---| +| `backend/pom.xml` | Create | Spring Boot 3.3 + MyBatis-Plus + Flyway + JJWT + BCrypt 依赖 | +| `backend/src/main/java/com/xly/erp/Application.java` | Create | 启动类 + @MapperScan | +| `backend/src/main/resources/application.yml` / `application-test.yml` | Create | DB / JWT 配置 + Jackson 严格反序列化 + MyBatis mapper-locations | +| `backend/src/main/resources/logback-spring.xml` | Create | Logback 基础配置 | +| `backend/src/main/resources/mapper/usr/SysUserMapper.xml` | Create | REQ-004 动态 SQL JOIN + WHERE | +| `backend/src/main/java/com/xly/erp/common/response/{Result,ErrorCode,PageResult}.java` | Create | 统一响应包装 + 错误码（含 40001/40003/40004/40101/40103/40301/40302/40401/40901/40902/42301）+ 通用分页 VO | +| `backend/src/main/java/com/xly/erp/common/exception/{BizException,GlobalExceptionHandler}.java` | Create | 业务异常 + 全局 @RestControllerAdvice | +| `backend/src/main/java/com/xly/erp/common/security/{JwtUtil,LoginContext,RequireSuperAdmin,JwtHandlerInterceptor}.java` | Create | JWT 工具 + ThreadLocal + 角色守卫注解 + 鉴权拦截器 | +| `backend/src/main/java/com/xly/erp/common/config/{PasswordEncoderConfig,WebMvcConfig}.java` | Create | BCrypt Bean + interceptor 注册 | +| `backend/src/main/java/com/xly/erp/module/usr/entity/Sys*.java` | Create | SysUser / SysCompany / SysEmployee / SysPermissionCategory / SysUserPermissionCategory 5 张表实体 | +| `backend/src/main/java/com/xly/erp/module/usr/mapper/Sys*Mapper.java` + `UserQueryParams.java` | Create | 5 个 mapper + REQ-004 查询参数 DTO | +| `backend/src/main/java/com/xly/erp/module/usr/dto/{LoginReq,CreateUserReq,UpdateUserReq,UserQueryReq}.java` | Create | 4 个请求 DTO | +| `backend/src/main/java/com/xly/erp/module/usr/vo/{LoginVo,UserInfoVo,CreateUserVo,UserDetailVo,UserListItemVo}.java` | Create | 5 个响应 VO | +| `backend/src/main/java/com/xly/erp/module/usr/service/*Service.java` + `impl/*ServiceImpl.java` | Create | LoginService / UserCreateService / UserDetailService / UserUpdateService / UserListService | +| `backend/src/main/java/com/xly/erp/module/usr/controller/{AuthController,UserController}.java` | Create | 5 个 HTTP 端点（POST /auth/login，POST/GET/PUT /users，GET /users/{id}） | +| `backend/src/test/...` | Create | 14 个测试类，201 个测试方法 | +| `scripts/test.sh` | Modify | 把 `./mvnw` 改为系统 `mvn`（与 docs/07 § 一 Maven 3.9.x 依赖对齐；backend 未带 wrapper） | +| `docs/05-API接口契约.md` | Modify | REQ-002 去 password 字段 / 40002；REQ-003 补 GET 详情段；REQ-004 错误码列表补 sortField + 40101 | + +> 文件总数：59 个新建（44 个 main + 14 个 test），1 个修改（scripts/test.sh + docs/05）；约 5118 行 backend/ 净增。 + +## ④ 数据库使用表 + +- 读: `sys_user`, `sys_company`, `sys_employee`, `sys_department`, `sys_permission_category`, `sys_user_permission_category` +- 写: `sys_user`（新增 / 部分字段更新 / 登录追踪字段 / 失败计数原子 UPDATE），`sys_user_permission_category`（增删差集） + +> `sys_company` / `sys_employee` / `sys_department` 本模块全程只读使用；新增 / 编辑这三张表的接口推迟到后续运营 / HR 模块。 + +## ⑤ 测试结果 + +- `scripts/test.sh` 最终：GREEN（详见 `docs/superpowers/module-reports/module_usr-test-gate.md`） +- 通过: 201 / 失败: 0 / 跳过: 0 +- 覆盖率: 未配置覆盖率插件；REQ 级 spec 验收覆盖： + - REQ-USR-001：12/12（含 BizException 单测、JWT 单测、并发原子累加回归） + - REQ-USR-002：15/15（spec § 15 唯一索引兜底未单测，依赖文本匹配；记入 ⑩） + - REQ-USR-003：22/22（spec § 23 作废用户登录路径属 REQ-USR-001 既有，不重复） + - REQ-USR-004：26/26（含 spec § 业务规则 3 isDeleted/lastLoginDate 强制 equals 回归） + +## ⑥ 本模块新增 Migration + +—（本模块无 schema 改动；V1__initial_schema.sql 已在 A 阶段建好 6 张表，本模块全程复用） + +## ⑦ 跨模块改动清单（软规则 S2） + +—（本模块未触碰其他模块代码；scripts/test.sh 改动属于项目级基础设施修复，不构成跨模块改动。docs/05 修订属于本模块自己的 API 契约同步。） + +## ⑧ 偏离 spec 清单 + +- **REQ-USR-001**: docs/04 § 1.6 描述了 access + refresh token 双 token 模型，本 REQ 只签发 access token；refresh 推迟到后续 REQ。spec 已显式声明此偏离。 +- **REQ-USR-001**: docs/04 § 1.6 提及"签发后写 Redis"，本 REQ 不实现 Redis 黑名单，JWT 自包含验证。spec 已声明。 +- **REQ-USR-002**: REQ 卡片表 1 与 docs/05 在密码字段处理上原本冲突；spec 锁定为"系统生成初始密码 666666"（以 REQ 卡为准），docs/05 同步删除 password 字段与 40002 错误码。 +- **跨 REQ 文档冲突**: docs/04 § 1.3 错误码段位（10xxx/20xxx/.../60xxx）与 docs/05 + 代码实际使用的 HTTP-aligned 段位（40001/40101/40301/40901/...）不一致。本模块沿用 docs/05 + HTTP-aligned 方案；建议后续单独 PR 修订 docs/04 § 1.3 表述以拉齐 SSoT。 + +## ⑨ AI reviewer 报告汇总 + +- REQ-USR-001: round 1 — request-changes（4 high + 7 medium，已落地 5 项修复）；round 2 — approve（4 nice-to-have） +- REQ-USR-002: round 1 — approve（13 nice-to-have，0 must-fix） +- REQ-USR-003: round 1 — approve（6 nice-to-have，0 must-fix；归档时顺手补 docs/05 PUT § 40101） +- REQ-USR-004: round 1 — request-changes（2 medium）；round 2 — approve（4 nice-to-have） + +## ⑩ 已知问题 + +1. **spec § 15 唯一索引兜底（REQ-USR-002）未单测**: UserCreateServiceImpl 在 DataIntegrityViolationException 时通过 message 文本匹配 `uk_sys_user_username` / `uk_sys_user_code` 转 40901/40902；与 MySQL 驱动版本/locale 强耦合，缺 @SpyBean 模拟回归测试。建议后续用 `SQLState='23000' + 错误号 1062` 解析 + 单测覆盖。 +2. **权限分类批量插入未走 batchInsert**: REQ-USR-002 / 003 用 for + 单条 insert（N 次 IO）。当前 N < 20 可接受，建议未来补 `insertBatch`。 +3. **permissionCategoryIds 差集无乐观锁**: REQ-USR-003 并发 PUT 同一用户可能产生交叉写入。建议未来引入 `sys_user.iVersion` 做乐观锁。 +4. **ErrorCode.COMPANY_NOT_FOUND 复用语义错位**: REQ-USR-002 / 003 用 40004 抛"权限分类不存在"，常量名 COMPANY_NOT_FOUND 与 message 字面冲突。建议重命名为 RELATED_ENTITY_NOT_FOUND 或拆专用 code。 +5. **entity Lombok 字段沿用 SQL 列名匈牙利前缀**: 偏离 docs/04 § 1.2 Java 字段小驼峰约定。当前为了让 MyBatis-Plus 零配置映射；建议未来 refactor 用 @TableField 显式映射。 +6. **跨文档错误码段位冲突**: docs/04 § 1.3 vs docs/05 + 代码（见 ⑧ 偏离）。 +7. **mapper XML ORDER BY 硬编码 u.\* 前缀**: REQ-USR-004 sortField 白名单当前仅 sys_user 表列；未来扩展到 e.* / d.* 列需更新前缀逻辑。 +8. **JwtHandlerInterceptor 每请求重查 DB**: 无缓存；后续容量评估后可加 Caffeine 短期缓存。 +9. **scripts/test.sh 之前调用不存在的 ./mvnw**: 本模块期间发现并修复（改用系统 mvn）；首次 test-gate 失败已记录在 test-gate evidence。 + +## ⑪ 下一模块预览 + +后端阶段仅本一个模块（module_usr），全部 REQ 已完成。 + +**下一步**：本 MR 合并到 master 后，重跑 `/erp-workflow:coding-start`，会自动检测 `backend_done=true && frontend_done=false`，派发 `frontend-start` 进入前端阶段。前端阶段会以 `prototype/` 的 HTML mockup 为权威推导 FE 业务功能清单，按 FE 循环（fe-feature-brainstorm → plan → tdd → verify → review）完成。 + +**前端预期工作量**：基于已实现的 6 个端点（auth/login、users CRUD + 列表 + 详情），FE 至少需要：登录页、用户列表 + 筛选页、用户新增 / 编辑 Modal 表单。`prototype/` 目前为空，进入前端阶段时 `frontend-start` 会通过 AskUserQuestion 引导补齐 mockup。 + +## ⑫ MR 链接 + +- !1 http://git.xlyprint.cn/zhuzc/test5/-/merge_requests/1 +- 标题: `feat(module_usr): 用户管理` +- 目标分支: master +- 源分支: module-module_usr diff --git a/docs/superpowers/module-reports/module_usr-test-gate.md b/docs/superpowers/module-reports/module_usr-test-gate.md new file mode 100644 index 0000000..9d8aaa1 --- /dev/null +++ b/docs/superpowers/module-reports/module_usr-test-gate.md @@ -0,0 +1,36 @@ +## Local test gate — module_usr + +执行时间: 2026-05-15T10:33:28+08:00 + +### scripts/test.sh (subagent) +- 子会话: a9aa7d814ffd7dd13 +- 命令: `cd /Users/reporkey/Desktop/test5 && set -a && . ./.env.local && set +a && ./scripts/test.sh` +- 退出码: 0 +- 通过: 201 / 失败: 0 +- 关键 stdout (≤30 行): + +``` +[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.746 s -- in com.xly.erp.common.exception.GlobalExceptionHandlerTest +[INFO] +[INFO] Results: +[INFO] +[INFO] Tests run: 201, Failures: 0, Errors: 0, Skipped: 0 +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 02:32 min +[INFO] Finished at: 2026-05-15T10:33:28+08:00 +[test.sh] skip frontend test +[test.sh] 5/6 E2E +[test.sh] e2e 略 (no frontend) +[test.sh] 6/6 reset test db +[setup-test-db] done — schema will be applied by Flyway when Spring Boot starts +[test.sh] GREEN +``` + +### 备注 + +首次运行 test-gate 时 `scripts/test.sh` 在 stage 2/6 build 失败，因为脚本调用 `./mvnw` 而 backend 没有 Maven Wrapper。修复：把 `./mvnw` 全部替换为系统 `mvn`（与 docs/07 § 一 声明的 Maven 3.9.x 依赖一致）。修后 6 个 stage 全部 GREEN。 + +结论: green diff --git a/docs/superpowers/plans/2026-05-15-REQ-USR-001.md b/docs/superpowers/plans/2026-05-15-REQ-USR-001.md new file mode 100644 index 0000000..789bc0b --- /dev/null +++ b/docs/superpowers/plans/2026-05-15-REQ-USR-001.md @@ -0,0 +1,462 @@ +--- +req_id: REQ-USR-001 +date: 2026-05-15 +spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-001.md +--- + +# REQ-USR-001 用户登录 Implementation Plan + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 实现 `POST /api/v1/auth/login`，按 spec 完成 4 类校验（公司 / 作废 / 锁定 / 密码）+ 失败计数 + 锁定写入 + JWT 签发，并落地后端项目骨架以支撑后续 REQ。 + +**Architecture:** +- Spring Boot 3 + MyBatis-Plus + Flyway + BCrypt + JJWT (HS256)；分层 controller → service(impl) → mapper（docs/04 § 1.1）。 +- 业务逻辑全部在 `LoginServiceImpl`，事务边界为成功路径的"清零计数 + 更新登录时间 + 签发 JWT"原子提交。 +- 失败逻辑（计数累加 + 锁定写入）在独立事务里执行；锁定时间通过 `tLockUntil` 字段比对 `NOW()` 判定（无需 Redis）。 +- 错误码集中在 `ErrorCode` 常量类；`GlobalExceptionHandler` 把 `BizException` 转 `Result.fail`。 + +**Tech Stack:** Spring Boot 3.x（Java 17）/ MyBatis-Plus 最新稳定 / Flyway 10.x（core + mysql）/ Spring Security crypto（BCryptPasswordEncoder，不启用完整 Security filter chain）/ JJWT 0.12.x / Lombok / Jakarta Validation。 + +--- + +## Schema 改动 + +无。V1 已建好 `sys_user` / `sys_company` / `sys_employee`，本 REQ 不动 schema。 + +--- + +## 文件变更清单 + +**Bootstrap（首次 REQ 一次性投入，后续 REQ 复用）：** +- `backend/pom.xml` — Create（Maven POM，声明依赖与插件） +- `backend/src/main/java/com/xly/erp/Application.java` — Create（Spring Boot 启动类） +- `backend/src/main/resources/application.yml` — Create（主配置，从 `.env.local` / 环境变量读敏感项） +- `backend/src/main/resources/application-test.yml` — Create（测试 profile，复用相同 schema 但禁日志彩色） +- `backend/src/main/resources/logback-spring.xml` — Create（最小 logback 配置） + +**通用基础层（首次 REQ 一次性投入）：** +- `backend/src/main/java/com/xly/erp/common/response/Result.java` — Create +- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — Create +- `backend/src/main/java/com/xly/erp/common/exception/BizException.java` — Create +- `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java` — Create +- `backend/src/main/java/com/xly/erp/common/security/JwtUtil.java` — Create +- `backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java` — Create（`BCryptPasswordEncoder` Bean） + +**业务层（REQ-USR-001 专属）：** +- `backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java` — Create（只读 join 用，最小字段） +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java` — Create（接口） +- `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java` — Create + +**测试：** +- `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` — Create（unit/integration with Spring Test + 真实 MySQL，按 spec 验收 1-10 项） +- `backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java` — Create（`MockMvc` 端到端覆盖错误码 40001 / 40004 / 40101 / 40103 / 42301） +- `backend/src/test/resources/sql/req-usr-001-seed.sql` — Create（测试 fixture：1 个启用用户、1 个作废用户、2 个公司、1 个员工） + +--- + +## 约束常量（跨任务，写死不允许漂移） + +**错误码**（`ErrorCode` 常量类）： + +| 常量名 | 值 | HTTP | +|---|---|---| +| `OK` | `200` | 200 | +| `BAD_REQUEST` | `40001` | 400 | +| `COMPANY_NOT_FOUND` | `40004` | 400 | +| `BAD_CREDENTIALS` | `40101` | 401 | +| `ACCOUNT_DELETED` | `40103` | 401 | +| `ACCOUNT_LOCKED` | `42301` | 423 | +| `INTERNAL_ERROR` | `50000` | 500 | + +**JWT 常量**：算法 HS256；TTL 7200 秒；claims 名 `sub` / `username` / `userType` / `companyCode` / `language` / `iat` / `exp` / `jti`；签名密钥从 `application.yml` 注入 `${JWT_SECRET}`（已在 `.env.local` 配置）。 + +**锁定策略**：阈值 5 次（含第 5 次触发锁定）；锁定时长 30 分钟。Magic number 集中在 `LoginServiceImpl` 私有常量 `MAX_FAILED_LOGIN_COUNT = 5` 与 `LOCK_DURATION_MINUTES = 30L`。 + +**API 形状**： + +``` +POST /api/v1/auth/login (公开接口，无需 Bearer) +Request: LoginReq { username:String, password:String, companyCode:String } +Response: Result + LoginVo { accessToken:String, tokenType:"Bearer", expiresInSec:7200, userInfo:UserInfoVo } + UserInfoVo { userId:int, username:String, userType:String, language:String, + employeeName:String?, companyCode:String } +``` + +--- + +## 任务步骤 + +### Task 1: Bootstrap Spring Boot 项目骨架 + +**Files:** +- Create: `backend/pom.xml` +- Create: `backend/src/main/java/com/xly/erp/Application.java` +- Create: `backend/src/main/resources/application.yml` +- Create: `backend/src/main/resources/application-test.yml` +- Create: `backend/src/main/resources/logback-spring.xml` +- Create: `backend/src/test/java/com/xly/erp/ApplicationContextTest.java` + +**配置要点**（POM 内容由 TDD 实现，签名约束如下）： +- Parent: `spring-boot-starter-parent:3.3.x`，Java 17 +- Dependencies: `spring-boot-starter-web`, `spring-boot-starter-validation`, `spring-boot-starter-test`, `mybatis-plus-spring-boot3-starter:3.5.x`, `mysql-connector-j` (runtime), `flyway-core` + `flyway-mysql`, `spring-security-crypto`（**不**引入 `spring-boot-starter-security`，避免开启 filter chain），`io.jsonwebtoken:jjwt-api/jjwt-impl/jjwt-jackson:0.12.5`, `lombok` +- Flyway 自动启用：默认指向 classpath:db/migration，本项目改为 `classpath:db/migration` 同步指向仓库根 `sql/migrations/` —— **由 Spring Boot 配置加载实现**：在 `application.yml` 写 `spring.flyway.locations: filesystem:../sql/migrations`（相对 backend/ 目录） +- `application.yml` 必须用 `${VAR_NAME}` 注入 DB / JWT 凭据（来源 `.env.local`，启动时由 maven-dotenv-plugin 或 `EnvironmentPostProcessor` 加载——TDD 选择最简单方案 `spring-boot-dotenv` 第三方 starter 或 spring-cloud-context 都不引入，改用 `application.yml` 占位 + 启动命令显式 `--spring.config.location` 或 OS 环境变量；**推荐**：要求开发者把 `.env.local` 中的变量 export 到 shell 后 `./mvnw spring-boot:run`；测试场景由 surefire `` 注入或测试自行 `@TestPropertySource` 覆盖） + +> 注：以上"如何加载 .env.local"是 Spring Boot 项目的通用工程难题，本任务**最小可行实现**：测试用 `@DynamicPropertySource` 从 `System.getenv()` 注入；启动用 OS 环境变量。生产部署后续 REQ 再优化。 + +**API shape**: +- `Application.main(String[])` — 标准 `SpringApplication.run` +- `ApplicationContextTest#contextLoads()` — Spring Test 验证 ApplicationContext 启动 + +- [ ] **Step 1: 写失败测试** + - 测试名: `ApplicationContextTest#contextLoads` + - 意图: 验证 Spring Boot context 能启动；Flyway 能连接到 .env.local 指定的 MySQL 并发现 V1 已 apply（含 `flyway_schema_history` 表） + - 子会话确认 FAIL（pom.xml 不存在 / Application 类不存在） + +- [ ] **Step 2: 实现最小代码** + - 写 pom.xml（依赖如上）、Application.java、application.yml、application-test.yml、logback-spring.xml + - 在 `application-test.yml` 中通过 `@DynamicPropertySource` 或 `spring.datasource.url=jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_SCHEMA}` 占位符让测试读 env + +- [ ] **Step 3: 子会话验证 PASS** + - 子会话跑 `cd backend && ./mvnw -B test -Dtest=ApplicationContextTest` 应绿 + +- [ ] **Step 4: Commit** + - `git add backend/pom.xml backend/src/main/java/com/xly/erp/Application.java backend/src/main/resources/ backend/src/test/java/com/xly/erp/ApplicationContextTest.java` + - `git commit -m "feat(usr): bootstrap spring boot 后端骨架 REQ-USR-001"` + +--- + +### Task 2: 通用响应包装 + 异常处理 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/common/response/Result.java` +- Create: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` +- Create: `backend/src/main/java/com/xly/erp/common/exception/BizException.java` +- Create: `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java` +- Create: `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java` + +**API shape:** +- `Result { int code; String message; T data; long timestamp; static Result ok(T data); static Result fail(int code, String message); }` +- `ErrorCode` — 常量类，含上方"约束常量"表中所有 code（int 字段） +- `BizException extends RuntimeException { int code; String message; BizException(int code, String message); }` +- `GlobalExceptionHandler` — `@RestControllerAdvice`，handles： + - `BizException` → 按其 `code` 映射到 `ResponseEntity`，HTTP 状态按 ErrorCode 表 + - `MethodArgumentNotValidException` / `ConstraintViolationException` → `Result.fail(40001, ...)`，HTTP 400 + - `Exception`（兜底） → `Result.fail(50000, "服务器内部错误")`，HTTP 500，记 ERROR 日志，**不**回显堆栈到 message + +- [ ] **Step 1: 写失败测试** + - 测试名: `GlobalExceptionHandlerTest#bizException_returnsCodeAndHttpStatus` 等 3 个测试 + - 意图: 用 `MockMvc` 配合一个 `/_test/throw-biz` 测试 controller 触发 `BizException(42301, "...")`，断言 HTTP 423 + body `code=42301`；类似覆盖 `BizException(40101, ...)` → 401，以及兜底 `RuntimeException` → 500 且 message 不含 "java." 前缀 + - 子会话确认 FAIL + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): 通用响应包装 + 全局异常处理 REQ-USR-001"` + +--- + +### Task 3: JWT 工具 + 密码编码器 Bean + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/common/security/JwtUtil.java` +- Create: `backend/src/main/java/com/xly/erp/common/config/PasswordEncoderConfig.java` +- Create: `backend/src/test/java/com/xly/erp/common/security/JwtUtilTest.java` + +**API shape:** +- `JwtUtil#issue(Map claims, long ttlSec) : String` — 用 `${JWT_SECRET}`（注入 `@Value`）签发 HS256 JWT，含 `iat` / `exp` / `jti(=UUID)` +- `JwtUtil#parse(String token) : Map` — 验签 + 解析，签名错或过期抛 `BizException(40101, ...)` +- `PasswordEncoderConfig#passwordEncoder() : BCryptPasswordEncoder` — Spring Bean，strength=10 + +- [ ] **Step 1: 写失败测试** + - 测试名: `JwtUtilTest#issuedToken_canBeParsedBackToClaims` / `JwtUtilTest#tamperedToken_throwsBizException` / `JwtUtilTest#expiredToken_throwsBizException`（用 ttl=0 模拟） + - 意图: 验证签发→解析往返一致；篡改任意一字节抛 40101；过期抛 40101 + +- [ ] **Step 2: 实现最小代码** + - JWT_SECRET 来自 `application-test.yml` 的 `jwt.secret: ${JWT_SECRET:test-secret-256bit-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}` + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): JWT 工具 + BCrypt 编码器 REQ-USR-001"` + +--- + +### Task 4: Entity + Mapper（sys_user / sys_company / sys_employee） + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysUser.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysCompany.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysEmployee.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysCompanyMapper.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysEmployeeMapper.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java` +- Create: `backend/src/test/resources/sql/req-usr-001-seed.sql` + +**API shape:** +- `SysUser` — 含 `iIncrement / sUsername / sUserCode / sPasswordHash / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / iFailedLoginCount / tLockUntil / tLastLoginDate / sCreatedBy / sUpdatedBy / tUpdatedDate` 字段（命名按 docs/03，TableField 映射）；`@TableName("sys_user")`，`@TableId(value="iIncrement", type=IdType.AUTO)` +- `SysCompany` — 含 `iIncrement / sCompanyCode / sCompanyName / iIsDeleted`（最小字段） +- `SysEmployee` — 含 `iIncrement / sEmployeeName / iDepartmentId`（最小字段） +- Mapper 三个均 `extends BaseMapper`（MyBatis-Plus）；`SysUserMapper` 额外定义一个方法：`selectByUsername(String username) : SysUser`（@Select 注解），用于登录查找 + +**Seed SQL** 内容（写死）： +```sql +-- req-usr-001-seed.sql +DELETE FROM sys_user_permission_category; +DELETE FROM sys_user; +DELETE FROM sys_employee; +DELETE FROM sys_company; + +INSERT INTO sys_company (sCompanyName, sCompanyCode, iIsDeleted) VALUES + ('总部', 'HQ', 0), + ('已删公司', 'DEL_CO', 1); + +INSERT INTO sys_employee (sEmployeeName, sEmployeeCode, iDepartmentId) +SELECT '张三', 'E001', 1 FROM (SELECT 1) t +WHERE EXISTS (SELECT 1 FROM sys_department LIMIT 1); +-- 若 sys_department 为空，先插入一行 +INSERT INTO sys_department (sDepartmentName, sDepartmentCode) VALUES ('技术部', 'TECH'); +INSERT INTO sys_employee (sEmployeeName, sEmployeeCode, iDepartmentId) + SELECT '张三', 'E001', iIncrement FROM sys_department WHERE sDepartmentCode='TECH' LIMIT 1; + +-- password = 'Password1!' 的 BCrypt(strength=10) 哈希（TDD 阶段实际生成填入） +INSERT INTO sys_user (sUsername, sUserCode, sPasswordHash, iEmployeeId, sUserType, sLanguage, iIsDeleted, iFailedLoginCount, sCreatedBy) + SELECT 'alice', 'U001', '', iIncrement, 'NORMAL', 'zh-CN', 0, 0, 'system' + FROM sys_employee WHERE sEmployeeCode='E001'; + +INSERT INTO sys_user (sUsername, sUserCode, sPasswordHash, sUserType, sLanguage, iIsDeleted, sCreatedBy) + VALUES ('bob_deleted', 'U002', '', 'NORMAL', 'zh-CN', 1, 'system'); +``` +> `` 在 Task 4 实现时通过一次性 java main 或 `BCryptPasswordEncoder` 调用生成后填入；不允许保留占位符进 commit。 + +- [ ] **Step 1: 写失败测试** + - 测试名: `SysUserMapperTest#selectByUsername_returnsUserWithAllFields` / `SysUserMapperTest#selectByUsername_returnsNullWhenNotFound` + - 意图: seed 后查 `alice` → 字段完整；查 `nobody` → null + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): sys_user/sys_company/sys_employee entity + mapper REQ-USR-001"` + +--- + +### Task 5: LoginReq DTO + LoginVo + UserInfoVo + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/LoginReq.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/LoginVo.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserInfoVo.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/LoginReqValidationTest.java` + +**API shape:** +- `LoginReq { @NotBlank @Size(max=50) String username; @NotBlank @Size(max=128) String password; @NotBlank @Size(max=50) String companyCode; }` +- `LoginVo { String accessToken; String tokenType; long expiresInSec; UserInfoVo userInfo; }` +- `UserInfoVo { Integer userId; String username; String userType; String language; String employeeName; String companyCode; }` + +- [ ] **Step 1: 写失败测试** + - 测试名: `LoginReqValidationTest#blankUsername_fails` / `LoginReqValidationTest#tooLongUsername_fails` / `LoginReqValidationTest#allFieldsPresent_passes` + - 意图: 用 `Validator` 校验 jakarta 约束注解工作正常 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): LoginReq + LoginVo + UserInfoVo REQ-USR-001"` + +--- + +### Task 6: LoginService 接口骨架 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/LoginService.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` + +**API shape:** +- `LoginService#login(String username, String password, String companyCode) : LoginVo` — 业务方法签名 +- `LoginServiceImpl implements LoginService` — `@Service`，注入 `SysUserMapper`、`SysCompanyMapper`、`SysEmployeeMapper`、`BCryptPasswordEncoder`、`JwtUtil` +- `LoginServiceImpl` 私有常量：`MAX_FAILED_LOGIN_COUNT = 5`、`LOCK_DURATION_MINUTES = 30L`、`TOKEN_TTL_SEC = 7200L` + +本 task 仅产出**接口 + 空实现 + 一个 baseline 测试**（直接抛 UnsupportedOperationException），用于建立后续 task 的脚手架。 + +- [ ] **Step 1: 写失败测试** + - 测试名: `LoginServiceImplTest#contextLoads`（验证 LoginService Bean 注入成功；与 `@SpringBootTest` + seed.sql 一起工作） + - 意图: Bean 装配可用 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): LoginService 接口骨架 REQ-USR-001"` + +--- + +### Task 7: Login — 公司不存在或已删 → 40004 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` + +**API behavior**：当 `companyCode` 在 `sys_company` 查不到（不存在 OR `iIsDeleted=1`）→ 抛 `BizException(ErrorCode.COMPANY_NOT_FOUND, "公司不存在或已删除")`；**不**触碰 sys_user。 + +- [ ] **Step 1: 写失败测试** + - 测试名: `LoginServiceImplTest#login_unknownCompany_throws40004` / `login_softDeletedCompany_throws40004` + - 意图: 用 seed 中的 `HQ`（正常）vs `NOPE`（不存在）vs `DEL_CO`（软删）触发不同分支；断言抛 `BizException` 且 `code == 40004`；同时断言 `alice` 的 `iFailedLoginCount` 仍为 0（未被错误计入失败） + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): 登录校验公司存在性 REQ-USR-001"` + +--- + +### Task 8: Login — 用户不存在 / 密码错 → 40101（同文案，含失败计数） + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` + +**API behavior**: +- 用户名不存在 → `BizException(40101, "用户名或密码错误")`；不写 DB（无 user 行可写） +- 用户存在 + 密码 hash 不匹配 → `sys_user.iFailedLoginCount += 1`，返 `BizException(40101, "用户名或密码错误")` + +- [ ] **Step 1: 写失败测试** + - 测试名: + - `login_unknownUser_throws40101_noDbWrite` + - `login_badPassword_throws40101_andIncrementsFailCount` （断言一次错误后 `iFailedLoginCount == 1`） + - 意图: 防用户名枚举 + 失败计数累加 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): 登录用户名/密码错误统一返回 40101 + 累加失败计数 REQ-USR-001"` + +--- + +### Task 9: Login — 失败 5 次锁定 → 第 6 次返 42301 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` + +**API behavior**: +- 累计第 5 次错误密码时，在同一事务里写 `tLockUntil = NOW() + 30 分钟`；本次响应仍返 `40101`（**不**在第 5 次直接返锁定，避免泄露阈值） +- 后续请求遇到 `tLockUntil IS NOT NULL AND tLockUntil > NOW()` → 直接抛 `BizException(ACCOUNT_LOCKED, "账号已锁定，请稍后再试")`，HTTP 423；**不**计入失败次数 +- `tLockUntil <= NOW()`（锁定到期）→ 视为已解锁，正常进入密码校验流程（即仍允许累加失败、仍允许成功） + +- [ ] **Step 1: 写失败测试** + - 测试名: + - `login_5thBadPassword_setsLockUntil_andStillReturns40101`（断言 `iFailedLoginCount == 5` 且 `tLockUntil` 不为空 ≥ NOW()+29min） + - `login_duringLockWindow_throws42301_noCountIncrement` + - `login_afterLockExpired_allowsNewAttempt`（用 SQL 把 tLockUntil 改成过去时刻，再次登录正确密码 → 应成功并清零计数；属于先做小验证，可在 Task 10 完整覆盖成功路径） + - 意图: 锁定语义闭环 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): 登录失败 5 次锁定 30 分钟 REQ-USR-001"` + +--- + +### Task 10: Login — 作废账号 → 40103；成功 → 签 JWT + 清零 + 更新登录时间 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java` + +**API behavior**: +- `sys_user.iIsDeleted == 1` → `BizException(ACCOUNT_DELETED, "账号已被作废，禁止登录")`，HTTP 401；**不**进入密码校验，**不**累加失败 +- 成功路径（`@Transactional`）： + 1. `iFailedLoginCount = 0`，`tLockUntil = NULL`，`tLastLoginDate = NOW()`（一次 UPDATE） + 2. 加载 `sys_employee.sEmployeeName`（若 `iEmployeeId` 非空） + 3. 构造 JWT claims（`sub=userId`, `username`, `userType`, `companyCode`, `language`, `jti=UUID`），通过 `JwtUtil.issue(claims, TOKEN_TTL_SEC)` + 4. 返回 `LoginVo` + +判定顺序（先后明确）：1) 公司校验 → 2) 用户查找 → 3) 作废校验 → 4) 锁定校验 → 5) 密码校验 → 6) 成功路径。 + +- [ ] **Step 1: 写失败测试** + - 测试名: + - `login_deletedUser_throws40103_noCountIncrement` + - `login_success_returnsTokenAndClearsFailCount_andUpdatesLastLogin` + - `login_success_jwtParsesBack_with_sub_username_companyCode` + - 意图: 成功路径与作废路径都覆盖；JWT 验签往返 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): 登录成功签发 JWT + 作废账号 40103 REQ-USR-001"` + +--- + +### Task 11: AuthController + 端到端 MockMvc 测试 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/AuthController.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/AuthControllerTest.java` + +**API shape:** +- `AuthController` — `@RestController @RequestMapping("/api/v1/auth")` +- `POST /api/v1/auth/login` 方法 `login(@RequestBody @Valid LoginReq req) : Result`，委托给 `LoginService` + +- [ ] **Step 1: 写失败测试** + - 测试名（`AuthControllerTest` 用 `@SpringBootTest + MockMvc`）： + - `post_login_success_returns200_andLoginVo` + - `post_login_badCredentials_returns401_code40101` + - `post_login_lockedAccount_returns423_code42301` + - `post_login_deletedAccount_returns401_code40103` + - `post_login_unknownCompany_returns400_code40004` + - `post_login_blankUsername_returns400_code40001` + - 意图: 6 个 HTTP 路径全部覆盖 spec § 验收 1-10 + +- [ ] **Step 2: 实现最小代码** + +- [ ] **Step 3: 子会话验证 PASS** + +- [ ] **Step 4: Commit** + - `git commit -m "feat(usr): POST /api/v1/auth/login controller + 端到端测试 REQ-USR-001"` + +--- + +## 提交计划 + +按 task 顺序产生 11 个 commit： + +| Task | Commit message | +|---|---| +| 1 | `feat(usr): bootstrap spring boot 后端骨架 REQ-USR-001` | +| 2 | `feat(usr): 通用响应包装 + 全局异常处理 REQ-USR-001` | +| 3 | `feat(usr): JWT 工具 + BCrypt 编码器 REQ-USR-001` | +| 4 | `feat(usr): sys_user/sys_company/sys_employee entity + mapper REQ-USR-001` | +| 5 | `feat(usr): LoginReq + LoginVo + UserInfoVo REQ-USR-001` | +| 6 | `feat(usr): LoginService 接口骨架 REQ-USR-001` | +| 7 | `feat(usr): 登录校验公司存在性 REQ-USR-001` | +| 8 | `feat(usr): 登录用户名/密码错误统一返回 40101 + 累加失败计数 REQ-USR-001` | +| 9 | `feat(usr): 登录失败 5 次锁定 30 分钟 REQ-USR-001` | +| 10 | `feat(usr): 登录成功签发 JWT + 作废账号 40103 REQ-USR-001` | +| 11 | `feat(usr): POST /api/v1/auth/login controller + 端到端测试 REQ-USR-001` | diff --git a/docs/superpowers/plans/2026-05-15-REQ-USR-002.md b/docs/superpowers/plans/2026-05-15-REQ-USR-002.md new file mode 100644 index 0000000..237bebf --- /dev/null +++ b/docs/superpowers/plans/2026-05-15-REQ-USR-002.md @@ -0,0 +1,310 @@ +--- +req_id: REQ-USR-002 +date: 2026-05-15 +spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-002.md +--- + +# REQ-USR-002 新增用户 Implementation Plan + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** `POST /api/v1/users` 接口，超级管理员新建用户（初始密码 `666666` 系统生成 + 哈希），同时落地 JWT 鉴权 HandlerInterceptor + `@RequireSuperAdmin` 角色守卫基础设施。 + +**Architecture:** +- 鉴权：手写 `JwtHandlerInterceptor` 实现 `HandlerInterceptor`，通过 `WebMvcConfigurer` 注册，匹配 `/api/v1/**`，放行 `/api/v1/auth/login`；通过 `LoginContext` ThreadLocal 把当前用户上下文传递到 controller / service。 +- 角色守卫：`@RequireSuperAdmin` 方法级注解；同一 interceptor 在 `handler instanceof HandlerMethod` 时检查注解 + `LoginContext.userType`。 +- 业务：`UserCreateService` 单一职责（创建用户 + 写权限分类授权），事务边界一整个写入流程；唯一性预检 + DB 唯一索引兜底；外键存在性预检（employee + permissionCategory）。 +- docs/05 同步：删除 CreateUserReq 的 `password` 字段与 `40002` 错误码（在 Task 1 一并完成）。 + +**Tech Stack:** 复用 REQ-USR-001 已建（Spring Boot 3 / MyBatis-Plus / BCrypt / JJWT）；本 REQ 新增依赖：无。 + +--- + +## Schema 改动 + +无。V1 已建。 + +--- + +## 文件变更清单 + +**基础设施（鉴权 / 角色守卫）**： +- `backend/src/main/java/com/xly/erp/common/security/LoginContext.java` — Create（ThreadLocal 工具） +- `backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java` — Create +- `backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java` — Create（注解） +- `backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java` — Create（注册 interceptor） +- `backend/src/main/resources/application.yml` — Modify:21（启用 `spring.jackson.deserialization.fail-on-unknown-properties: true`） + +**业务（REQ-USR-002 专属）**： +- `backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — Modify（新增 `selectByUserCode` + `existsByUsername` + `existsByUserCode` 方法） +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java` — Create（接口） +- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java` — Create +- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java` — Create + +**文档同步**： +- `docs/05-API接口契约.md` — Modify（去掉 `password` + `40002`） + +**测试**： +- `backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java` — Create（鉴权 / 角色守卫单测，含 MockMvc） +- `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java` — Create（service 集成测） +- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java` — Create（controller 端到端） +- `backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java` — Modify（扩展 seed：添加 SUPER_ADMIN 用户 + 2 个权限分类） + +--- + +## 约束常量 + +**错误码新增**（添加到 `ErrorCode`）： + +| 常量 | 值 | HTTP | +|---|---|---| +| `FORBIDDEN` | `40301` | 403 | +| `CONFLICT_USERNAME` | `40901` | 409 | +| `CONFLICT_USERCODE` | `40902` | 409 | + +**初始密码**：常量 `UserCreateServiceImpl.INITIAL_PASSWORD = "666666"`。 + +**LoginContext API**（ThreadLocal 工具）： +- `LoginContext.set(int userId, String username, String userType, String companyCode)` +- `LoginContext.current() : LoginUser`（含上述 4 字段，未登录返 null） +- `LoginContext.clear()` + +**`@RequireSuperAdmin`**：方法级注解，无属性。 + +**`JwtHandlerInterceptor`** 行为序列（`preHandle`）： +1. handler 非 HandlerMethod → return true（静态资源等） +2. method 标注 `@RequireSuperAdmin` 或在 `/api/v1/**` 路径下（非 login）→ 必须鉴权 +3. 取 `Authorization` 头；缺失或无 `Bearer ` 前缀 → `BizException(40101, "未携带 token")` +4. `jwtUtil.parse(token)` 取 claims +5. `userMapper.selectByUsername(claims.username)` 查最新状态；不存在 / `iIsDeleted=1` / `tLockUntil > NOW()` → `BizException(40101, "token 关联用户不可用")` +6. `LoginContext.set(...)` +7. 若 method 标注 `@RequireSuperAdmin` 且 `userType != "SUPER_ADMIN"` → `BizException(40301, "权限不足，仅超级管理员可调用")` +8. return true +9. `afterCompletion` 调 `LoginContext.clear()` + +--- + +## 任务步骤 + +### Task 1: docs/05 同步 + ErrorCode 新增 3 个常量 + +**Files:** +- Modify: `docs/05-API接口契约.md` § REQ-USR-002 — 删除 password 字段 + 40002 错误码 +- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 新增 FORBIDDEN / CONFLICT_USERNAME / CONFLICT_USERCODE 常量 + 在 `toHttpStatus` 对 40301 / 40901 / 40902 加映射 +- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java` — Create（覆盖新增 HTTP 映射） + +**API shape:** +- `ErrorCode.FORBIDDEN = 40301` +- `ErrorCode.CONFLICT_USERNAME = 40901` +- `ErrorCode.CONFLICT_USERCODE = 40902` +- `ErrorCode.toHttpStatus(40301) == 403`、`toHttpStatus(40901) == 409`、`toHttpStatus(40902) == 409` + +- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes` +- [ ] **Step 2: 实现最小代码** + 改 docs/05 +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `chore(usr): docs/05 去 password 字段 + ErrorCode 新增 40301/40901/40902 REQ-USR-002` + +### Task 2: LoginContext ThreadLocal + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/common/security/LoginContext.java` +- Create: `backend/src/test/java/com/xly/erp/common/security/LoginContextTest.java` + +**API shape:** +- `LoginContext.LoginUser` — record（userId:Integer, username:String, userType:String, companyCode:String） +- `LoginContext.set(LoginUser)` / `LoginContext.current()` / `LoginContext.clear()` +- 用 `InheritableThreadLocal` 否，纯 `ThreadLocal`（避免子线程意外继承） + +- [ ] **Step 1: 写失败测试** + - `LoginContextTest#setAndCurrent_isolatedPerThread` — 两个线程 set 不同值，互不影响 + - `LoginContextTest#clear_returnsNullForCurrent` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): LoginContext ThreadLocal REQ-USR-002` + +### Task 3: @RequireSuperAdmin 注解 + JwtHandlerInterceptor + WebMvcConfig + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/common/security/RequireSuperAdmin.java` +- Create: `backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java` +- Create: `backend/src/main/java/com/xly/erp/common/config/WebMvcConfig.java` +- Create: `backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java` + +**API shape:** +- `@RequireSuperAdmin` — `@Target(METHOD) @Retention(RUNTIME)` +- `JwtHandlerInterceptor implements HandlerInterceptor` —— 行为见"约束常量" +- `WebMvcConfig implements WebMvcConfigurer` —— `addInterceptors(registry)`：注册 JwtHandlerInterceptor，`.addPathPatterns("/api/v1/**").excludePathPatterns("/api/v1/auth/login")` + +测试用一个 `@TestController` 暴露 `/api/v1/_test/admin-only`（标 `@RequireSuperAdmin`）和 `/api/v1/_test/any-auth`（不标），MockMvc 调用： + +- [ ] **Step 1: 写失败测试** + - `noAuthHeader_returns401_40101` + - `invalidToken_returns401_40101` + - `tokenForDeletedUser_returns401_40101` + - `tokenForLockedUser_returns401_40101` + - `validToken_normalUser_canAccessAnyAuthEndpoint` + - `validToken_normalUser_cannotAccessAdminOnly_returns403_40301` + - `validToken_superAdmin_canAccessAdminOnly` + - `loginEndpointPath_skipsInterceptor`（鉴权未注入也能调 /api/v1/auth/login） + - `loginContext_clearedAfterRequest`（请求结束后 ThreadLocal 应清空） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): JwtHandlerInterceptor + @RequireSuperAdmin REQ-USR-002` + +### Task 4: SysPermissionCategory + SysUserPermissionCategory entity + mapper + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/entity/SysUserPermissionCategory.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysPermissionCategoryMapper.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/support/LoginTestSeeder.java` — 扩展插入 SUPER_ADMIN 用户 + 2 个权限分类，并暴露 alice 的 ID + admin 的 ID + 权限分类 ID 给 Fixture record + +**API shape:** +- entity 字段对齐 docs/03（与 SysUser 一致风格，匈牙利前缀 + Lombok @Data） +- `SysPermissionCategoryMapper#countActiveByIds(List ids) : int`（@Select 显式列，过滤 iIsDeleted=0） +- `SysUserPermissionCategoryMapper extends BaseMapper<...>`，无自定义方法 +- Fixture record 扩展：`Fixture(aliceId, bobDeletedId, employeeId, adminId, permissionCategoryIds)` 其中 permissionCategoryIds 是 List，admin 用户名常量 `USER_ADMIN = "admin"` + +- [ ] **Step 1: 写失败测试** + - `SysPermissionCategoryMapperTest#countActiveByIds_excludesDeleted` + - `LoginTestSeederTest#fixture_includesAdminAndPermissionCategories` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): sys_permission_category + sys_user_permission_category entity/mapper REQ-USR-002` + +### Task 5: SysUserMapper 唯一性查询方法 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` — 新增 `existsByUsername / existsByUserCode` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java` — 补测试 + +**API shape:** +- `SysUserMapper#existsByUsername(String username) : boolean`（@Select `SELECT COUNT(*) > 0 FROM sys_user WHERE sUsername = #{username}`；MyBatis 把 int 0/1 自动转 boolean，或用 Integer 后 service 层做判断） +- `SysUserMapper#existsByUserCode(String userCode) : boolean` + +- [ ] **Step 1: 写失败测试** + - `SysUserMapperTest#existsByUsername_trueForExisting / falseForUnknown` + - `SysUserMapperTest#existsByUserCode_trueForExisting / falseForUnknown` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 用户名/用户号唯一性查询 REQ-USR-002` + +### Task 6: CreateUserReq + CreateUserVo + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/CreateUserVo.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/CreateUserReqValidationTest.java` +- Modify: `backend/src/main/resources/application.yml` — 启用 `spring.jackson.deserialization.fail-on-unknown-properties: true` +- Modify: `backend/src/main/resources/application-test.yml` — 同上 + +**API shape:** +- `CreateUserReq { @NotBlank @Pattern(regexp="^[A-Za-z0-9_]{3,20}$") username, @NotBlank @Size(max=50) userCode, @NotBlank @Pattern(regexp="NORMAL|SUPER_ADMIN") userType, @NotBlank @Pattern(regexp="zh-CN|en-US|zh-TW") language, @NotNull Boolean canEditDocument, Integer employeeId, List permissionCategoryIds }` +- `CreateUserVo { Integer userId; String username; String userCode; }` + @Builder + +注意：不定义 `password` 字段；启用 fail-on-unknown-properties 后，请求带 password 会被 Jackson 直接拒绝。Jackson 反序列化异常 → 在 `GlobalExceptionHandler` 已有 `HttpMessageNotReadableException` handler（如果没有，本 Task 顺带补；同 round 1 review 推迟项） + +> 实际：round 1 没补 HttpMessageNotReadable handler。本 Task 顺手补到 `GlobalExceptionHandler`，让"包含未知字段"返 40001 / 400 而非 50000。 + +- [ ] **Step 1: 写失败测试** + - `CreateUserReqValidationTest`（10 个用例）：空 / 越长 / 用户名非法字符 / userType 非枚举 / language 非枚举 / canEditDocument 缺失 / employeeId 可空 / permissionCategoryIds 可空 / 全合法 / userCode 越长 +- [ ] **Step 2: 实现最小代码** + 改两份 application yml + 补 HttpMessageNotReadable handler +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): CreateUserReq/Vo + Jackson 严格反序列化 REQ-USR-002` + +### Task 7: UserCreateService 接口 + Impl 骨架（仅唯一性 / 外键校验） + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserCreateService.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java` + +**API shape:** +- `UserCreateService#create(CreateUserReq req, String operatorUsername) : CreateUserVo` +- `UserCreateServiceImpl` 注入：SysUserMapper / SysEmployeeMapper / SysPermissionCategoryMapper / SysUserPermissionCategoryMapper / BCryptPasswordEncoder +- 常量 `INITIAL_PASSWORD = "666666"` +- `@Transactional` + +本 Task 范围：实现 4 项校验（唯一用户名、唯一用户号、employeeId 存在、permissionCategoryIds 全部存在），但不实现实际写入——直接返回 dummy CreateUserVo(0, ..., ...)；写入路径在 Task 8。 + +- [ ] **Step 1: 写失败测试**（service 集成测，复用扩展后的 LoginTestSeeder） + - `create_usernameExists_throws40901` + - `create_userCodeExists_throws40902` + - `create_employeeIdNotFound_throws40004` + - `create_employeeIdSoftDeleted_throws40004` + - `create_permissionCategoryNotFound_throws40004`（含数组中混入不存在 ID） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserCreateService 唯一性 + 外键校验 REQ-USR-002` + +### Task 8: UserCreateService 写入路径（sys_user + sys_user_permission_category 事务） + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserCreateServiceImplTest.java` + +**API behavior:** +- 校验全过 → BCrypt encode "666666" → 插入 sys_user（sCreatedBy = operatorUsername）→ 批量插入 sys_user_permission_category（每条 sGrantedBy = operatorUsername）→ 返回 CreateUserVo(新 userId, username, userCode) +- 捕获 `DataIntegrityViolationException`（如并发同名）→ 抛 40901 / 40902（按异常消息含 `uk_sys_user_username` / `uk_sys_user_code` 判别） + +- [ ] **Step 1: 写失败测试** + - `create_minimalFields_persistsUserWithInitialPassword` + - `create_fullFields_persistsUserAndPermissionMappings` + - `create_emptyPermissionCategories_persistsUserOnly`（permissionCategoryIds=空数组 / null 都允许） + - `create_initialPasswordMatchesBcrypt666666`（用 BCryptPasswordEncoder.matches("666666", DB hash) == true） + - `create_dataIntegrityViolation_username_throws40901`（先 select 返 false 但插入时报 DuplicateKey；用 spy / 模拟难，可在测试用并发场景模拟，或直接抛模拟异常验证转换） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserCreateService 写入用户 + 权限分类授权 REQ-USR-002` + +### Task 9: UserController POST /api/v1/users + 端到端测试 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerTest.java` + +**API shape:** +- `UserController` — `@RestController @RequestMapping("/api/v1/users")` +- `POST /api/v1/users`：标注 `@RequireSuperAdmin`，方法签名 `Result create(@RequestBody @Valid CreateUserReq req)`；调用 `userCreateService.create(req, LoginContext.current().username())`；返回 `ResponseEntity.status(201).body(Result.ok(vo))` + +端到端测试（`@SpringBootTest + @AutoConfigureMockMvc`）：用 admin token 调用，覆盖： + +- [ ] **Step 1: 写失败测试** + - `post_users_success_returns201_andCreatedVo` + - `post_users_blankUsername_returns400_40001` + - `post_users_invalidUserType_returns400_40001` + - `post_users_unknownPropertyPassword_returns400_40001`（请求 body 含 `"password":"...".` 字段） + - `post_users_noAuthHeader_returns401_40101` + - `post_users_normalUserToken_returns403_40301` + - `post_users_deletedUserToken_returns401_40101` + - `post_users_duplicateUsername_returns409_40901` + - `post_users_duplicateUserCode_returns409_40902` + - `post_users_unknownEmployee_returns400_40004` + - `post_users_unknownPermissionCategory_returns400_40004` + - `post_users_success_canLoginWithInitialPassword`（创建后立即调 /auth/login 用 666666 应成功） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): POST /api/v1/users controller + 端到端测试 REQ-USR-002` + +--- + +## 提交计划 + +| Task | Commit message | +|---|---| +| 1 | `chore(usr): docs/05 去 password 字段 + ErrorCode 新增 40301/40901/40902 REQ-USR-002` | +| 2 | `feat(usr): LoginContext ThreadLocal REQ-USR-002` | +| 3 | `feat(usr): JwtHandlerInterceptor + @RequireSuperAdmin REQ-USR-002` | +| 4 | `feat(usr): sys_permission_category + sys_user_permission_category entity/mapper REQ-USR-002` | +| 5 | `feat(usr): SysUserMapper 用户名/用户号唯一性查询 REQ-USR-002` | +| 6 | `feat(usr): CreateUserReq/Vo + Jackson 严格反序列化 REQ-USR-002` | +| 7 | `feat(usr): UserCreateService 唯一性 + 外键校验 REQ-USR-002` | +| 8 | `feat(usr): UserCreateService 写入用户 + 权限分类授权 REQ-USR-002` | +| 9 | `feat(usr): POST /api/v1/users controller + 端到端测试 REQ-USR-002` | diff --git a/docs/superpowers/plans/2026-05-15-REQ-USR-003.md b/docs/superpowers/plans/2026-05-15-REQ-USR-003.md new file mode 100644 index 0000000..1998f61 --- /dev/null +++ b/docs/superpowers/plans/2026-05-15-REQ-USR-003.md @@ -0,0 +1,362 @@ +--- +req_id: REQ-USR-003 +date: 2026-05-15 +spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-003.md +--- + +# REQ-USR-003 修改用户 Implementation Plan + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 实现 `GET /api/v1/users/{userId}` + `PUT /api/v1/users/{userId}` 两个端点；PUT 支持部分字段更新 + permissionCategoryIds 增量增删差集 + 自我停用守卫；GET 返回 UserDetailVo（含 employeeName + permissionCategoryIds）。 + +**Architecture:** +- 鉴权 / 角色守卫 / 事务 / Result / 异常处理全部复用 REQ-USR-002 基础设施。 +- 新增 `UserUpdateService`（PUT）+ `UserDetailService`（GET），单一职责。 +- permissionCategoryIds 用差集：先 select 现有 → 计算 toAdd / toRemove → DELETE + INSERT 在同一事务。 +- PATCH 语义简化：缺省 / 显式 null 都视为不变；`employeeId=0` 作为约定的"解除关联"信号。 + +**Tech Stack:** 复用 REQ-USR-002（Spring Boot 3 + MyBatis-Plus + Jakarta Validation）。 + +--- + +## Schema 改动 + +无。 + +--- + +## 文件变更清单 + +**新增**： +- `backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java` +- `backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java` + +**修改**： +- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`（新增 40302 / 40401 + 404 映射） +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（新增 `existsByUserCodeExcludingId`） +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java`（新增 `selectPermissionCategoryIdsByUserId` + `deleteByUserAndCategoryIds`） +- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（新增 GET + PUT 方法） + +**文档**：本 REQ 不改 docs/05（已含 REQ-USR-003 段，但 docs/05 当前漏写 GET 详情接口；本 REQ 补充）。 + +**测试**： +- `backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java` +- `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java` +- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java`（独立文件避免冲击 REQ-USR-002 既有 UserControllerTest） + +--- + +## 约束常量 + +**ErrorCode 新增**： + +| 常量 | 值 | HTTP | +|---|---|---| +| `USER_FORBIDDEN_SELF_DEACTIVATE` | `40302` | 403 | +| `USER_NOT_FOUND` | `40401` | 404 | + +> `ErrorCode.toHttpStatus` 已含 401/403/404 段位映射，不需新增。 + +**API 形状**： + +``` +GET /api/v1/users/{userId} @RequireSuperAdmin + → Result + errors: 40101, 40301, 40401 + +PUT /api/v1/users/{userId} @RequireSuperAdmin + body: UpdateUserReq (PATCH) + → Result + errors: 40001, 40004, 40101, 40301, 40302, 40401, 40902 + +UserDetailVo { + Integer userId, String username, String userCode, + String userType, String language, Boolean canEditDocument, Boolean isDeleted, + Integer employeeId, String employeeName, + List permissionCategoryIds, + String updatedBy, LocalDateTime updatedDate +} + +UpdateUserReq { + String userCode, // 缺省/null = 不变 + String userType, // 同上 + String language, // 同上 + Boolean canEditDocument, // 同上 + Integer employeeId, // 缺省/null = 不变；0 = 解除关联；正整数 = 更新 + Boolean isDeleted, // 同上 + List permissionCategoryIds // 缺省/null = 不变；空数组 = 清空；非空 = 增删差集 +} +``` + +**PATCH 语义约定**（写死，跨任务一致）：所有字段缺省 / null 视为 "保持原值"；`employeeId == 0` 视为 "解除关联"，DB 写 NULL。其他字段无清除语义。 + +--- + +## 任务步骤 + +### Task 1: ErrorCode 新增 40302 / 40401 + 404 映射 + docs/05 补 GET 详情段 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` +- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java` +- Modify: `docs/05-API接口契约.md` § REQ-USR-003 之前加 `GET /api/v1/users/{userId}` 段 + +**API shape:** +- `ErrorCode.USER_FORBIDDEN_SELF_DEACTIVATE = 40302` +- `ErrorCode.USER_NOT_FOUND = 40401` +- `ErrorCode.toHttpStatus(40302) == 403` +- `ErrorCode.toHttpStatus(40401) == 404` + +docs/05 补充内容（追加到现 REQ-USR-003 段之前）： + +``` +### REQ-USR-003 GET 用户详情 + +- Method: GET +- Path: /api/v1/users/{userId} +- Auth: Bearer Token；仅 userType=SUPER_ADMIN 可调用 +- 请求: Path userId: int +- 响应: JSON UserDetailVo { userId, username, userCode, userType, language, canEditDocument, isDeleted, employeeId, employeeName, permissionCategoryIds[], updatedBy, updatedDate } + +#### 错误码 +- 40101 — 未携带或无效 Token +- 40301 — 当前用户非超级管理员，无权调用 +- 40401 — 用户不存在 +``` + +- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes_v003` +- [ ] **Step 2: 实现最小代码** + docs/05 改动 +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `chore(usr): docs/05 补 GET 详情 + ErrorCode 新增 40302/40401 REQ-USR-003` + +### Task 2: UpdateUserReq + UserDetailVo + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UpdateUserReq.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserDetailVo.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/UpdateUserReqValidationTest.java` + +**API shape**: 见 "约束常量"。 + +校验注解（仅在字段非 null 时生效，jakarta `@Pattern` 等天然 null-safe）： +- `userCode`: `@Size(max=50)` +- `userType`: `@Pattern(regexp="NORMAL|SUPER_ADMIN")` +- `language`: `@Pattern(regexp="zh-CN|en-US|zh-TW")` +- `employeeId`: `@Min(0)` （0 = 解除关联约定） +- 其余字段无 @ 注解 + +- [ ] **Step 1: 写失败测试** `UpdateUserReqValidationTest` 覆盖： + - 全空请求体合法（PATCH，所有字段可选） + - userType 非枚举 → 失败 + - language 非枚举 → 失败 + - userCode 越长 → 失败 + - userCode 空字符串 → 失败（@Size 不限定下界，但建议加 @Pattern("\S+") 防空白；本任务不强制） + - employeeId=-1 → 失败 + - employeeId=0 合法（约定的解除关联） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UpdateUserReq + UserDetailVo REQ-USR-003` + +### Task 3: SysUserMapper.existsByUserCodeExcludingId + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperTest.java` + +**API shape:** +- `SysUserMapper#existsByUserCodeExcludingId(String userCode, Integer excludedUserId) : boolean` +- SQL: `SELECT EXISTS(SELECT 1 FROM sys_user WHERE sUserCode = #{userCode} AND iIncrement <> #{excludedUserId})` + +- [ ] **Step 1: 写失败测试** + - `existsByUserCodeExcludingId_otherUserHasCode_returnsTrue` (alice U001, query U001 excluding admin → true) + - `existsByUserCodeExcludingId_selfHasCode_returnsFalse` (alice U001, query U001 excluding alice → false) + - `existsByUserCodeExcludingId_unknownCode_returnsFalse` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 排除自身的 userCode 唯一查询 REQ-USR-003` + +### Task 4: SysUserPermissionCategoryMapper 增删辅助方法 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapper.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserPermissionCategoryMapperTest.java` + +**API shape:** +- `SysUserPermissionCategoryMapper#selectPermissionCategoryIdsByUserId(Integer userId) : List` + - SQL: `SELECT iPermissionCategoryId FROM sys_user_permission_category WHERE iUserId = #{userId}` +- `SysUserPermissionCategoryMapper#deleteByUserAndCategoryIds(@Param("userId") Integer userId, @Param("ids") List categoryIds) : int` + - SQL: `DELETE FROM sys_user_permission_category WHERE iUserId = #{userId} AND iPermissionCategoryId IN (...)` （@Select script） + +- [ ] **Step 1: 写失败测试** + - 准备：admin user + 授权 {PUR, SAL} + - `selectPermissionCategoryIdsByUserId_returnsAllCurrent` + - `deleteByUserAndCategoryIds_onlyDeletesGivenSubset`（删 {PUR} 后剩 {SAL}） + - `deleteByUserAndCategoryIds_nonMatchingIds_noop_returns0` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): SysUserPermissionCategoryMapper 查/删辅助方法 REQ-USR-003` + +### Task 5: UserDetailService 接口 + 实现 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserDetailService.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserDetailServiceImpl.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserDetailServiceImplTest.java` + +**API shape:** +- `UserDetailService#getById(Integer userId) : UserDetailVo` +- 找不到用户 → `BizException(ErrorCode.USER_NOT_FOUND, "用户不存在")` +- 包含作废用户（用于恢复启用场景的回显） +- 装配逻辑：select sys_user → 若 iEmployeeId 非空 select sys_employee.sEmployeeName → selectPermissionCategoryIdsByUserId + +- [ ] **Step 1: 写失败测试** + - `getById_existingActiveUser_returnsFullVo`（含 employeeName + permissionCategoryIds） + - `getById_userWithoutEmployee_employeeNameIsNull` + - `getById_userWithoutPermissions_emptyList` + - `getById_deletedUser_stillReturned`（iIsDeleted=1 的用户也能查到，VO.isDeleted=true） + - `getById_unknownId_throws40401` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserDetailService 用户详情查询 REQ-USR-003` + +### Task 6: UserUpdateService 接口 + 校验骨架 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserUpdateService.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java` + +**API shape:** +- `UserUpdateService#update(Integer userId, UpdateUserReq req, Integer operatorUserId, String operatorUsername) : UserDetailVo` +- `@Transactional` +- 注入：SysUserMapper / SysEmployeeMapper / SysPermissionCategoryMapper / SysUserPermissionCategoryMapper / UserDetailService（复用详情装配返回最终 VO） + +本 Task 范围：校验路径（不写入），全部抛 BizException 路径覆盖： +1. `userId` 不存在 → 40401 +2. `req.isDeleted == true && userId == operatorUserId` → 40302 +3. `req.userCode` 非 null 且 `existsByUserCodeExcludingId(userCode, userId)` → 40902 +4. `req.employeeId` 是正整数（非 0）且不存在或软删 → 40004 +5. `req.permissionCategoryIds` 非 null 且非空且含不存在 ID → 40004 + +- [ ] **Step 1: 写失败测试** 5 个测试覆盖以上路径 +- [ ] **Step 2: 实现最小代码**（更新方法体仅 throw，不写 DB） +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 校验路径骨架 REQ-USR-003` + +### Task 7: UserUpdateService 部分字段写入 + employee 三态 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java` + +**API behavior:** +- 校验全过后用 `UpdateWrapper().eq("iIncrement", userId)` 链式 set： + - `if (req.userCode != null)` → set sUserCode + - `if (req.userType != null)` → set sUserType + - `if (req.language != null)` → set sLanguage + - `if (req.canEditDocument != null)` → set iCanEditDocument (true → 1, false → 0) + - `if (req.employeeId != null)`：req.employeeId == 0 → set iEmployeeId NULL；正整数 → set iEmployeeId 值 + - `if (req.isDeleted != null)` → set iIsDeleted (true → 1, false → 0) + - 总是 set sUpdatedBy=operatorUsername、tUpdatedDate=NOW() +- 不处理 permissionCategoryIds（推到 Task 8） + +- [ ] **Step 1: 写失败测试** + - `update_userCode_only_persisted_otherFieldsUnchanged` + - `update_userType_language_canEditDocument` + - `update_employeeId_positiveInteger_setsToValue` + - `update_employeeId_zero_setsToNull` + - `update_employeeId_unchanged_preservesOriginalValue`（缺省字段不变） + - `update_isDeleted_true_marksUserDeleted` + - `update_isDeleted_false_revivesUser` + - `update_emptyRequest_onlyUpdatesAuditFields`（sUpdatedBy + tUpdatedDate） +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 部分字段写入 + employeeId 三态 REQ-USR-003` + +### Task 8: UserUpdateService permissionCategoryIds 增量差集 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java` +- Modify: `backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java` + +**API behavior:** +- 仅当 `req.permissionCategoryIds != null` 时执行： + - `current = selectPermissionCategoryIdsByUserId(userId)`（Set 化以便比较） + - `target = new HashSet<>(req.permissionCategoryIds)`（dedup） + - `toRemove = current \ target` → `deleteByUserAndCategoryIds(userId, toRemove)`（若 toRemove 非空） + - `toAdd = target \ current` → 循环 insert SysUserPermissionCategory（sGrantedBy=operator） +- 返回 `userDetailService.getById(userId)` 作为响应（聚合最新状态） + +- [ ] **Step 1: 写失败测试** + - `update_permissionCategories_emptyList_clearsAll`（初始 {PUR,SAL} → 请求 [] → 最终 ∅） + - `update_permissionCategories_subsetDelta_addsAndRemoves`（初始 {PUR,SAL} → 请求 [SAL, 新分类 X] → 最终 {SAL, X}）；断言 SAL 行 iIncrement 不变（差集而非全量替换） + - `update_permissionCategories_omitted_preservesExisting`（请求中无 permissionCategoryIds → 不动） + - `update_permissionCategories_duplicateInRequest_deduped`（请求 [PUR, PUR, SAL] → 最终 {PUR, SAL}） + - `update_returnsUserDetailVoReflectingFinalState` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserUpdateService 权限分类增量增删差集 REQ-USR-003` + +### Task 9: UserController GET + PUT + 端到端测试 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（追加 GET + PUT 方法） +- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerUpdateTest.java` + +**API shape:** +- `@GetMapping("/{userId}") @RequireSuperAdmin getById(@PathVariable Integer userId) : Result` +- `@PutMapping("/{userId}") @RequireSuperAdmin update(@PathVariable Integer userId, @RequestBody @Valid UpdateUserReq req) : Result` +- PUT 调用 `userUpdateService.update(userId, req, LoginContext.current().userId(), LoginContext.current().username())` + +端到端测试（覆盖 spec § 验收 1-23）： + +**GET（5 个）**： +- `get_existingUser_returns200_andFullVo` +- `get_unknownUser_returns404_40401` +- `get_normalUser_returns403_40301` +- `get_noAuthHeader_returns401_40101` +- `get_deletedUser_stillReturns200` + +**PUT（16 个）**： +- `put_updateUserCodeAndType_returns200` +- `put_updateEmployeeId_toAnotherEmployee` +- `put_updateEmployeeId_zero_clearsRelation` +- `put_updateEmployeeId_unknown_returns400_40004` +- `put_isDeletedTrue_marksAndOriginalTokenRejectedNextCall`（修改后用旧 token 调 GET 应得 40101） +- `put_permissionCategories_subsetDelta`（断言差集行为） +- `put_permissionCategories_emptyArray_clearsAll` +- `put_permissionCategories_unknownId_returns400_40004_andRollsBack`（断言事务回滚——sys_user 也未被改） +- `put_duplicateUserCode_returns409_40902` +- `put_userCodeUnchangedSameAsSelf_returns200` +- `put_selfDeactivate_returns403_40302` +- `put_unknownProperty_username_returns400_40001` +- `put_unknownProperty_password_returns400_40001` +- `put_unknownUserId_returns404_40401` +- `put_normalUser_returns403_40301` +- `put_emptyBody_only_updates_audit_fields` + +- [ ] **Step 1: 写失败测试** （21 个测试） +- [ ] **Step 2: 实现最小代码**（在现有 UserController 上追加方法） +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): GET + PUT /api/v1/users/{userId} controller + 端到端测试 REQ-USR-003` + +--- + +## 提交计划 + +| Task | Commit message | +|---|---| +| 1 | `chore(usr): docs/05 补 GET 详情 + ErrorCode 新增 40302/40401 REQ-USR-003` | +| 2 | `feat(usr): UpdateUserReq + UserDetailVo REQ-USR-003` | +| 3 | `feat(usr): SysUserMapper 排除自身的 userCode 唯一查询 REQ-USR-003` | +| 4 | `feat(usr): SysUserPermissionCategoryMapper 查/删辅助方法 REQ-USR-003` | +| 5 | `feat(usr): UserDetailService 用户详情查询 REQ-USR-003` | +| 6 | `feat(usr): UserUpdateService 校验路径骨架 REQ-USR-003` | +| 7 | `feat(usr): UserUpdateService 部分字段写入 + employeeId 三态 REQ-USR-003` | +| 8 | `feat(usr): UserUpdateService 权限分类增量增删差集 REQ-USR-003` | +| 9 | `feat(usr): GET + PUT /api/v1/users/{userId} controller + 端到端测试 REQ-USR-003` | diff --git a/docs/superpowers/plans/2026-05-15-REQ-USR-004.md b/docs/superpowers/plans/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..5dc3adb --- /dev/null +++ b/docs/superpowers/plans/2026-05-15-REQ-USR-004.md @@ -0,0 +1,325 @@ +--- +req_id: REQ-USR-004 +date: 2026-05-15 +spec_ref: docs/superpowers/specs/2026-05-15-REQ-USR-004.md +--- + +# REQ-USR-004 查询用户 Implementation Plan + +> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 实现 `GET /api/v1/users` 分页 + 多字段筛选 + 排序的用户列表查询；服务端做白名单 + 类型转换 + 越界矫正；输出 PageResult（JOIN sys_employee/sys_department 取员工名 / 部门名）。 + +**Architecture:** +- 复用 REQ-USR-002 / 003 已建的鉴权 + 角色守卫 + 异常处理。 +- 新增 `UserListService` 单一职责；动态 SQL 通过 MyBatis XML（@Select script 也可，本任务用 XML 便于维护）实现 JOIN + WHERE 动态拼接。 +- 白名单映射：queryField / sortField / matchMode / sortOrder 全部在 service 层校验后才进 SQL。 +- 越界矫正在 service 层：先查目标 page，若 records 为空但 total>0 → 重算 lastPage 再查。 +- PageResult 引入为通用类（放 common.response 包，供后续 REQ 复用）。 + +**Tech Stack:** 复用 Spring Boot 3 + MyBatis-Plus（本 REQ 用 mapper XML 写动态查询）+ Jakarta Validation。 + +--- + +## Schema 改动 + +无。 + +--- + +## 文件变更清单 + +**新增（通用）**： +- `backend/src/main/java/com/xly/erp/common/response/PageResult.java` + +**新增（业务）**： +- `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java` +- `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java` +- `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java` +- `backend/src/main/resources/mapper/usr/SysUserMapper.xml` + +**修改**： +- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`（新增 INVALID_ENUM_PARAM=40003） +- `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（新增 selectByQuery + countByQuery） +- `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（新增 GET / list 方法） + +**测试**： +- `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java` +- `backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java` +- `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java` + +--- + +## 约束常量 + +**ErrorCode 新增**： + +| 常量 | 值 | HTTP | +|---|---|---| +| `INVALID_ENUM_PARAM` | `40003` | 400 | + +> ErrorCode.toHttpStatus(40003) → 400/100=400，已在现有映射，新增常量即可。 + +**白名单常量**（全部定义在 `UserListServiceImpl` 的 `static final Map`）： + +``` +SORT_FIELDS = {"tCreateDate", "tLastLoginDate", "sUsername", "sUserCode"} + +QUERY_FIELD_TO_SQL = { + "username": "u.sUsername", + "employeeName": "e.sEmployeeName", + "userCode": "u.sUserCode", + "departmentName": "d.sDepartmentName", + "userType": "u.sUserType", + "isDeleted": "u.iIsDeleted", + "lastLoginDate": "u.tLastLoginDate", + "createdBy": "u.sCreatedBy" +} + +MATCH_MODES = {"contains", "notContains", "equals"} +SORT_ORDERS = {"asc", "desc"} + +USER_TYPES = {"NORMAL", "SUPER_ADMIN"} + +DEFAULT_PAGE = 1 +DEFAULT_SIZE = 20 +MAX_SIZE = 100 +DEFAULT_SORT_FIELD = "tCreateDate" +DEFAULT_SORT_ORDER = "desc" +DEFAULT_MATCH_MODE = "contains" +``` + +**API 形状**： + +``` +GET /api/v1/users?page=1&size=20&sortField=tCreateDate&sortOrder=desc + &queryField=username&matchMode=contains&queryValue=ali + &userType=NORMAL&isDeleted=false +@RequireSuperAdmin +→ Result> + +PageResult { + List records; + long total; + int page; + int size; +} + +UserListItemVo { + Integer userId, String username, String employeeName, String userCode, + String departmentName, String userType, String language, + Boolean isDeleted, LocalDateTime lastLoginDate, + String createdBy, LocalDateTime createdDate +} + +UserQueryReq { + Integer page, // @Min(1) + Integer size, // @Min(1) @Max(100) + String sortField, + String sortOrder, + String queryField, + String matchMode, + String queryValue, + String userType, + Boolean isDeleted +} +``` + +--- + +## 任务步骤 + +### Task 1: ErrorCode 新增 40003 + PageResult 通用类 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` +- Create: `backend/src/main/java/com/xly/erp/common/response/PageResult.java` +- Modify: `backend/src/test/java/com/xly/erp/common/response/ErrorCodeTest.java` + +**API shape:** +- `ErrorCode.INVALID_ENUM_PARAM = 40003` +- `ErrorCode.toHttpStatus(40003) == 400` +- `PageResult { records: List; total: long; page: int; size: int }` + @Builder + +- [ ] **Step 1: 写失败测试** `ErrorCodeTest#httpMappings_coverNewCodes_v004` 验 40003→400 +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): ErrorCode 新增 40003 + PageResult 通用类 REQ-USR-004` + +### Task 2: UserQueryReq DTO + UserListItemVo + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java` + +**API shape:** +- `UserQueryReq` 所有字段可选；jakarta 注解只用 `@Min(1)`（page）、`@Min(1) @Max(100)`（size）；其他枚举值在 service 层做白名单校验（不用 @Pattern，因为 @Pattern 失败会落到 40001，本 REQ 要 40003） +- `UserListItemVo` 字段同 spec § 输出 + +- [ ] **Step 1: 写失败测试** 5 个用例： + - 全空合法（PATCH 风格） + - page=0 → @Min(1) 失败 + - size=101 → @Max(100) 失败 + - size=0 → @Min(1) 失败 + - 全合法字段 → pass +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserQueryReq + UserListItemVo + PageResult REQ-USR-004` + +### Task 3: SysUserMapper.selectByQuery + countByQuery (XML) + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java`（声明方法） +- Create: `backend/src/main/resources/mapper/usr/SysUserMapper.xml`（动态 SQL） +- Modify: `backend/src/main/resources/application.yml`（mybatis-plus.mapper-locations: classpath*:/mapper/**/*.xml） +- Modify: `backend/src/main/resources/application-test.yml`（同上） +- Create: `backend/src/test/java/com/xly/erp/module/usr/mapper/SysUserMapperQueryTest.java` + +**API shape:** +- `SysUserMapper#selectByQuery(@Param("p") QueryParams p) : List` +- `SysUserMapper#countByQuery(@Param("p") QueryParams p) : long` +- `QueryParams` — 内部 record / DTO，包含已通过白名单校验的字段：`sqlSortField`（列名）, `sqlSortOrder`（asc/desc）, `sqlQueryColumn`（已映射列名 OR null）, `matchMode`, `queryValue`, `userType`, `isDeleted`（Integer 0/1 或 null）, `offset`, `limit` + +> service 层把 spec 入参规范化为 `QueryParams`，mapper XML 用 `${}` 拼接 `sqlSortField` / `sqlSortOrder` / `sqlQueryColumn`（白名单值），用 `#{}` 绑定 queryValue / userType / isDeleted / offset / limit。 + +XML 关键片段（仅作为 plan 锁定的契约，TDD 实现可改细节）： + +```xml + + FROM sys_user u + LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId + LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId + + + + + + + + AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%') + + + AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%') + OR ${p.sqlQueryColumn} IS NULL) + + + AND ${p.sqlQueryColumn} = #{p.queryValue} + + + + AND u.sUserType = #{p.userType} + AND u.iIsDeleted = #{p.isDeleted} + + + + + + +``` + +> MyBatis-Plus 默认 `mapper-locations: classpath*:/mapper/**/*.xml`，但需在 application.yml 显式声明以确保 XML 被加载。当前 application.yml 仅声明了 mybatis-plus 配置项，未声明 mapper-locations；本任务添加。 + +- [ ] **Step 1: 写失败测试** `SysUserMapperQueryTest`： + - `count_noFilters_returnsAllRows` + - `select_withSortByUsername_ascending` + - `select_withQueryFieldUsername_contains` + - `select_joinsEmployeeAndDepartment_returnsBothNames` +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): SysUserMapper 动态查询 XML + JOIN 员工/部门 REQ-USR-004` + +### Task 4: UserListService 白名单 + 越界矫正 + +**Files:** +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/UserListService.java` +- Create: `backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java` +- Create: `backend/src/test/java/com/xly/erp/module/usr/service/UserListServiceImplTest.java` + +**API shape:** +- `UserListService#list(UserQueryReq req) : PageResult` +- 内部规范化流程： + 1. 应用默认值（page=1, size=20, sortField=tCreateDate, sortOrder=desc, matchMode=contains） + 2. 白名单校验：sortField / sortOrder / queryField / matchMode / userType — 不在白名单抛 `BizException(40003)` 或 `BizException(40001)` 按入参类型决定 + 3. queryField→sqlQueryColumn 映射；queryValue 转换（对 isDeleted 列：'true'→1, 'false'→0；其他不在 {true,false,0,1} 抛 40001） + 4. 越界矫正：先查 `selectByQuery(目标 page)`；若 records 空 && total>0 → 重算 lastPage 再查；响应 page 反映实际页 + +> userType 入参既可作 explicit query param 也可作 queryField=userType+queryValue。两条路径都要走白名单校验。 + +- [ ] **Step 1: 写失败测试** 12 个用例覆盖 spec 验收 5-21 +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): UserListService 白名单校验 + 动态查询 + 越界矫正 REQ-USR-004` + +### Task 5: UserController GET / + 端到端测试 + +**Files:** +- Modify: `backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java`（追加 GET / 方法） +- Create: `backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerListTest.java` + +**API shape:** +- `@GetMapping @RequireSuperAdmin list(@Valid UserQueryReq req) : Result>` +- 用 `@ModelAttribute` 或省略让 Spring 默认从 query 绑定 DTO + +端到端测试（覆盖 spec § 验收 1-26）： + +GET 路径（admin token）： +- `list_default_returnsAllUsersSortedByCreateDateDesc` +- `list_pagination_secondPage` +- `list_sizeOver100_returns400_40001` +- `list_pageZero_returns400_40001` +- `list_sortByUsernameAsc` +- `list_sortFieldInvalid_returns400_40003` +- `list_sortOrderInvalid_returns400_40001` +- `list_queryByUsernameContains` +- `list_queryByUsernameEquals_returnsExactOne` +- `list_queryByUsernameNotContains` +- `list_queryByEmployeeName_joinsCorrectly` +- `list_queryByDepartmentName_multiLevelJoin` +- `list_queryByUserType_equals` +- `list_queryByIsDeletedTrue_filtersDeleted` +- `list_queryFieldInvalid_returns400_40003` +- `list_matchModeInvalid_returns400_40003` +- `list_queryFieldWithoutValue_skipsCondition` +- `list_explicitUserTypeFilter` +- `list_explicitUserTypeInvalid_returns400_40001` +- `list_explicitIsDeletedFalse_filtersActiveOnly` +- `list_composedFilters_andSemantics`（queryField+queryValue + userType + isDeleted） +- `list_pageBeyondTotal_returnsLastPage` +- `list_normalUserToken_returns403_40301` +- `list_noAuthHeader_returns401_40101` +- `list_responseDoesNotContainPasswordField` +- `list_emptyTable_returnsZeroTotal`（drop + recreate 用户为空时） + +- [ ] **Step 1: 写失败测试** +- [ ] **Step 2: 实现最小代码** +- [ ] **Step 3: 子会话验证 PASS** +- [ ] **Step 4: Commit** `feat(usr): GET /api/v1/users controller + 端到端测试 REQ-USR-004` + +--- + +## 提交计划 + +| Task | Commit message | +|---|---| +| 1 | `feat(usr): ErrorCode 新增 40003 + PageResult 通用类 REQ-USR-004` | +| 2 | `feat(usr): UserQueryReq + UserListItemVo + PageResult REQ-USR-004` | +| 3 | `feat(usr): SysUserMapper 动态查询 XML + JOIN 员工/部门 REQ-USR-004` | +| 4 | `feat(usr): UserListService 白名单校验 + 动态查询 + 越界矫正 REQ-USR-004` | +| 5 | `feat(usr): GET /api/v1/users controller + 端到端测试 REQ-USR-004` | diff --git a/docs/superpowers/reviews/2026-05-15-REQ-USR-001.md b/docs/superpowers/reviews/2026-05-15-REQ-USR-001.md new file mode 100644 index 0000000..a91285a --- /dev/null +++ b/docs/superpowers/reviews/2026-05-15-REQ-USR-001.md @@ -0,0 +1,40 @@ +--- +req_id: REQ-USR-001 +date: 2026-05-15 +round: 2 +reviewer: superpower-code-reviewer +--- + +# Review: REQ-USR-001 — round 2 + +## 结论 +approve + +## Must-fix +（无） + +## Nice-to-have + +- backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java:28 — incrementFailedLoginCountAtomic 依赖 MySQL `SET` 子句左到右求值语义；建议加链接 dev.mysql.com/doc/refman/8.0/en/update.html 提醒切换数据库方言时复查 +- backend/src/main/java/com/xly/erp/module/usr/service/impl/LoginServiceImpl.java:66 — lockUntil 在 service 层 ISO 字符串化；建议改为直接放 LocalDateTime 让 Jackson 全局规则统一处理 +- backend/src/main/java/com/xly/erp/common/exception/BizException.java:25 — (int, String, Throwable) 构造的 data=null 是合理默认；未来若有"包装异常 + data"诉求再加 4 参构造 +- backend/src/test/java/com/xly/erp/module/usr/service/LoginServiceImplTest.java:171 — 并发测试用 2×2 低于阈值；可补 3×2 高于阈值场景断言 lock 触发 + count 准确 + +## 反例 / 测试覆盖缺口 + +Round 1 标记『推迟』的 4 项（docs/04 vs docs/05 跨文档不一致、HttpMessageNotReadableException 兜底、ErrorCode.toHttpStatus future-proof、application.yml flyway 路径）本轮未触及，符合 round 1 review 约定，不视为 gap。Reviewer 沙箱因无 MySQL 连接产生 28 个测试 error，已通过 surefire 报告确认为环境问题；主会话 34 测试全过。 + +## 本轮变更归档 + +Round 1 修复全部正确落地： + +| # | 项目 | 状态 | +|---|------|-----| +| H1 | 42301 data.lockUntil | ✓ BizException 扩 data 链路完整 | +| H2 | 失败计数原子 UPDATE | ✓ 单 SQL，去 noRollbackFor，并发回归覆盖 | +| H3 | SELECT * → 显式列 | ✓ 两个 mapper 都改 | +| M5 | JWT 短密钥静默补零 | ✓ < 32 字节 PostConstruct 硬抛 | +| M6 | loginSuccess 双路径 | ✓ 去 entity，走 markLoginSuccess SQL | +| NTH | exp-iat==7200 / lockUntil / 并发原子累加 测试 | ✓ 全部新增 | + +未引入新回归。Approve。 diff --git a/docs/superpowers/reviews/2026-05-15-REQ-USR-002.md b/docs/superpowers/reviews/2026-05-15-REQ-USR-002.md new file mode 100644 index 0000000..19531d2 --- /dev/null +++ b/docs/superpowers/reviews/2026-05-15-REQ-USR-002.md @@ -0,0 +1,41 @@ +--- +req_id: REQ-USR-002 +date: 2026-05-15 +round: 1 +reviewer: superpower-code-reviewer +--- + +# Review: REQ-USR-002 — round 1 + +## 结论 +approve + +## Must-fix +（无） + +## Nice-to-have + +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:82 — DataIntegrityViolationException 转 40901/40902 用 message 文本匹配，与驱动版本/locale 强耦合；建议改判 SQLState='23000' + 错误号 1062，并补 @SpyBean Mockito 回归测试（spec § 15 唯一索引并发兜底测试缺口） +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:93 — 权限分类批量插入用 for + 单条 insert（N 次 IO）；建议改 saveBatch 或在注释里写明 'N < 20 不批量' +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:57 — countActiveByIds 用 COUNT(*) + size 比较，重复 ID（如 [1,1,2]）会误判 40004；建议先 dedup 或改用 COUNT(DISTINCT iIncrement) +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserCreateServiceImpl.java:52 — employee/permissionCategory 校验失败抛 COMPANY_NOT_FOUND 但 message 含义错位；后续可拆 RESOURCE_NOT_FOUND 段位或重命名 COMPANY_NOT_FOUND → REFERENCE_NOT_FOUND +- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:48 — 每请求 1 次 selectByUsername DB 查询；后续可加 Caffeine 短期缓存（容量评估时再做） +- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:60 — claims.get('companyCode') 未做 null 校验；建议在 LoginUser 处文档化或加 log.warn +- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:66 — set LoginContext 早于角色守卫；建议加注释说明该顺序是有意的，afterCompletion 保证清理 +- backend/src/main/java/com/xly/erp/common/security/JwtHandlerInterceptor.java:35 — plan 声明 'handler 非 HandlerMethod → return true'，实际未实现该顶部短路；建议补齐对齐 plan +- backend/src/test/java/com/xly/erp/common/security/JwtHandlerInterceptorTest.java:124 — plan 列出 `loginContext_clearedAfterRequest` 测试用例但未实现；建议补显式清理回归 +- backend/src/main/java/com/xly/erp/module/usr/dto/CreateUserReq.java:24 — userType/language 用 @Pattern 枚举校验失类型安全；可改为 service 层 toEnum 模式 +- backend/src/main/resources/application.yml:8 — fail-on-unknown-properties=true 是全局开关；建议在 docs/04 § 1.3 留痕说明所有 DTO 必须完整定义 +- backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java:28 — LoginContext.current() 未 null 校验；建议加防御性 Optional.ofNullable +- backend/src/main/java/com/xly/erp/module/usr/entity/SysPermissionCategory.java:17 — entity 含未写入的多租户字段（sId/sBrandsId 等），与 SysUser 风格一致，可接受 + +## 反例 / 测试覆盖缺口 + +1. spec § 15「唯一索引兜底（DataIntegrityViolationException 路径）」未实测——UserCreateServiceImplTest 缺乏对 catch 分支的回归 +2. plan § Step 1 列出 `loginContext_clearedAfterRequest` 但实际未实现，ThreadLocal 清理路径无显式回归 +3. docs/04 § 1.3 段位（10xxx/20xxx/...）与代码 / docs/05 实际使用的 HTTP-aligned 段位（40001/40101/40301/...）冲突——round 1 REQ-USR-001 已记录，本 REQ 沿用未拉齐；建议单独 PR 修订 docs/04 § 1.3 +4. `permissionCategoryIds` 含重复 ID 行为未定义（countActiveByIds 用 COUNT(*) + size 会 false-negative），无对应测试 + +## 总结 + +REQ-USR-002 整体实现质量较高：鉴权 / 角色守卫拦截器流程清晰、事务边界正确、唯一性预检 + DB 兜底双层防御、初始密码 BCrypt 哈希、Jackson 严格反序列化拒绝 password 字段、85 测试覆盖 spec 验收 1-14。文档同步（docs/05 删除 password+40002）已完成，错误码新增 40301/40901/40902 + HTTP 映射准确。功能、安全、文档与 plan/spec 三方一致，无高/中级阻塞问题。Approve。 diff --git a/docs/superpowers/reviews/2026-05-15-REQ-USR-003.md b/docs/superpowers/reviews/2026-05-15-REQ-USR-003.md new file mode 100644 index 0000000..3e29614 --- /dev/null +++ b/docs/superpowers/reviews/2026-05-15-REQ-USR-003.md @@ -0,0 +1,31 @@ +--- +req_id: REQ-USR-003 +date: 2026-05-15 +round: 1 +reviewer: superpower-code-reviewer +--- + +# Review: REQ-USR-003 — round 1 + +## 结论 +approve + +## Must-fix +（无） + +## Nice-to-have + +- docs/05-API接口契约.md PUT § REQ-USR-003 错误码列表缺 40101（GET 段已列）— 本轮归档前已修 +- docs/superpowers/specs/2026-05-15-REQ-USR-003.md § 输入表行写 "显式 null 表示解除关联"，与 § PATCH 语义实现细节的 "null = 不变；employeeId=0 = 解除关联" 约定矛盾；代码遵循后者，建议日后回填修订前者 +- backend/src/main/java/com/xly/erp/module/usr/mapper/SysUserMapper.java:52 — existsByUserCodeExcludingId 未过滤 iIsDeleted；如希望软删用户不参与唯一性，可补 `AND iIsDeleted=0`，但当前 spec 未要求 +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java:108 — permissionCategoryIds 差集流程在 @Transactional 内无行锁；并发 PUT 同一用户可能出现交叉写入。建议未来引入 sys_user.iVersion 做乐观锁 +- backend/src/test/java/com/xly/erp/module/usr/service/UserUpdateServiceImplTest.java:127 — update_employeeId_positiveInteger_setsToValue 注释 '避开自我停用守卫' 误导（本测试不会触发守卫）；建议改用合法对手用户或删除该注释 +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserUpdateServiceImpl.java:78 — 复用 COMPANY_NOT_FOUND（40004）抛"权限分类不存在"，常量名与 message 字面冲突；建议未来将 40004 重命名为更通用的 RELATED_ENTITY_NOT_FOUND 或拆分专用 code（跨模块技术债） + +## 反例 / 测试覆盖缺口 + +无功能或安全级 gap。spec 验收 1-22 全部映射到测试；验收 23（作废用户登录 40103）spec 明确声明属 REQ-USR-001 既有路径，符合约定。事务边界（@Transactional + BizException extends RuntimeException + Spring 默认回滚）正确；自我停用守卫精确；userCode 唯一性"自身同值跳过查询"优化有效；employee 三态（null/0/正整数）与 permissionCategoryIds 三态（缺省/空数组/非空）语义清晰且测试覆盖；作废即时生效由 JwtHandlerInterceptor 每请求重查保证；权限分类差集策略保留项 iIncrement 不变已用单测显式断言。N+1 仅出现在 UserDetailService（user + employee + pcIds 三查），单详情场景可接受。 + +## 总结 + +REQ-USR-003 实现严格对齐 spec / plan：GET + PUT 共用 UserDetailVo、PATCH 三态、permissionCategoryIds 增删差集、自我停用守卫、userCode 唯一性排除自身、作废即时生效、事务回滚全部正确实现，147 测试覆盖 spec 验收 1-22。仅有若干文档不一致与可读性建议，本轮归档前已补 docs/05 PUT 错误码 40101。无功能/安全/正确性阻塞。Approve。 diff --git a/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md b/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..f00d40d --- /dev/null +++ b/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md @@ -0,0 +1,39 @@ +--- +req_id: REQ-USR-004 +date: 2026-05-15 +round: 2 +reviewer: superpower-code-reviewer +--- + +# Review: REQ-USR-004 — round 2 + +## 结论 +approve + +## Must-fix +（无） + +## Nice-to-have + +- backend/src/main/java/com/xly/erp/module/usr/service/impl/UserListServiceImpl.java:148 — `normalizeQueryValue` 用全限定 `java.time.LocalDate.parse` 而非顶部 import，纯风格瑕疵 +- matchMode 白名单校验在 forced-equals 覆盖之前；调用方传 matchMode=contains + queryField=isDeleted 时白名单接受 contains 再静默覆盖为 equals — 行为正确但稍不透明，可加 logger.debug 留痕 +- UserListServiceImplTest 末尾 `@Autowired JdbcTemplate jdbc` 字段定义在测试方法之后，风格不一致；建议挪到类顶部 +- round 1 已标记『推迟』的 4 项保持不变（queryField=userType 不走 USER_TYPES 白名单；UserQueryParams public 可变字段；list_emptyTable_returnsZeroTotal 命名；mapper ORDER BY 硬编码 u.* 前缀） + +## 反例 / 测试覆盖缺口 + +Round 2 测试覆盖完整：spec § 业务规则 3 的 isDeleted/lastLoginDate matchMode 强制 equals + 类型归一化由 3 个新测试明确断言；spec § 验收 1-26 由 198+3 测试映射；spec § 验收 26 空表场景由 list_emptyTable_returnsZeroTotal（虽命名不准）覆盖。Reviewer 子会话无本地 MySQL，未独立复跑 mvn test；信任 commit 8bf84c9 + 主会话 feature-verify 报告的 201/0 结果。 + +## 本轮变更归档 + +Round 1 全部修复落地： + +| # | 项目 | 状态 | +|---|------|-----| +| M1 | EQUALS_ONLY_FIELDS 强制 matchMode=equals | ✓ 仅在 queryField+queryValue 都非空时覆盖，scoped 严格，不影响其他路径 | +| M2 | lastLoginDate 类型归一化 | ✓ 支持 LocalDateTime / LocalDate，非法值抛 40001 | +| M3 | queryValue 用 isBlank 判空 | ✓ | +| M4 | docs/05 错误码补 sortField + 40101 | ✓ | +| Test | 新增 3 个回归测试 | ✓ | + +未引入新回归。verdict=approve。 diff --git a/docs/superpowers/specs/2026-05-15-REQ-USR-001.md b/docs/superpowers/specs/2026-05-15-REQ-USR-001.md new file mode 100644 index 0000000..7b595b6 --- /dev/null +++ b/docs/superpowers/specs/2026-05-15-REQ-USR-001.md @@ -0,0 +1,127 @@ +--- +req_id: REQ-USR-001 +date: 2026-05-15 +module: module_usr +--- + +# Spec: REQ-USR-001 — 用户登录 + +## 目标 + +提供用户名 + 密码 + 公司编码的登录接口，校验通过后签发 JWT access token（HS256，TTL 2 小时）并返回当前用户基础信息，用于后续接口的 Bearer 鉴权。本 REQ 仅签发 access token，refresh token 推迟到后续 REQ（与 docs/05 LoginVo 一致；docs/04 § 1.6 的 refresh 描述视为未来增量，本 REQ 范围内不实现）。 + +## 输入 / 触发 + +HTTP 入口 `POST /api/v1/auth/login`，公开接口（无需 Bearer）。 + +**请求体 LoginReq**（JSON）： + +| 字段 | 类型 | 必填 | 校验规则（登录场景，宽松，不复用创建场景的强度规则） | +|---|---|---|---| +| `username` | string | 是 | 非空；长度 1-50（容纳潜在历史账号；越界返 `40001`） | +| `password` | string | 是 | 非空；长度 1-128（密码强度只在创建/重置流程校验，登录只校验匹配；越界返 `40001`） | +| `companyCode` | string | 是 | 非空；最大长度 50；命中 `sys_company.sCompanyCode AND iIsDeleted=0`，否则返 `40004` | + +> **登录与创建的校验差异**：REQ-USR-002 创建用户时密码必须 8-20 位含大小写字母和数字（强度规则）；本 REQ 登录只校验"非空且未超长"，避免历史账号或未来规则放宽时无法登录。 + +## 输出 / 结果 + +**成功 200**：`Result`，其中 `LoginVo`： + +```json +{ + "accessToken": "", + "tokenType": "Bearer", + "expiresInSec": 7200, + "userInfo": { + "userId": 123, + "username": "alice", + "userType": "NORMAL", + "language": "zh-CN", + "employeeName": "张三", + "companyCode": "HQ" + } +} +``` + +- `employeeName` 通过 `sys_user.iEmployeeId` JOIN `sys_employee.sEmployeeName` 取得；未绑定职员时字段省略。 +- 副作用：写库 `sys_user.iFailedLoginCount = 0`、`sys_user.tLockUntil = NULL`、`sys_user.tLastLoginDate = NOW()`。 + +**失败**：见错误码段，全部走全局异常处理器映射为 `Result.fail(code, message)`。错误码段位与 docs/05 一致： + +| HTTP | code | 含义 | 触发条件 | +|---|---|---|---| +| 400 | 40001 | 用户名或密码格式错误 | 必填字段缺失 / 类型错 / 长度越界 | +| 400 | 40004 | 公司不存在或已删除 | `companyCode` 在 `sys_company` 查不到（含 `iIsDeleted=1`） | +| 401 | 40101 | 用户名或密码错误 | 用户不存在 OR 密码哈希不匹配（统一文案，不区分两者，防用户名枚举） | +| 401 | 40103 | 账号已被作废，禁止登录 | `sys_user.iIsDeleted = 1` | +| 423 | 42301 | 账号已锁定，请稍后再试 | `sys_user.tLockUntil IS NOT NULL AND tLockUntil > NOW()`；`data.lockUntil` 返回 ISO 8601 剩余截止时刻 | + +## 业务规则 + +1. **账号查找**：以 `sUsername` 全等匹配（大小写敏感，与建表 collation `utf8mb4_unicode_ci` 行为一致，登录时不做规范化）。 +2. **作废态优先**：若用户记录 `iIsDeleted = 1`，直接返 `40103`，不进入密码校验，**不**累加 `iFailedLoginCount`。 +3. **锁定优先**：若用户 `tLockUntil` 不为空且大于当前时间，直接返 `42301`，**不**进入密码校验，**不**累加。锁定到期（`tLockUntil <= NOW()`）视为已解锁，正常进入密码校验。 +4. **密码校验**：使用 Spring Security `BCryptPasswordEncoder.matches(rawPassword, sPasswordHash)`。docs/03 业务注记里"BCrypt / Argon2" 二选一，本 REQ 锁定 BCrypt——`BCryptPasswordEncoder` 是 Spring Security 默认实现，无额外依赖；strength=10。 +5. **失败计数**：密码不匹配时 `sys_user.iFailedLoginCount += 1`。 + - 阈值：累计达到 **5 次**（含第 5 次）时，**同步**写 `sys_user.tLockUntil = NOW() + 30 分钟`；下一次（第 6 次）请求会落到锁定分支返 `42301`。 + - 阈值前的失败仍返 `40101`，**不**主动告诉客户端剩余尝试次数（防探测）。 +6. **登录成功**：原子事务（service 层 `@Transactional`）内： + - `sys_user.iFailedLoginCount = 0` + - `sys_user.tLockUntil = NULL` + - `sys_user.tLastLoginDate = NOW()` + - 然后签发 JWT（事务内构造 claim，事务提交后返响应）。 +7. **JWT claims**： + - `sub` = `sys_user.iIncrement`（数字主键，字符串化） + - `username` = `sys_user.sUsername` + - `userType` = `sys_user.sUserType` + - `companyCode` = 请求传入的 `companyCode`（已校验存在） + - `language` = `sys_user.sLanguage` + - `iat` / `exp` = 标准时间 claims（TTL 7200s） + - `jti` = UUID（为未来 refresh / 黑名单预留，本 REQ 不消费） +8. **JWT 密钥**：从 `.env.local` 的 `JWT_SECRET` 读取；`application.yml` 用 `${JWT_SECRET}` 占位符注入，代码层不允许硬编码。 + +## 边界与约束 + +- **HTTPS 传输**：密码以明文走 HTTPS body，生产部署由 Nginx 终止 TLS（docs/07 § 二）；本 REQ 不在应用层加密 / 解密密码。 +- **统一响应**：全部走 `Result` / `Result.fail`（docs/04 § 1.3）；错误响应禁回显堆栈。 +- **审计日志**：登录成功 / 失败 / 锁定均通过 Logback 写 INFO / WARN 日志（含 traceId 与 username），日志位置遵循 docs/04 / docs/07；本 REQ 不写额外的 DB 审计表。 +- **Redis**：docs/04 § 1.6 提及"签发后写 Redis"，**本 REQ 不实现**——签发后不写 Redis，JWT 自包含可独立验证；登出黑名单功能推迟到后续 REQ。`pom.xml` 不强制要求 redis 依赖（如已加入也不使用）。 +- **并发安全**：失败计数 / 锁定写入位于同一事务；MySQL 默认 RR 隔离 + 行锁可避免并发同账号失败计数竞争。 +- **不实现**：管理员手动解锁、密码重置、refresh token、登出、多端互踢、Redis 黑名单——全部推迟到后续 REQ。 + +## 依赖的 schema 表 / 字段 + +读 + 写 `sys_user`（V1 已建）： +- 读：`iIncrement`, `sUsername`, `sPasswordHash`, `sUserType`, `sLanguage`, `iEmployeeId`, `iIsDeleted`, `iFailedLoginCount`, `tLockUntil` +- 写：`iFailedLoginCount`, `tLockUntil`, `tLastLoginDate` + +只读 `sys_company`（V1 已建）： +- 读：`sCompanyCode`, `iIsDeleted` + +只读 JOIN `sys_employee`（V1 已建）： +- 读：`sEmployeeName` + +**本 REQ 不需要新增 migration**（schema 已就绪）。 + +## 依赖的接口 + +- 本 REQ 提供：`POST /api/v1/auth/login`（docs/05 § module_usr）。 +- 外部依赖（前端会调，但本 REQ 范围不实现）：`GET /api/v1/companies`（公司下拉），由后续运营模块或前端阶段使用 fixture 数据替代。 + +## 验收标准 + +后端集成测试（不依赖前端）： + +1. **正确凭据 + 启用账号 + 存在公司** → 200，返回 `accessToken`（非空 JWT），`userInfo` 字段完整；`sys_user.tLastLoginDate` 更新、`iFailedLoginCount = 0`、`tLockUntil IS NULL`。 +2. **JWT 可验签**：用 `JWT_SECRET` HS256 验签通过；`sub` = `userId` 字符串；`exp - iat == 7200`。 +3. **错误密码 N 次（N<5）** → 401 / 40101；`iFailedLoginCount = N`；`tLockUntil` 仍为 NULL。 +4. **第 5 次错误密码** → 401 / 40101；`iFailedLoginCount = 5`；`tLockUntil` 被写为 NOW() + 30 分钟。 +5. **锁定期间第 6 次（任意密码）** → 423 / 42301；返回 `data.lockUntil` 字段；`iFailedLoginCount` 不再累加。 +6. **锁定到期后** → 锁定字段自然过期，下一次正确密码登录 200 并清零计数。 +7. **作废账号（iIsDeleted=1）正确密码** → 401 / 40103；`iFailedLoginCount` 不变。 +8. **用户名不存在** → 401 / 40101（与密码错误同文案）。 +9. **公司不存在 / 已删除** → 400 / 40004，**不**累加失败计数（先于密码校验完成公司校验）。 +10. **请求体缺字段 / 越长** → 400 / 40001。 +11. **响应不回显堆栈**：故意制造服务端异常时，响应 `message` 为通用文案，无 stack trace。 +12. **日志记录**：每次登录成功 / 失败 / 锁定均有日志行（人工或 grep 抽样验证即可）。 diff --git a/docs/superpowers/specs/2026-05-15-REQ-USR-002.md b/docs/superpowers/specs/2026-05-15-REQ-USR-002.md new file mode 100644 index 0000000..f2c72ce --- /dev/null +++ b/docs/superpowers/specs/2026-05-15-REQ-USR-002.md @@ -0,0 +1,133 @@ +--- +req_id: REQ-USR-002 +date: 2026-05-15 +module: module_usr +--- + +# Spec: REQ-USR-002 — 新增用户 + +## 目标 + +超级管理员通过 `POST /api/v1/users` 新建用户账号。账号立即生效；初始密码由系统统一设为 `666666`（哈希后存入）；可选关联职员；同时按勾选写入权限分类授权关系。 + +## 输入 / 触发 + +HTTP 入口 `POST /api/v1/users`。要求请求头 `Authorization: Bearer `。 + +**请求体 CreateUserReq**（JSON）： + +| 字段 | 类型 | 必填 | 校验规则 | +|---|---|---|---| +| `username` | string | 是 | 非空；3-20 位字母数字下划线（正则 `^[A-Za-z0-9_]{3,20}$`）；系统内唯一（命中 `sys_user.sUsername` 返 40901） | +| `userCode` | string | 是 | 非空；最大 50；系统内唯一（命中 `sys_user.sUserCode` 返 40902） | +| `userType` | string | 是 | 枚举 `NORMAL` / `SUPER_ADMIN` | +| `language` | string | 是 | 枚举 `zh-CN` / `en-US` / `zh-TW` | +| `canEditDocument` | boolean | 是 | true / false | +| `employeeId` | int | 否 | 若不为 null，必须命中 `sys_employee.iIncrement` AND `iIsDeleted=0`，否则返 40004 | +| `permissionCategoryIds` | int[] | 否 | 可为空数组或省略；每个元素必须命中 `sys_permission_category.iIncrement` AND `iIsDeleted=0`，否则返 40004 | + +> **本 REQ 不接受 `password` 字段**：用户提交的任何 password 字段被忽略（或返 40001）。docs/05 应同步删除 `password` 与 `40002` —— 本 REQ 落地时由实现方在 docs/05 一并修订（spec 自审范畴）。 + +## 输出 / 结果 + +**成功 201 Created**：`Result` + +```json +{ "code": 200, "message": "操作成功", "data": { "userId": 42, "username": "alice", "userCode": "U001" }, "timestamp": ... } +``` + +> HTTP 201 体现新资源创建；body 仍走统一 `Result` 包装（docs/04 § 1.3）。 + +副作用（同一事务）： +1. `sys_user` 插入一条新记录： + - `sPasswordHash` = `BCryptPasswordEncoder.encode("666666")` + - `iFailedLoginCount` = 0、`tLockUntil` = NULL、`tLastLoginDate` = NULL + - `iIsDeleted` = 0 + - `sCreatedBy` = 当前登录用户 username（来自 JWT claim） +2. `sys_user_permission_category` 按 `permissionCategoryIds` 批量插入授权记录，`sGrantedBy` = 当前登录用户 username + +**失败**： + +| HTTP | code | 含义 | 触发条件 | +|---|---|---|---| +| 400 | 40001 | 必填字段缺失或格式错误 | jakarta 校验失败（@NotBlank / @Pattern / 枚举不合法）；请求包含 `password` 字段（本 REQ 不允许） | +| 400 | 40004 | 员工或权限分类不存在 | `employeeId` 或 `permissionCategoryIds` 中任一不命中 | +| 401 | 40101 | 未携带或无效 Token | Authorization 缺失 / 解析失败 / 用户已作废 / 用户已锁定 | +| 403 | 40301 | 非超级管理员调用 | JWT claim `userType != SUPER_ADMIN` | +| 409 | 40901 | 用户名已存在 | sUsername 唯一冲突（DB 唯一键 `uk_sys_user_username` 兜底；service 层 select 预检以返友好错误） | +| 409 | 40902 | 用户号已存在 | sUserCode 唯一冲突 | + +## 业务规则 + +1. **鉴权**：手写 `JwtHandlerInterceptor` 实现 `HandlerInterceptor`，注册到 `WebMvcConfigurer`，匹配 `/api/v1/**` 但排除 `/api/v1/auth/login`： + - 读 `Authorization: Bearer ` 头；缺失 → 抛 `BizException(40101, "未携带 token")` + - `JwtUtil.parse(token)` 抛 BizException 时透传（JwtUtil 内部已返 40101） + - 解析 claims → 查 `sys_user.iIncrement = sub`；若不存在 / `iIsDeleted=1` / `tLockUntil > NOW()` → 抛 `BizException(40101, "token 关联用户不可用")` + - 把 username / userType / userId / companyCode 放入 `LoginContext`（ThreadLocal 工具）供后续使用 + - 业务方法结束时（`afterCompletion`）清理 ThreadLocal +2. **角色守卫**：用自定义注解 `@RequireSuperAdmin`（标注在 controller 方法上）+ 同一 interceptor 检查 `handler instanceof HandlerMethod && method.isAnnotationPresent(...)` → 校验 `LoginContext.userType == SUPER_ADMIN`；不匹配 → 抛 `BizException(40301, "权限不足，仅超级管理员可调用")` +3. **唯一性校验**：在 service 写入前用 `selectByUsername` / `selectByUserCode` 查重（友好返 40901 / 40902）；DB 唯一索引兜底（捕获 `DataIntegrityViolationException` 转 40901 或 40902，避免堆栈泄漏） +4. **外键校验**：employeeId / permissionCategoryIds 在写入前一次性 select 校验（SELECT iIncrement FROM ... WHERE iIncrement IN(...) AND iIsDeleted=0），数量不齐 → 40004 +5. **初始密码**：固定字符串 `"666666"`，通过 `BCryptPasswordEncoder.encode` 哈希；常量定义在 `LoginServiceImpl.INITIAL_PASSWORD`（已存在）或新建 `UserCreateServiceImpl.INITIAL_PASSWORD` +6. **事务**：`@Transactional`，sys_user 插入 + sys_user_permission_category 批量插入在同一事务；唯一冲突或 FK 不存在均回滚 +7. **本 REQ 不接受 password 字段**：DTO 不定义 password 属性；若客户端误传，Jackson 默认配置（`FAIL_ON_UNKNOWN_PROPERTIES=false`）会忽略——但为防御性，建议 `application.yml` 设 `spring.jackson.deserialization.fail-on-unknown-properties: true`，确保多余字段返 40001 + +## 边界与约束 + +- **HTTPS / 鉴权 / 统一响应 / 异常**：复用 REQ-USR-001 已建的全部基础设施 +- **HandlerInterceptor 位置**：放在 `backend/src/main/java/com/xly/erp/common/security/`，与 `JwtUtil` 同包 +- **ThreadLocal 工具**：`LoginContext` 单例，提供 `current() / set() / clear()`；测试场景可手工 set 以模拟登录态 +- **@RequireSuperAdmin 注解**：放在 `backend/src/main/java/com/xly/erp/common/security/` +- **不实现**： + - 修改密码 / 重置密码（推迟到后续 REQ） + - 用户软删除接口（推迟到 REQ-USR-003 的"作废"路径） + - 权限分类的新增 / 编辑（运营模块） + - 员工的 CRUD（HR 模块） + - JWT 黑名单 / refresh token / 多端互踢（推迟） +- **docs/05 同步修订**：本 REQ 实现时需同步修订 docs/05 § REQ-USR-002，去掉 `password` 字段与 `40002` 错误码（与 REQ 卡片对齐为"系统生成初始密码"） + +## 依赖的 schema 表 / 字段 + +写 `sys_user`（V1 已建）： +- 写入：`sUsername`, `sUserCode`, `sPasswordHash`, `iEmployeeId`, `sUserType`, `sLanguage`, `iCanEditDocument`, `iIsDeleted=0`, `iFailedLoginCount=0`, `sCreatedBy` + +写 `sys_user_permission_category`（V1 已建）： +- 写入：`iUserId`, `iPermissionCategoryId`, `sGrantedBy` + +只读 `sys_employee`（V1 已建）： +- 读：`iIncrement`, `iIsDeleted`（校验 employeeId 存在） + +只读 `sys_permission_category`（V1 已建）： +- 读：`iIncrement`, `iIsDeleted`（校验 permissionCategoryIds 全部存在） + +**本 REQ 不需要新增 migration**。 + +## 依赖的接口 + +- 本 REQ 提供：`POST /api/v1/users` +- 鉴权前置依赖：JWT 由 REQ-USR-001 签发 +- 下游会消费但本 REQ 不实现的接口： + - `GET /api/v1/employees`（员工下拉，后续 HR 模块） + - `GET /api/v1/permission-categories`（权限分类下拉，后续运营模块） + +## 验收标准 + +后端集成测试： + +1. **正常路径（最小字段）**：管理员 token + 合法 username / userCode / userType / language / canEditDocument，不带 employeeId / permissionCategoryIds → 201；DB 出现新用户记录，`sPasswordHash` 非空且可被 `BCryptPasswordEncoder.matches("666666", ...)` 验证；`iIsDeleted=0`，`iFailedLoginCount=0`，`sCreatedBy` = 管理员 username +2. **正常路径（完整字段）**：带 employeeId + permissionCategoryIds（2 条）→ 201；DB sys_user 一行 + sys_user_permission_category 两行；`sGrantedBy` 正确 +3. **新用户立刻可登录**：调用 `POST /api/v1/auth/login` 用初始密码 `666666` + 任意有效公司 → 200 + token +4. **缺 Authorization 头** → 401 / 40101 +5. **Token 无效（篡改）** → 401 / 40101 +6. **Token 关联用户已作废** → 401 / 40101 +7. **NORMAL 用户 token 调用** → 403 / 40301 +8. **username 重复** → 409 / 40901；DB 没有新用户被插入 +9. **userCode 重复** → 409 / 40902；DB 没有新用户被插入 +10. **employeeId 不存在 / 已软删** → 400 / 40004 +11. **permissionCategoryIds 含不存在 ID** → 400 / 40004；事务回滚（sys_user 也未插入） +12. **请求体缺 username / username 含非法字符** → 400 / 40001 +13. **请求体携带 password 字段** → 400 / 40001（Jackson 严格反序列化） +14. **userType / language 非枚举值** → 400 / 40001 +15. **唯一索引兜底**：模拟绕过 service 层预检的并发场景（DataIntegrityViolationException 路径），断言返 40901 而非 50000 + +测试基础：复用 `LoginTestSeeder` + 扩展 `UserCreateTestSeeder`（管理员 token 注入 + 权限分类 fixture）。 diff --git a/docs/superpowers/specs/2026-05-15-REQ-USR-003.md b/docs/superpowers/specs/2026-05-15-REQ-USR-003.md new file mode 100644 index 0000000..2f1d7bb --- /dev/null +++ b/docs/superpowers/specs/2026-05-15-REQ-USR-003.md @@ -0,0 +1,181 @@ +--- +req_id: REQ-USR-003 +date: 2026-05-15 +module: module_usr +--- + +# Spec: REQ-USR-003 — 修改用户 + +## 目标 + +超级管理员对已有用户的非密码、非用户名字段做部分更新（PATCH 语义），并支持增量增删权限分类授权。同时提供 GET 详情接口供前端表单回显（与修改入参 / 返回字段同源）。 + +## 输入 / 触发 + +两个 HTTP 入口（均需 `Authorization: Bearer ` 且 `userType=SUPER_ADMIN`）： + +### 1. `GET /api/v1/users/{userId}` 用户详情 + +Path：`userId: int`（命中 `sys_user.iIncrement`，否则 40401）。 + +无请求体。 + +### 2. `PUT /api/v1/users/{userId}` 修改用户 + +Path：`userId: int`。 + +**请求体 UpdateUserReq**（JSON，PATCH 语义；任一字段缺省视为不变）： + +| 字段 | 类型 | 必填 | 校验 | +|---|---|---|---| +| `userCode` | string | 否 | 提供时 `@Size(max=50) @NotBlank`；若与其他用户的 sUserCode 冲突返 40902（当前用户自身的同值视为不变，跳过冲突判定）| +| `userType` | string | 否 | 提供时 `NORMAL` / `SUPER_ADMIN` | +| `language` | string | 否 | 提供时 `zh-CN` / `en-US` / `zh-TW` | +| `canEditDocument` | boolean | 否 | true / false | +| `employeeId` | int 或 null | 否 | 提供为非 null 时必须命中 `sys_employee.iIncrement` AND `iIsDeleted=0`，否则返 40004；显式传 `null` 表示解除关联，DB 写 NULL | +| `isDeleted` | boolean | 否 | true 表示作废 / false 表示恢复启用；尝试停用当前登录用户自己返 40302 | +| `permissionCategoryIds` | int[] | 否 | 提供时按差集做增删；每个元素必须命中 `sys_permission_category.iIncrement AND iIsDeleted=0`，否则返 40004；缺省表示权限分类不变 | + +**严禁字段**：请求体含 `username` 或 `password` 字段直接返 40001（Jackson `fail-on-unknown-properties=true` 已在 REQ-USR-002 启用全局，缺省命中此防御）。 + +### permissionCategoryIds 增删差集策略 + +- 设当前已授权集合 `current = {pcId1, pcId2, ...}`（从 `sys_user_permission_category WHERE iUserId=?` 查） +- 设请求集合 `target = req.permissionCategoryIds` +- `toRemove = current \ target` → DELETE FROM sys_user_permission_category WHERE iUserId=? AND iPermissionCategoryId IN (toRemove) +- `toAdd = target \ current` → INSERT 对应行，`sGrantedBy = 当前登录 username` +- 同 `target ∩ current` 项保持不动（iIncrement / tCreateDate 不变） + +## 输出 / 结果 + +两个接口共用 `UserDetailVo`： + +```json +{ + "userId": 42, + "username": "alice", + "userCode": "U001", + "userType": "NORMAL", + "language": "zh-CN", + "canEditDocument": false, + "isDeleted": false, + "employeeId": 7, + "employeeName": "张三", + "permissionCategoryIds": [1, 2], + "updatedBy": "admin", + "updatedDate": "2026-05-15T09:30:00" +} +``` + +- `employeeName` 通过 `iEmployeeId` JOIN `sys_employee.sEmployeeName`；未关联职员时省略 +- `permissionCategoryIds` 是当前授权集合（增删后的最终状态）；空数组表示无授权 +- `updatedBy` / `updatedDate` 由本接口在更新时写入（`sUpdatedBy` / `tUpdatedDate`）；GET 取 DB 现有值，可能为 null + +**成功 200 OK**：`Result` + +**失败**： + +| HTTP | code | 含义 | 触发条件 | +|---|---|---|---| +| 400 | 40001 | 请求体格式错误 / 含未知字段（username/password） | jakarta 校验 OR Jackson fail-on-unknown | +| 400 | 40004 | 员工或权限分类不存在 | employeeId / permissionCategoryIds 校验失败 | +| 401 | 40101 | 未携带或无效 Token | 鉴权层 | +| 403 | 40301 | 非超级管理员调用 | 角色守卫 | +| 403 | 40302 | 试图停用当前登录用户自己 | `req.isDeleted == true && userId == LoginContext.userId()` | +| 404 | 40401 | 用户不存在 | `userId` 不命中 `sys_user.iIncrement` | +| 409 | 40902 | 用户号已被占用 | 提供的 userCode 命中其他用户的 sUserCode（排除自身） | + +## 业务规则 + +1. **鉴权 / 角色守卫**：复用 REQ-USR-002 的 JwtHandlerInterceptor + `@RequireSuperAdmin`。两个接口都标 `@RequireSuperAdmin`。 +2. **存在性校验**：先查 `sys_user.iIncrement = userId AND iIsDeleted ∈ {0,1}`（包含作废用户，因为恢复启用允许）；找不到 → 40401。 +3. **自我停用守卫**（PUT 专属）：`req.isDeleted == true && userId == LoginContext.current().userId()` → 40302。**注意**：恢复启用（`isDeleted == false`）即便针对自己也允许（不会有此场景，因为已登录用户必然非作废，但仍保留对称语义）。 +4. **userCode 唯一性**（PUT 专属）：仅当 `req.userCode != null && !req.userCode.equals(currentUser.sUserCode)` 时才检查；用 `selectByUserCodeExcludingId(userCode, userId)` 排除自身。冲突 → 40902。 +5. **外键校验**：employeeId（非 null）和 permissionCategoryIds（非 null）按 REQ-USR-002 同样的方式校验。`employeeId == null` 显式表示解除关联（DB 置 NULL），与字段缺省不同（缺省 = 不变）。 +6. **部分更新**：只更新请求体中显式提供的字段；用 MyBatis-Plus `UpdateWrapper` 显式列出 set 项。`sUpdatedBy = LoginContext.current().username()`、`tUpdatedDate = NOW()` 一定写。 +7. **作废即时生效**：PUT 把 `iIsDeleted=1` 写库后，该用户已签发的 token 在下一次请求时会被 JwtHandlerInterceptor 检测到 iIsDeleted=1 并返 40101（已由 REQ-USR-002 基础设施保证）。 +8. **GET 详情**：聚合 sys_user + sys_employee（JOIN）+ sys_user_permission_category（IN 查询）一次返回；不查询作废过滤之外的额外字段。 + +## PATCH 语义实现细节 + +`UpdateUserReq` 用包装类型（Integer / Boolean / String / List）+ 自定义 `JsonNode` 检测"字段是否在 JSON 中出现"以区分"显式 null"与"缺省"。 + +具体方案： +- `userCode` / `userType` / `language` / `canEditDocument` / `isDeleted` / `permissionCategoryIds` — 缺省 = 不变；提供（非 null）= 更新；**不接受**显式 null（@NotNull 在 service 层不强制，但缺省即视为 null 表示"不变"） +- `employeeId` — 三态：缺省（不变）/ 非 null 整数（更新）/ 显式 null（解除关联）。用 `JsonNullable`（来自 `openapi-generator` 工具库）实现三态。**最小可行替代**：在 controller 层用 `JsonNode` 解析 `employeeId` 字段，传给 service 一个 `EmployeeIdUpdate` 三态枚举（`UNCHANGED / SET(value) / UNSET`）。 + +> **简化决策**：本 REQ 不引入 `jakarta.json` 或 `JsonNullable` 第三方库（违反技术栈表）。采用如下约定： +> - 请求体仅当字段**存在且值非 null**时才更新；字段**完全缺省**视为不变；字段**显式 null** 视为不变（即不区分缺省与显式 null） +> - 单独提供"清除关联"语义：`employeeId == 0` 视为解除关联（DB 写 NULL）。这是一个约定（非业界标准 PATCH），spec 必须明示 + +实现简化后：`UpdateUserReq` 所有字段都是普通可空包装类型；`employeeId` 取值规则：null / 缺省 → 不变；`0` → 解除关联；正整数 → 更新到该 ID。 + +## 边界与约束 + +- **基础设施复用**：鉴权 / GlobalExceptionHandler / Result / BizException / LoginContext / JwtUtil / BCryptPasswordEncoder / SeederFixture 全部复用 REQ-USR-002 +- **ErrorCode 新增**：`USER_FORBIDDEN_SELF_DEACTIVATE = 40302`（HTTP 403）、`USER_NOT_FOUND = 40401`（HTTP 404）。`ErrorCode.toHttpStatus` 已含 401/403/404 段位映射，本 REQ 不需要新增映射。 +- **不实现**： + - 用户名 / 密码修改（推迟到独立 REQ） + - 批量修改（YAGNI） + - 修改历史审计表（推迟） + - GET 列表（REQ-USR-004 范围） + +## 依赖的 schema 表 / 字段 + +读 + 写 `sys_user`（V1 已建）： +- 读：iIncrement / sUsername / sUserCode / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / sCreatedBy / sUpdatedBy / tUpdatedDate / tCreateDate（详情查询需要） +- 写：sUserCode / iEmployeeId / sUserType / sLanguage / iCanEditDocument / iIsDeleted / sUpdatedBy / tUpdatedDate + +读 + 写 `sys_user_permission_category`（V1 已建）： +- 增删差集 + +只读 `sys_employee`（V1 已建）： +- 校验 employeeId 存在 + 取 sEmployeeName + +只读 `sys_permission_category`（V1 已建）： +- countActiveByIds 校验 + +**本 REQ 不需要新增 migration**。 + +## 依赖的接口 + +- 本 REQ 提供： + - `GET /api/v1/users/{userId}` — 用户详情 + - `PUT /api/v1/users/{userId}` — 修改用户 +- 前置依赖：JWT 由 REQ-USR-001 签发；JwtHandlerInterceptor 由 REQ-USR-002 提供 + +## 验收标准 + +后端集成测试： + +### GET 详情 + +1. **admin token + 存在用户** → 200，UserDetailVo 完整（含 employeeName + permissionCategoryIds） +2. **admin token + 不存在 userId** → 404 / 40401 +3. **NORMAL token** → 403 / 40301 +4. **无 Authorization** → 401 / 40101 +5. **作废用户** → 200（详情查询包含作废用户；不过滤） + +### PUT 修改 + +6. **修改 userCode + userType + language**（admin token）→ 200，DB 已更新；sUpdatedBy=admin、tUpdatedDate 非空；其他字段不变 +7. **修改 employeeId 为另一个有效员工** → 200，DB 写新值 +8. **修改 employeeId=0 解除关联** → 200，DB 写 NULL +9. **修改 employeeId=99999 不存在** → 400 / 40004 +10. **修改 isDeleted=true** → 200，DB 写 1；该用户原 token 下一次请求返 40101 +11. **修改 permissionCategoryIds（差集增删）**：初始权限 `[1,2]`，请求 `[2,3]` → 200，最终 DB 状态 `[2,3]`；分类 1 的行被 DELETE，分类 3 的行被 INSERT；分类 2 的行 iIncrement 保持不变（验证差集而非全量替换） +12. **permissionCategoryIds 为空数组** → 200，最终授权清空 +13. **permissionCategoryIds 含不存在 ID** → 400 / 40004，事务回滚（DB 授权无变化） +14. **修改 userCode 冲突（其他用户已用）** → 409 / 40902 +15. **修改 userCode 等于自身原值** → 200，无 40902 +16. **试图停用自己**（admin 用 admin token 改 admin 用户 isDeleted=true）→ 403 / 40302 +17. **请求体含 username 字段** → 400 / 40001 +18. **请求体含 password 字段** → 400 / 40001 +19. **userId 不存在** → 404 / 40401 +20. **NORMAL token 调用 PUT** → 403 / 40301 +21. **空请求体 `{}`** → 200，仅写 sUpdatedBy / tUpdatedDate（其他字段不变） + +### PUT + 立即可观察 + +22. **修改后调用 GET 详情** → 返回的字段反映 PUT 的写入值 +23. **作废用户尝试登录** → 401 / 40103（REQ-USR-001 既有路径，不在本 REQ 添加新测试，但成功路径验收应链路一致） diff --git a/docs/superpowers/specs/2026-05-15-REQ-USR-004.md b/docs/superpowers/specs/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..eb4ed6e --- /dev/null +++ b/docs/superpowers/specs/2026-05-15-REQ-USR-004.md @@ -0,0 +1,167 @@ +--- +req_id: REQ-USR-004 +date: 2026-05-15 +module: module_usr +--- + +# Spec: REQ-USR-004 — 查询用户 + +## 目标 + +`GET /api/v1/users`：超级管理员分页 + 多字段筛选 + 排序查询用户列表，单条记录聚合 sys_user + sys_employee + sys_department 信息（部门名、员工名）。只读，无写副作用，不返回密码。 + +## 输入 / 触发 + +HTTP 入口 `GET /api/v1/users`，要求 `Authorization: Bearer ` + `userType=SUPER_ADMIN`。 + +**Query 参数**（全部可选）： + +| 参数 | 类型 | 默认 | 校验 | +|---|---|---|---| +| `page` | int | 1 | `@Min(1)`；< 1 返 40001；大于总页数返"最后一页"数据（不是空列表） | +| `size` | int | 20 | `@Min(1) @Max(100)`；越界返 40001 | +| `sortField` | string | `tCreateDate` | 白名单：`tCreateDate` / `tLastLoginDate` / `sUsername` / `sUserCode`；不在白名单返 40003 | +| `sortOrder` | string | `desc` | `asc` / `desc`；其他值返 40001 | +| `queryField` | string | （不筛选） | 白名单：`username` / `employeeName` / `userCode` / `departmentName` / `userType` / `isDeleted` / `lastLoginDate` / `createdBy`；不在白名单返 40003 | +| `matchMode` | string | `contains` | `contains` / `notContains` / `equals`；不在白名单返 40003 | +| `queryValue` | string | （不筛选） | 任意字符串；空字符串或 null 视为不应用此条件；与 queryField 配对使用——只提供 queryField 不提供 queryValue 也视为不应用 | +| `userType` | string | （不筛选） | 若提供，必须是 `NORMAL` / `SUPER_ADMIN`；其他返 40001 | +| `isDeleted` | boolean | （不筛选） | true / false | + +> **复合规则**：所有筛选条件用 `AND` 拼接：queryField+queryValue 提供时构成一条动态条件；userType / isDeleted 作为额外固定条件叠加。 + +## 输出 / 结果 + +**成功 200**：`Result>` + +```json +{ + "code": 200, + "message": "操作成功", + "data": { + "records": [ + { + "userId": 42, + "username": "alice", + "employeeName": "张三", + "userCode": "U001", + "departmentName": "技术部", + "userType": "NORMAL", + "language": "zh-CN", + "isDeleted": false, + "lastLoginDate": "2026-05-15T08:00:00", + "createdBy": "admin", + "createdDate": "2026-05-15T07:00:00" + } + ], + "total": 17, + "page": 1, + "size": 20 + } +} +``` + +字段： +- `userId` = sys_user.iIncrement +- `username` / `userCode` / `userType` / `language` / `isDeleted` / `lastLoginDate` / `createdBy` / `createdDate` 直接来自 sys_user +- `employeeName` = LEFT JOIN sys_employee.sEmployeeName（用户未关联职员时返回 null） +- `departmentName` = LEFT JOIN sys_department.sDepartmentName via sys_employee.iDepartmentId（未关联或部门软删时返回 null） + +**失败**： + +| HTTP | code | 含义 | 触发 | +|---|---|---|---| +| 400 | 40001 | 分页 / 类型 / 排序参数错误 | page<1 / size<1 / size>100 / sortOrder 非 asc-desc / userType 非枚举 | +| 400 | 40003 | queryField / matchMode / sortField 不在白名单 | 用户传非法枚举值 | +| 401 | 40101 | 未携带或无效 Token | 鉴权层 | +| 403 | 40301 | 非超级管理员 | 角色守卫 | + +## 业务规则 + +1. **鉴权**：复用 `@RequireSuperAdmin` + JwtHandlerInterceptor。 +2. **白名单映射**（service 层维护静态 Map）： + - `sortField` 入参 → SQL 列名：`tCreateDate`/`tLastLoginDate`/`sUsername`/`sUserCode` 均与列名同名（直接使用）。**禁止用户传任意列名**——必须白名单匹配。 + - `queryField` 入参 → SQL 列引用（含 JOIN 别名）： + - `username` → `u.sUsername` + - `employeeName` → `e.sEmployeeName` + - `userCode` → `u.sUserCode` + - `departmentName` → `d.sDepartmentName` + - `userType` → `u.sUserType` + - `isDeleted` → `u.iIsDeleted` + - `lastLoginDate` → `u.tLastLoginDate` + - `createdBy` → `u.sCreatedBy` +3. **matchMode 处理**： + - `contains` → `LIKE CONCAT('%', #{queryValue}, '%')` + - `notContains` → `NOT LIKE CONCAT('%', #{queryValue}, '%') OR IS NULL` + - `equals` → `= #{queryValue}` + - 对 `isDeleted`（int）/ `lastLoginDate`（datetime）这类非字符串字段：无论 matchMode 一律按 `equals` 处理（service 层规范化 queryValue 为对应类型；非法值返 40001）。 +4. **空 queryValue**：queryField 给了但 queryValue 为 null / 空串 → 跳过此条件，不参与 WHERE。 +5. **空 queryField + 有 queryValue**：跳过（缺 queryField 没法应用）。 +6. **越界 page**：先按入参 page/size 查；若返回 records 为空但 total > 0，service 层用 `lastPage = (total + size - 1) / size` 重新查一次并返回 lastPage 的数据。响应 `page` 字段反映**实际返回的页码**（即 lastPage），让前端能感知矫正。 +7. **排序 SQL**：在 ORDER BY 前用白名单映射列名 + asc/desc 拼接；用 MyBatis 字符串替换（`${}`）但只限白名单值（白名单已校验，安全）。 +8. **不返回密码**：UserListItemVo 不含 sPasswordHash 字段；mapper SELECT 列表显式列出业务列。 +9. **N+1 防御**：JOIN 而非多次查询；单查询返回所有字段。 +10. **空查询**：所有筛选都空时返回全表分页（admin 用例需要"全部 用户"视图）。 + +## 边界与约束 + +- **白名单兜底**：所有动态字段（queryField / matchMode / sortField / sortOrder）必须 service 层先做白名单检查，再拼到 SQL；用户输入永远不直接进 ORDER BY / SELECT。 +- **MyBatis 注入**：用 `#{}` 参数化输入；只有列名 / 排序方向用 `${}`（已白名单约束）。 +- **size 上限 100**：与 docs/04 § 3.2 一致。 +- **作废用户参与查询**：默认不过滤；用户通过 `isDeleted=false` 显式过滤启用账号。 +- **登录追踪**：本 REQ 不修改 tLastLoginDate / iFailedLoginCount / tLockUntil — 纯查询。 +- **不实现**： + - 多字段同时筛选（spec 仅允许单一 queryField，多字段筛选推迟） + - 自定义列展示（前端事） + - 导出 / 导入（YAGNI） + +## 依赖的 schema 表 / 字段 + +只读 `sys_user`（V1 已建）： +- 读列：iIncrement, sUsername, sUserCode, sUserType, sLanguage, iIsDeleted, tLastLoginDate, sCreatedBy, tCreateDate, iEmployeeId +- 排序 / 筛选列：sUsername, sUserCode, sUserType, iIsDeleted, tLastLoginDate, sCreatedBy, tCreateDate + +只读 `sys_employee`（V1 已建）： +- LEFT JOIN：iIncrement = u.iEmployeeId +- 读 / 筛选列：sEmployeeName, iDepartmentId + +只读 `sys_department`（V1 已建）： +- LEFT JOIN：iIncrement = e.iDepartmentId +- 读 / 筛选列：sDepartmentName + +**本 REQ 不需要新增 migration**。 + +## 依赖的接口 + +- 本 REQ 提供：`GET /api/v1/users` + +## 验收标准 + +后端集成测试： + +1. **admin token + 默认参数** → 200，返回所有用户（按 tCreateDate desc）；total = 实际行数；不含密码字段 +2. **page=2 size=2** → 返回第 2 页 2 条；page=2，total 不变 +3. **size > 100** → 400 / 40001 +4. **page < 1** → 400 / 40001 +5. **sortField=sUsername sortOrder=asc** → 按 username 升序返回 +6. **sortField=nonExisting** → 400 / 40003 +7. **sortOrder=foo** → 400 / 40001 +8. **queryField=username matchMode=contains queryValue=ali** → 返回含 "ali" 的用户 +9. **queryField=username matchMode=equals queryValue=alice** → 仅返回 alice +10. **queryField=username matchMode=notContains queryValue=ali** → 不含 alice 但含 admin / bob_deleted +11. **queryField=employeeName matchMode=contains queryValue=张** → 返回员工名含张的用户（JOIN） +12. **queryField=departmentName matchMode=equals queryValue=技术部** → 返回部门=技术部的用户（多级 JOIN） +13. **queryField=userType matchMode=equals queryValue=SUPER_ADMIN** → 仅 admin +14. **queryField=isDeleted matchMode=equals queryValue=true** → 仅 bob_deleted +15. **queryField=invalid** → 400 / 40003 +16. **matchMode=invalid** → 400 / 40003 +17. **queryField 提供但 queryValue 为空** → 跳过条件，返回全表（不报错） +18. **userType=NORMAL** explicit 参数 → 仅 NORMAL 用户 +19. **userType=INVALID** → 400 / 40001 +20. **isDeleted=false** explicit → 仅启用用户 +21. **复合：queryField=username queryValue=al userType=NORMAL isDeleted=false** → 仅匹配三条件的用户（alice） +22. **page 越界（page=999 size=10，total=3）** → 200，返回最后一页（page=1，1 个 records 或更少），total=3 +23. **NORMAL token** → 403 / 40301 +24. **无 token** → 401 / 40101 +25. **响应不含 sPasswordHash 字段** → JSON 没有 password 相关字段 +26. **空表（无用户）** → 200，records=[]，total=0 diff --git a/scripts/test.sh b/scripts/test.sh index 2841486..825b0ea 100755 --- a/scripts/test.sh +++ b/scripts/test.sh @@ -8,6 +8,13 @@ set -euo pipefail PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$PROJECT_ROOT" +# 加载 .env.local，让后续 mvn / setup-test-db 子进程都能继承 DB / JWT 凭据 +if [ -f .env.local ]; then + set -a + . ./.env.local + set +a +fi + # Stack detection (runtime, mode-agnostic) HAS_BACKEND=0; [ -d backend ] && HAS_BACKEND=1 HAS_FRONTEND=0; [ -d frontend ] && HAS_FRONTEND=1 @@ -20,19 +27,19 @@ echo "[test.sh] 1/6 setup test db" ./scripts/setup-test-db.sh echo "[test.sh] 2/6 build" -if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B -DskipTests package); else echo "[test.sh] skip backend build"; fi -if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm install --frozen-lockfile && pnpm build); else echo "[test.sh] skip frontend build"; fi +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B -DskipTests clean package); else echo "[test.sh] skip backend build"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm ci && npm run build); else echo "[test.sh] skip frontend build"; fi echo "[test.sh] 3/6 lint" -if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B -q -P lint verify -DskipTests || ./mvnw -B -q checkstyle:check spotbugs:check || :); else echo "[test.sh] skip backend lint"; fi -if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm lint); else echo "[test.sh] skip frontend lint"; fi +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B -q checkstyle:check || mvn -B -q spotless:check || echo "[test.sh] backend lint skipped (no plugin configured)"); else echo "[test.sh] skip backend lint"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run lint); else echo "[test.sh] skip frontend lint"; fi echo "[test.sh] 4/6 unit + integration" -if [ $HAS_BACKEND -eq 1 ]; then (cd backend && ./mvnw -B test); else echo "[test.sh] skip backend test"; fi -if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && pnpm test -- --run); else echo "[test.sh] skip frontend test"; fi +if [ $HAS_BACKEND -eq 1 ]; then (cd backend && mvn -B test); else echo "[test.sh] skip backend test"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npm run test -- --run); else echo "[test.sh] skip frontend test"; fi echo "[test.sh] 5/6 E2E" -if [ $HAS_FRONTEND -eq 1 ] && [ -f frontend/playwright.config.ts ]; then (cd frontend && pnpm exec playwright test); else echo "[test.sh] e2e 略"; fi +if [ $HAS_FRONTEND -eq 1 ]; then (cd frontend && npx playwright test); else echo "[test.sh] e2e 略 (no frontend)"; fi echo "[test.sh] 6/6 reset test db" ./scripts/setup-test-db.sh diff --git a/sql/migrations/V1__initial_schema.sql b/sql/migrations/V1__initial_schema.sql index c341d90..41ed418 100644 --- a/sql/migrations/V1__initial_schema.sql +++ b/sql/migrations/V1__initial_schema.sql @@ -1,141 +1,158 @@ -- Flyway migration V1 — initial schema for 小羚羊 --- Generated: 2026-05-14T01:37:50Z +-- Generated: 2026-05-14T15:46:57Z -- Source: 由 A4 db-init 从 docs/03-数据库设计文档.md 翻译生成（schema SSoT 是 docs/03） -- This is the FIRST migration; subsequent schema changes must be written as new files sql/migrations/V2__.sql, V3__... etc. -- Apply: Flyway runs this automatically at Spring Boot startup. -- Do not hand-edit this file after it is committed; write a new migration instead. --- =========================================================================== --- t_user — 系统用户主表，承载登录认证与基础属性 --- =========================================================================== -CREATE TABLE `t_user` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `sUserNo` VARCHAR(50) NOT NULL COMMENT '用户号；关联职员后自动同步员工号；系统内唯一', - `sUserName` VARCHAR(50) NOT NULL COMMENT '登录用户名；系统内唯一；3-50 位', - `iEmployeeId` INT NULL DEFAULT NULL COMMENT '关联职员 t_employee.iIncrement；可空（非员工账号如系统管理员）', - `sPasswordHash` VARCHAR(255) NOT NULL COMMENT '密码哈希（BCrypt / Argon2）；禁止明文；初始密码 666666 哈希后存入', - `sUserType` VARCHAR(20) NOT NULL DEFAULT 'NORMAL' COMMENT '用户类型枚举：NORMAL（普通用户）/ SUPER_ADMIN（超级管理员）', - `sLanguage` VARCHAR(10) NOT NULL DEFAULT 'zh-CN' COMMENT '语言枚举：zh-CN（中文）/ en-US（英文）/ zh-TW（繁体）', - `bModifyDoc` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '单据修改权限：0 否 / 1 是', - `bVoid` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '作废标记（软删除）：0 启用 / 1 已作废', - `iLoginFailCount` INT NOT NULL DEFAULT 0 COMMENT '连续登录失败次数；达到阈值触发临时锁定；登录成功后清零', - `tLockUntil` DATETIME NULL DEFAULT NULL COMMENT '锁定截止时间；NULL 表示未锁定', - `tLastLoginDate` DATETIME NULL DEFAULT NULL COMMENT '最近一次登录时间', - `sCreator` VARCHAR(100) NULL DEFAULT NULL COMMENT '制单人（创建该账号的操作员用户名）', +-- ============================================================================= +-- Table: sys_company — 公司 / 版本字典，登录页下拉选择来源 +-- ============================================================================= +CREATE TABLE `sys_company` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sCompanyName` VARCHAR(100) NOT NULL COMMENT '公司 / 版本名称（登录页下拉显示文本）', + `sCompanyCode` VARCHAR(50) NOT NULL COMMENT '公司编码（前端唯一识别）', + `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '下拉列表排序权重，升序', + `iIsDeleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '软删除标记，0=正常 1=已删', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_user_username` (`sUserName`), - UNIQUE KEY `uk_user_userno` (`sUserNo`), - KEY `idx_user_employee` (`iEmployeeId`), - KEY `idx_user_tenant` (`sBrandsId`, `sSubsidiaryId`), - KEY `idx_user_void` (`bVoid`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='系统用户主表，承载登录认证与基础属性'; - --- =========================================================================== --- t_employee — 公司职员主档 --- =========================================================================== -CREATE TABLE `t_employee` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `sEmployeeNo` VARCHAR(50) NOT NULL COMMENT '员工号；系统内唯一', - `sName` VARCHAR(100) NOT NULL COMMENT '姓名', - `iDepartmentId` INT NULL DEFAULT NULL COMMENT '部门 ID，关联 t_department.iIncrement', - `sPhone` VARCHAR(20) NULL DEFAULT NULL COMMENT '手机号', - `sEmail` VARCHAR(100) NULL DEFAULT NULL COMMENT '邮箱', - `bDisabled` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否离职：0 在职 / 1 离职', + UNIQUE KEY `uk_sys_company_code` (`sCompanyCode`), + KEY `idx_sys_company_is_deleted` (`iIsDeleted`, `iSortOrder`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司 / 版本字典，登录页下拉选择来源'; + + +-- ============================================================================= +-- Table: sys_department — 部门字典，职员归属 +-- ============================================================================= +CREATE TABLE `sys_department` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sDepartmentName` VARCHAR(100) NOT NULL COMMENT '部门名称', + `sDepartmentCode` VARCHAR(50) NOT NULL COMMENT '部门编码', + `iIsDeleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '软删除标记', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_employee_no` (`sEmployeeNo`), - KEY `idx_employee_dept` (`iDepartmentId`), - KEY `idx_employee_name` (`sName`), - KEY `idx_employee_tenant` (`sBrandsId`, `sSubsidiaryId`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司职员主档'; - --- =========================================================================== --- t_department — 部门组织树 --- =========================================================================== -CREATE TABLE `t_department` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `sName` VARCHAR(100) NOT NULL COMMENT '部门名称', - `sCode` VARCHAR(50) NOT NULL COMMENT '部门编码；系统内唯一', - `iParentId` INT NULL DEFAULT NULL COMMENT '上级部门 ID，NULL 表示根部门', - `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '排序值，小者靠前', + UNIQUE KEY `uk_sys_department_code` (`sDepartmentCode`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='部门字典，职员归属'; + + +-- ============================================================================= +-- Table: sys_employee — 职员档案，员工基础信息 +-- ============================================================================= +CREATE TABLE `sys_employee` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sEmployeeName` VARCHAR(50) NOT NULL COMMENT '员工姓名（2-50 字符）', + `sEmployeeCode` VARCHAR(50) NOT NULL COMMENT '员工工号（系统内唯一）', + `iDepartmentId` INT NOT NULL COMMENT '所属部门 ID（FK → sys_department.iIncrement）', + `sPhone` VARCHAR(20) NULL DEFAULT NULL COMMENT '手机号', + `sEmail` VARCHAR(100) NULL DEFAULT NULL COMMENT '邮箱', + `iIsDeleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '软删除标记', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_department_code` (`sCode`), - KEY `idx_department_parent` (`iParentId`), - KEY `idx_department_tenant` (`sBrandsId`, `sSubsidiaryId`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='部门组织树'; - --- =========================================================================== --- t_permission — 权限分类字典 --- =========================================================================== -CREATE TABLE `t_permission` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `sCode` VARCHAR(50) NOT NULL COMMENT '权限码，例如 USR:ADD / USR:EDIT；系统内唯一', - `sName` VARCHAR(100) NOT NULL COMMENT '权限分类名称（展示用）', - `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '同分类内排序', + UNIQUE KEY `uk_sys_employee_code` (`sEmployeeCode`), + KEY `idx_sys_employee_department` (`iDepartmentId`), + KEY `idx_sys_employee_name` (`sEmployeeName`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='职员档案，员工基础信息'; + + +-- ============================================================================= +-- Table: sys_user — 用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪） +-- ============================================================================= +CREATE TABLE `sys_user` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sUsername` VARCHAR(50) NOT NULL COMMENT '用户名（登录凭据，系统内全局唯一，3-20 位字母数字下划线）', + `sUserCode` VARCHAR(50) NOT NULL COMMENT '用户号（业务展示用编码，系统内唯一）', + `sPasswordHash` VARCHAR(255) NOT NULL COMMENT '密码哈希（BCrypt / Argon2，禁明文）', + `iEmployeeId` INT NULL DEFAULT NULL COMMENT '关联职员 ID（可选；FK → sys_employee.iIncrement）', + `sUserType` VARCHAR(20) NOT NULL DEFAULT 'NORMAL' COMMENT '用户类型枚举：NORMAL=普通用户 / SUPER_ADMIN=超级管理员', + `sLanguage` VARCHAR(10) NOT NULL DEFAULT 'zh-CN' COMMENT '语言：zh-CN=中文 / en-US=英文 / zh-TW=繁体', + `iCanEditDocument` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '单据修改权限：0=否 1=是', + `iIsDeleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否作废：0=启用 1=作废（停用）', + `iFailedLoginCount` INT NOT NULL DEFAULT 0 COMMENT '累计登录失败次数，达阈值锁定，登录成功清零', + `tLockUntil` DATETIME NULL DEFAULT NULL COMMENT '锁定截止时间，NULL=未锁定，过期自动解锁', + `tLastLoginDate` DATETIME NULL DEFAULT NULL COMMENT '最后一次成功登录时间，REQ-USR-004 登录日期来源', + `sCreatedBy` VARCHAR(50) NULL DEFAULT NULL COMMENT '制单人（创建该用户的用户名），REQ-USR-002 制单人', + `sUpdatedBy` VARCHAR(50) NULL DEFAULT NULL COMMENT '最后修改人用户名', + `tUpdatedDate` DATETIME NULL DEFAULT NULL COMMENT '最后修改时间', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_permission_code` (`sCode`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限分类字典'; + UNIQUE KEY `uk_sys_user_username` (`sUsername`), + UNIQUE KEY `uk_sys_user_code` (`sUserCode`), + KEY `idx_sys_user_employee` (`iEmployeeId`), + KEY `idx_sys_user_type` (`sUserType`), + KEY `idx_sys_user_is_deleted` (`iIsDeleted`), + KEY `idx_sys_user_created_by` (`sCreatedBy`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户账号（登录认证 + 类型 + 语言 + 状态 + 登录追踪）'; + --- =========================================================================== --- t_user_permission — 用户-权限分类关联表 --- =========================================================================== -CREATE TABLE `t_user_permission` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `iUserId` INT NOT NULL COMMENT '用户 ID，关联 t_user.iIncrement', - `iPermissionId` INT NOT NULL COMMENT '权限分类 ID，关联 t_permission.iIncrement', +-- ============================================================================= +-- Table: sys_permission_category — 权限分类字典 +-- ============================================================================= +CREATE TABLE `sys_permission_category` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `sCategoryName` VARCHAR(100) NOT NULL COMMENT '权限分类名称（如 采购管理 / 销售管理）', + `sCategoryCode` VARCHAR(50) NOT NULL COMMENT '权限分类编码（系统内唯一，代码层引用）', + `sCategoryDesc` VARCHAR(255) NULL DEFAULT NULL COMMENT '分类说明', + `iSortOrder` INT NOT NULL DEFAULT 0 COMMENT '列表展示顺序', + `iIsDeleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '软删除标记', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_user_perm` (`iUserId`, `iPermissionId`), - KEY `idx_user_perm_perm` (`iPermissionId`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户-权限分类关联表'; - --- =========================================================================== --- t_company — 公司 / 版本字典 --- =========================================================================== -CREATE TABLE `t_company` ( - `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', - `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', - `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '品牌 ID（多租户隔离，标准列）', - `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', - `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', - `sCode` VARCHAR(50) NOT NULL COMMENT '公司 / 版本编码；系统内唯一', - `sName` VARCHAR(100) NOT NULL COMMENT '显示名称', + UNIQUE KEY `uk_sys_permission_category_code` (`sCategoryCode`), + KEY `idx_sys_permission_category_sort` (`iIsDeleted`, `iSortOrder`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限分类字典'; + + +-- ============================================================================= +-- Table: sys_user_permission_category — 用户 × 权限分类授权关系 +-- ============================================================================= +CREATE TABLE `sys_user_permission_category` ( + `iIncrement` INT NOT NULL AUTO_INCREMENT COMMENT '整数主键 ID（标准列）', + `sId` VARCHAR(100) NULL DEFAULT (UUID()) COMMENT '业务 ID（标准列）', + `sBrandsId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '母公司 ID（多租户隔离，标准列）', + `sSubsidiaryId` VARCHAR(100) NULL DEFAULT '1111111111' COMMENT '子公司 ID（组织层级隔离，标准列）', + `tCreateDate` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间（标准列）', + `iUserId` INT NOT NULL COMMENT '用户 ID（FK → sys_user.iIncrement）', + `iPermissionCategoryId` INT NOT NULL COMMENT '权限分类 ID（FK → sys_permission_category.iIncrement）', + `sGrantedBy` VARCHAR(50) NULL DEFAULT NULL COMMENT '授予人用户名', PRIMARY KEY (`iIncrement`), - UNIQUE KEY `uk_company_code` (`sCode`) -) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='公司 / 版本字典'; + UNIQUE KEY `uk_sys_user_permission_category` (`iUserId`, `iPermissionCategoryId`), + KEY `idx_sys_user_permission_category_category` (`iPermissionCategoryId`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户 × 权限分类授权关系'; --- =========================================================================== --- 外键约束（统一在最后追加，避免建表顺序依赖） --- =========================================================================== -ALTER TABLE `t_user` - ADD CONSTRAINT `fk_user_employee` FOREIGN KEY (`iEmployeeId`) REFERENCES `t_employee` (`iIncrement`) ON DELETE SET NULL ON UPDATE RESTRICT; -ALTER TABLE `t_employee` - ADD CONSTRAINT `fk_employee_department` FOREIGN KEY (`iDepartmentId`) REFERENCES `t_department` (`iIncrement`) ON DELETE SET NULL ON UPDATE RESTRICT; +-- ============================================================================= +-- Foreign keys +-- ============================================================================= +ALTER TABLE `sys_employee` + ADD CONSTRAINT `fk_sys_employee_department` + FOREIGN KEY (`iDepartmentId`) REFERENCES `sys_department` (`iIncrement`) + ON DELETE RESTRICT ON UPDATE CASCADE; -ALTER TABLE `t_department` - ADD CONSTRAINT `fk_department_parent` FOREIGN KEY (`iParentId`) REFERENCES `t_department` (`iIncrement`) ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE `sys_user` + ADD CONSTRAINT `fk_sys_user_employee` + FOREIGN KEY (`iEmployeeId`) REFERENCES `sys_employee` (`iIncrement`) + ON DELETE SET NULL ON UPDATE CASCADE; -ALTER TABLE `t_user_permission` - ADD CONSTRAINT `fk_userperm_user` FOREIGN KEY (`iUserId`) REFERENCES `t_user` (`iIncrement`) ON DELETE CASCADE ON UPDATE RESTRICT; +ALTER TABLE `sys_user_permission_category` + ADD CONSTRAINT `fk_sys_upc_user` + FOREIGN KEY (`iUserId`) REFERENCES `sys_user` (`iIncrement`) + ON DELETE CASCADE ON UPDATE CASCADE; -ALTER TABLE `t_user_permission` - ADD CONSTRAINT `fk_userperm_perm` FOREIGN KEY (`iPermissionId`) REFERENCES `t_permission` (`iIncrement`) ON DELETE RESTRICT ON UPDATE RESTRICT; +ALTER TABLE `sys_user_permission_category` + ADD CONSTRAINT `fk_sys_upc_permission_category` + FOREIGN KEY (`iPermissionCategoryId`) REFERENCES `sys_permission_category` (`iIncrement`) + ON DELETE CASCADE ON UPDATE CASCADE;