mjava-ai/openspec/changes/archive/2026-04-19-extend-yida-api-coverage/tasks.md

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 路径
• 1.2 新建 com.malk.server.aliwork.YDAuth 数据载体（已有 YDConf 是 @Component 单例不能直接当参数，故新建 YDAuth 作为原子接口的请求上下文）
• 1.3 现有 YDParam 建造者保留不动；新原子接口直接用 Map<String,Object> body_ext 模式，语义更清晰

2. YDClient_Form 接口

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

3. YDClient_Form 实现

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

4. YDClient_Process 接口与实现

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