跳到主要内容

表单定义扫描

表单定义扫描用于读取来源系统中“有哪些表单、每张表单有哪些字段”的配置,并在 Soln 中生成可配置的表单模型。适用于低代码系统、CRM、ERP 等将表单结构保存在配置表或 JSON/XML 文档中的应用。

例如,来源数据库中有一张 form_records 表,客户、订单、合同的记录都保存在其中。仅扫描数据库结构,只能看到 form_id、data 等物理列;读取表单定义后,才能识别“客户名称”“订单金额”等业务字段。

先分清三类配置​

配置解决的问题示例
数据库结构扫描数据库有哪些表、列、键和物理关系发现 forms、form_fields、form_records
表单定义扫描来源系统有哪些表单和业务字段识别 account 表单及其 customer_name 字段
业务数据读取规则每条业务记录和字段值从哪里读取从 form_records.data 读取 customer_name

表单定义扫描完成,不代表已经可以查询业务记录。 扫描后还需要配置业务数据读取规则,再创建数据集。表单之间的关联由关系定义扫描另外配置。

如果来源本身就是一张字段清晰的业务表,也可以直接从数据库表创建数据集,无需先扫描表单定义。

开始前准备​

  1. 创建并测试数据源,完成数据库结构扫描。
  2. 找到保存表单定义和字段定义的位置。两者可以在不同表中,也可以在同一份文档中。
  3. 确认表单名称、表单编码,以及字段所属表单的标识。
  4. 准备至少一张表单及其字段样例。需要读取选项、特殊类型或 JSON/XML 时,优先选择包含这些内容的样例。

名称用于显示,编码用于标识业务对象。例如“客户”是名称,account 是表单编码;“客户名称”是名称,customer_name 是字段编码。不要将可修改的显示名称当作稳定编码。

新建扫描规则​

  1. 进入数据源的结构页面,打开 表单定义扫描,新建规则。
  2. 填写便于维护的规则名称,例如“CRM 表单与字段定义”。
  3. 在 表单定义来源 中选择来源表和读取方式,配置表单属性。
  4. 获取表单列表,检查名称、编码和来源表单 ID。
  5. 选择一张表单,在 字段定义来源 中配置所属表单匹配和字段属性。
  6. 获取字段,检查当前表单是否只出现属于自己的字段;再切换其他表单检查。
  7. 需要时配置选项、唯一字段、显示名称字段和字段类型映射。
  8. 点击 保存并开始扫描,等待后台扫描完成,再到结构页面检查生成的表单模型。

保存需要同时完成表单与字段规则。规则名称或必填读取配置未填写时,点击保存会显示全局提示。预览用于检查配置,保存并执行扫描后才会生成或更新表单定义。

配置表单定义来源​

选择读取方式​

方式定义的存储形式配置重点
数据库列每行一张表单,属性分别保存在列中直接选择名称、编码等对应列
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:

idapi_namename
f_customeraccount客户
f_ordersales_order订单

字段定义保存在 public.form_fields:

idform_idapi_namenametypeis_uniqueis_display_name
fld_1f_customercustomer_code客户编号texttruefalse
fld_2f_customercustomer_name客户名称textfalsetrue
fld_3f_customercustomer_level客户等级textfalsefalse
fld_4f_customeraddress客户地址objectfalsefalse
fld_5f_orderorder_no订单编号texttruetrue
fld_6f_orderamount订单金额decimalfalsefalse

form_fields 另外有一列 options,customer_level 的值是:

[
{ "label": "重要客户", "value": "important" },
{ "label": "普通客户", "value": "normal" }
]

业务记录保存在 public.form_records:

idform_iddata
r_customer_1f_customer客户字段值的 JSON 对象
r_order_1f_order订单字段值的 JSON 对象

其中一条客户记录的 data 为:

{
"customer_code": "C001",
"customer_name": "华远科技",
"customer_level": "important",
"address": { "province": "北京市", "city": "北京市", "street": "中关村南大街18号" }
}

2. 配置表单定义​

新建规则“CRM 表单与字段定义”,填写:

配置项选择值
表单定义来源public.forms
读取方式数据库列
名称name
编码api_name
来源表单 IDid

获取表单后,预期看到“客户 / account”和“订单 / sales_order”,来源表单 ID 分别为 f_customer、f_order。

3. 配置字段定义​

配置项选择值
字段定义来源public.form_fields
读取方式数据库列
所属表单匹配来源表单 ID
所属表单标识来源数据库列 form_id
字段名称name
字段编码api_name
来源字段 IDid
来源字段类型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 元数据中继续使用其内部值时,可以识别子字段。例如,将“客户地址”中的省、市、街道作为可选子字段。

  1. 确保父字段已识别为 JSON 或 XML,并已配置业务记录读取规则。
  2. 在表单定义扫描编辑弹窗的字段列表中,打开该字段的 识别子字段。
  3. 读取业务记录样例,或粘贴有代表性的 JSON/XML 值。
  4. 检查标量路径、字段名称和类型,勾选需要保留的字段,按需调整顺序。
  5. 应用到扫描规则,再保存并执行扫描。
  6. 刷新并保存受影响的数据集,使子字段出现在图表配置和 API 元数据中。

识别最多读取 20 条样例;样例中没有出现的路径需要另取样例检查。数组和 XML 重复节点不展开。MySQL 和 MariaDB 不支持查询 XML 子字段。

“字段定义使用 JSON 读取”不代表每个字段都需要识别子字段。只有业务值本身是 JSON/XML,且需要使用内部属性时才配置。

使用 AI 协助分析​

打开具体数据源的结构页面后,可以在现有 AI 对话中输入:

分析当前数据源的表结构,识别表单定义和字段定义的来源,验证字段所属表单的匹配方式。给出名称、编码、来源 ID、类型和选项的配置方案,并说明样例验证结果。先分析,不保存。

当前页面会提供数据源及所选表的上下文,AI 可以进一步读取结构和有限样例、验证候选关联。检查结论中的来源表、匹配列和路径,再决定是否应用。仅有表名相似或少量样例匹配,不能证明全部记录都满足关系。

维护规则与排查问题​

每条规则可以单独配置定时扫描。来源定义变更后,重新执行表单定义扫描;若物理表、列也发生变化,应先刷新数据库结构。扫描完成后,继续检查受影响的数据读取规则和数据集。

删除表单定义扫描规则会保留已生成的表单和字段,并解除它们与该规则的归属关系。

现象优先检查
没有表单结果来源表是否有数据,名称和编码列是否正确,JSON/XML 是否有效、列表位置是否正确
有表单,但获取不到字段所属表单标识是否保存 ID 或编码;表单规则是否读取了对应值
不同表单混入相同字段字段所属表单列或文档标识路径是否正确
字段显示“未识别类型”类型读取位置是否正确,实际类型值是否需要新增映射;修改后重新扫描
选项为空或混入其他表单选项列表、标签和值是否正确,是否缺少字段或表单匹配
可以看到字段,但业务预览为空检查业务数据读取规则中的记录来源、表单筛选、字段路径
子字段识别不到内容父字段类型和业务读取是否正确,样例是否为空、无效或只有数组
保存时提示规则未完成同时检查表单与字段来源、必填属性、所属表单匹配及已启用的选项/标记配置

接下来配置关系定义扫描和业务数据读取规则。