mjava-ai/openspec/changes/rename-dingtalk-impl-suffix/design.md

Design

关键决策

1. 为什么分批 4 批

14 文件一把改的成本：

• grep 引用清单 ≥ 50 行（钉钉是基座最重的接入），用户审阅压力大
• 一次 PR 影响所有钉钉调用方，回滚必须全量
• 任一引用方漏改 → 编译爆炸 → 整个仓库阻塞

分批 4 批的好处：

• 每批 3~4 文件，grep 清单 ≤ 15 行
• 每批独立 commit，回滚成本 = 1 批
• 用户可在批次间叫停（"批次 1 出问题，先观察一周再继续"）
• 失败半径限定在该批关联调用方

2. 批次顺序为什么这样排

批次	文件	排序理由
1	DDImplClient / DDImplService / DDImplClient_Attendance	主流量入口，先打通主路径验证迁移可行性
2	DDImplClient_Contacts / _Group / _Notice	通讯通知，高频但相对独立
3	DDImplClient_Personnel / _Report / _Schedule	人事日历，与考勤强关联
4	DDImplClient_Dedicated / _Event / _Extension / _Storage / _Workflow	长尾，引用方少，最后清扫

3. Spring Bean 名 by-name 兼容性

Spring 默认 Bean 名是类名首字母小写。改名后：

旧 Bean 名	新 Bean 名
dDImplClient	dDClientImpl
dDImplClient_Attendance	dDClient_AttendanceImpl
...	...

调用方影响：

• @Autowired DDClient ddClient（by 接口类型）— 不受影响，Spring 仍能找到唯一实现
• @Autowired @Qualifier("dDImplClient") DDClient client（by-name）— 受影响，必须改
• @Resource(name = "dDImplClient_Attendance") — 受影响，必须改

每批 R4 grep 时必须加扫 @Qualifier @Resource(name= 字面量。

4. 没用 @Component("dDImplClient_Attendance") 别名兼容

可以给新类标 @Component("dDImplClient_Attendance") 保留旧 Bean 名，让调用方零修改。拒绝，原因：

• 旧 Bean 名继续存在会让代码长期维持「类名后缀 + Bean 名中缀」的语义裂缝，违反 R5 精神
• 别名是临时栈，迟早要拆 → 拆别名时还得做一遍引用扫，反复做 2 次
• 一次性切换的总成本 ≤ 双轨过渡

5. 跨仓 grep 范围

• mjava-ai：必扫
• 光明独立仓 /Users/malk/server/cur/mjava-guangming/：含 mjava-guangming/mjava-shunfeng 模块 — 必扫
• akds 项目：路径在用户 memory 中（独立维护），ACK 时由用户确认是否扫
• 其他客户独立仓：用户 ACK 时主动补充清单

grep 命令模板（每批执行）：

# 该批每个旧类名扫:
grep -rE "(import\s+.+\.DDImplClient_Attendance|DDImplClient_Attendance\.class|@Qualifier\(\"dDImplClient_Attendance\"|@Resource\(name\s*=\s*\"dDImplClient_Attendance)" \
  --include="*.java" \
  /Users/malk/server/cur/mjava-ai/ \
  /Users/malk/server/cur/mjava-guangming/ \
  {其他客户仓}

6. 验证流程（每批）

1. 改名 + import 替换
2. mvn -pl mjava -am clean compile（基座）
3. mvn -pl mjava-mcli,mjava-pro,mjava-com -am clean compile（子项目）
4. 跨仓客户项目验证（用户在 ACK 时指定）
5. 抽样运行：钉钉考勤/通讯录最常用接口的集成测试

拒绝的方案

• 一次 commit 14 文件 — 拒绝。爆炸半径过大
• 同时改 DDClient 接口名 — 拒绝。R5 只约束 Impl 命名；接口名变化触发跨仓所有 import 变化，超出本 change 范围
• 保留旧 Bean 名作为别名 — 拒绝（见 §4）