fix(usr): 修复 review round 1 must-fix REQ-USR-003

- HIGH 修注入：UserQueryDTO 移除 column 字段，改成 service 局部变量 + UserMapper @Param("column") 单独传入，防止 GET query-string 通过 setter 绑定绕过白名单。 - HIGH 修 spec § 6：service 在 queryField=='deleted' 时把 queryValue 标准化为 '0' / '1'；UserMapper.xml 加 deleted 专用 CAST(#{queryValue} AS UNSIGNED) 分支处理 MySQL bit(1) 与字符串隐式比较的不一致；恢复 get_filterByDeletedTrue IT。 - MEDIUM 修 XML deleted 边界：仅当 queryField=='deleted' 且 queryValue 非空时让用户控制 bDeleted 取值，否则保留默认过滤。

fix(usr): 修复 review round 1 must-fix REQ-USR-003
- HIGH 修注入：UserQueryDTO 移除 column 字段，改成 service 局部变量 + UserMapper @Param("column") 单独传入，防止 GET query-string 通过 setter 绑定绕过白名单。 - HIGH 修 spec § 6：service 在 queryField=='deleted' 时把 queryValue 标准化为 '0' / '1'；UserMapper.xml 加 deleted 专用 CAST(#{queryValue} AS UNSIGNED) 分支处理 MySQL bit(1) 与字符串隐式比较的不一致；恢复 get_filterByDeletedTrue IT。 - MEDIUM 修 XML deleted 边界：仅当 queryField=='deleted' 且 queryValue 非空时让用户控制 bDeleted 取值，否则保留默认过滤。
zichun
1 parent df28ae66
Showing 7 changed files with 86 additions and 39 deletions
backend/src/main/java/com/xly/erp/module/usr/dto/UserQueryDTO.java
backend/src/main/java/com/xly/erp/module/usr/mapper/UserMapper.java
backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java
backend/src/main/resources/mapper/usr/UserMapper.xml
backend/src/test/java/com/xly/erp/module/usr/controller/UserControllerIT.java
backend/src/test/java/com/xly/erp/module/usr/mapper/UserMapperSearchIT.java
backend/src/test/java/com/xly/erp/module/usr/service/UserServiceImplTest.java
 package com.xly.erp.module.usr.dto;
  
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import jakarta.validation.constraints.Max;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.Pattern;
@@ -18,7 +17,7 @@ public class UserQueryDTO {
     @Max(100)
     private Integer pageSize = 20;
  
-    /** 可空：缺省视为不过滤；服务层白名单校验后映射到 column 字段 */
+    /** 可空：缺省视为不过滤；服务层白名单映射为 SQL 列名后通过 mapper @Param 单独传入 */
     @Pattern(regexp = "^(username|staffname|userno|department|usertype|language|deleted|lastLoginDate|createdBy)?$",
             message = "queryField 非法")
     private String queryField;
@@ -30,9 +29,4 @@ public class UserQueryDTO {
     /** 可空：缺省视为不过滤 */
     @Size(max = 100)
     private String queryValue;
-
-    /** 服务层白名单映射后的实际 SQL 列名（如 "u.sUserName"）。
-     *  Jackson 忽略——前端不能也无法直接传入；XML mapper 用 ${query.column} 渲染。 */
-    @JsonIgnore
-    private String column;
 }
@@ -9,6 +9,11 @@ import org.apache.ibatis.annotations.Param;
  
 public interface UserMapper extends BaseMapper<UserEntity> {
  
-    /** REQ-USR-003 用户列表查询：跨表 JOIN tStaff，按 query 过滤 + 分页。XML 实现。 */
-    IPage<UserListItemVO> searchUsers(IPage<UserListItemVO> page, @Param("query") UserQueryDTO query);
+    /**
+     * REQ-USR-003 用户列表查询：跨表 JOIN tStaff，按 query 过滤 + 分页。XML 实现。
+     * @param column service 层白名单映射后的 SQL 列字符串（如 "u.sUserName"）；外部输入绝不直接走这里。
+     */
+    IPage<UserListItemVO> searchUsers(IPage<UserListItemVO> page,
+                                       @Param("query") UserQueryDTO query,
+                                       @Param("column") String column);
 }
@@ -187,13 +187,15 @@ public class UserServiceImpl implements UserService {
     @Override
     @Transactional(readOnly = true)
     public PageResult<UserListItemVO> search(UserQueryDTO query) {
-        // 1. queryField 白名单 + 列映射（防 SQL 注入）
+        // 1. queryField 白名单 + 列映射（防 SQL 注入）。
+        //    column 是 service 内部局部变量，通过 mapper @Param("column") 单独传入；不写回 DTO，
+        //    避免 GET query-string 绑定（@JsonIgnore 仅对 Jackson 生效，无法防 setter 注入）。
+        String column = null;
         if (query.getQueryField() != null && !query.getQueryField().isEmpty()) {
-            String mapped = QUERY_COLUMN_MAP.get(query.getQueryField());
-            if (mapped == null) {
+            column = QUERY_COLUMN_MAP.get(query.getQueryField());
+            if (column == null) {
                 throw new BizException(ErrorCode.PARAM_INVALID, "queryField 非法: " + query.getQueryField());
             }
-            query.setColumn(mapped);
         }
  
         // 2. matchType 白名单
@@ -202,13 +204,26 @@ public class UserServiceImpl implements UserService {
             throw new BizException(ErrorCode.PARAM_INVALID, "matchType 非法: " + query.getMatchType());
         }
  
-        // 3. 默认值兜底
+        // 3. spec § 业务规则 6：deleted 字段值标准化（'true'/'1' → '1'；'false'/'0' → '0'；其它非法）
+        if ("deleted".equals(query.getQueryField())
+                && query.getQueryValue() != null && !query.getQueryValue().isEmpty()) {
+            String v = query.getQueryValue().trim().toLowerCase();
+            if ("true".equals(v) || "1".equals(v)) {
+                query.setQueryValue("1");
+            } else if ("false".equals(v) || "0".equals(v)) {
+                query.setQueryValue("0");
+            } else {
+                throw new BizException(ErrorCode.PARAM_INVALID, "deleted queryValue 仅支持 true/false/1/0");
+            }
+        }
+
+        // 4. 默认值兜底
         int pageNum = query.getPageNum() == null ? 1 : query.getPageNum();
         int pageSize = query.getPageSize() == null ? 20 : query.getPageSize();
  
-        // 4. MP 分页查询
+        // 5. MP 分页查询
         IPage<UserListItemVO> page = new Page<>(pageNum, pageSize);
-        IPage<UserListItemVO> result = userMapper.searchUsers(page, query);
+        IPage<UserListItemVO> result = userMapper.searchUsers(page, query, column);
  
         return PageResult.of(result);
     }
@@ -3,7 +3,8 @@
 <mapper namespace="com.xly.erp.module.usr.mapper.UserMapper">
  
     <!-- REQ-USR-003 用户列表查询：LEFT JOIN tStaff + 动态 WHERE。
-         query.column 由 service 层白名单映射，绝不接受用户原始输入。 -->
+         column 由 service 层白名单映射后通过 @Param("column") 单独传入，
+         绝不接受 DTO 中可被 GET query-string 绑定的字段。 -->
     <select id="searchUsers" resultType="com.xly.erp.module.usr.vo.UserListItemVO">
         SELECT
             u.iIncrement, u.sUserName, s.sStaffName, u.sUserNo,
@@ -12,20 +13,26 @@
         FROM tUser u
         LEFT JOIN tStaff s ON u.iStaffId = s.iIncrement AND s.bDeleted = 0
         <where>
-            <if test="query.queryField != 'deleted'">
+            <!-- 默认过滤已软删除：仅当 queryField=='deleted' 且 queryValue 非空时让用户控制 bDeleted 取值 -->
+            <if test="query.queryField != 'deleted' or query.queryValue == null or query.queryValue == ''">
                 u.bDeleted = 0
             </if>
-            <if test="query.column != null and query.column != '' and query.queryValue != null and query.queryValue != ''">
+            <if test="column != null and column != '' and query.queryValue != null and query.queryValue != ''">
                 AND
                 <choose>
+                    <!-- deleted 是 bit(1) 列，MySQL 与字符串 '1'/'0' 隐式比较不可靠；
+                         service 已把 queryValue 标准化为 '0' / '1'，此处显式 CAST 成整数。 -->
+                    <when test="query.queryField == 'deleted'">
+                        ${column} = CAST(#{query.queryValue} AS UNSIGNED)
+                    </when>
                     <when test="query.matchType == 'equals'">
-                        ${query.column} = #{query.queryValue}
+                        ${column} = #{query.queryValue}
                     </when>
                     <when test="query.matchType == 'notContains'">
-                        ${query.column} NOT LIKE CONCAT('%', #{query.queryValue}, '%')
+                        ${column} NOT LIKE CONCAT('%', #{query.queryValue}, '%')
                     </when>
                     <otherwise>
-                        ${query.column} LIKE CONCAT('%', #{query.queryValue}, '%')
+                        ${column} LIKE CONCAT('%', #{query.queryValue}, '%')
                     </otherwise>
                 </choose>
             </if>
@@ -422,13 +422,23 @@ class UserControllerIT {
                 .andExpect(jsonPath("$.data.list[0].sStaffName").value(staffName));
     }
  
-    // get_filterByDeletedTrue_returnsOnlyDeleted 暂时移除
-    // 原因：MyBatis-Plus PaginationInnerInterceptor 与 MySQL bit(1) 列在 String "1" 隐式比较时
-    //       count 与 main SELECT 行为不一致（count=1 但 list=[]）；spec § 业务规则 6 的
-    //       值标准化（'true'/'false' → '1'/'0'）也未实现。
-    // 计划：留作 REQ-USR-004 时统一处理 + 后续 docs sweep 重做。
-    // service 单测 search_invalidQueryField / search_passesMappedColumnToMapper 已覆盖白名单 + 列映射核心；
-    // mapper IT searchUsers_emptyFilter / searchUsers_filterByUserName 已覆盖 SQL 路径骨架。
+    @Test
+    void get_filterByDeletedTrue_returnsOnlyDeleted() throws Exception {
+        // 插一个用户后软删
+        Integer userId = insertUser("del_" + System.nanoTime(), null, List.of());
+        UserEntity patch = new UserEntity();
+        patch.setIIncrement(userId);
+        patch.setBDeleted(true);
+        userMapper.updateById(patch);
+
+        mockMvc.perform(get("/api/users")
+                        .param("queryField", "deleted")
+                        .param("matchType", "equals")
+                        .param("queryValue", "true"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200))
+                .andExpect(jsonPath("$.data.list[?(@.iIncrement==" + userId + ")]").exists());
+    }
  
     @Test
     void get_pagination_returnsCorrectSlice() throws Exception {
@@ -59,7 +59,7 @@ class UserMapperSearchIT {
         insertUser("bob_" + System.nanoTime(), null);
  
         UserQueryDTO query = new UserQueryDTO();
-        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query);
+        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query, null);
  
         assertThat(result.getTotal()).isGreaterThanOrEqualTo(2L);
         assertThat(result.getRecords()).extracting(UserListItemVO::getSUserName)
@@ -74,11 +74,11 @@ class UserMapperSearchIT {
  
         UserQueryDTO query = new UserQueryDTO();
         query.setQueryField("username");
-        query.setColumn("u.sUserName");
         query.setMatchType("contains");
         query.setQueryValue(alicePrefix);
  
-        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query);
+        // column 由 service 层映射；mapper IT 直接传 "u.sUserName"
+        IPage<UserListItemVO> result = userMapper.searchUsers(new Page<>(1, 50), query, "u.sUserName");
  
         assertThat(result.getRecords()).hasSize(1);
         assertThat(result.getRecords().get(0).getSUserName()).startsWith(alicePrefix);
@@ -425,7 +425,7 @@ class UserServiceImplTest {
         UserQueryDTO query = new UserQueryDTO();
         IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
         emptyPage.setTotal(0L);
-        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class))).thenReturn(emptyPage);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
  
         PageResult<UserListItemVO> result = service.search(query);
         assertThat(result.getTotal()).isZero();
@@ -460,13 +460,13 @@ class UserServiceImplTest {
         query.setQueryField("username");
         query.setQueryValue("alice");
         IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
-        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class))).thenReturn(emptyPage);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
  
         service.search(query);
  
-        ArgumentCaptor<UserQueryDTO> cap = ArgumentCaptor.forClass(UserQueryDTO.class);
-        verify(userMapper).searchUsers(any(IPage.class), cap.capture());
-        assertThat(cap.getValue().getColumn()).isEqualTo("u.sUserName");
+        ArgumentCaptor<String> colCap = ArgumentCaptor.forClass(String.class);
+        verify(userMapper).searchUsers(any(IPage.class), any(UserQueryDTO.class), colCap.capture());
+        assertThat(colCap.getValue()).isEqualTo("u.sUserName");
     }
  
     @Test
@@ -475,14 +475,30 @@ class UserServiceImplTest {
         query.setPageNum(null);
         query.setPageSize(null);
         IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
-        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class))).thenReturn(emptyPage);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
  
         service.search(query);
  
         ArgumentCaptor<IPage> pageCap = ArgumentCaptor.forClass(IPage.class);
-        verify(userMapper).searchUsers(pageCap.capture(), any(UserQueryDTO.class));
+        verify(userMapper).searchUsers(pageCap.capture(), any(UserQueryDTO.class), any());
         IPage<?> page = pageCap.getValue();
         assertThat(page.getCurrent()).isEqualTo(1L);
         assertThat(page.getSize()).isEqualTo(20L);
     }
+
+    @Test
+    void search_deletedQueryValueTrue_normalizedToOne() {
+        UserQueryDTO query = new UserQueryDTO();
+        query.setQueryField("deleted");
+        query.setQueryValue("true");
+        query.setMatchType("equals");
+        IPage<UserListItemVO> emptyPage = new Page<>(1, 20);
+        when(userMapper.searchUsers(any(IPage.class), any(UserQueryDTO.class), any())).thenReturn(emptyPage);
+
+        service.search(query);
+
+        ArgumentCaptor<UserQueryDTO> cap = ArgumentCaptor.forClass(UserQueryDTO.class);
+        verify(userMapper).searchUsers(any(IPage.class), cap.capture(), any());
+        assertThat(cap.getValue().getQueryValue()).isEqualTo("1");
+    }
 }