mjava-ai/openspec/changes/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 对照宜搭开放平台当前版本文档更新上述覆盖度矩阵，补齐 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 归档