vibeCoding/mjava-ai @ 660b557f8258a3d7c1bd2e7f2f33ac45ac271843

状态（2026-04-18 立项）：规则定义阶段，不做代码改造 优先级：最高（Phase B.1 首个专项）改造执行等规则通过后，走 /opsx:apply extend-yida-api-coverage

Why

YDClient 当前只有两个聚合方法 operateData(param, FORM_OPERATION) 与 queryData(param, FORM_QUERY)，通过枚举内部路由到不同宜搭 API。违反 mjava-baseline §3.4 的"Client 原子接口 1:1 对应官方 endpoint"规范：

一个方法承载多种语义，调用方必须理解 FORM_OPERATION 枚举才能用；
参数通过 YDParam 建造者承载，无法从方法签名直接看出哪些字段必填；
官方新增 endpoint 时没有明确的落地位置，容易漏或错位；
Service 层无法对单一 endpoint 做精准缓存或审计（审计颗粒度只能到 operateData）。

现有三个客户模块（mcli / shunfeng / guangming）依赖旧 operateData / queryData，不能直接删。采用"新增对齐方法 + 保留旧方法 @Deprecated"的并行策略（mjava-baseline §3.4.4）。

What Changes

按宜搭开放平台官方文档，把 YDClient 拆分为：

service/aliwork/
├── YDClient.java              # 保留旧 operateData/queryData, 标 @Deprecated
├── YDClient_Form.java         # 表单数据 API 原子接口（新增）
├── YDClient_Process.java      # 流程审批 API 原子接口（新增）
└── YDService.java             # 组合服务（保留，内部改调 Form/Process 原子方法）

新增 YDClient_Form：覆盖表单实例增删改查、批量、按条件删除、查询组件值等
新增 YDClient_Process：覆盖发起/同意/拒绝/转交/跳转/撤回/终止/任务评论等
方法签名严格按 mjava-baseline §3.4.2 规则：必填参数显式、可选参数放 Map body_ext 并在 javadoc 中穷举
每个方法 @apiNote 链到宜搭官方文档对应页面

Capabilities

New Capabilities

yida-form-atomic：宜搭表单原子接口集
yida-process-atomic：宜搭流程原子接口集

Modified Capabilities

yida-legacy-aggregate（现有）：标记为 deprecated，保持现有行为

Impact

新增文件：YDClient_Form.java + YDClient_Process.java + impl/ 两份实现 + 可能的 YDParam 补字段
不动：YDClient.operateData / queryData 方法签名与行为
YDService 改造（可选）：内部调用从 YDClient.operateData 迁到新原子方法，保持公开签名不变，让调用方透明受益
mcli / shunfeng / guangming 三个客户：零影响
审计日志：每个原子方法都能被 UtilHttp 单独打点，颗粒度从"操作/查询"提升到具体 endpoint

Non-Goals

❌ 不删旧 operateData / queryData（等所有新方法稳定 + 全部调用方迁移完成，再单独走一个 remove-yida-legacy-aggregate change）
❌ 不封装 SDK 层（依然走 UtilHttp.doRequest）
❌ 本提案不做"连接器"、"附件"、"流程设计器"模块（作为后续扩展 change）
❌ 不改 YDParam 建造者的对外契约（内部扩字段 OK）

proposal.md 3.1 KB Előzmények Nyers

Why