表单模块研发说明

适用对象

维护表单设计器、表单运行时、统一数据源和字段元数据的开发人员。

能力边界

架构与能力细节见 表单引擎导读 与 monorepo L1 docs/form-designer-architecture.md；与流程协作见 表单 × 流程协作。开放项见 L1 §17。

本页保留：入口路径、表、API、实现锚点。

入口路径

前端入口：

/form-template
/form-template/data
/form-template/instance/new
/form-template/instance/:id
/form-designer

后端入口：

/form/template
/form/instance
/form/attachment
/form/component
/form/data-source
/system/data-source
/system/field-metadata

核心数据和接口

核心表：

frm_template
frm_field_meta
frm_instance
frm_attachment_bind
sys_data_source
sys_data_source_param
sys_field_metadata

接口清单：

POST /form/template/save
GET /form/template/list
GET /form/template/versions/{templateKey}
GET /form/template/all
GET /form/template/{id}
GET /form/template/{id}/fields
POST /form/instance/save
GET /form/instance/data/{flowInstanceId}
GET /form/instance/list
GET /form/instance/{id}
POST /form/instance/draft
PUT /form/instance/{id}
POST /form/instance/{id}/submit
POST /form/instance/{id}/archive
POST /form/instance/{id}/unarchive
POST /form/instance/submit
DELETE /form/instance/{id}
POST /form/instance/triggers/execute
POST /form/data-source/{code}/options
GET/POST/PUT/DELETE /system/data-source
GET/POST/PUT/DELETE /system/field-metadata

数据源和字段元数据

数据源类型：

dictionary：读取 sourceConfigJson.options/items。
business：读取组织、岗位、角色、用户。
external_api、internal_api：调用 HTTP 接口并按 resultMappingJson 提取选项。
external_sql：通过 sys_database 连接执行具名参数 SQL 并映射选项。

字段元数据：

code 建议为 object.field。
fieldType 用于组件推荐。
optionSourceCode 可自动填充字段默认选项源。
recommendedComponentsJson、validationConfigJson、defaultConfigJson 已建模；运行时默认/校验应用见主文档 §17 E4。

权限或预留能力

已落地：

form:template
sys:data-source
sys:field-metadata

预留：

frm_field_meta.isCondition 和字段配置 isCondition 用于流程条件。
biz_runtime_module.formTemplateId 用于运行时模块绑定表单模板。

字段行为规则

字段行为规则存储在字段 config 中，随 frm_template.schemaJson 版本化。

visibleConditionGroups、readonlyConditionGroups、requiredConditionGroups：字段状态条件，配合 *WhenMode 表示 AND / OR。
actionRules：字段值变化后执行的动作。动作类型包括 setValue、copyValue、clearValue。
eventHandlers：字段值变化后执行的 JS 脚本。运行时注入 value、oldValue、field、formValues、getValue、setValue、clearValue。

运行时由 FormPreview 统一解释字段行为规则。独立表单实例、表单数据页新增弹窗和流程表单渲染共用该组件，因此字段行为不需要在各业务页重复实现。

字段行为规则用于前端交互，不替代后端校验。保存、提交、归档、删除、列表查询、导入导出等实例级逻辑应使用 instanceConfig.triggers 配置表单触发器，并通过 runBeforeFormTrigger / runAfterFormTrigger 接入。

架构文档

类型	路径
oars-docs 导读	表单引擎导读、协作页
L1 内核	`docs/form-designer-architecture.md`（开放项 §17）

待确认事项

表单 schema 版本升级策略（产品向说明）。
表单与运行时 DSL 模块的自动生成/绑定策略。
数据源对外开放的安全策略摘要（实现见主文档 §14.5、§17 E3）。

表单模块研发说明 ​

适用对象 ​

能力边界 ​

入口路径 ​

核心数据和接口 ​

数据源和字段元数据 ​

权限或预留能力 ​

字段行为规则 ​

相关实现位置 ​

架构文档 ​

待确认事项 ​