docs(mod): review approval REQ-MOD-004

zichun
1 parent a46be5d2
Showing 4 changed files with 348 additions and 1 deletions
docs/08-模块任务管理.md
docs/superpowers/plans/2026-05-06-REQ-MOD-004.md
docs/superpowers/reviews/2026-05-06-REQ-MOD-004.md
docs/superpowers/specs/2026-05-06-REQ-MOD-004.md
@@ -63,7 +63,7 @@
     - [x] REQ-MOD-001 模块新增
     - [x] REQ-MOD-002 模块修改
     - [x] REQ-MOD-003 模块删除
-    - [ ] REQ-MOD-004 模块查询
+    - [x] REQ-MOD-004 模块查询
  
 - module_usr 用户管理
   - 依赖: —
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-004.md
+---
+
+# REQ-MOD-004 模块查询 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `GET /api/modules?keyword=...`：返回未软删除模块的树形结构，可选按 `sModuleNameZh` 模糊匹配并保留命中节点的祖先链。
+
+**Architecture:** 一次性 selectList 拉所有未删除模块到内存，按 keyword 过滤命中集合，沿父链向上收集祖先合并到结果集，最后在内存按 iParentId 组装树。同级按 iSortOrder ASC + iIncrement ASC 排序。叶子 `children=[]`。
+
+**Tech Stack:** 沿用 REQ-MOD-001~003。
+
+---
+
+## Schema 改动
+
+无。
+
+## 文件变更清单
+
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleTreeNodeVO.java` — 树形节点 VO（7 字段 + children 列表）
+- 创建: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java` — 查询参数 DTO（keyword）
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 追加 `tree(ModuleQueryDTO query): List<ModuleTreeNodeVO>`
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 实现 tree
+- 修改: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 追加 `@GetMapping`
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 追加 6 个 tree 单测
+- 修改: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 追加 7 个 GET 集成测试
+
+## 任务步骤
+
+### Task 1: VO + DTO
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleTreeNodeVO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java`
+
+**API shape:**
+- `ModuleTreeNodeVO`：7 字段 + `List<ModuleTreeNodeVO> children`，Lombok `@Data`，含静态工厂 `from(ModuleEntity e)`（创建带空 children 列表的节点）。
+- `ModuleQueryDTO`：单字段 `@Size(max=50) String keyword`（可空）。Bean Validation 由 controller 触发。
+
+- [ ] **Step 1.1 创建 VO + DTO（无独立单测；Bean Validation 在 IT 层覆盖）**
+
+- [ ] **Step 1.2 提交**
+  - `git commit -m "feat(mod): module tree VO + query DTO REQ-MOD-004"`
+
+---
+
+### Task 2: ModuleService.tree — 树构建逻辑（mock 单元测试）
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`
+
+**API shape:**
+- `interface ModuleService` 追加：`List<ModuleTreeNodeVO> tree(ModuleQueryDTO query)`
+- 实现步骤：
+  1. `all = moduleMapper.selectList(LambdaQueryWrapper.eq(BDeleted, false))`
+  2. 若 `query.keyword == null || keyword.isEmpty()` → 跳到步骤 5（用全量构树）
+  3. 否则在 `all` 内存里筛选 `hits = all.filter(e -> e.sModuleNameZh.contains(keyword))`
+  4. 对每个 hit 沿 `iParentId` 链向上收集祖先（用 `byId = all.stream().toMap(IIncrement)` 索引）；合并到 `survivors = hits ∪ ancestors`
+  5. 按 iIncrement 索引 `survivors`，按 iParentId 分组子节点列表，同级按 (iSortOrder, iIncrement) ASC 排序
+  6. 取 `iParentId == null || iParentId not in survivors` 的节点作为根（这样过滤后一些祖先链断裂的节点也会被提到根，避免孤立）；递归挂 children
+  7. 返回根节点列表
+- 标 `@Transactional(readOnly = true)`
+
+**关键不变量**（写入 plan 锁定）：
+- 叶子节点 `children = new ArrayList<>()`，**不为 null**
+- 排序键稳定：`Comparator.comparingInt(ModuleTreeNodeVO::getISortOrder).thenComparingInt(ModuleTreeNodeVO::getIIncrement)`
+- 祖先链深度上限 5（与 docs/03 § tModule 注记一致）；超 5 仍向上视为业务异常并记一行 `log.warn`，不抛错（不影响 200 返回）
+
+- [ ] **Step 2.1 写失败测试（6 个）**
+  - `tree_emptyDb_returnsEmptyList`：mapper.selectList 返回空 → service 返回 `List.of()`
+  - `tree_singleRoot_returnsOneNodeWithEmptyChildren`：1 个 root，断言返回 list 长度 1，children 是 `[]`
+  - `tree_multiLevel_buildsNestedStructureSortedByISortOrder`：root(sort=2) + root(sort=1) + child of root1，断言返回顺序 [sort=1, sort=2]，root1.children 包含 child
+  - `tree_keywordHit_includesAncestorChain`：grandparent → parent → child（sModuleNameZh 各不同），keyword 匹配 child；断言返回 grandparent → parent → child 三层
+  - `tree_keywordNoMatch_returnsEmptyList`
+  - `tree_softDeletedExcluded`（验证 mapper 调用时 wrapper 含 `eq(bDeleted, false)`；ArgumentCaptor<Wrapper>）
+  - 测试方式：`@ExtendWith(MockitoExtension.class)`，构造 `List<ModuleEntity>` 喂 mock 返回值
+  - 子会话: FAIL（方法不存在）
+
+- [ ] **Step 2.2 实现 service.tree**
+  - 子会话: PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(mod): query module tree service REQ-MOD-004"`
+
+---
+
+### Task 3: ModuleController GET 端点 + 端到端 IT
+
+**Files:**
+- Modify: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Modify: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`
+
+**API shape:**
+- 新方法：
+  ```
+  @GetMapping
+  public ApiResponse<List<ModuleTreeNodeVO>> tree(@Valid ModuleQueryDTO query)
+  ```
+- Javadoc：`REQ-MOD-004 模块查询 — REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:READ')")`
+- `@Valid` 触发 Bean Validation；keyword 长度超限 → MethodArgumentNotValidException → GlobalExceptionHandler → 40010
+
+> **注意**：query 参数对象用 `@Valid ModuleQueryDTO` 时，Spring MVC 会把 `keyword` query 参数绑定到 DTO 字段（无需 @ModelAttribute，bean 类型默认走 query string）。
+
+- [ ] **Step 3.1 写失败测试（7 个）**
+  - `get_emptyKeyword_returnsAllUndeletedAsTree`：先 mapper.insert 几条（含 root + child + soft-deleted），GET 不带 keyword；断言 200 + data 长度等于未删 root 数；递归断言子树。
+  - `get_keyword_filtersByModuleNameZhWithAncestors`：插入 grandparent("系统配置") → parent("用户管理") → child("登录")；GET `?keyword=登录`；断言返回三层链。
+  - `get_keywordNoMatch_returnsEmptyArray`：GET `?keyword=不存在`，断言 `data=[]`，code=200。
+  - `get_keywordTooLong_returns40010`：keyword 51 字符。
+  - `get_softDeletedNotInResult`：插入一条并立即 update bDeleted=1，GET 全量，断言不在结果。
+  - `get_responseExcludesInternalFields`：断言 `$.data[0].sProcedureName` doesNotExist；同时验证 `sModuleType` / `bShowPermission` / `tCreateDate` / `bDeleted` 不出现。
+  - `get_leafNodeChildrenIsEmptyArrayNotNull`：断言叶子 `$.data[*].children` is array 且 length=0（非 null）。
+  - 测试方式：`@SpringBootTest @AutoConfigureMockMvc @Transactional @Rollback` + `@Autowired ModuleMapper`
+  - 子会话: FAIL（端点不存在）
+
+- [ ] **Step 3.2 实现 GET 端点**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 跑全量 backend 测试**
+  - 期望累计 47 + 6(service tree) + 7(controller GET) = 60 个，全绿（mvn 报数会因共享 context 而合并）
+
+- [ ] **Step 3.4 提交**
+  - `git commit -m "feat(mod): GET /api/modules controller REQ-MOD-004"`
+
+---
+
+## 提交计划
+
+- `feat(mod): module tree VO + query DTO REQ-MOD-004`（Task 1）
+- `feat(mod): query module tree service REQ-MOD-004`（Task 2）
+- `feat(mod): GET /api/modules controller REQ-MOD-004`（Task 3）
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-004 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:530 — 补 IT 覆盖 spec § 验收 #7『同级排序』：插入 root(iSortOrder=2) + root(iSortOrder=1)，断言 GET 返回数组首个 iIncrement 是 sort=1 那条。当前同级排序仅在单测覆盖，缺端到端断言。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:530 — 补 IT 覆盖 spec § 验收 #6『keyword 含中英混合』：插入 sModuleNameZh='user 用户'，GET ?keyword=user 用户 命中。
+- backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java:497 — `tree_softDeletedExcluded` 仅 verify(...).selectList(any())，未捕 wrapper 形状（plan 要求 ArgumentCaptor）。建议改名或真用 ArgumentCaptor 抽 `wrapper.getTargetSql()` 断言含 `bDeleted = 0`。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:227 — Comparator 对 iSortOrder 做了 null→0 防御，但 docs/03 已注明 NOT NULL；可简化为 `Comparator.comparingInt(ModuleTreeNodeVO::getISortOrder).thenComparingInt(::getIIncrement)`。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:198 — `survivorIds = byId.keySet()` 是 live view，与 keyword 分支返回的独立 HashSet 类型不一致；建议改成 `new HashSet<>(byId.keySet())` 一致化。
+- backend/pom.xml:121 — surefire includes 修改是项目级配置；建议在 docs/04 测试规范节追加一行说明『*IT.java 走 surefire (mvn test) 而非 failsafe (mvn verify)』，避免后续贡献者破坏 includes。
+- docs/03-数据库设计文档.md § tModule 业务注记 — 建议追加一行『模块树最大深度 5 层（iParentId 自引用），由 service 层校验，REQ-MOD-002 / REQ-MOD-004 引用本约束』，把深度上限提升为 SSoT。
+- backend/src/main/java/com/xly/erp/module/mod/dto/ModuleQueryDTO.java:11 — 在 @Size 上方 javadoc 写明『empty 视为不过滤』。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 #7 同级排序的端到端 IT 缺失（仅单测）。
+2. spec § 验收 #6 中英混合 keyword 没有专属 IT。
+3. `tree_softDeletedExcluded` 单测断言强度低于 plan 期望。
+4. 反例缺：keyword 含 SQL 通配符 `%` / `_`（spec 声明本期不转义，作为已知边界）。
+5. 反例缺：祖先链深度 ≥ 5 的截断边界用例；docs/03 已限深度 5，正常打不到边界，可后续补 6 层强构数据单测固化截断语义。
+6. Controller javadoc 标了『REQ-USR-004 完成后追加 @PreAuthorize』但缺集中跟踪——建议在 docs/08 § 二 USR-004 子项挂 follow-up 备注。
+
+**核心结论**：实现忠实于 spec — keyword 过滤 + 祖先链 walk-up + 内存树构造 + 同级 (iSortOrder, iIncrement) 排序 + 叶子 children=[] 全部正确。API 契约字段精简到位（VO 7 个公开字段 + children）。surefire includes 修复是揭示性发现——本仓库之前 *IT.java 没在 mvn test 跑过，REQ-MOD-001/002/003 的 IT 都是"死代码"；本 REQ commit body 已披露，REQ-MOD-004 的 IT 是首次在 mvn test 跑通。
+---
+req_id: REQ-MOD-004
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-004 — 模块查询
+
+## 目标
+
+实现后端 `GET /api/modules` 接口：以**树形结构**返回所有未软删除的模块，可选按 `sModuleNameZh` 模糊匹配过滤；过滤命中时同时保留命中节点的所有**祖先路径**以便定位上下文。
+
+## 输入 / 触发
+
+**接口**：`GET /api/modules`，无请求体。
+
+**Query parameters**：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 |
+|---|---|---|---|
+| `keyword` | String | 否 | 长度 ≤ 50；非空时对 `sModuleNameZh` 做 `LIKE '%keyword%'`（不区分大小写——MySQL `utf8mb4_unicode_ci` 默认行为） |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:READ`。沿用 SecurityConfig permitAll；Controller Javadoc：`REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:READ')")`。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": [
+    {
+      "iIncrement": 1,
+      "sModuleNameZh": "系统配置",
+      "sDisplayType": "系统配置",
+      "sManageDeptEn": "IT",
+      "iParentId": null,
+      "iSortOrder": 0,
+      "children": [
+        {
+          "iIncrement": 2,
+          "sModuleNameZh": "用户管理",
+          "sDisplayType": "前端业务",
+          "sManageDeptEn": "IT",
+          "iParentId": 1,
+          "iSortOrder": 1,
+          "children": []
+        }
+      ]
+    }
+  ],
+  "timestamp": 1746528600000
+}
+```
+
+`data` 是根节点数组（`iParentId == null` 的节点）；每个节点带 `children` 数组（同结构递归）。
+
+新增 VO `ModuleTreeNodeVO`：字段 `iIncrement` / `sModuleNameZh` / `sDisplayType` / `sManageDeptEn` / `iParentId` / `iSortOrder` / `children: List<ModuleTreeNodeVO>`。
+
+> **不返回的字段**（避免泄露内部）：`sProcedureName` / `sModuleType` / `bShowPermission` / `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `sCreatedBy` / `bDeleted` / `tDeletedDate` / `sDeletedBy`。如未来 REQ 需要其中字段，再扩 VO。
+
+## 业务规则
+
+1. **范围过滤**：`bDeleted = 0`（默认仅返回未软删除）。
+2. **空 keyword**：返回所有未软删除模块构成的完整树。
+3. **非空 keyword**：
+   - 步骤 a：在所有未软删除模块中找出 `sModuleNameZh LIKE '%keyword%'` 的命中集合 `hits`。
+   - 步骤 b：对每个 `hit`，沿 `iParentId` 链向上收集所有未软删除祖先（深度上限 5 与 docs/03 § tModule 一致），并入结果集合。
+   - 步骤 c：用结果集合在内存中按 `iParentId` 组装树。
+   - 命中节点本身的子孙不会被强制纳入（除非也命中）；这样避免一次过滤拉出整棵子树。
+4. **排序**：同级节点按 `iSortOrder ASC` 升序，`iSortOrder` 相同则按 `iIncrement ASC`（确定性排序）。
+5. **`children` 字段**：叶子节点为 `[]`，不为 `null`（确保前端可直接 `.map`）。
+6. **空结果**：keyword 无匹配 → `data = []`，**HTTP 200 + code=200**，不返回 404 类错误。
+7. **只读**：本接口不写库，无事务要求；标 `@Transactional(readOnly = true)`。
+
+## 边界与约束
+
+### 鉴权策略
+
+沿用 REQ-MOD-001/002/003 SecurityConfig permitAll。
+
+### 错误码
+
+| 场景 | 错误码 | ErrorCode 枚举 |
+|---|---|---|
+| `keyword` 长度 > 50 | 40010 | `PARAM_INVALID`（已存在） |
+| 服务端兜底 | 50000 | `INTERNAL_ERROR` |
+
+### 性能
+
+- 单次 `selectList(LambdaQueryWrapper.eq(bDeleted, false))` 拉取所有未删除模块；spec § 性能上限 docs/03 注明"单次返回不超过 500 项 / 树深度上限 5 层"，本期数据量低不分页。
+- 在内存里 O(N) 建索引（id → entity）+ O(N) 建子节点列表 + O(N) 排序 + O(K * D) 沿祖先链向上（K=hits 数，D=深度上限 5）。
+- 不引入 SQL 递归 CTE / 自连接；保持 mapper 层轻量。
+
+### 大小写敏感
+
+`utf8mb4_unicode_ci` collation 默认不区分大小写。MyBatis-Plus `LambdaQueryWrapper.like(...)` 走 SQL `LIKE`，行为与 collation 一致。无需额外处理。
+
+### keyword 中的特殊字符
+
+`%` / `_` 在 SQL `LIKE` 模式里是通配符。简化处理：本期不做转义（业务模块名通常不含这些字符）；如未来需要，service 层先把 keyword 中的 `%` / `_` / `\` 替换为转义形式（`MyBatis-Plus 5.x` 的 `like` 已自带 escape，本期 3.5.7 需手动）。**本 REQ 暂不处理转义**，作为已知边界记录。
+
+## 依赖的 schema 表 / 字段
+
+**读表**：`tModule`
+
+| 字段 | 用途 |
+|---|---|
+| `iIncrement` | 节点 id；输出 |
+| `sModuleNameZh` | 模糊匹配列；输出 |
+| `sDisplayType` | 输出 |
+| `sManageDeptEn` | 输出 |
+| `iParentId` | 父子关系；输出 |
+| `iSortOrder` | 排序；输出 |
+| `bDeleted` | 过滤未删除（=0） |
+
+**索引利用**：
+- `idx_module_name_zh`：`LIKE '%keyword%'` 实际不走索引（左模糊），但本期数据量低可接受。
+- `idx_parent`：祖先链查询时按 iIncrement PK 走 selectById，不用 idx_parent。
+- `idx_module_deleted`（未单独建，但 bDeleted 在多个 idx 中已有）：bDeleted 过滤时 MySQL 优化器自行选择。
+
+**外键**：本接口只读，不触发 FK 检查。
+
+## 依赖的接口
+
+无（独立查询接口）。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 空 keyword 返回完整树**：DB 中 5 棵根 + 多层子模块；GET 返回 5 个根节点，子孙完整嵌套；同级按 iSortOrder 升序。
+2. **正向 — keyword 模糊匹配 + 祖先**：DB 有 root("系统配置") → 子("用户管理") → 孙("登录")；GET `?keyword=登录` 返回 root → 子 → 孙 三层（即命中节点 + 全部祖先）。
+3. **正向 — keyword 部分匹配**：keyword="管理"，匹配多个节点；返回它们各自完整祖先链合并的树。
+4. **正向 — 软删除模块过滤**：DELETE 一个模块后再查，结果不含该模块。
+5. **正向 — 空结果**：keyword="不存在的关键词"，返回 `data=[]` + code=200。
+6. **正向 — keyword 含中英混合**：keyword="user 用户" 也走 LIKE '%user 用户%'（与 spec § 业务规则 3 一致；不拆词）。
+7. **同级排序**：两根 iSortOrder=2/1，返回顺序 1 在前。
+8. **children 字段**：叶子节点 children 是 `[]` 而非 null（jsonPath 断言）。
+9. **keyword 长度超限**：keyword=51 字符，返回 `code=40010`。
+10. **无登录也可访问**（permitAll 阶段）：直接 GET 不带 Authorization 返回 200。
+11. **响应字段精简**：响应不含 sProcedureName / sModuleType / bShowPermission / 标准列等内部字段（jsonPath 断言）。
+
+### 接口契约一致性
+
+- 响应格式 `{code, message, data, timestamp}`。
+- 错误码 200 / 40010 / 50000。
+- 不回显堆栈。
+
+### 测试覆盖
+
+- **单元测试** `ModuleServiceImplTest` 追加（mock ModuleMapper）：
+  - tree_emptyDb_returnsEmptyList
+  - tree_singleRoot_returnsOneNodeWithEmptyChildren
+  - tree_multiLevel_buildsNestedStructureSortedByISortOrder
+  - tree_keywordHit_includesAncestorChain
+  - tree_keywordNoMatch_returnsEmptyList
+  - tree_softDeletedExcluded（mapper 已过滤；service 不重复过滤）
+
+- **集成测试** `ModuleControllerIT` 追加：
+  - get_emptyKeyword_returnsAllUndeletedAsTree
+  - get_keyword_filtersByModuleNameZhWithAncestors
+  - get_keywordNoMatch_returnsEmptyArray
+  - get_keywordTooLong_returns40010
+  - get_softDeletedNotInResult
+  - get_responseExcludesInternalFields
+  - get_leafNodeChildrenIsEmptyArrayNotNull
+
+### 代码与文档
+
+- `// REQ-MOD-004` 注释贴在 Controller / Service / VO。
+- 提交按 `feat(mod): <subject> REQ-MOD-004` 规范。