## 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 ⚠️ **阻塞**：官方文档 WebFetch 未成功（索引页），覆盖度矩阵基于 2026-04 训练知识 + 现有 `YDClientImpl` 已验证 URL。实施冒烟前必须对照官方文档逐条复核，尤其是 `processes/tasks/*` 与 `listApprovalRecords` 路径
- [x] 1.2 新建 `com.malk.server.aliwork.YDAuth` 数据载体（已有 YDConf 是 @Component 单例不能直接当参数，故新建 YDAuth 作为原子接口的请求上下文）
- [x] 1.3 现有 `YDParam` 建造者保留不动；新原子接口直接用 `Map<String,Object> body_ext` 模式，语义更清晰

## 2. YDClient_Form 接口

- [x] 2.1 新建 `mjava/src/main/java/com/malk/service/aliwork/YDClient_Form.java` 接口
- [x] 2.2 声明 16 个方法（14 必须 + `remarkForm` 评论 + `convertTempUrl` 附件临时 URL 从旧 YDClient 迁入）
- [x] 2.3 每个方法 javadoc 写全 `@apiNote` + `body_ext` 字段枚举

## 3. YDClient_Form 实现

- [x] 3.1 新建 `impl/YDClient_FormImpl.java`
- [x] 3.2 每个方法通过 `UtilHttp.doPost/doGet/doPut/doDelete` 实现；update 走 PUT，delete 走 DELETE
- [x] 3.3 返回值 `String` / `Map<String,Object>` / `List<Map<String,Object>>` / `Boolean` 按官方语义选择
- [x] 3.4 错误处理：`assertResult` 统一抛 `McException` 带宜搭原始错误码

## 4. YDClient_Process 接口与实现

- [x] 4.1 新建 `YDClient_Process.java` 接口
- [x] 4.2 声明 11 个方法（startProcess / terminateProcess / revokeProcess / redirectProcess / agreeTask / disagreeTask / redirectTask / ccTask / commentTask / getProcess / searchProcesses / listProcessIds / listApprovalRecords — 实际 13 个，超额覆盖 design.md 最小要求）
- [x] 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` 归档