From 7921432e9e1583db243c35cefc2e4d146becd709 Mon Sep 17 00:00:00 2001
From: zichun <zhuzichunhogan@gmail.com>
Date: Fri, 8 May 2026 11:44:26 +0800
Subject: [PATCH] fix(usr): 修复 review round 1 must-fix REQ-USR-003

---
 backend/src/main/java/com/example/erp/module/usr/controller/UserController.java    | 1 +
 backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java | 1 +
 backend/src/main/resources/mapper/UsrUserMapper.xml                                | 5 +++--
 docs/05-API接口契约.md                                                         | 4 ++--
 frontend/src/pages/usr/UserListPage.tsx                                            | 1 +
 5 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/backend/src/main/java/com/example/erp/module/usr/controller/UserController.java b/backend/src/main/java/com/example/erp/module/usr/controller/UserController.java
index 4636fc6..faa9d2e 100644
--- a/backend/src/main/java/com/example/erp/module/usr/controller/UserController.java
+++ b/backend/src/main/java/com/example/erp/module/usr/controller/UserController.java
@@ -31,6 +31,7 @@ public class UserController {
         return Result.ok(userService.createUser(req, principal));
     }
 
+    // REQ-USR-003: 查询用户
     @GetMapping("/users")
     public Result<PageVO<UserListItemVO>> getUsers(
             @RequestParam(defaultValue = "username") String queryField,
diff --git a/backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java b/backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java
index 0b38a04..23dfe60 100644
--- a/backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java
+++ b/backend/src/main/java/com/example/erp/module/usr/service/impl/UserServiceImpl.java
@@ -121,6 +121,7 @@ public class UserServiceImpl implements UserService {
         }).collect(Collectors.toList());
     }
 
+    // REQ-USR-003: 查询用户
     @Override
     @Transactional(readOnly = true)
     public PageVO<UserListItemVO> getUserList(UserListQueryDTO query, String brandId) {
diff --git a/backend/src/main/resources/mapper/UsrUserMapper.xml b/backend/src/main/resources/mapper/UsrUserMapper.xml
index 67c212c..661a7d4 100644
--- a/backend/src/main/resources/mapper/UsrUserMapper.xml
+++ b/backend/src/main/resources/mapper/UsrUserMapper.xml
@@ -3,6 +3,7 @@
         "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
 <mapper namespace="com.example.erp.module.usr.mapper.UsrUserMapper">
 
+    <!-- REQ-USR-003: 查询用户 -->
     <select id="selectUserList" resultType="com.example.erp.module.usr.vo.UserListItemVO">
         SELECT u.sId, u.sUsername, u.sUserCode, u.sUserType, u.sLanguage,
                u.bIsDisabled, u.tLastLoginDate, u.sCreatorUsername, u.tCreateDate,
@@ -24,7 +25,7 @@
                 <when test="queryField == 'staffName'">
                     <choose>
                         <when test="matchType == 'contains'">AND s.sStaffName LIKE CONCAT('%', #{queryValue}, '%')</when>
-                        <when test="matchType == 'notContains'">AND s.sStaffName NOT LIKE CONCAT('%', #{queryValue}, '%')</when>
+                        <when test="matchType == 'notContains'">AND (s.sStaffName IS NULL OR s.sStaffName NOT LIKE CONCAT('%', #{queryValue}, '%'))</when>
                         <otherwise>AND s.sStaffName = #{queryValue}</otherwise>
                     </choose>
                 </when>
@@ -38,7 +39,7 @@
                 <when test="queryField == 'department'">
                     <choose>
                         <when test="matchType == 'contains'">AND s.sDepartment LIKE CONCAT('%', #{queryValue}, '%')</when>
-                        <when test="matchType == 'notContains'">AND s.sDepartment NOT LIKE CONCAT('%', #{queryValue}, '%')</when>
+                        <when test="matchType == 'notContains'">AND (s.sDepartment IS NULL OR s.sDepartment NOT LIKE CONCAT('%', #{queryValue}, '%'))</when>
                         <otherwise>AND s.sDepartment = #{queryValue}</otherwise>
                     </choose>
                 </when>
diff --git a/docs/05-API接口契约.md b/docs/05-API接口契约.md
index 0780d93..fd400c1 100644
--- a/docs/05-API接口契约.md
+++ b/docs/05-API接口契约.md
@@ -73,8 +73,8 @@ BasePath: `/api`
 - **Path**: `/api/usr/users`
 - **Auth**: Bearer Token
 - **Permission**: `usr:query`
-- **请求**: Query 参数：`field=用户名|员工名|用户号|部门|用户类型|作废|登录日期|制单人`、`matchMode=包含|不包含|等于`、`value=string`、`pageNum=int`、`pageSize=int`
-- **响应**: `{ list: [{ "userId", "username", "staffName", "userCode", "department", "userType", "language", "isDisabled", "lastLoginDate", "creatorUsername", "createDate" }], total, pageNum, pageSize }` — 密码字段不返回
+- **请求**: Query 参数：`queryField=username|staffName|userCode|department|userType|disabled|lastLoginDate|creator`（默认 username）、`matchType=contains|notContains|equals`（默认 contains）、`queryValue=string`、`page=int`（默认 1）、`pageSize=int`（默认 20，最大 100）
+- **响应**: `{ list: [{ "sId", "sUsername", "sUserCode", "sUserType", "sLanguage", "bIsDisabled", "tLastLoginDate", "sCreatorUsername", "tCreateDate", "sStaffName", "sDepartment" }], total, page, pageSize }` — sPasswordHash / iLoginFailCount / tLockUntil 不返回
 
 #### 错误码
 - `40001` — 参数校验失败
diff --git a/frontend/src/pages/usr/UserListPage.tsx b/frontend/src/pages/usr/UserListPage.tsx
index f782673..fc21583 100644
--- a/frontend/src/pages/usr/UserListPage.tsx
+++ b/frontend/src/pages/usr/UserListPage.tsx
@@ -36,6 +36,7 @@ const columns: ColumnsType<UserListItemVO> = [
   { title: '制单日期', dataIndex: 'tCreateDate' },
 ]
 
+// REQ-USR-003: 查询用户
 export default function UserListPage() {
   const [drawerOpen, setDrawerOpen] = useState(false)
   const [data, setData] = useState<PageVO<UserListItemVO> | null>(null)
--
libgit2 0.22.2