字段对照表
调用前先确认数据属于哪个应用、哪张表，再建立字段映射。中文列名用于阅读，字段标识与存储值用于接口，不能直接互换。
读取应用和表单信息
产品 API 文档提供 获取应用信息 和 获取应用表单信息。页面会带入当前 applicationId，调用时仍需核对目标。
| 方法与相对路径 | 返回用途 | 认证上下文 |
|---|---|---|
| GET /apaas/app/{applicationId} | 应用名称、说明和状态等信息 | Bearer、TENANT-ID；核对应用上下文 |
| GET /form/form-metadata/application/{applicationId} | 目标应用下的表单列表 | Bearer、TENANT-ID、X-APPLICATION-ID |
这两个信息接口与 /open-api/openapi/form/* 的签名数据接口不同，按各自文档提供请求头，不因同样读取信息就混用地址或参数。
响应中的表单 ID、applicationId 与当前应用一致后，再选择目标表单；不要根据相似名称猜 ID。示例路径中的花括号表示占位符，发送前替换成真实值。
建立字段对照表
在 字段对照表 核对当前表单的展示名称和实际字段。需要组件选项、关联或文件协议时，由有权人员提供完整字段定义；只看中文名称不足以拼写入值。
建议为集成保存以下映射：
| 内容 | 作用 |
|---|---|
| 应用 ID、表单 ID、table | 明确目标与归属 |
| 业务字段名、真实 field、物理列 | 区分展示、写入和查询标识 |
| 组件类型、必填、唯一、只读 | 选择值形态与可操作范围 |
| 选项 field、开关 activeId/inactiveId | 避免将展示文字当作存储值 |
| 关联目标和子表 schema | 确认关联 ID 与嵌套结构 |
使用正确的值
| 组件 | 典型协议值 | 注意 |
|---|---|---|
| 文本 | "事项说明" | 核对长度与必填 |
| 数字 | 12.5 | 核对精度、范围和单位 |
| 单选、多选 | ["OPTION_FIELD_ID"] | 即使单选也按协议数组；使用 options[].field |
| 开关 | ["ACTIVE_ID"] | 使用真实 activeId/inactiveId，不能用 true/false 代替 |
| 上传 | [{"url":"FILE_URL","name":"example.pdf"}] | 单文件也为数组；文件访问权限另验 |
| 人员、部门、关联与子表 | 按对应定义 | 不套用普通文本或选项协议 |
上表是值形态示意，OPTION_FIELD_ID 等都不是可提交到任意表单的真实值。选项的 label/value 不用于推导 field。
区分 V1 与 V2 字段结构
V1 兼容写入通过 columns.metadata 和 columns.values 按位置对应字段和值；V2 通过 data 对象提交语义字段。查询条件中的 var 应使用当前查询合同要求的实际列标识，不假定与 data 的语义映射相同。
字段改名、选项调整或部署升级后重新核对映射。不要把旧截图或另一环境的字段 ID 当作当前定义。示例见数据写入与网关。
字段对照表怎样取得
这是一项文档页功能，不是一个可凭名称拼造的 HTTP 接口。先打开目标表单的 API 文档，再选择“字段对照表”；核对组件标识、字段标识、物理列、组件类型和系统字段标记。需要程序读取应用或表单元数据时，分别使用应用信息和应用表单信息。
| 用途 | 应采用的标识 |
|---|---|
| V1 columns.metadata | 当前表单实际物理列，按示例使用表单ID.列名 |
| V2 data 的键 | 当前映射支持的组件 field、componentId 或物理列；推荐稳定 field |
| 匿名 submit 的 data 键 | 分享表单 formSettings.field |
| 界面中文标题 | 用于阅读，不能直接代替存储标识 |
V2 映射会把已登记的 field / componentId 解析到实际列；未知键不保证自动修复。重命名标题不会自动更改接口字段合同。正式接入前保存目标表单的当前映射，变更后重新核对。