chore(usr): REQ-USR-004 review approve + 归档 spec/plan/review

zichun
1 parent 8bf84c92
Showing 4 changed files with 532 additions and 1 deletions
docs/08-模块任务管理.md
docs/superpowers/plans/2026-05-15-REQ-USR-004.md
docs/superpowers/reviews/2026-05-15-REQ-USR-004.md
docs/superpowers/specs/2026-05-15-REQ-USR-004.md
@@ -63,7 +63,7 @@
     - [x] REQ-USR-001 用户登录
     - [x] REQ-USR-002 新增用户
     - [x] REQ-USR-003 修改用户
-    - [ ] REQ-USR-004 查询用户
+    - [x] REQ-USR-004 查询用户
  
 ## 三、Coding 阶段（前端整体）
  
+---
+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<UserListItemVo>（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<UserListItemVo>>
+
+PageResult<T> {
+  List<T> 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<T> { records: List<T>; 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<UserListItemRow>`
+- `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
+<sql id="baseFrom">
+  FROM sys_user u
+  LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId
+  LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId
+</sql>
+
+<sql id="whereClause">
+  <where>
+    <if test="p.sqlQueryColumn != null and p.queryValue != null and p.queryValue != ''">
+      <choose>
+        <when test="p.matchMode == 'contains'">
+          AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%')
+        </when>
+        <when test="p.matchMode == 'notContains'">
+          AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%')
+               OR ${p.sqlQueryColumn} IS NULL)
+        </when>
+        <otherwise>
+          AND ${p.sqlQueryColumn} = #{p.queryValue}
+        </otherwise>
+      </choose>
+    </if>
+    <if test="p.userType != null">AND u.sUserType = #{p.userType}</if>
+    <if test="p.isDeleted != null">AND u.iIsDeleted = #{p.isDeleted}</if>
+  </where>
+</sql>
+
+<select id="selectByQuery" resultType="com.xly.erp.module.usr.vo.UserListItemVo">
+  SELECT u.iIncrement AS userId, u.sUsername AS username,
+         e.sEmployeeName AS employeeName, u.sUserCode AS userCode,
+         d.sDepartmentName AS departmentName, u.sUserType AS userType,
+         u.sLanguage AS language, u.iIsDeleted AS isDeleted,
+         u.tLastLoginDate AS lastLoginDate, u.sCreatedBy AS createdBy,
+         u.tCreateDate AS createdDate
+  <include refid="baseFrom"/>
+  <include refid="whereClause"/>
+  ORDER BY u.${p.sqlSortField} ${p.sqlSortOrder}
+  LIMIT #{p.offset}, #{p.limit}
+</select>
+
+<select id="countByQuery" resultType="long">
+  SELECT COUNT(*)
+  <include refid="baseFrom"/>
+  <include refid="whereClause"/>
+</select>
+```
+
+> 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<UserListItemVo>`
+- 内部规范化流程：
+  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<PageResult<UserListItemVo>>`
+- 用 `@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` |
+---
+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。
+---
+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 <accessToken>` + `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<PageResult<UserListItemVo>>`
+
+```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<String, String>）：
+   - `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 <col> 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