2026-04-30-REQ-USR-003.md 6.31 KB

Edit Raw Blame History



req_id: REQ-USR-003
date: 2026-04-30


spec_ref: docs/superpowers/specs/2026-04-30-REQ-USR-003.md


REQ-USR-003 用户查询 Implementation Plan


Execution: Parent skill feature-tdd executes this plan task-by-task.


Goal: 实现 GET /api/usr/users 单条件分页查询：tUser LEFT JOIN tStaff，按 field × match × value 动态过滤。

Architecture: 新增 UserListVO + UserListQuery 内部封装类（field/match/value/page）+ UserMapper#pageWithFilter 自定义动态 SQL + UserService#list + controller @GetMapping。

Tech Stack: 沿用；MyBatis 动态 SQL <script> + <foreach> / <if>。


Schema 改动

无。


文件变更清单


新增


backend/src/main/java/com/xly/erp/module/usr/vo/UserListVO.java

backend/src/main/java/com/xly/erp/module/usr/dto/UserListQuery.java（内部封装规范化后的查询参数）


修改


backend/src/main/java/com/xly/erp/module/usr/mapper/UserMapper.java — 追加 pageWithFilter + countWithFilter


backend/src/main/resources/mapper/usr/UserMapper.xml — 新建 XML（动态 SQL 复杂，注解 @Select 不易读）

backend/src/main/java/com/xly/erp/module/usr/service/UserService.java — 追加 list(...)


backend/src/main/java/com/xly/erp/module/usr/service/impl/UserServiceImpl.java — 实现 list（字段映射 + 校验 + 调 mapper）

backend/src/main/java/com/xly/erp/module/usr/controller/UserController.java — 追加 GET 端点
测试：UserMapperIT(+1) / UserServiceImplTest(+10) / UserControllerIT(+8)


任务步骤


Task 1: UserListVO + UserMapper#pageWithFilter / countWithFilter + IT

Files:


Create: vo/UserListVO.java
Modify: mapper/UserMapper.java + resources/mapper/usr/UserMapper.xml
Modify: test/.../mapper/UserMapperIT.java


API shape:


UserListVO 11 字段（参 spec），@JsonProperty 锁定 JSON 名

UserMapper.pageWithFilter（XML）参数：@Param("field") String physicalCol, @Param("match") String matchOp, @Param("value") Object value, @Param("offset") int offset, @Param("size") int size；physicalCol 由 service 映射成 u.sUserName / s.sStaffName 等

UserMapper.countWithFilter 同参数（除 offset/size）


XML 关键结构：
<select id="pageWithFilter" resultType="com.xly.erp.module.usr.vo.UserListVO">
  SELECT u.iIncrement, u.sUserName, s.sStaffName AS staffName, u.sUserNo,
         s.sDepartment AS department, u.sUserType, u.sLanguage,
         u.bDeleted, u.tLastLoginDate, u.sCreatedBy, u.tCreateDate
  FROM tUser u
  LEFT JOIN tStaff s ON s.iIncrement = u.iStaffId AND s.bDeleted = 0
  <where>
    <if test="value != null and value != ''">
      <choose>
        <when test="matchOp == 'contains'">${field} LIKE CONCAT('%', #{value}, '%')</when>
        <when test="matchOp == 'notContains'">${field} NOT LIKE CONCAT('%', #{value}, '%')</when>
        <when test="matchOp == 'equals'">
          <choose>
            <when test="field == 'DATE(u.tLastLoginDate)'">${field} = #{value}</when>
            <otherwise>${field} = #{value}</otherwise>
          </choose>
        </when>
      </choose>
    </if>
  </where>
  ORDER BY u.iIncrement DESC
  LIMIT #{offset}, #{size}
</select>


（XML 复杂度由 service 提供归一化的 field(物理列名 with prefix) / matchOp(英文常量) / value 后大幅简化）


 Step 1: 写失败 IT pageWithFilter_filtersAndJoins

 Step 2: 实现 entity/VO + mapper + XML

 Step 3: 子会话验证 PASS

 Step 4: Commit：feat(usr): user list mapper + vo with join REQ-USR-003


Task 2: UserListQuery + UserService.list 主流程（合法 + 字段映射）

Files:


Create: dto/UserListQuery.java（service 内部）
Modify: service/UserService.java + impl/UserServiceImpl.java
Modify: test/.../service/UserServiceImplTest.java


API shape:


UserService#list(String field, String match, String value, Integer pageNum, Integer pageSize) : Map<String, Object>（返回 records/total/pageNum/pageSize）
内部：归一化（默认值/trim）→ field/match 校验 → value 解析（日期/布尔）→ 调 mapper.countWithFilter + pageWithFilter → 装结果 Map


字段映射表（service 静态常量）：
"用户名"   -> ("u.sUserName", STRING)
"员工名"   -> ("s.sStaffName", STRING)
"用户号"   -> ("u.sUserNo", STRING)
"部门"     -> ("s.sDepartment", STRING)
"用户类型" -> ("u.sUserType", STRING)
"作废"     -> ("u.bDeleted", BOOLEAN)
"登录日期" -> ("DATE(u.tLastLoginDate)", DATE)
"制单人"   -> ("u.sCreatedBy", STRING)


match 映射：包含→contains，不包含→notContains，等于→equals

校验顺序：pageSize 上限 → field 枚举 → match 枚举 → field/match 兼容（布尔/日期仅 equals）→ value 解析（日期）


 Step 1: 写失败测试 4 条主流程用例


listWithDefaults_invokesMapperWithUserNameContainsEmpty
listWithEmptyValue_skipsFilterCondition
listWithKeywordTrim
listReturnsEmptyRecords_whenMapperReturnsEmptyPage


 Step 2: 实现 service

 Step 3: 子会话验证 PASS

 Step 4: Commit：feat(usr): user list service + field/match mapping REQ-USR-003


Task 3: Service 异常分支（field/match/兼容/pageSize/日期格式/布尔）


 Step 1: 追加 6 用例


listWithInvalidField_throws40001
listWithInvalidMatch_throws40001
listWithIncompatibleFieldMatch_throws40001
listWithPageSizeExceeds100_throws40002
listWithInvalidLoginDateFormat_throws40001
listWithBooleanFieldEqualsTrue_passesIntegerOne


 Step 2: 实现校验分支

 Step 3: 子会话验证 PASS（期望 18 + 4 + 6 = 28 用例）
 Step 4: Commit：feat(usr): user list error branches REQ-USR-003


Task 4: Controller GET + 8 IT + 全量回归


 Step 1: 追加 8 IT（参 spec 验收清单）
 Step 2: 实现 controller GET

 Step 3: 子会话跑全量回归（期望 ≥ 129 用例）
 Step 4: Commit：test(usr): user list integration coverage REQ-USR-003


提交计划


commit
覆盖


feat(usr): user list mapper + vo with join REQ-USR-003
Task 1


feat(usr): user list service + field/match mapping REQ-USR-003
Task 2


feat(usr): user list error branches REQ-USR-003
Task 3


test(usr): user list integration coverage REQ-USR-003
Task 4