## 目标架构

```
┌─────────────────────────────────────────────────────┐
│ 业务 Controller (mcli / shunfeng / guangming / pro) │
└─────────────────────┬───────────────────────────────┘
                      │
          ┌───────────▼────────────┐
          │  YDService (组合)      │  公开签名不变
          └───────────┬────────────┘
                      │ 内部改调原子
     ┌────────────────┼────────────────┐
     │                │                │
┌────▼────┐    ┌──────▼──────┐   ┌─────▼──────┐
│YDClient │    │YDClient_Form│   │YDClient_Proc│
│(deprecated)│  │ (新增原子)  │   │ (新增原子) │
└─────────┘    └─────────────┘   └─────────────┘
                      │                │
                      └────┬───────────┘
                           ▼
                      UtilHttp (审计日志 §3.5)
                      UtilToken (tenantId:yida:appType)
```

## 模块拆分映射

### YDClient_Form（表单数据）

按宜搭官方文档模块映射：

| 子模块 | 方法前缀 | 备注 |
|--------|---------|------|
| 表单实例 CRUD | `saveForm` / `updateForm` / `deleteForm` / `getForm` | 单实例 |
| 查询 | `searchForm` / `listFormIds` / `listFormsAll` | 分页 / ID 列表 / 全量含子表 |
| 批量 | `batchSaveForm` / `batchUpsertForm` | 批量接口 |
| 组件值 | `listComponentValues` | 指定字段取值 |
| 操作日志 | `listFormOperations` | 审计日志 |
| 按条件删除 | `deleteFormByCondition` | 条件批量删 |

### YDClient_Process（流程审批）

| 子模块 | 方法前缀 | 备注 |
|--------|---------|------|
| 流程实例 | `startProcess` / `terminateProcess` / `revokeProcess` / `getProcess` / `searchProcesses` | 发起 / 终止 / 撤回 / 查 |
| 任务 | `agreeTask` / `disagreeTask` / `redirectTask` / `ccTask` / `commentTask` / `searchTasks` | 审批动作 |
| 节点 | `redirectProcess` / `removeNode` | 跳转节点 |

## 方法签名模板（强约束）

```java
/**
 * 新增表单实例
 * @apiNote https://open.dingtalk.com/document/orgapp/add-or-update-form-instances
 *
 * @param conf            宜搭应用鉴权（appType + systemToken + userId）
 * @param formUuid        表单 UUID（必填）
 * @param formDataJson    表单数据 JSON 字符串（必填，字段名使用表单 fieldId）
 * @param body_ext 可选字段：
 *   - noExecuteExpression (Boolean): 是否不执行公式字段计算
 *   - language (String): 语言（zh_CN/en_US）
 *   - ...（完整清单见官方文档）
 * @return formInstanceId 新增成功的表单实例 ID
 */
String saveForm(YDConf conf, String formUuid, String formDataJson, Map<String, Object> body_ext);
```

**强约束**：
1. 第 1 参永远是 `YDConf`（封装 appType / systemToken / userId）
2. 必填参数严格按官方文档顺序
3. 可选参数 `body_ext` 即使当前业务用不到也必须保留
4. javadoc 必须有 `@apiNote` 官方文档链接
5. javadoc 必须列出 body_ext 支持的 key（每个 key 标明类型）

## 兼容策略

- `YDClient` 接口文件不动，旧方法签名保持
- 旧方法在下个 `remove-yida-legacy-aggregate` change 里统一加 `@Deprecated` 并标注迁移目标
- `YDService` 可以内部悄悄切换到新方法，**只要公开签名不变**

## Non-Goals

- 不重写 `YDParam` 建造者的契约
- 不做"连接器应用"、"附件管理"、"表单设计器" 模块（作为后续 change 扩展）
- 不做反射式调度（每个方法显式实现）

## 风险

| 风险 | 缓解 |
|------|------|
| 旧 operateData 某些边角 case 在新方法里漏 | 迁移前保留旧路径，新方法就绪后做等价测试再切 YDService |
| 字段过多，`body_ext` javadoc 难维护 | 文档化**日期与当前官方版本**，后续按需更新；鼓励 PR review 时对照 |
| 客户子项目里有人绕过 YDService 直接调 YDClient 旧方法 | grep 审计 + 后续 Deprecated + 编译告警推动 |