5.3 KiB

Raw Blame History

Handoff: CRM Controller IO Conventions Implementation

Date: 2026-08-10 Branch: master Last commits: ae103a1 (ticket 01 main), 80bc063 (ticket 01 status update)

1. What This Project Is

CRM 后端（Java 17 + Spring Boot 3 + MyBatis-Plus，Maven 多模块单体）。正在统一 Controller 出入参约定，由 ADR-0017 驱动，推翻旧的三类方案（SaveParam/PageParam/DTO），改为两类（Param/DTO）。

核心工件（勿重复，引用即可）：

ADR-0017: docs/adr/0017-controller-io-param-dto-conventions.md
Spec: .scratch/controller-io-conventions/spec.md
7 个 Ticket: .scratch/controller-io-conventions/issues/01-*.md 至 07-*.md
研究文档: docs/research/2026-08-10-dto-vo-param-conventions.md

2. What's Done

Ticket 01 — BaseDTO 重构 + IBaseService 清理（resolved）

Commit ae103a1，15 files, +360/-62。

文件	改动
`crm-base/.../domain/dto/BaseDTO.java`	`abstract`，仅 `id`/`createTime`/`updateTime`（`@JsonInclude NON_NULL`），移除 `creatorId`/`updaterId`/`deleted`/`toEntity(Supplier)`
`crm-base/.../service/IBaseService.java`	删除 `saveDTO`/`updateDTO` 死代码
`crm-base/.../utils/BeanCopyUtils.java`	javadoc 移除 `BaseDTO.toEntity` 引用
`README.md`	§3/§4/§10 同步更新
`crm-auth/.../ResourceController.java`	修复预存 UTF-8 BOM
`crm-auth/.../RoleController.java`	修复预存 UTF-8 BOM

验证：mvn clean compile 全 6 模块 SUCCESS；mvn test 45 tests, 0 failures, 0 errors。

3. Key Technical Decisions（ADR-0017 摘要）

两类对象：XxxParam（查询/分页入参，extends BaseParam）+ XxxDTO（写入参+出参双向，Route A）
BaseDTO：abstract，仅 id/createTime/updateTime，@JsonInclude(NON_NULL)；统计/聚合类不继承
Mass assignment 防御：全局 @ControllerAdvice + @InitBinder + setDisallowedFields，strip 掉 createTime/updateTime/creatorId/updaterId/deleted/builtin（尚未实现 = ticket 02）
硬约束：Entity 不出现在 Controller 签名；deleted/creatorId/updaterId 不出现在 HTTP 响应
封装阈值：≥3 参数封 XxxDTO，≤2 保持 @RequestParam（纯参数个数）
转换：fromEntity()/toEntity() 写在各 DTO 类上，Service 层调用
表单绑定：隐式 @ModelAttribute（不加 @RequestBody），契合 application/x-www-form-urlencoded 契约
全量回填：所有存量违规代码全改（非仅新代码）
命名：dto/ 包内 HTTP 出入参类一律 XxxDTO 后缀；存量 VO 已重命名

4. Frontier — What's Next

Ticket 02 — 全局 @InitBinder Mass Assignment 防御（无阻塞，可立即开始）

目标：创建全局 @ControllerAdvice + @InitBinder，用 setDisallowedFields strip 掉服务端裁定的字段。

strip 字段列表：createTime, updateTime, creatorId, updaterId, deleted, builtin

实现位置：crm-base/src/main/java/com/crm/base/advice/ 包下新建类（已有 GlobalExceptionHandler 在同包）

验收标准（见 02-init-binder-mass-assignment.md）：

创建 @ControllerAdvice 类，含 @InitBinder 方法
调用 binder.setDisallowedFields(...) 覆盖 6 个字段
不影响已有 @ModelAttribute 绑定的正常工作
编译通过 + 测试通过

Ticket 02 完成后解锁

Tickets 03/04/05/06 同时解锁：

03 DictGroup Controller IO（blocked by 02）
04 DictItem Controller IO（blocked by 02）
05 ResourceNode 重命名为 ResourceDTO（blocked by 02）
06 RoleController IO 改造（blocked by 02）

Ticket 07（SystemController IO）blocked by 05。

依赖图

01 (resolved) ──┐
                ├─► 02 (ready) ──┬─► 03
                │                 ├─► 04
                │                 ├─► 05 ──► 07
                │                 └─► 06
                └─────────────────────────────────► (done)

5. Environment Notes

Maven 路径：D:\apache-maven-3.9.9\bin\mvn.cmd（不在系统 PATH 上，需用全路径调用）
PowerShell：不支持 &&，用 ; 分隔
Java：JDK 17
编译命令：cd d:\code\crm-backend-matt; D:\apache-maven-3.9.9\bin\mvn.cmd clean compile
测试命令：cd d:\code\crm-backend-matt; D:\apache-maven-3.9.9\bin\mvn.cmd test

6. Suggested Skills

Skill	When to use
`/implement`	实现 ticket 02-07，每次一个 ticket
`/code-review`	每个 ticket 实现后审查（Standards + Spec 双轴）
`/diagnosing-bugs`	如果编译或测试出现意外错误
`/tdd`	如果想先写测试再实现（ticket 02 的 @InitBinder 适合 TDD）

7. Conventions to Follow

每个 ticket 完成后：编译 + 测试 + 提交 + 更新 ticket 状态为 resolved
提交信息格式：refactor: <description> (ADR-0017 ticket 0N)
代码风格：匹配周围代码的注释密度、命名、惯用法
不要提交 target/ 目录下的构建产物
不要提交 .idea/ 目录下的 IDE 配置
ADR + spec + tickets 已存在，勿重复创建，只更新

5.3 KiB Raw Blame History