## ADDED 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** 返回该实例的全部变更历史记录（含操作人 / 操作时间 / 操作类型）