表单与远程数据源

工作流表单用于收集流程变量、渲染审批详情和驱动分支/审批人解析。当前引擎支持三种表单来源，并提供远程数据源增强表单选项；对外部系统的统一外呼配置见连接器。

表单来源

类型	数据归属	说明
designer 表单库设计器	workflow_instances.formData	通过「表单库」维护可复用表单，流程定义绑定 formId
custom 自定义业务表单	workflow_instances.formData	通过 React 组件承载复杂交互，提交值仍进入流程实例
external 业务系统主导	业务模块自己的表	流程只保存 bizType + bizId 和路由变量，审批详情由业务查看组件渲染

表单库

表单库页面支持表单分页列表、启停、创建、编辑、复制和删除。流程设计器选择表单后，发起工作台、审批页和实例详情都使用同一套内置渲染器。

表单更新携带乐观锁版本号 revision：保存时回传 expectedRevision，与服务端当前版本不一致返回 409，编辑器提示加载最新内容，避免多人同时编辑互相覆盖。

字段标识（key）重命名会自动级联：除表单内部引用（显隐/必填/只读规则、级联、天数联动、公式、比较校验）外，保存时还会把重命名映射发给服务端，重写所有引用该表单的流程定义 flowData 中的分支条件、字段权限、审批人字段（formUser/formDepartment）、触发器模板（{{form.字段}}）、子流程映射、摘要字段和业务编号模板（{FORM.字段}）。已发布版本快照与历史实例保持冻结不变。

字段类型

分组	字段
基础控件	单行文本、多行文本、数字、金额、日期、日期区间、时间
选择控件	下拉单选、下拉多选、自动完成、单选框组、复选框组、开关、滑块、级联选择、标签、颜色
格式化控件	手机号、邮箱、身份证、网址、密码、验证码、评分、NPS 量表、矩阵量表、公式
系统组件	人员选择、部门选择、字典选择、关联审批单
高级控件	附件、图片、省市区、定位、手写签名、富文本、明细
布局控件	说明文字、流水号、分栏、分割线、分组、标签页、分步

附件与图片字段在发起、审批可编辑场景中通过 POST /api/workflows/attachments 上传：按工作流身份（可发起或可审批任一权限）放行，执行统一大小上限与 magic bytes 真实类型校验，落入受管文件并记录工作流审计。字段可配置数量上限、单文件大小与类型（accept）。

字段可配置必填、默认值、默认值公式、占位提示、帮助文本、长度、正则、数值范围、日期限制、文件限制、选项颜色与配图、动态可见、动态必填、动态只读、字段比较、自定义校验公式、明细列唯一和公式表达式。显隐/必填/只读规则组支持嵌套子组（如「A 且 (B 或 C)」），前端渲染与服务端校验同源求值。

设计器操作

• 画布所见即所得：画布按字段配置渲染真实控件外观与 24 栅格并排布局，与填写页一致（超过 80 个字段自动降级简洁模式）；分栏支持拖拽分隔线调列宽（双击均分）；容器支持有限嵌套（分栏列内放分组/明细、分组内放分栏/明细，深度 ≤ 3）。
• 画布交互：字段右键菜单（上移/下移/复制/粘贴/创建副本/必填切换/存为模板/删除）、键盘操作（Ctrl+C/V 复制粘贴、Delete 删除、↑/↓ 切换选中、Esc 取消、Ctrl+Z/Shift+Z 撤销重做）、多选（Ctrl 点选 / Shift 范围）批量删除、批量宽度/必填/只读、合并为分栏；拖拽支持边缘自动滚动、插槽指示与浮签。
• 大纲树：左侧面板「大纲」页展示字段嵌套结构，点击定位画布并选中。
• 防丢失：编辑内容自动本地暂存（3 秒防抖），意外关闭后重新打开提示恢复草稿；保存前可查看变更摘要（新增/删除/重命名/修改明细）。
• 历史：撤销/重做外提供历史步骤面板，点击任意步骤直接跳转。
• 模板：工具栏「模板」支持插入常用字段组，或打开表单模板库（请假/报销/采购/入职/出差/合同等完整模板，预览后一键应用，可撤销）；任意字段可右键「存为我的模板」保存到本地，在控件面板「我的模板」中复用。
• 配置面板：校验/显隐 Tab 带「已配置」圆点；支持配置项关键词搜索快速跳转；选项类字段支持批量文本模式（值|显示名 多行粘贴）与选项配图。
• 明细表：填写时支持行复制与「从剪贴板粘贴」（Excel 多行粘贴自动按列解析、数字类型自动转换）；子列可配置固定列宽、行内公式（引用同行列自动计算）、行内显隐与行内校验公式。
• 联动赋值：静态选项映射之外，绑定远程数据源的下拉支持按选中记录回填其它字段（配置目标字段 → 数据源记录字段映射）。

表单运行时与服务端校验

显隐规则、条件必填等运行时求值逻辑统一收敛在 @zenith/shared 的 workflow-form-runtime 中，前端渲染器与服务端同源引用，避免两端行为漂移：

• 发起与提交草稿：服务端按表单快照强制执行全量规则校验——必填（含条件必填）、文本长度、正则、数值范围、日期可选范围、跨字段比较、自定义校验公式、明细行级（行必填/列唯一/行内校验公式），并遵循显隐联动与发起节点（start）字段权限——被隐藏或只读的字段不参与校验，越权提交的字段值被丢弃。公式求值统一使用 shared 的 workflow-formula（与前端实时计算同一引擎）。
• 定时发起与自动化发起：沿用宽松语义，不强制必填。
• 实例详情：formData 按查看者身份脱敏——发起人按 start 节点权限、参与人按其任务节点权限并集过滤 hidden 字段；监控管理员与超管不脱敏；未配置字段权限的旧流程回退为全量返回。

公式字段

公式字段使用 {字段key} 引用字段值，使用 {明细key.列key} 引用明细列聚合。支持数学、逻辑、文本、日期函数，例如：

IF({days}>3, {amount}*0.9, {amount})
SUM({items.amount})
DATEDIF({start}, {end}, "d")

公式编辑器支持在光标处点选插入字段引用（含明细列）与函数片段，并提供实时试算：为每个引用填入样例值即可即时查看计算结果。函数覆盖数学/逻辑/文本/日期与查表格式化（NETWORKDAYS 工作日、DATEADD 日期加减、LOOKUP 查表、FORMAT 千分位、ISEMPTY 判空等）。表单体检会检测公式、天数联动与联动赋值之间的循环依赖（如 A 公式引用 B、B 公式又引用 A），存在循环时按错误阻断保存。

字段在流程中的作用

场景	说明
条件分支	使用表单字段和聚合值计算分支命中
审批人解析	formUser 读取人员字段，formDepartment 读取部门字段并解析负责人
表单权限	节点按字段设置只读、可编辑、隐藏
路由分支	规则中心决策表、评分卡或决策流 outputs 会合并进 formData，可作为后续字段变量使用
子流程映射	父流程字段映射到子流程，子流程输出回填父流程
触发器模板	{{form.field}} 占位符渲染请求体、更新字段或回调参数

自定义业务表单

custom 表单适合表单库控件无法覆盖的交互。流程定义保存组件路径和变量声明，运行时通过 BusinessFormHost 加载。

配置	说明
创建 / 填写组件	相对 packages/web/src/pages 的组件路径
查看组件	可选；为空时复用创建组件并以只读模式渲染
图标	用于业务表单入口展示
变量	声明可被条件分支和审批人解析读取的字段；key 须以字母/下划线开头、仅含字母数字下划线且不可重复（面板内联校验）

业务组件接收 mode、container、definitionId、instanceId、value、readOnly、variables 和 getFormApi。在发起和审批可编辑场景中，组件需通过 getFormApi 暴露 validate() 与 getValues()。

运行时行为：

• 发起：mode='create'，草稿编辑时以 value 回填已保存的 formData；「存草稿」优先经 getValues() 直取当前值（不校验，与服务端草稿宽松语义一致），正式提交仍执行 validate() 全量校验。
• 审批：当前处理人所在节点存在权限为「编辑」的变量时，以 mode='approve' 可编辑渲染，审批提交时按 edit 白名单收集变更合并进实例 formData（服务端 sanitizeFormUpdatesByNodePerms 双重过滤）；否则以 mode='view' 只读渲染。
• 发布门禁：创建组件（及填写了的查看组件）路径必须能在 src/pages 下解析，变量声明 key 须完整合法，否则阻断发布并跳回「表单」步骤。

业务系统主导表单

external 表单用于已有业务实体接入审批。业务数据保留在业务表中，工作流实例只保存业务键和少量路由变量。完整接入方式见 业务模块接入工作流。

• 此类型仅需配置审批查看页组件（创建页输入已隐藏），审批与详情恒为只读；节点「表单权限」的编辑列被禁用。
• 发起守卫：节点按 formUser / formDepartment 解析审批人且未配置空审批人兜底策略时，对应路由变量缺失会阻断发起并返回明确错误，避免节点被默认「自动通过」静默跳过。
• 业务键（bizType + bizId）的发起去重口径为活跃实例（草稿/运行中/挂起/退回待重提）；流程终态（通过/驳回/撤回/取消）后，业务记录可修改后重新发起新流程。

另外，在设计器「表单」步骤切换表单类型时，若已有表单绑定或业务表单配置，会弹出确认提示：保存后另一族配置将被清空，基于原字段（变量）的分支条件、审批人与字段权限需重新检查。designer 类型发布时还会校验：流程引用了表单字段却未绑定表单、或绑定表单已停用/被删除，均阻断发布。

远程数据源

远程数据源用于让表单选项从外部 HTTP 接口拉取，主要服务于下拉、自动完成等字段。

配置	说明
名称	数据源显示名
方法	GET / POST
URL	以 http:// 或 https:// 开头
请求头	静态 Header（AES-256-GCM 加密存储，回显时值脱敏为 ******，更新时传 ****** 沿用旧值）
列表路径	从响应 JSON 中提取数组的路径
值字段 / 显示字段	映射为表单选项的 value 和 label
关键词参数	搜索时传给远程接口的参数名
状态	启用 / 禁用

页面入口为 工作流引擎 → 远程数据源。列表支持测试拉取选项，表单字段配置面板可选择已启用的数据源。数据源仅登记后才可被代理调用，避免任意 URL 直连造成 SSRF。

运行时代理接口：

方法	路径	说明
GET	/api/workflows/data-sources/{id}/options	拉取候选项
GET	/api/workflows/data-sources/{id}/record	按值读取原始记录，供联动赋值回填