mjava-ai/openspec/specs/yida-form-atomic/spec.md

yida-form-atomic Specification

Purpose

TBD - created by archiving change extend-yida-api-coverage. Update Purpose after archive.

Requirements

Requirement: 表单实例 CRUD 原子接口

YDClient_Form SHALL 提供与宜搭官方 1:1 对应的表单实例增删改查原子方法。方法签名 MUST 严格遵守 mjava-baseline §3.4.2（必填参数显式 + body_ext 承接可选参数 + javadoc 枚举全部 body_ext key + @apiNote 链到官方文档）。

Scenario: 新增表单实例

• WHEN 调用 YDClient_Form.saveForm(conf, formUuid, formDataJson, body_ext)
• THEN 发起 POST /v1.0/yida/forms/instances（或旧版 /dingtalk/yida/processes/saveFormData）
• AND body_ext 所有可选参数必须透传（不删、不填默认）
• AND 失败时抛 McException 带宜搭原始错误码

Scenario: 更新表单实例

• WHEN 调用 YDClient_Form.updateForm(conf, formInstanceId, updateFormDataJson, body_ext)
• THEN 必须支持 useLatestVersion / ignoreEmpty 选项（通过 body_ext 透传）
• AND 默认不改这两个参数的宜搭侧默认行为

Scenario: 删除表单实例

• WHEN 调用 YDClient_Form.deleteForm(conf, formInstanceId, body_ext)
• THEN 单条删除走 DELETE 接口；批量条件删除走 deleteFormByCondition

Requirement: 表单查询原子接口

YDClient_Form SHALL 提供分页、ID 列表、全量含子表三种查询粒度，查询方法 MUST 分别对应宜搭官方的不同 endpoint（不混用一个方法承担多种语义）。

Scenario: 分页查询

• WHEN searchForm(conf, formUuid, searchFieldJson, currentPage, pageSize, body_ext)
• THEN 对应 POST /v1.0/yida/forms/instances/search
• AND pageSize 超过 100 时抛 McException（宜搭侧强制上限）

Scenario: 全量查询含子表

• WHEN listFormsAll(conf, formUuid, currentPage, pageSize, body_ext)
• THEN 对应 retrieve_list_all（含子表数据），与 searchForm（不含子表）行为区分清楚

Scenario: 查询组件值

• WHEN listComponentValues(conf, formUuid, fieldId, body_ext)
• THEN 可获取指定字段的可选项列表

Requirement: 批量操作

YDClient_Form SHALL 提供批量新增与批量 upsert 两个方法，MUST 遵守宜搭侧每批 ≤ 100 条的限制。

Scenario: 批量新增

• WHEN batchSaveForm(conf, formUuid, formDataListJson, body_ext)
• THEN 一次调用批量创建多条记录
• AND 超过 100 条时必须由调用方自行分片（或方法内自动分片，策略见 Service 层）

Scenario: 批量 upsert

• WHEN batchUpsertForm(conf, formUuid, searchConditionListJson, dataListJson, body_ext)
• THEN 对应批量 upsert
• AND searchCondition 里日期字段 MUST 用字符串数组格式（规避 selectListException）

Requirement: 操作日志查询

YDClient_Form SHALL 提供表单实例的操作历史查询方法。

Scenario: 查询实例变更历史

• WHEN listFormOperations(conf, formInstanceId, body_ext)
• THEN 返回该实例的全部变更历史记录（含操作人 / 操作时间 / 操作类型）