diff --git a/docs/08-模块任务管理.md b/docs/08-模块任务管理.md index fb78b84..19d2cea 100644 --- a/docs/08-模块任务管理.md +++ b/docs/08-模块任务管理.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 阶段（前端整体） diff --git a/docs/superpowers/plans/2026-05-15-REQ-USR-004.md b/docs/superpowers/plans/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..5dc3adb --- /dev/null +++ b/docs/superpowers/plans/2026-05-15-REQ-USR-004.md @@ -0,0 +1,325 @@ +--- +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（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 { + List 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 { records: List; 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` +- `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 + + FROM sys_user u + LEFT JOIN sys_employee e ON e.iIncrement = u.iEmployeeId + LEFT JOIN sys_department d ON d.iIncrement = e.iDepartmentId + + + + + + + + AND ${p.sqlQueryColumn} LIKE CONCAT('%', #{p.queryValue}, '%') + + + AND (${p.sqlQueryColumn} NOT LIKE CONCAT('%', #{p.queryValue}, '%') + OR ${p.sqlQueryColumn} IS NULL) + + + AND ${p.sqlQueryColumn} = #{p.queryValue} + + + + AND u.sUserType = #{p.userType} + AND u.iIsDeleted = #{p.isDeleted} + + + + + + +``` + +> 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` +- 内部规范化流程： + 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>` +- 用 `@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` | diff --git a/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md b/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..f00d40d --- /dev/null +++ b/docs/superpowers/reviews/2026-05-15-REQ-USR-004.md @@ -0,0 +1,39 @@ +--- +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。 diff --git a/docs/superpowers/specs/2026-05-15-REQ-USR-004.md b/docs/superpowers/specs/2026-05-15-REQ-USR-004.md new file mode 100644 index 0000000..eb4ed6e --- /dev/null +++ b/docs/superpowers/specs/2026-05-15-REQ-USR-004.md @@ -0,0 +1,167 @@ +--- +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 ` + `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>` + +```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）： + - `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 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