From 405982ff08eed758e0db5fc24cb0cf34836c902b Mon Sep 17 00:00:00 2001
From: zichun <zhuzichunhogan@gmail.com>
Date: Fri, 15 May 2026 10:03:35 +0800
Subject: [PATCH] feat(usr): UserQueryReq + UserListItemVo REQ-USR-004

---
 backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java               | 28 ++++++++++++++++++++++++++++
 backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java              | 28 ++++++++++++++++++++++++++++
 backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+), 0 deletions(-)
 create mode 100644 backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryReq.java
 create mode 100644 backend/src/main/java/com/xly/erp/module/usr/vo/UserListItemVo.java
 create mode 100644 backend/src/test/java/com/xly/erp/module/usr/dto/UserQueryReqValidationTest.java

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