# CustomForm 操作使用手册（宴请预订）

适用范围：
- 组件目录：lowcode-react-material/src/components/custom-form
- 对照页面配置：lowcode-react-material/src/components/custom-form/schema.json

目标：
- 按照现有 schema.json 的业务口径，使用 CustomForm 还原“宴请预订表单”
- 你可以按本文逐项配置并逐项测试

---

## 1. 对照关系（schema.json -> CustomForm）

### 1.1 旧 schema 的关键业务点

1. 字段状态（state）
- banquet_date
- banquet_time
- guest_count
- package_name
- package_name_text
- package_price
- user_name
- user_mobile
- memo
- order_desc
- order_status（默认值：待处理）

2. 数据源
- 套餐列表查询：node_ocmk24smc2g
  - POST /source/api/dynamicFormTableRecord/page/1203689394066821120
- 提交预订：node_ocmk24smc3g
  - POST /source/api/dynamicFormTableRecord/1203690686210248704/

3. 旧逻辑方法
- onPackageNameChange：根据套餐 id 回填 package_price、package_name_text
- onSubmitClick：拼接 order_desc，组装 itemList，调用提交数据源

### 1.2 在 CustomForm 中的对应能力

1. 字段状态维护
- 由 CustomForm 内部统一管理，不再手写多个 onXxxChange

2. 套餐联动
- 用 fieldLinkage 替代 onPackageNameChange
- 通过 dataSource + fillFields 一次回填多个字段

3. 订单描述拼接
- 用 computedFields 替代手动拼接 order_desc

4. 提交参数组装
- 用 submitMapping 替代 onSubmitClick 中手动 itemList

5. 提交动作
- 提交按钮绑定数据源（对应 node_ocmk24smc3g）

---

## 2. 宴请预订表单配置清单（按顺序）

以下步骤在低代码设计器中，对 CustomForm 组件进行配置。

### 步骤 1：放置 CustomForm

1. 拖入 CustomForm 到页面
2. 推荐布局：
- columns：2
- labelAlign：left
- fullWidth：true

### 步骤 2：配置表单项 formItems

按下面字段建立表单项：

1. 宴请日期
- field：banquet_date
- label：宴请日期
- required：true
- componentType：DatePicker 或 Input（若要与旧 schema 完全一致可选 Input）

2. 宴请时间
- field：banquet_time
- label：宴请时间
- required：true
- componentType：Input

3. 宴请人数
- field：guest_count
- label：宴请人数
- required：true
- componentType：NumberPicker（或 Input）

4. 套餐名称
- field：package_name
- label：套餐名称
- required：true
- componentType：Select
- optionsBind：绑定套餐列表数据，value=套餐id，label=套餐名

5. 套餐名称文本（可不展示）
- field：package_name_text
- label：套餐名称文本
- componentType：Input
- formItemProps.invisible：true（若你希望隐藏）

6. 套餐价格
- field：package_price
- label：套餐价格
- componentType：Input
- componentProps.readOnly：true

7. 预订人名称
- field：user_name
- label：预订人名称
- required：true
- componentType：Input

8. 预订人联系方式
- field：user_mobile
- label：预订人联系方式
- required：true
- componentType：Input

9. 备注
- field：memo
- label：备注
- componentType：TextArea
- columnSpan：2

### 步骤 3：配置字段初始化 initialValues

建议添加：
- field：order_status
- valueType：fixed
- value：待处理

### 步骤 4：配置计算字段 computedFields

添加一条：
- targetField：order_desc
- template：{package_name_text},{package_price},预订日期时间：{banquet_date} {banquet_time},宴请人数：{guest_count}人

### 步骤 5：配置字段联动 fieldLinkage

使用数据源模式，添加一条规则：
- watchField：package_name
- linkageMode：dataSource
- dataSource：绑定套餐列表数据源（与 optionsBind 同源）
- matchKey：id
- fillFields：
  - package_price -> package_price
  - package_name_text -> package_name

说明：
- 旧 schema 中 package_name 存的是套餐 id，因此 matchKey 要和数据源主键一致（常见为 id）

### 步骤 6：配置提交映射 submitMapping

1. targetField：itemList
2. items 按下列顺序添加：
- columnName=banquet_time，template={banquet_date} {banquet_time}
- columnName=guest_count，field=guest_count
- columnName=package_name，field=package_name
- columnName=package_name_text，field=package_name_text
- columnName=package_price，field=package_price
- columnName=user_name，field=user_name
- columnName=user_mobile，field=user_mobile
- columnName=memo，field=memo
- columnName=order_desc，field=order_desc
- columnName=order_status，field=order_status

### 步骤 7：配置操作按钮 operations

建议保留两按钮：

1. 提交按钮
- text：提交预订
- action：submit
- type：primary
- submitValidate：true
- dataSource：绑定提交接口（原 schema 的 node_ocmk24smc3g）

2. 重置按钮
- text：重置
- action：reset
- type：normal

---

## 3. 测试流程（可直接照测）

### 用例 1：套餐数据加载

步骤：
1. 进入页面
2. 打开“套餐名称”下拉

期望：
- 能看到套餐选项
- 每个选项展示套餐名，提交值为套餐 id

### 用例 2：套餐联动回填

步骤：
1. 选择任意套餐

期望：
- package_price 自动回填
- package_name_text 自动回填

### 用例 3：计算字段生成

步骤：
1. 填写 banquet_date、banquet_time、guest_count
2. 选择套餐并完成联动

期望：
- order_desc 自动生成
- 格式为：套餐名称文本,套餐价格,预订日期时间：日期 时间,宴请人数：X人

### 用例 4：必填校验

步骤：
1. 不填必填项直接点“提交预订”

期望：
- 不触发提交接口
- 展示对应字段错误提示

### 用例 5：提交参数结构

步骤：
1. 完整填写表单后点击“提交预订”
2. 在网络面板或接口日志查看请求体

期望：
- 请求中包含 itemList 数组
- itemList 中 columnName/columnValue 与 submitMapping 配置一致
- 包含 order_desc 和 order_status

### 用例 6：重置按钮

步骤：
1. 先填写多个字段
2. 点击“重置”

期望：
- 可编辑字段被清空
- 若配置了 order_status 的初始值，可按设计预期保留或恢复

---

## 4. 快速排错

1. 选套餐后价格不回填
- 检查 fieldLinkage.matchKey 是否和数据源主键一致
- 检查 optionsBind 的 value 是否就是该主键

2. 提交后没有 itemList
- 检查 submitMapping.targetField 是否为 itemList
- 检查 items 是否至少有一条有效映射

3. order_desc 为空
- 检查 computedFields 的模板字段名是否与 formItems.field 完全一致

4. 提交按钮没调接口
- 检查 operations 中 submit 按钮是否绑定了 dataSource
- 检查 submitValidate 打开时是否存在校验失败

---

## 5. 推荐对照检查表

每次提测前可按下列核对：

1. 表单项字段名与 submitMapping 字段名完全一致
2. 套餐下拉 optionsBind 和 fieldLinkage.dataSource 同源
3. matchKey 与 optionsBind 的 value 字段一致
4. order_status 有初始值 待处理
5. 提交按钮绑定正确数据源（提交接口）
6. 必填项都设置了 required

完成以上 6 项，基本可覆盖 schema.json 中宴请预订主流程。
