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

zichun
1 parent c0da0c5f
Showing 4 changed files with 571 additions and 1 deletions
docs/08-模块任务管理.md
docs/superpowers/plans/2026-05-06-REQ-MOD-001.md
docs/superpowers/reviews/2026-05-06-REQ-MOD-001.md
docs/superpowers/specs/2026-05-06-REQ-MOD-001.md
@@ -60,7 +60,7 @@
   - 路径: backend/src/main/java/com/xly/erp/module/mod/, frontend/src/pages/mod/
   - MR: —
   - 功能:
-    - [ ] REQ-MOD-001 模块新增
+    - [x] REQ-MOD-001 模块新增
     - [ ] REQ-MOD-002 模块修改
     - [ ] REQ-MOD-003 模块删除
     - [ ] REQ-MOD-004 模块查询
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+spec_ref: docs/superpowers/specs/2026-05-06-REQ-MOD-001.md
+---
+
+# REQ-MOD-001 模块新增 Implementation Plan
+
+> **Execution:** Parent skill `feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 实现 `POST /api/modules` 接口，把一条新业务模块写入 `tModule`，并顺带建立服务于本 REQ 的最小 Spring Boot 骨架。
+
+**Architecture:** 标准三层（Controller → Service → Mapper）。Spring Boot 3 + MyBatis-Plus + Flyway 自动 apply migrations。鉴权暂以 `SecurityConfig` permitAll 占位，REQ-USR-004 时回头收紧。统一响应 `ApiResponse<T>`、统一异常 `BizException` + `GlobalExceptionHandler`。
+
+**Tech Stack:** Spring Boot 3.x、MyBatis-Plus（spring-boot3-starter）、Flyway 10.x、MySQL 8、JUnit 5 + Spring Boot Test + MockMvc + Spring Security Test、Hutool、MapStruct（可选）、Maven 3.9。
+
+---
+
+## Schema 改动
+
+无（`tModule` 已由 A4 `V1__initial_schema.sql` 创建）。
+
+## 文件变更清单
+
+- `backend/pom.xml` — 创建（Spring Boot 父 pom + 依赖清单）
+- `backend/src/main/java/com/xly/erp/ErpApplication.java` — 创建（启动类）
+- `backend/src/main/resources/application.yml` — 创建（DB / Flyway / MyBatis-Plus / 端口配置，从环境变量注入）
+- `backend/src/main/resources/application-test.yml` — 创建（测试 profile，连 DB_SCHEMA test 库）
+- `backend/src/main/java/com/xly/erp/common/response/ApiResponse.java` — 创建（统一响应包装）
+- `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java` — 创建（错误码枚举）
+- `backend/src/main/java/com/xly/erp/common/exception/BizException.java` — 创建（业务异常）
+- `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java` — 创建（@RestControllerAdvice）
+- `backend/src/main/java/com/xly/erp/config/SecurityConfig.java` — 创建（permitAll 临时配置）
+- `backend/src/main/java/com/xly/erp/config/MybatisPlusConfig.java` — 创建（分页插件，本 REQ 不用，REQ-MOD-004 用，本任务先建空骨架）
+- `backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java` — 创建（@TableName("tModule")）
+- `backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java` — 创建（继承 BaseMapper）
+- `backend/src/main/resources/mapper/mod/ModuleMapper.xml` — 创建（空骨架，本 REQ 仅用 BaseMapper 默认 SQL）
+- `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java` — 创建（入参 + Bean Validation）
+- `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleVO.java` — 创建（出参）
+- `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java` — 创建（接口）
+- `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java` — 创建（实现，含 create 方法）
+- `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java` — 创建（POST /api/modules）
+- `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java` — 创建（单元）
+- `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java` — 创建（单元）
+- `backend/src/test/java/com/xly/erp/module/mod/mapper/ModuleMapperIT.java` — 创建（@SpringBootTest 集成）
+- `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java` — 创建（单元 + Mockito）
+- `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java` — 创建（MockMvc + @SpringBootTest）
+- `backend/src/test/resources/application-test.yml` — 创建（测试 profile 副本，便于 IDE 跑测试）
+- `.env.local` — 不修改（已有 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA / JWT_SECRET）
+
+---
+
+## 任务步骤
+
+### Task 1: 引导 Spring Boot 项目骨架（compile + boot 通过）
+
+**Files:**
+- Create: `backend/pom.xml`
+- Create: `backend/src/main/java/com/xly/erp/ErpApplication.java`
+- Create: `backend/src/main/resources/application.yml`
+- Create: `backend/src/main/resources/application-test.yml`
+- Create: `backend/src/test/resources/application-test.yml`（与上一行同内容，Spring Boot 测试时从 test/resources 优先加载）
+- Create: `backend/src/main/java/com/xly/erp/ErpApplicationTest.java`（验证 context 启动）
+
+**API shape:**
+- `ErpApplication` 主类标 `@SpringBootApplication`、`@MapperScan("com.xly.erp.**.mapper")`
+- `application.yml` 通过 `${DB_HOST}` / `${DB_PORT}` / `${DB_USER}` / `${DB_PASSWORD}` / `${DB_SCHEMA}` / `${JWT_SECRET}` 占位（值由本地启动脚本或 IDE EnvFile 插件从 `.env.local` 注入；详见 docs/04 § 3.5）
+- 启用 Flyway：`spring.flyway.locations=classpath:db/migration` —— 但项目 migrations 在 `sql/migrations/`；改为 `spring.flyway.locations=filesystem:../sql/migrations` 让 backend 直接复用仓库根的 V*.sql
+
+**pom.xml 锁定依赖**（写死，不让 TDD 自由选）：
+- `spring-boot-starter-parent` 3.2.x
+- `spring-boot-starter-web`、`-validation`、`-security`、`-test`
+- `spring-security-test`
+- `mybatis-plus-spring-boot3-starter` 最新稳定版（写明确版本号，本任务由 TDD 确认 mvn central 最新可用）
+- `flyway-core` + `flyway-mysql` 10.x
+- `mysql-connector-j` 8.x
+- `org.projectlombok:lombok`（编译期）+ `lombok-mapstruct-binding`
+- `org.mapstruct:mapstruct` 1.5.x + `mapstruct-processor`
+- `cn.hutool:hutool-all` 5.x
+- Java 编译目标 17
+
+- [ ] **Step 1.1 写测试**
+  - 文件: `backend/src/test/java/com/xly/erp/ErpApplicationTest.java`
+  - 测试名: `ErpApplicationTest#contextLoads`
+  - 内容: 空 `@SpringBootTest @ActiveProfiles("test")` + 空 test 方法
+  - 意图: ApplicationContext 能在 test profile 下成功启动 + Flyway 能 apply V1（apply 到现有 test schema 应是 no-op，因为表已存在；Flyway 跑完会建 `flyway_schema_history` 表 + 注册 V1 已 baseline）
+  - 子会话确认 FAIL（项目还没建好）
+
+- [ ] **Step 1.2 创建 pom.xml**
+  - 仅声明依赖、Java 17、surefire 配置
+  - `mvn -B -f backend/pom.xml dependency:resolve` 应通过
+
+- [ ] **Step 1.3 创建 ErpApplication + application.yml**
+  - `ErpApplication` 仅做启动 + `@MapperScan`
+  - `application.yml` 主键：`server.port=8080`、`spring.profiles.active=${SPRING_PROFILES_ACTIVE:dev}`、datasource、mybatis-plus、flyway
+  - `application-test.yml`：override `spring.flyway.baseline-on-migrate=true` + `spring.flyway.baseline-version=0`（让 Flyway 把当前已存在的 schema 作为 baseline，再追 apply）
+  - 子会话 `cd backend && mvn -B test -Dtest=ErpApplicationTest#contextLoads -DSPRING_PROFILES_ACTIVE=test` 应 PASS
+
+- [ ] **Step 1.4 提交**
+  - `git add backend/pom.xml backend/src/main/java/com/xly/erp/ErpApplication.java backend/src/main/resources/application*.yml backend/src/test/resources/application*.yml backend/src/test/java/com/xly/erp/ErpApplicationTest.java`
+  - `git commit -m "chore(mod): bootstrap spring boot skeleton REQ-MOD-001"`
+
+---
+
+### Task 2: 统一响应与错误码（ApiResponse + ErrorCode）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/response/ApiResponse.java`
+- Create: `backend/src/main/java/com/xly/erp/common/response/ErrorCode.java`
+- Test: `backend/src/test/java/com/xly/erp/common/response/ApiResponseTest.java`
+
+**API shape:**
+- `ApiResponse<T>`：字段 `int code`、`String message`、`T data`、`long timestamp`；静态工厂 `ok(T data)`、`ok(String message, T data)`、`fail(ErrorCode ec)`、`fail(int code, String message)`
+- `ErrorCode` 枚举（int code, String message）至少包含：
+  - `SUCCESS(200, "操作成功")`
+  - `PARAM_INVALID(40010, "参数错误")`
+  - `MODULE_PARENT_NOT_FOUND(40411, "父模块不存在或已删除")`
+  - `MODULE_PROCEDURE_NAME_DUPLICATE(40911, "存储过程名称已存在")`
+  - `INTERNAL_ERROR(50000, "服务器内部错误")`
+
+**锁定常量**（跨模块复用，写死）：
+```
+SUCCESS              = 200
+PARAM_INVALID        = 40010
+MOD_PARENT_NOT_FOUND = 40411
+MOD_PROC_NAME_DUP    = 40911
+INTERNAL_ERROR       = 50000
+```
+
+- [ ] **Step 2.1 写失败测试**
+  - 测试名: `ApiResponseTest#ok_setsCode200AndDataAndTimestamp`、`ApiResponseTest#fail_mapsErrorCodeFields`
+  - 意图: `ok(data)` → code=200，message="操作成功"，data=入参，timestamp 在合理范围；`fail(ErrorCode.PARAM_INVALID)` → code=40010，message="参数错误"
+  - 子会话 PASS：FAIL（class 不存在）
+
+- [ ] **Step 2.2 实现 ApiResponse + ErrorCode**
+  - 用 Lombok `@Data` 减少样板，但保留显式工厂方法
+  - 子会话 PASS
+
+- [ ] **Step 2.3 提交**
+  - `git commit -m "feat(common): unified ApiResponse and ErrorCode REQ-MOD-001"`
+
+---
+
+### Task 3: 业务异常 + 全局异常处理器
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/common/exception/BizException.java`
+- Create: `backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java`
+- Test: `backend/src/test/java/com/xly/erp/common/exception/GlobalExceptionHandlerTest.java`（用 MockMvc + 一个临时 controller 触发各类异常）
+
+**API shape:**
+- `BizException extends RuntimeException`：构造 `BizException(ErrorCode ec)`、`BizException(ErrorCode ec, String detail)`；getter: `code()`, `message()`
+- `GlobalExceptionHandler` 处理：
+  - `BizException` → `ApiResponse.fail(ec)` 200 OK（业务错误也走 200 + 内部 code，docs/05 § 全局约定）
+  - `MethodArgumentNotValidException`（@Valid 失败）→ 提取 fieldError，组合 `ApiResponse.fail(PARAM_INVALID, "<field>: <reason>")`
+  - `Exception`（兜底）→ `ApiResponse.fail(INTERNAL_ERROR)` + log error；**响应不含堆栈**（docs/04 § 1.4）
+
+- [ ] **Step 3.1 写失败测试**
+  - 测试名（4 个）:
+    - `GlobalExceptionHandlerTest#bizException_returns200WithBizCode`
+    - `GlobalExceptionHandlerTest#validationException_returns200WithParamInvalidCode`
+    - `GlobalExceptionHandlerTest#uncaughtException_returns200WithInternalErrorCode`
+    - `GlobalExceptionHandlerTest#response_doesNotContainStackTrace`
+  - 测试方式: `@WebMvcTest(controllers=DummyController.class)` 内置一个 `DummyController` 故意抛各类异常，断言 `MockMvc.perform(...).andExpect(jsonPath("$.code").value(...))`
+  - 子会话: FAIL
+
+- [ ] **Step 3.2 实现 BizException + Handler**
+  - 子会话: PASS
+
+- [ ] **Step 3.3 提交**
+  - `git commit -m "feat(common): biz exception and global handler REQ-MOD-001"`
+
+---
+
+### Task 4: SecurityConfig（permitAll 占位）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/config/SecurityConfig.java`
+- Test: `backend/src/test/java/com/xly/erp/config/SecurityConfigTest.java`
+
+**API shape:**
+- `SecurityFilterChain securityFilterChain(HttpSecurity http)`：禁用 CSRF（API 项目）、禁用默认表单登录、所有 `/api/**` permitAll
+- 显式注释：`// REQ-USR-004 完成后改为 .authenticated() + JWT filter`
+
+- [ ] **Step 4.1 写失败测试**
+  - 测试名: `SecurityConfigTest#anyApiEndpoint_isPermittedWithoutAuth`
+  - 测试方式: `@SpringBootTest @AutoConfigureMockMvc` + 在 controller package 临时加一个 `/api/__ping` GET（**或**复用 Task 3 的 `DummyController`），无 token 请求应返回 200 而非 401/403
+  - 子会话: FAIL（默认 Spring Security 401）
+
+- [ ] **Step 4.2 实现 SecurityConfig**
+  - 子会话: PASS
+
+- [ ] **Step 4.3 提交**
+  - `git commit -m "feat(config): permitAll security skeleton REQ-MOD-001"`
+
+---
+
+### Task 5: ModuleEntity + ModuleMapper（Mapper 集成测试落库）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/entity/ModuleEntity.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/mapper/ModuleMapper.java`
+- Create: `backend/src/main/resources/mapper/mod/ModuleMapper.xml`（仅头部 `<mapper namespace="...ModuleMapper"/>`，预留扩展）
+- Test: `backend/src/test/java/com/xly/erp/module/mod/mapper/ModuleMapperIT.java`
+
+**API shape:**
+- `@TableName("tModule")` ；字段名严格匹配 docs/03（保留匈牙利前缀，使用 `@TableField` 显式映射），主键 `iIncrement` 用 `@TableId(type = IdType.AUTO)`
+- 列 ↔ Java 属性命名采用**保留前缀**（如 `iIncrement` Java 字段名也叫 `iIncrement`，方便对照 schema），与 docs/04 § 1.2 命名约定中的"小驼峰"略有出入——本约束**优先**：DB schema SSoT 是 docs/03，Java 字段直接复用列名以避免双向映射歧义。Lombok `@Data`。
+- `ModuleMapper extends BaseMapper<ModuleEntity>`，本 REQ 仅用 `insert` + `selectById` + `selectCount`(条件)；不写自定义 SQL
+
+- [ ] **Step 5.1 写失败测试**
+  - 测试名: `ModuleMapperIT#insertAndSelectById_persistsAllFields`、`ModuleMapperIT#selectCountByProcedureName_returnsExisting`
+  - 测试方式: `@SpringBootTest @ActiveProfiles("test")` + `@Transactional`（自动回滚），DI `ModuleMapper`，构造 entity 调 `insert`，再 `selectById` 断言全部字段；用 `selectCount(new LambdaQueryWrapper<ModuleEntity>().eq(ModuleEntity::getSProcedureName, ...))` 验证唯一查询
+  - 子会话: FAIL
+
+- [ ] **Step 5.2 实现 Entity + Mapper**
+  - 子会话: PASS（DDL 已存在，直接 insert）
+
+- [ ] **Step 5.3 提交**
+  - `git commit -m "feat(mod): module entity and mapper REQ-MOD-001"`
+
+---
+
+### Task 6: DTO + VO
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/dto/ModuleCreateDTO.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/vo/ModuleVO.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/dto/ModuleCreateDTOValidationTest.java`
+
+**API shape:**
+
+`ModuleCreateDTO` 字段（带 Bean Validation）：
+- `@NotBlank @Pattern(regexp="^(手机端|前端业务|系统配置|接口)$") String sDisplayType`
+- `@NotBlank @Size(max=100) String sProcedureName`
+- `@NotBlank @Size(max=50) String sModuleType`
+- `@NotBlank @Size(max=50) String sManageDeptEn`
+- `Boolean bShowPermission`（可空，service 层 default false）
+- `@NotBlank @Size(max=100) String sModuleNameZh`
+- `Integer iParentId`（可空）
+- `@Min(0) Integer iSortOrder`（可空，default 0）
+
+`ModuleVO` 字段（11 个，见 spec § 输出）：`iIncrement`, `sDisplayType`, `sProcedureName`, `sModuleType`, `sManageDeptEn`, `bShowPermission`, `sModuleNameZh`, `iParentId`, `iSortOrder`, `tCreateDate`, `bDeleted`。
+
+> Entity → VO 的转换写在 `ModuleVO` 的静态工厂 `from(ModuleEntity)` 里，不引入 MapStruct 单独 mapper 类（YAGNI；REQ 多了再抽）。
+
+- [ ] **Step 6.1 写失败测试**
+  - 测试名: `ModuleCreateDTOValidationTest#blankRequiredFields_yieldsViolations`、`ModuleCreateDTOValidationTest#invalidDisplayTypeEnum_yieldsViolation`、`ModuleCreateDTOValidationTest#allValidFields_yieldsNoViolations`
+  - 测试方式: `Validation.buildDefaultValidatorFactory().getValidator()` + 断言 violation 集合
+  - 子会话: FAIL
+
+- [ ] **Step 6.2 实现 DTO + VO**
+  - 子会话: PASS
+
+- [ ] **Step 6.3 提交**
+  - `git commit -m "feat(mod): module create DTO and VO REQ-MOD-001"`
+
+---
+
+### Task 7: ModuleService.create（核心业务）
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/service/ModuleService.java`
+- Create: `backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/service/ModuleServiceImplTest.java`（Mockito 单元测试，mock ModuleMapper）
+
+**API shape:**
+- `interface ModuleService { ModuleVO create(ModuleCreateDTO dto); }`
+- `@Service @RequiredArgsConstructor class ModuleServiceImpl implements ModuleService`，字段 `private final ModuleMapper moduleMapper;`
+- `create` 方法步骤（写在 plan 锁定，不让 TDD 自由发挥逻辑顺序）：
+  1. 若 `dto.iParentId != null`：`moduleMapper.selectById(iParentId)`，结果为 `null` 或 `bDeleted == true` → 抛 `BizException(MOD_PARENT_NOT_FOUND)`
+  2. 唯一性预检：`moduleMapper.selectCount(LambdaQueryWrapper.eq(ModuleEntity::getSProcedureName, dto.sProcedureName).eq(ModuleEntity::getBDeleted, 0))` > 0 → 抛 `BizException(MOD_PROC_NAME_DUP)`
+  3. 构造 `ModuleEntity`：复制 dto 字段；`bShowPermission` null → `false`；`iSortOrder` null → `0`；`tCreateDate = LocalDateTime.now()`；`bDeleted = 0`；`sBrandsId/sSubsidiaryId/sCreatedBy/sId/tDeletedDate/sDeletedBy = null`
+  4. `moduleMapper.insert(entity)`；MyBatis-Plus 回写 `iIncrement` 到 entity
+  5. 捕获 `DuplicateKeyException`（并发下 uk_procedure_name 兜底）→ 抛 `BizException(MOD_PROC_NAME_DUP)`
+  6. `return ModuleVO.from(entity)`
+- 标 `@Transactional(rollbackFor = Exception.class)`
+
+- [ ] **Step 7.1 写失败测试（6 个）**
+  - `ModuleServiceImplTest#create_rootModule_returnsVOWithGeneratedId`
+  - `ModuleServiceImplTest#create_childModule_validatesParentExists`
+  - `ModuleServiceImplTest#create_parentNotFound_throwsBizException40411`
+  - `ModuleServiceImplTest#create_parentSoftDeleted_throwsBizException40411`
+  - `ModuleServiceImplTest#create_duplicateProcedureName_preCheck_throwsBizException40911`
+  - `ModuleServiceImplTest#create_duplicateProcedureName_concurrentInsert_throwsBizException40911`（mock `moduleMapper.insert` 抛 `DuplicateKeyException`）
+  - 测试方式: `@ExtendWith(MockitoExtension.class)` + `@InjectMocks ModuleServiceImpl` + `@Mock ModuleMapper`
+  - 子会话: FAIL
+
+- [ ] **Step 7.2 实现 ModuleService + ModuleServiceImpl**
+  - 子会话: PASS
+
+- [ ] **Step 7.3 提交**
+  - `git commit -m "feat(mod): create module service REQ-MOD-001"`
+
+---
+
+### Task 8: ModuleController + 端到端集成测试
+
+**Files:**
+- Create: `backend/src/main/java/com/xly/erp/module/mod/controller/ModuleController.java`
+- Test: `backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java`
+
+**API shape:**
+- `@RestController @RequestMapping("/api/modules")`
+- `@PostMapping public ApiResponse<ModuleVO> create(@Valid @RequestBody ModuleCreateDTO dto)` → `ApiResponse.ok(moduleService.create(dto))`
+- 类上保留注释：`// REQ-USR-004 完成后追加 @PreAuthorize("hasAuthority('MOD:CREATE')")`
+
+- [ ] **Step 8.1 写失败测试（6 个验收用例）**
+  - `ModuleControllerIT#post_validRootModule_returns200WithVO`
+  - `ModuleControllerIT#post_validChildModule_returns200`
+  - `ModuleControllerIT#post_duplicateProcedureName_returns200WithCode40911`
+  - `ModuleControllerIT#post_parentNotFound_returns200WithCode40411`
+  - `ModuleControllerIT#post_missingRequiredField_returns200WithCode40010`
+  - `ModuleControllerIT#post_invalidDisplayTypeEnum_returns200WithCode40010`
+  - 测试方式: `@SpringBootTest @AutoConfigureMockMvc @ActiveProfiles("test") @Transactional`（自动回滚），用 `MockMvc` 发 POST，断言 `$.code` / `$.data.iIncrement` / `$.data.sProcedureName` 等
+  - 子会话: FAIL
+
+- [ ] **Step 8.2 实现 ModuleController**
+  - 子会话: PASS
+
+- [ ] **Step 8.3 全量 backend 测试**
+  - `cd backend && mvn -B test -DSPRING_PROFILES_ACTIVE=test`
+  - 期望全绿（Task 1-8 累计 ~25 个测试方法）
+
+- [ ] **Step 8.4 提交**
+  - `git commit -m "feat(mod): POST /api/modules controller REQ-MOD-001"`
+
+---
+
+## 提交计划
+
+- `chore(mod): bootstrap spring boot skeleton REQ-MOD-001`（覆盖 Task 1）
+- `feat(common): unified ApiResponse and ErrorCode REQ-MOD-001`（覆盖 Task 2）
+- `feat(common): biz exception and global handler REQ-MOD-001`（覆盖 Task 3）
+- `feat(config): permitAll security skeleton REQ-MOD-001`（覆盖 Task 4）
+- `feat(mod): module entity and mapper REQ-MOD-001`（覆盖 Task 5）
+- `feat(mod): module create DTO and VO REQ-MOD-001`（覆盖 Task 6）
+- `feat(mod): create module service REQ-MOD-001`（覆盖 Task 7）
+- `feat(mod): POST /api/modules controller REQ-MOD-001`（覆盖 Task 8）
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+round: 1
+reviewer: superpower-code-reviewer
+---
+
+# Review: REQ-MOD-001 — round 1
+
+## 结论
+approve
+
+## Must-fix
+（无）
+
+## Nice-to-have
+
+- backend/src/main/java/com/xly/erp/common/exception/GlobalExceptionHandler.java:30 — 兜底 `@ExceptionHandler(Exception.class)` 会吃掉 `HttpMessageNotReadableException` / `HttpRequestMethodNotSupportedException` / `MissingServletRequestParameterException` 等参数类异常并映射到 50000；语义上更接近 40010。建议下一个 REQ 顺手为这几类异常补独立 handler。
+- backend/src/main/java/com/xly/erp/config/SecurityConfig.java:18 — `csrf -> csrf.disable()` 等三处 lambda 可改用方法引用 `AbstractHttpConfigurer::disable`，更符合 Spring Security 6 官方示例风格。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:39 — `.eq(ModuleEntity::getBDeleted, false)` 可读性建议统一用 `Boolean.FALSE` 或抽常量，依赖 JDBC 默认转换不影响正确性。
+- backend/src/main/java/com/xly/erp/module/mod/service/impl/ModuleServiceImpl.java:26 / Controller / Mapper / Entity — spec § 代码与文档要求关键类贴 `// REQ-MOD-001 模块新增` 标签；目前 Controller 仅有 REQ-USR-004 备忘注释，缺 REQ-MOD-001 标签，Service / Mapper / Entity / DTO / VO 也均未显式标。建议补一行类级注释。
+- backend/src/main/java/com/xly/erp/config/JacksonConfig.java:18 — JacksonConfig 是计划外补丁（修复匈牙利前缀字段 JSON 序列化）；plan 文件清单未列出。建议补一条 ObjectMapper 序列化测试断言 `iIncrement` 而非 `IIncrement`，把这个隐式契约钉死。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:55 — `post_validRootModule` 应额外断言 VO 字段值（sDisplayType / sModuleNameZh / iSortOrder / tCreateDate / bShowPermission），spec 验收 § 1 要求"DB 中查询新记录字段与入参一致"。
+- backend/src/test/java/com/xly/erp/module/mod/controller/ModuleControllerIT.java:77 — `post_validChildModule` 没有断言 iSortOrder / bShowPermission / sCreatedBy 留 NULL 等持久化字段，建议补 select-after-insert 验证。
+- backend/src/main/java/com/xly/erp/common/response/ApiResponse.java:28 — `fail(ErrorCode ec, String detail)` 把 message 替换为 detail，前端会吃到带英文字段名的中文混合串。建议将 detail 单列字段或保留 ec.getMessage() 作为 message。
+- backend/src/main/resources/application.yml:21 — 全局 `map-underscore-to-camel-case: false` 对未来非匈牙利前缀字段有传染影响；当前 entity 已显式 `@TableField`，可改回 MyBatis-Plus 默认 true。
+
+## 反例 / 测试覆盖缺口
+
+1. spec § 验收 § 功能正确性 1 要求"DB 中查询新记录字段与入参一致"——目前 `ControllerIT` 只断言 3 个字段、未回查 DB；`ModuleMapperIT` 单独覆盖 mapper 层往返，端到端层面字段一致性不直观。
+2. spec § 测试覆盖列出"并发同 sProcedureName"用例标可选，未实现——可接受。
+3. spec § 业务规则 5 要求 `bDeleted=0` / `tDeletedDate=NULL` / `sDeletedBy=NULL` / `sBrandsId/sSubsidiaryId/sCreatedBy=NULL` 在 INSERT 后真正落库——`ModuleServiceImplTest` 用 mock 不能验证 entity 在传给 `mapper.insert` 前的赋值；建议加 `ArgumentCaptor` 断言。
+4. Controller 层缺 `HttpMessageNotReadableException` 用例（POST 非法 JSON 当前会走 50000 兜底）；spec 未显式要求，但 docs/04 § 1.4 友好错误码原则下属盲区。
+5. 计划清单列出的 `MybatisPlusConfig.java` 未创建——plan 自身注明"REQ-MOD-001 不用，先建空骨架"，YAGNI 角度可接受；建议在 plan 上同步勾掉或删除该行。
+6. 未发现硬编码凭据、未跨模块改动、未引入技术栈外组件、commit 全部带 `REQ-MOD-001` 标签、响应不回显堆栈——全部合规。spec 写明的 REQ-USR-004 技术债（permitAll + 多租户字段 NULL + sCreatedBy NULL）落地受控，无失控扩散。
+---
+req_id: REQ-MOD-001
+date: 2026-05-06
+module: module_mod
+---
+
+# Spec: REQ-MOD-001 — 模块新增
+
+## 目标
+
+实现后端 `POST /api/modules` 接口：将一条新的业务模块定义写入 `tModule` 表，作为 ERP 系统功能与权限分组的基础单位，返回新模块主键 `iIncrement` 与完整 VO。
+
+本 REQ 是 module_mod 模块的第一个 REQ，也是整个 B 阶段的首个 REQ；需顺带建立 Spring Boot 项目骨架（最小可运行单元），仅落地能让本接口工作的横切组件。其余横切组件（JWT 鉴权、登录用户上下文）按 docs/02 § 三 约定由 REQ-USR-004 首次落地。
+
+## 输入 / 触发
+
+**接口**：`POST /api/modules`，Content-Type `application/json`。
+
+**Request body**（`ModuleCreateDTO`）字段：
+
+| 字段 | 类型 | 必填 | 校验 / 取值 | 落库列 |
+|---|---|---|---|---|
+| `sDisplayType` | String | 是 | 枚举：`手机端` / `前端业务` / `系统配置` / `接口` | `tModule.sDisplayType` |
+| `sProcedureName` | String | 是 | 长度 1-100；系统内唯一（`bDeleted=0` 范围内） | `tModule.sProcedureName` |
+| `sModuleType` | String | 是 | 长度 1-50（自由文本） | `tModule.sModuleType` |
+| `sManageDeptEn` | String | 是 | 长度 1-50（自由文本） | `tModule.sManageDeptEn` |
+| `bShowPermission` | Boolean | 否 | 默认 `false` | `tModule.bShowPermission` |
+| `sModuleNameZh` | String | 是 | 长度 1-100 | `tModule.sModuleNameZh` |
+| `iParentId` | Integer | 否 | 必须指向已存在且未软删除的 `tModule.iIncrement` | `tModule.iParentId` |
+| `iSortOrder` | Integer | 否 | 默认 `0`；非负整数 | `tModule.iSortOrder` |
+
+**鉴权**：契约要求 `Authorization: Bearer <accessToken>` + 权限码 `MOD:CREATE`。本 REQ 暂不实施实际鉴权（见 § 边界与约束），但 Controller 仍按需要鉴权的形态编写（无 `@AnonymousAccess` 标注），以便 REQ-USR-004 加入 SecurityFilterChain 后零改动。
+
+## 输出 / 结果
+
+**HTTP 200，响应体**（统一响应格式）：
+
+```json
+{
+  "code": 200,
+  "message": "操作成功",
+  "data": {
+    "iIncrement": 12,
+    "sDisplayType": "前端业务",
+    "sProcedureName": "sp_audit_user_module",
+    "sModuleType": "USR",
+    "sManageDeptEn": "IT",
+    "bShowPermission": false,
+    "sModuleNameZh": "用户管理",
+    "iParentId": null,
+    "iSortOrder": 0,
+    "tCreateDate": "2026-05-06T10:30:00",
+    "bDeleted": false
+  },
+  "timestamp": 1746528600000
+}
+```
+
+返回 VO（`ModuleVO`）字段：`iIncrement` / `sDisplayType` / `sProcedureName` / `sModuleType` / `sManageDeptEn` / `bShowPermission` / `sModuleNameZh` / `iParentId` / `iSortOrder` / `tCreateDate` / `bDeleted`。其他标准列（`sId` / `sBrandsId` / `sSubsidiaryId` / `sCreatedBy` / `tDeletedDate` / `sDeletedBy`）不对外暴露。
+
+## 业务规则
+
+1. **唯一性**：`sProcedureName` 在未软删除范围内（`bDeleted=0`）系统内唯一。冲突返回错误码 `40911`。
+2. **父模块校验**：若 `iParentId` 非空，必须指向 `tModule` 中存在且 `bDeleted=0` 的记录；不存在或已删除返回错误码 `40411`。
+3. **bShowPermission 默认值**：未传入或传 `null` → 落库 `0`。
+4. **iSortOrder 默认值**：未传入 → 落库 `0`。
+5. **新建记录初始状态**：`bDeleted=0`、`tDeletedDate=NULL`、`sDeletedBy=NULL`、`tCreateDate=now()`（应用层取系统时间，不依赖 DB DEFAULT）。
+6. **多租户字段 (`sBrandsId` / `sSubsidiaryId`)**：本 REQ **不写入**（落库 `NULL`，列已 nullable）。多租户上下文将由 REQ-USR-004 引入登录会话后注入；后续 REQ 通过迁移补齐已有数据。
+7. **`sCreatedBy`**：本 REQ 落库 `NULL`。等待 REQ-USR-004 引入登录用户上下文后从 `SecurityContextHolder` 取当前用户号回写。
+8. **`sId`**（业务 ID 标准列）：本 REQ 落库 `NULL`，不在本接口分配。后续若有外部对接需求再以独立 migration 补齐策略。
+
+## 边界与约束
+
+### 鉴权策略（本 REQ 限定）
+
+- 项目首个 REQ，尚无 SecurityFilterChain。本 REQ 在 `SecurityConfig` 里配置 `permitAll()` 临时放行所有 `/api/**`。
+- Controller 不写 `@PreAuthorize("hasAuthority('MOD:CREATE')")`（无 SecurityContext 时该注解会因 `Authentication=null` 抛 `AccessDeniedException`）；改为在 Controller 上方写一行说明性注释：`// REQ-USR-004 完成后改为 @PreAuthorize("hasAuthority('MOD:CREATE')")`。
+- REQ-USR-004 完成后会回头给本接口加 `@PreAuthorize`，并把 `permitAll` 改为 `authenticated()`。这是已知技术债，**仅在 REQ-USR-004 范围内偿还**，本 REQ 不擅自前置。
+
+### 字段长度与字符集
+
+- 字符集统一 `utf8mb4`（DDL 已约束），允许中文落库。
+- 字符串字段超出 DDL 长度限制视为参数错误（`40010`），不截断。
+
+### 事务
+
+- Service 方法标注 `@Transactional(rollbackFor = Exception.class)`，单表写入即可，事务范围最小化。
+
+### 性能与并发
+
+- 本 REQ 是单条 INSERT，预期无高并发。`uk_procedure_name` 唯一约束兜底并发竞争；唯一冲突映射为 `40911`。
+
+### 项目骨架引导（首 REQ 一次性附带）
+
+本 REQ 顺带建立**最小可运行**的 Spring Boot 项目骨架（仅引入服务于本 REQ 的部分；后续 REQ 按需扩充）。预期新增目录与文件：
+
+```
+backend/
+├── pom.xml
+└── src/main/
+    ├── java/com/xly/erp/
+    │   ├── ErpApplication.java
+    │   ├── config/
+    │   │   ├── MybatisPlusConfig.java
+    │   │   └── SecurityConfig.java          // 临时 permitAll
+    │   ├── common/
+    │   │   ├── response/
+    │   │   │   ├── ApiResponse.java
+    │   │   │   └── ErrorCode.java
+    │   │   └── exception/
+    │   │       ├── BizException.java
+    │   │       └── GlobalExceptionHandler.java
+    │   └── module/mod/
+    │       ├── controller/ModuleController.java
+    │       ├── service/ModuleService.java
+    │       ├── service/impl/ModuleServiceImpl.java
+    │       ├── mapper/ModuleMapper.java
+    │       ├── entity/Module.java
+    │       ├── dto/ModuleCreateDTO.java
+    │       └── vo/ModuleVO.java
+    └── resources/
+        ├── application.yml                  // ${DB_HOST}/${DB_PORT}/... 占位，从 .env.local 注入
+        └── mapper/mod/ModuleMapper.xml
+```
+
+`pom.xml` 依赖：`spring-boot-starter-web` / `-validation` / `-security`、`mybatis-plus-spring-boot3-starter`、`flyway-core` + `flyway-mysql`、`mysql-connector-j`、`mapstruct`、`hutool-all`、`spring-boot-starter-test`、`spring-security-test`。
+
+`application.yml` 通过 Spring Profile + `dotenv-java`（或本地启动脚本）加载 `.env.local`；不在仓内硬编码任何凭据（与 `docs/04 § 3.5` 一致）。
+
+## 依赖的 schema 表 / 字段
+
+**写表**：`tModule`（详见 `docs/03-数据库设计文档.md` § tModule）
+
+| 字段 | 落库逻辑 |
+|---|---|
+| `iIncrement` | DB 自增分配 |
+| `sId` | 落 `NULL`（本 REQ 不分配业务 ID） |
+| `sBrandsId` | 落 `NULL`（多租户 REQ-USR-004 后引入） |
+| `sSubsidiaryId` | 落 `NULL`（同上） |
+| `tCreateDate` | 应用层 `LocalDateTime.now()` |
+| `sDisplayType` | 入参（必填） |
+| `sProcedureName` | 入参（必填，唯一） |
+| `sModuleType` | 入参（必填） |
+| `sManageDeptEn` | 入参（必填） |
+| `bShowPermission` | 入参（默认 `false`） |
+| `sModuleNameZh` | 入参（必填） |
+| `iParentId` | 入参（可选；FK 校验通过的 `tModule.iIncrement`） |
+| `iSortOrder` | 入参（默认 `0`） |
+| `sCreatedBy` | 落 `NULL`（REQ-USR-004 后引入登录上下文） |
+| `bDeleted` | 落 `0` |
+| `tDeletedDate` | 落 `NULL` |
+| `sDeletedBy` | 落 `NULL` |
+
+**索引利用**：
+- `uk_procedure_name` UNIQUE：唯一性约束触发并发兜底
+- `idx_parent`：父模块查询场景（FK 校验时按 `iParentId` 查 `tModule`）
+
+**外键**：本 REQ 利用 `fk_module_parent` 作为 DB 层兜底；应用层在写入前先查父模块存在性，提前返回 `40411`，避免直接抛 SQL 完整性异常。
+
+## 依赖的接口
+
+无（本接口是 module_mod 的入口接口，不依赖其他业务接口）。
+
+后续在 REQ-USR-004 完成后，需要回归补齐本接口的 `@PreAuthorize("hasAuthority('MOD:CREATE')")`，并要求请求携带有效 JWT。
+
+## 验收标准
+
+### 功能正确性
+
+1. **正向 — 根模块**：提交完整字段、`iParentId=null`，返回 200 + `data.iIncrement` 非空；DB 中查询新记录字段与入参一致；`bDeleted=0` / `tCreateDate` 已写入。
+2. **正向 — 子模块**：先创建 root 再以其 `iIncrement` 作为 `iParentId` 创建子模块，返回 200。
+3. **唯一性冲突**：用相同 `sProcedureName` 二次提交，返回 `code=40911` + 中文 message；DB 不产生重复记录。
+4. **父模块不存在**：传入 `iParentId=999999`，返回 `code=40411`。
+5. **必填缺失 / 枚举非法 / 长度超限**：返回 `code=40010` + 错误字段名定位。
+6. **可选默认值**：不传 `bShowPermission` / `iSortOrder` → DB 落 `false / 0`。
+
+### 接口契约一致性
+
+- 响应格式严格符合 `{code, message, data, timestamp}`（docs/05 § 全局约定）。
+- 错误码段位与 docs/05 一致：`200` / `40010` / `40911` / `40411` / `500xx`。
+- 异常堆栈不出现在响应里（GlobalExceptionHandler 拦截并映射为友好错误，docs/04 § 1.4）。
+
+### 测试覆盖（feature-tdd 阶段）
+
+- **单元测试**：`ModuleServiceImpl#create` 覆盖 6 类正/反路径（含唯一冲突的 `DuplicateKeyException` 映射）。
+- **集成测试（MockMvc + 真实 MySQL test schema）**：
+  - 正向：根模块、子模块创建后查 DB 验证字段
+  - 反向：唯一冲突、父模块不存在、必填缺失、枚举非法、长度超限 ≥ 5 个 case
+  - 并发：两线程同时插入同 `sProcedureName`，断言一条成功 + 一条 40911（可选，若 CI 跑得动）
+- **测试数据隔离**：每个测试方法 `@Transactional` 自动回滚；不污染其他测试。
+
+### 代码与文档
+
+- `// REQ-MOD-001` 注释贴在 Controller / Service / Mapper / DTO / VO 关键类。
+- 提交按 `feat(mod): add module create endpoint REQ-MOD-001` 规范。
+- 不引入 docs/04 § 零 技术栈外的依赖（如需，按软规则 S1 经 AskUserQuestion）。