目标架构
┌─────────────────────────────────────────────────────┐
│ 业务 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 |
跳转节点 |
方法签名模板（强约束）
/**
* 新增表单实例
* @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 参永远是
YDConf（封装 appType / systemToken / userId）
- 必填参数严格按官方文档顺序
- 可选参数
body_ext 即使当前业务用不到也必须保留
- javadoc 必须有
@apiNote 官方文档链接
- 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 + 编译告警推动 |
