表单定义扫描
表单定义扫描用于读取来源系统中“有哪些表单、每张表单有哪些字段”的配置,并在 Soln 中生成可配置的表单模型。适用于低代码系统、CRM、ERP 等将表单结构保存在配置表或 JSON/XML 文档中的应用。
例如,来源数据库中有一张 form_records 表,客户、订单、合同的记录都保存在其中。仅扫描数据库结构,只能看到 form_id、data 等物理列;读取表单定义后,才能识别“客户名称”“订单金额”等业务字段。
先分清三类配置
| 配置 | 解决的问题 | 示例 |
|---|---|---|
| 数据库结构扫描 | 数据库有哪些表、列、键和物理关系 | 发现 forms、form_fields、form_records |
| 表单定义扫描 | 来源系统有哪些表单和业务字段 | 识别 account 表单及其 customer_name 字段 |
| 业务数据读取规则 | 每条业务记录和字段值从哪里读取 | 从 form_records.data 读取 customer_name |
表单定义扫描完成,不代表已经可以查询业务记录。 扫描后还需要配置业务数据读取规则,再创建数据集。表单之间的关联由关系定义扫描另外配置。
如果来源本身就是一张字段清晰的业务表,也可以直接从数据库表创建数据集,无需先扫描表单定义。
开始前准备
- 创建并测试数据源,完成数据库结构扫描。
- 找到保存表单定义和字段定义的位置。两者可以在不同表中,也可以在同一份文档中。
- 确认表单名称、表单编码,以及字段所属表单的标识。
- 准备至少一张表单及其字段样例。需要读取选项、特殊类型或 JSON/XML 时,优先选择包含这些内容的样例。
名称用于显示,编码用于标识业务对象。例如“客户”是名称,account 是表单编码;“客户名称”是名称,customer_name 是字段编码。不要将可修改的显示名称当作稳定编码。
新建扫描规则
- 进入数据源的结构页面,打开 表单定义扫描,新建规则。
- 填写便于维护的规则名称,例如“CRM 表单与字段定义”。
- 在 表单定义来源 中选择来源表和读取方式,配置表单属性。
- 获取表单列表,检查名称、编码和来源表单 ID。
- 选择一张表单,在 字段定义来源 中配置所属表单匹配和字段属性。
- 获取字段,检查当前表单是否只出现属于自己的字段;再切换其他表单检查。
- 需要时配置选项、唯一字段、显示名称字段和字段类型映射。
- 点击 保存并开始扫描,等待后台扫描完成,再到结构页面检查生成的表单模型。
保存需要同时完成表单与字段规则。规则名称或必填读取配置未填写时,点击保存会显示全局提示。预览用于检查配置,保存并执行扫描后才会生成或更新表单定义。
配置表单定义来源
选择读取方式
| 方式 | 定义的存储形式 | 配置重点 |
|---|---|---|
| 数据库列 | 每行一张表单,属性分别保存在列中 | 直接选择名称、编码等对应列 |
| JSON | 表单定义保存在 JSON 列的对象或列表中 | 先选择定义列和表单列表位置,再选择每项属性 |
| XML | 表单定义保存在 XML 节点或属性中 | 先选择定义列和表单节点,再选择节点内容或属性 |
JSON/XML 的读取方式描述的是定义如何存储,与某个业务字段最终被识别为文本、JSON 或 XML 是两回事。表单定义使用数据库列读取时,其中的某个业务字段仍然可以是 JSON 类型。
表单属性怎么填
| 属性 | 是否必填 | 填写内容 |
|---|---|---|
| 名称 | 是 | 来源中的表单显示名称,例如 客户 |
| 编码 | 是 | 稳定的表单编码或 API 名称,例如 account |
| 来源表单 ID | 否,按匹配需要填写 | 来源系统为表单分配的 ID,例如 f_customer |
| 描述 | 否 | 表单说明 |
当字段定义、关系定义或业务记录通过表单 ID 归属到表单时,应读取 来源表单 ID。这个 ID 来自来源系统,与 Soln 生成的模型 ID、某条业务记录 ID 分别使用。
JSON/XML 模式中,列表位置用于定位每条表单定义,名称、编码等路径相对于选中的每条定义读取。尽量从样例下拉选项中选择,避免把整个文档路径重复填入属性位置。
配置字段定义来源
先配置字段属于哪张表单
字段规则必须明确每个字段的所属表单。匹配方式取决于来源实际保存的值:
| 字段定义中的值 | 应选择的匹配方式 | 前提 |
|---|---|---|
form_id = f_customer | 来源表单 ID | 表单规则已读取 f_customer |
form_code = account | 表单编码 | 表单规则已读取 account |
| 所属表单信息在 JSON/XML 内 | 从文档读取所属表单标识 | 选择表单列表、标识路径及其 ID/编码含义 |
例如,form_fields.form_id 应匹配表单定义的 forms.id,不能匹配 form_records.id。若两张表单都有 name 字段,必须先按所属表单区分,再读取字段;不能只按字段编码归类。
再配置每个字段的属性
| 属性 | 是否必填 | 用途 |
|---|---|---|
| 字段名称 | 是 | 展示给用户的名称,例如“客户名称” |
| 字段编码 | 是 | 标识字段,例如 customer_name |
| 来源字段 ID | 否 | 选项或关系通过字段 ID 匹配时需要读取 |
| 来源字段类型 | 否,建议读取 | 将来源类型转换为 Soln 标准类型 |
| 必填标记 | 否 | 读取来源定义的必填信息 |
| 描述 | 否 | 字段说明 |
唯一字段和显示名称字段可分别设置:
- 按标记识别:字段定义本身有标志,例如
is_unique = true、is_display_name = true,选择标记位置和匹配值。 - 按字段引用识别:某个配置位置保存了目标字段编码或 ID,例如表单配置中的
title_field = customer_name,读取该引用,再选择按字段编码或来源字段 ID 匹配。 - 来源没有对应信息时,可以不配置;后续再根据业务需要设置。
唯一字段表示来源定义声明该字段用于唯一识别,显示名称字段用于展示记录或关联值的名称。扫描不会读取全部业务记录验证字段是否重复,也不会为来源数据库创建唯一约束。
配置选项读取
单选等字段如果保存的是 important、normal 这类值,需要同时读取其显示名称,例如“重要客户”“普通客户”。否则预览中可能只能看到原始值。
| 选项来源 | 配置方式 |
|---|---|
| 字段行中的 JSON/XML 列 | 选择选项所在列、选项列表,以及每项的标签和值 |
| 字段定义文档内部 | 选择当前字段内的选项列表,再选择每项的标签和值 |
| 独立选项表 | 选择选项表、匹配列,以及标签列和值列 |
独立选项表可以按字段编码、来源字段 ID 或定义中保存的匹配值读取。按来源字段 ID 匹配时,字段规则必须读取该 ID;按定义中的匹配值读取时,需要配置该值的位置。
如果不同表单复用字段编码或字典标识,还应配置选项的所属表单列及 ID/编码匹配,避免将其他表单的选项混入当前字段。
配置表单字段类型映射
在表单定义扫描编辑弹窗中打开 表单字段类型映射。
- 来源字段类型 支持自动完成,可以选择常见值,也可以输入来源系统实际返回的类型名称。
- 标准类型 包括文本、整数、小数、数值、布尔、日期、日期时间、时间、JSON、XML、数组、UUID 和二进制。
- 同一数据源的所有表单定义扫描共用这套映射。
- 自定义映射优先;未自定义的类型按内置规则处理,清空自定义配置后恢复默认处理。
- 修改映射后,重新扫描表单定义,使已识别的字段更新类型。
例如,内置规则将 object 识别为 JSON。来源系统使用 single_line_text 表示文本时,可以新增 single_line_text → string;使用 money_amount 表示金额时,可以配置 money_amount → decimal。
不要仅根据名称推断类型。例如,同一个 timestamp 在不同数据库中可能有不同含义,应结合来源定义和实际值判断。这套配置影响表单字段元数据,不会改变物理数据库列类型,也不会修改来源数据。
完整示例:客户与订单共用一张记录表
以下是一个简化的 CRM 示例。表名和编码用于说明配置方法,不要求来源系统采用相同命名。
1. 理解来源结构
表单定义保存在 public.forms:
| id | api_name | name |
|---|---|---|
f_customer | account | 客户 |
f_order | sales_order | 订单 |
字段定义保存在 public.form_fields:
| id | form_id | api_name | name | type | is_unique | is_display_name |
|---|---|---|---|---|---|---|
fld_1 | f_customer | customer_code | 客户编号 | text | true | false |
fld_2 | f_customer | customer_name | 客户名称 | text | false | true |
fld_3 | f_customer | customer_level | 客户等级 | text | false | false |
fld_4 | f_customer | address | 客户地址 | object | false | false |
fld_5 | f_order | order_no | 订单编号 | text | true | true |
fld_6 | f_order | amount | 订单金额 | decimal | false | false |
form_fields 另外有一列 options,customer_level 的值是:
[
{ "label": "重要客户", "value": "important" },
{ "label": "普通客户", "value": "normal" }
]
业务记录保存在 public.form_records:
| id | form_id | data |
|---|---|---|
r_customer_1 | f_customer | 客户字段值的 JSON 对象 |
r_order_1 | f_order | 订单字段值的 JSON 对象 |
其中一条客户记录的 data 为:
{
"customer_code": "C001",
"customer_name": "华远科技",
"customer_level": "important",
"address": { "province": "北京市", "city": "北京市", "street": "中关村南大街18号" }
}
2. 配置表单定义
新建规则“CRM 表单与字段定义”,填写:
| 配置项 | 选择值 |
|---|---|
| 表单定义来源 | public.forms |
| 读取方式 | 数据库列 |
| 名称 | name |
| 编码 | api_name |
| 来源表单 ID | id |
获取表单后,预期看到“客户 / account”和“订单 / sales_order”,来源表单 ID 分别为 f_customer、f_order。
3. 配置字段定义
| 配置项 | 选择值 |
|---|---|
| 字段定义来源 | public.form_fields |
| 读取方式 | 数据库列 |
| 所属表单匹配 | 来源表单 ID |
| 所属表单标识来源 | 数据库列 form_id |
| 字段名称 | name |
| 字段编码 | api_name |
| 来源字段 ID | id |
| 来源字段类型 | type |
| 唯一字段 | 按标记识别,位置 is_unique,匹配值 true |
| 显示名称字段 | 按标记识别,位置 is_display_name,匹配值 true |
选项读取选择 JSON 文档,列选择 options,列表位置选择整个数组 $[*],标签选择 $.label,值选择 $.value。没有选项的字段不会因此变成单选字段。
选中“客户”获取字段,预期只看到前 4 个客户字段;切换“订单”后,预期只看到 order_no 和 amount。如果两边都出现全部字段,先检查 form_id 的匹配配置。
4. 检查类型与扫描结果
本例中,text 使用内置文本映射,decimal 识别为小数,object 识别为 JSON。点击 保存并开始扫描 后,检查:
- “客户”模型包含 4 个字段,“订单”模型包含 2 个字段。
- “客户编号”标记为唯一字段,“客户名称”标记为显示名称字段。
- “客户等级”包含
important → 重要客户、normal → 普通客户两个选项。 - “客户地址”的标准类型为 JSON。
5. 继续配置业务记录读取
在业务数据读取规则中选择 public.form_records 作为记录来源,将保存表单标识的列设置为 form_id,按来源表单 ID 匹配;字段值从 data 的对应字段编码读取。
这样,“客户”读取 form_id = f_customer 的记录,并从 data.customer_name 等位置取值;“订单”读取 form_id = f_order 的记录。预览应能看到“华远科技”,客户等级显示为“重要客户”。
需要在图表中单独使用地址的省、市时,再按下文识别 JSON 子字段。这里的业务数据读取属于下一步配置,不能用字段定义的 form_fields 表代替。
JSON 定义示例:表单与字段保存在同一份文档
如果 public.app_definitions.payload 保存以下内容:
{
"forms": [
{
"id": "f_customer",
"code": "account",
"name": "客户",
"fields": [
{ "id": "fld_1", "code": "customer_name", "name": "客户名称", "type": "text" },
{ "id": "fld_2", "code": "address", "name": "客户地址", "type": "object" }
]
}
]
}
表单与字段来源都选择 public.app_definitions,读取方式都选择 JSON。按下表选择样例中的位置:
| 配置区域 | 配置项 | 路径或选择值 |
|---|---|---|
| 表单定义 | 定义列 | payload |
| 表单定义 | 表单列表位置 | $.forms[*] |
| 表单定义 | 名称 / 编码 / 来源表单 ID | $.name / $.code / $.id |
| 字段定义 | 所属表单匹配 | 来源表单 ID |
| 字段定义 | 所属表单标识来源 | JSON 文档 |
| 字段定义 | 定义列 | payload |
| 字段定义 | 表单列表位置 | $.forms[*] |
| 字段定义 | 所属表单标识路径 | $.id |
| 字段定义 | 字段列表位置 | $.fields[*],相对于每条表单定义 |
| 字段定义 | 字段名称 / 编码 / 来源字段 ID / 类型 | $.name / $.code / $.id / $.type,相对于每条字段定义 |
这里 $.fields[*] 是从当前表单对象读取字段列表,不要填成 $.forms[*].fields[*] 后再次套用表单列表。
XML 的配置顺序相同:先定位表单节点,再定位表单内的字段节点,最后选择节点文本或属性。请使用 XML 样例生成的路径选项,不能直接套用 JSON 的 $.xxx 路径。
识别 JSON/XML 子字段
父字段是 JSON/XML 对象,且需要在数据集、图表或 API 元数据中继续使用其内部值时,可以识别子字段。例如,将“客户地址”中的省、市、街道作为可选子字段。
- 确保父字段已识别为 JSON 或 XML,并已配置业务记录读取规则。
- 在表单定义扫描编辑弹窗的字段列表中,打开该字段的 识别子字段。
- 读取业务记录样例,或粘贴有代表性的 JSON/XML 值。
- 检查标量路径、字段名称和类型,勾选需要保留的字段,按需调整顺序。
- 应用到扫描规则,再保存并执行扫描。
- 刷新并保存受影响的数据集,使子字段出现在图表配置和 API 元数据中。
识别最多读取 20 条样例;样例中没有出现的路径需要另取样例检查。数组和 XML 重复节点不展开。MySQL 和 MariaDB 不支持查询 XML 子字段。
“字段定义使用 JSON 读取”不代表每个字段都需要识别子字段。只有业务值本身是 JSON/XML,且需要使用内部属性时才配置。
使用 AI 协助分析
打开具体数据源的结构页面后,可以在现有 AI 对话中输入:
分析当前数据源的表结构,识别表单定义和字段定义的来源,验证字段所属表单的匹配方式。给出名称、编码、来源 ID、类型和选项的配置方案,并说明样例验证结果。先分析,不保存。
当前页面会提供数据源及所选表的上下文,AI 可以进一步读取结构和有限样例、验证候选关联。检查结论中的来源表、匹配列和路径,再决定是否应用。仅有表名相似或少量样例匹配,不能证明全部记录都满足关系。
维护规则与排查问题
每条规则可以单独配置定时扫描。来源定义变更后,重新执行表单定义扫描;若物理表、列也发生变化,应先刷新数据库结构。扫描完成后,继续检查受影响的数据读取规则和数据集。
删除表单定义扫描规则会保留已生成的表单和字段,并解除它们与该规则的归属关系。
| 现象 | 优先检查 |
|---|---|
| 没有表单结果 | 来源表是否有数据,名称和编码列是否正确,JSON/XML 是否有效、列表位置是否正确 |
| 有表单,但获取不到字段 | 所属表单标识是否保存 ID 或编码;表单规则是否读取了对应值 |
| 不同表单混入相同字段 | 字段所属表单列或文档标识路径是否正确 |
| 字段显示“未识别类型” | 类型读取位置是否正确,实际类型值是否需要新增映射;修改后重新扫描 |
| 选项为空或混入其他表单 | 选项列表、标签和值是否正确,是否缺少字段或表单匹配 |
| 可以看到字段,但业务预览为空 | 检查业务数据读取规则中的记录来源、表单筛选、字段路径 |
| 子字段识别不到内容 | 父字段类型和业务读取是否正确,样例是否为空、无效或只有数组 |
| 保存时提示规则未完成 | 同时检查表单与字段来源、必填属性、所属表单匹配及已启用的选项/标记配置 |