# 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 命令模板（每批执行）：

```bash
# 该批每个旧类名扫:
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）