## 0. 覆盖度矩阵（按官方文档对齐前置工作）

> 本节在实施前必须由开发者对照**当前**宜搭开放平台文档逐条填写。已知大致清单如下，具体参数以官方文档为准。

### YDClient_Form 覆盖度

| 官方 endpoint | HTTP | 方法名（建议） | 已对齐 | apiNote 链接 |
|--------------|------|---------------|-------|-------------|
| 新增表单实例 | POST | `saveForm` | ❌ | `/document/orgapp/add-or-update-form-instances` |
| 更新表单实例 | PUT | `updateForm` | ❌ | 待补 |
| 修改指定字段值 | PUT | `updateFormComponents` | ❌ | 待补 |
| 删除表单实例 | DELETE | `deleteForm` | ❌ | 待补 |
| 按条件删除 | POST | `deleteFormByCondition` | ❌ | 待补 |
| 查单条 | GET | `getForm` | ❌ | 待补 |
| 分页查询 | POST | `searchForm` | ❌ | `/document/orgapp/retrieve-search-form-information` |
| 全量查询含子表 | POST | `listFormsAll` | ❌ | `/document/orgapp/retrieve-list-all` |
| 查询 ID 列表 | POST | `listFormIds` | ❌ | 待补 |
| 组件值查询 | POST | `listComponentValues` | ❌ | 待补 |
| 批量新增 | POST | `batchSaveForm` | ❌ | 待补 |
| 批量 upsert | POST | `batchUpsertForm` | ❌ | 待补 |
| 查操作日志 | POST | `listFormOperations` | ❌ | 待补 |
| 附件临时 URL | POST | `convertTempUrl` | ✅（旧 `convertTemporaryUrl`）| 迁移 |

### YDClient_Process 覆盖度

| 官方 endpoint | HTTP | 方法名 | 已对齐 | apiNote |
|--------------|------|-------|-------|---------|
| 发起流程 | POST | `startProcess` | ❌ | `/document/orgapp/initiate-a-process` |
| 同意任务 | POST | `agreeTask` | ❌ | 待补 |
| 拒绝任务 | POST | `disagreeTask` | ❌ | 待补 |
| 转交任务 | POST | `redirectTask` | ❌ | 待补 |
| 抄送 | POST | `ccTask` | ❌ | 待补 |
| 评论任务 | POST | `commentTask` | ❌ | 待补 |
| 终止流程 | POST | `terminateProcess` | ❌ | 待补 |
| 撤回流程 | POST | `revokeProcess` | ❌ | 待补 |
| 跳转节点 | POST | `redirectProcess` | ❌ | 待补 |
| 查流程详情 | GET | `getProcess` | ❌ | 待补 |
| 分页查流程 | POST | `searchProcesses` | ❌ | 待补 |
| 查任务列表 | POST | `searchTasks` | ❌ | 待补 |

## 1. 前置准备

- [ ] 1.1 对照宜搭开放平台**当前版本**文档更新上述覆盖度矩阵，补齐 apiNote 链接
- [ ] 1.2 在 `com.malk.server.aliwork` 下建 `YDConf` 封装 `appType + systemToken + userId`（若已有则复用）
- [ ] 1.3 审视现有 `YDParam` 建造者，识别可沿用字段避免重复

## 2. YDClient_Form 接口

- [ ] 2.1 新建 `mjava/src/main/java/com/malk/service/aliwork/YDClient_Form.java` 接口
- [ ] 2.2 按覆盖度矩阵声明全部 14 个方法，signature 严格按 §3.4.2 规则
- [ ] 2.3 每个方法 javadoc 写全 `@apiNote` + `body_ext` 字段枚举

## 3. YDClient_Form 实现

- [ ] 3.1 新建 `impl/YDClient_FormImpl.java`
- [ ] 3.2 每个方法通过 `UtilHttp.doPost/doGet/doPut/doDelete` 实现
- [ ] 3.3 返回值统一 `Map` 或 `List<Map>`（特殊 DTO 情况另议）
- [ ] 3.4 错误处理：宜搭侧 `code != 0` 抛 `McException`

## 4. YDClient_Process 接口与实现

- [ ] 4.1 新建 `YDClient_Process.java` 接口
- [ ] 4.2 按覆盖度矩阵声明全部 12 个方法
- [ ] 4.3 新建 `impl/YDClient_ProcessImpl.java`

## 5. YDService 切换

- [ ] 5.1 `YDService` 公开签名不变，内部将 `operateData` / `queryData` 分支调用改为调原子方法
- [ ] 5.2 保留旧 `YDClient.operateData` / `queryData` 原样
- [ ] 5.3 回归测试：mcli / shunfeng / guangming 三个客户不回归

## 6. 文档与审计

- [ ] 6.1 审计日志（`UtilHttp` §3.5）在新原子方法生效时验证字段齐全
- [ ] 6.2 更新 `/Users/malk/Desktop/Tech/claude/后端/yida-serverside.md`，把"YDClient 用法"替换为新原子方法示例

## 7. 验证

- [ ] 7.1 单元测试覆盖所有 26 个方法的参数透传（mock `UtilHttp` 校验 body 含所有传入字段）
- [ ] 7.2 集成测试：至少对 3 个关键 endpoint（saveForm / startProcess / agreeTask）跑真实宜搭调用
- [ ] 7.3 `openspec validate extend-yida-api-coverage --strict` 通过

## 8. 交付

- [ ] 8.1 PR 附覆盖度矩阵对照截图
- [ ] 8.2 走 `/opsx:archive` 归档