unis-oa/docs/form-field-catalog.md

50 KiB
Raw Permalink Blame History

字段类型总表:44 类组件各管什么、值长什么样、哪一道闸判它

相关:option-source-design.md(选择类四兄弟的候选来源)、 form-data-integration-design.md(五种取数形态)、 ../README.md 的「表单设计」一节。 这一篇只回答三个问题:表单能摆哪些组件、每一格往 work.data 里存什么形状、 配错了 / 填错了在哪一步被挡。

0. 一页看完

问题 结论
一共几类 44 类(utils/formLayout.ts 的 FIELD_TYPES,左侧字段库按 基础 / 选择类 / 人与附件 / 系统带出 / 布局 五段摆)
这一轮新加的 richtext 富文本、month 月份、year 年份、timerange 时间段、week 星期、location 定位、group 分组标题、spacer 空白占位
最新加的一类 months 多选月份——一次圈几个月,连着几个月自动并成一段:挑 2026 年 10、11 两月,回填就是「2026年10-11月」。值仍是 YYYY-MM 数组,与 month 同一写法,见 §2.7
最近加的一类 tabs 标签页——把这张单切成几页,其中一页可以整页让给一个外部系统,那个页面才占得满一屏。同样是版面不是值,但归属记在别的字段身上(每格一个 tab),见 form-tabs-embed-design.md §1
又加了一类 embed 外部页面——把别的业务系统的页面嵌进表单,同一个功能不用在 OA 再开发一遍。它是版面不是值,但比 group 多一件事:它的 key 是环节字段权限的挂点,见 embed-page-field-design.md
顺带捞回来的 signature 手写签名——控件、只读态、导出、打印早就写好了,唯独左侧字段库没登记,于是界面上永远加不出这一类字段
老组件长了什么 文本那三类多了字数上限与校验正则;附件与图片多了允许类型 / 最多几个 / 单个多大;日期区间与时间段现在还会判起止先后
清单散在哪 前端 5 处、后端 4 处(见 §5)。以前分叉不会报错,只会在界面上悄悄少一格
谁来防 frontend/src/utils/fieldCatalog.spec.ts:拿 Node 的 fs 直接读后端源码,把「前端有的后端也得有」钉成断言
权威判定在哪 只有后端一次(service/formruntime.py:validate_submit)。前端那几道(maxlength、accept、个数截断)只是别让人白等一次上传

1. 总表:44 类

「条件」那一列是流程设计器里能拿这一格比什么(口径 utils/fieldCapabilities.ts ↔ 后端 service/threshold.py);「明细列」是这一类能不能当明细表的一列 (TABLE_COLUMN_TYPES,列与主表共用同一只录入控件)。

type 界面名 存进 data 的形状 明细列 条件 备注
text 单行文本 字符串 ✓ 文本 可配字数上限、校验正则
title 流程标题 字符串(= work.title) ✗ — 一张表单只认第一个;口径见 service/titles.py
textarea 多行文本 字符串 ✓ 文本 可配字数上限、校验正则
richtext 富文本 Markdown 原文(字符串) ✗ 文本 排版只在显示那一步做,见 §2.1
number 数字 数字 ✓ 数值 最小 / 最大 / 步长 / 小数位 / 单位 / 千分位
money 金额 数字 ✓ 数值 可开中文大写;导出与标题跟着走
formula 计算公式 数字或文本 ✗ 数值 每次提交后服务端重算
date 日期 2026-01-31 ✓ 先后
datetime 日期时间 2026-01-31T09:00 ✓ 先后
time 时间 09:30 ✓ 先后
daterange 日期区间 ["起","止"] ✓ 只判空 起止颠倒会被提交挡下
month 月份 2026-03 ✓ 先后 月度报销 / 月度报表那一类
months 多选月份 ["2026-10","2026-11"](去重升序) ✓ 只判空 并成「2026年10-11月」;下拉 / 弹出框 / 平铺三档挑,见 §2.7
year 年份 整数 2026 ✓ 数值 不是字符串,条件按数字比大小
timerange 时间段 ["09:00","10:30"] ✓ 只判空 考勤、会议、值班;同样判先后
week 星期 ["1","3","5"](1=周一) ✓ 只判空 排班、窗口开放日;条件按「包含」判某天
mobile / email / idcard / url 手机号 / 邮箱 / 身份证号 / 网址 字符串 ✓ 文本
address 详细地址 字符串 ✓ 文本
location 定位 {lng, lat, address}(物件) ✓ 只判空 见 §2.2
select 下拉框 单个值或一串(勾了「可以选好几个」) ✓ 文本 候选来自手填 / 字典
picker 下拉选择 同上 ✓ 文本 候选来自外部数据源 / 别的流程的单据
radio / checkbox 单选 / 多选 单个值 / 一串 ✓ 文本 / 只判空
switch 开关 布尔 ✓ 是 / 否 控件摆出来就是关着的,必填那道闸认「关着=答了」
rate 评分 整数星级 ✓ 数值 max 是满星数
dept 部门选择 部门路径串 ✓ 只判空
cascader 级联选择 从顶级到末级的字典项数组 ✓ 只判空
user 选人 登录账号数组 ✓ 只判空 只读态念成「姓名(账号)」,口径见 person-reference-design.md
attachment / image 附件 / 图片 附件对象数组 ✓ 只判空 可配允许类型 / 个数 / 单个大小,见 §2.3
signature 手写签名 PNG 的 data URL ✓ 只判空 导出只落「已签名」
relation 关联审批单 对方单据的 job ✓ 只判空 认得它但不单列一格:它就是「下拉选择 + 来源=流程单据」
table 明细表 行对象数组 ✗ 比列 列类型见 TABLE_COLUMN_TYPES;只读那一屏收不收折由 readonlyStyle 说(§2.9),一列能配的东西与主表字段同权、最多一行自动补(§2.10),列上也能挂外部取数、一行问一次(§2.12)
auto 系统带出 按带出的键 ✗ 文本 生成规则见 service/numbering.py
group 分组标题 无值 ✗ — 见 §2.4
divider 分割线 无值 ✗ —
description 说明文字 无值 ✗ — 阈值那句红字可以指定挂在这一格后面
spacer 空白占位 无值 ✗ — 只带一个 height(8-240px)
embed 外部页面 无值(连地址快照都不存) ✗ — 版面,但不是 divider:要有标题、要认 key,见 §2.5
tabs 标签页 无值 ✗ — 版面。它只切页;归属记在别的字段身上(field.tab),见 §2.6。tabsMode 决定这几页怎么排:tabs 顶上翻页(存量表单都是这一档)/ collapse 摊在同一屏各自收折(新摆的默认);收折那档另有 tabsDefault 管进来先开先合,段上一个三态 collapsed 覆盖
hidden 隐藏字段 按字段类型 ✗ 文本 默认整张流程不显示,值照常存

2. 这轮新加的东西里,四件需要说清的

2.1 富文本存的是 Markdown 原文,不是 HTML

第一反应是上所见即所得(contenteditable),但那等于把这格的值变成一段 markup: 导出表格、打印、条件判断、以及「这段到底填没填」全都要跟着解析一遍, work.data 里还会混进别人贴进来的 style 与 script。

存原文就没有这些债:

  • 录入控件是 components/oa/RichTextEditor.vue——左边 textarea,右边预览, 顶上那一排只是给不写语法的人省事的插入按钮,不是编辑器;
  • 上屏统一走 components/oa/MarkdownBlock.vue,底下是 utils/preview.ts:renderMarkdown (marked 管语法、DOMPurify 洗脚本);
  • 导出 / 打印 / 标题里读的是 formruntime.markdown_text() 那句去掉了记号的话, 单元格里躺的是「标题 / 加粗 一项」而不是 ## **标题**。

2.2 定位不接地图服务,这是有意的

本平台没配任何地图 key,硬塞一个第三方底图等于逼每个部署方先去申请一把。所以 location 存的是浏览器原生定位(WGS84)给的经纬度,加一句由人自己写的地址: {lng, lat, address},accuracy / at 只是给填单人看这次取得准不准。

于是有一条刻意的活口:台式机、没授权、非 https 页面都取不到位置,那时只写一句 地址也算填了(locationFilled ↔ 后端 location_filled)。这一格存的是一整包, 条件分支只判得出「填了没有」,别拿它比大小。

2.3 附件那三个限制:前端挡体验,后端挡绕过

accept(预设:不限 / 图片 / 文档 / 压缩包 / 自己写)、maxFiles、maxSizeMb。 前端在选文件时就挡(AttachmentUploader.withinLimits:超小的整只丢掉、超个数的截尾), 后端提交时按每条附件自带的 name / extension / length 再判一次 (formruntime._file_problems)——绕过界面直接 POST 的人照样拦得住。 图片格没配 accept 时默认还是只收 image/*(acceptOf ↔ effective_accept)。

2.4 分组标题与空白格是版面,不是值

group 只把长表单切成几段给人看,spacer 只在格子里留一段空(默认 24px,8-240 之间)。 它们进 NON_INPUT_TYPES:不产生值、不参与必填、不进额度、不进回写映射, 「字段权限」那套开关对它们也就是灰着的。design.py 的 LAYOUT_ONLY_TYPES 会把 「给分割线勾必填」这种自杀式配置挡在保存那一刻。

标题同理分两半:spacer 的 label 上屏后一个字都不显示,所以它可以没有标题 (LABELLESS_TYPES ↔ formLayout.ts:LABELLESS_TYPES,两边一份口径); group 的 label 就是那行抬头,缺了这一段就没名字,照旧要。 这条两边必须一致——前端放行、后端要标题,结果是设计器里加完空白格点保存才吃一句报错。

2.5 embed 是版面,但不能当装饰处理

embed(外部页面)跟 group 一样不产生值、不参与必填、挂不上阈值与额度, 所以它进同一族清单;两处不一样,都是故意的:

  1. 它要标题:那一行字是留痕和列表里唯一念得出它的东西,所以 LABELLESS_TYPES 不收它;
  2. 它认 key:api/design.py 校验字段时对 divider 直接 continue,连字段名都不查—— 这一格必须走完校验,因为环节字段权限(formPerms)是按 key 生效的, 没有 key 就没法在某一环把它藏起来,而"某一环能不能看见这个外部页面"正是它最要紧的一道闸。

于是它有 key 却没有值:work.data 里不会出现这个键,提交校验、条件、额度、导出 都按"这一格不存在"走,唯一拿它做判断的地方是权限。设计见 embed-page-field-design.md。

2.6 标签页切的是「这一屏摆哪几格」,不是值

tabs(标签页)与 embed 同族:不产生值、不参与必填、挂不上阈值与额度、条件里也不出现。 两种排法用的是同一批分组、同一份归页、同一套环节权限,换的只是"一次只摆一页"还是 "摊在同一屏里各自收折"(判据见 form-tabs-embed-design.md §2.5)。 它和 group 那种分段标题的区别在归属:分段标题只是给人看的一行抬头,标签页真的决定 「这一格在不在这一屏」。归属记在格子身上(每个字段一个 tab,没写 = 第一页), 标签页自己不装子字段——因为「这一格能不能填」全系统都是按平铺的字段 key 判的。

三条口径值得单独记:

  1. 页签的 key 是标识,不是文案。设计器只让改名字;改 key 等于把那一页的格子悄悄送回第一页;
  2. 环节把这一格设成隐藏,藏的是整片(页签 + 每一页的格子)。只藏页签、留着第一页的格子, 会得到一张翻不完也填不完的表单;
  3. 某一页装的是外部系统页面时,那一页只装它,压在那一页上的格子不显示——所以保存那一刻 就挡(它们还参与必填与提交校验);
  4. 收折那一档"进来先开还是先合"配在容器上(tabsDefault:全展开 / 全收起 / 只展开第一段), 段上那个三态 collapsed 只做个别覆盖。它和收折本身一样只是版面:合着的段照样参与必填、 联动、额度、导出,段头会写出"还差 N 项"。

设计与取舍见 form-tabs-embed-design.md。

2.7 多选月份并成一段,值的写法不变

months 那一格存的是 ["2026-10", "2026-11"]——与 month 同一句式(YYYY-MM), 去重、按时间排好,条件分支和导出读得懂,不像「2026年10、11月」那种人话还得再翻一遍。 给人看的那一句由 utils/formRuntime.ts:monthsText ↔ service/formruntime.py:months_text 现拼:连着几个月并成一段,同一年里只报一次年份,跨年那段两头都写全。

挑中 回填 / 只读 / 导出
2026-10、2026-11 2026年10-11月
2026-01、2026-02、2026-05、2027-07 2026年1-2月、5月、2027年7月
2026-12、2027-01、2027-02、2027-05 2026年12月-2027年2月、2027年5月

它装是一串月份,所以阈值与条件只判得出「填了没有」(fieldCapabilities.BAG_TYPES ↔ threshold.BAG_TYPES、routeExpression 的 OPAQUE_TYPES),额度也挂不上 (UNQUOTABLE_TYPES ↔ quota.UNCONTROLABLE_TYPES)——一串月份不是一笔能扣台账的数。

这一格长什么样由配的人挑:pickerStyle 三档,与设计器里「挑选方式」同一套取值 (utils/formRuntime.ts:monthsStyleOf ↔ service/formruntime.py:months_style_of)。

档位 界面上是什么 什么时候用
dropdown 下拉多选(默认,字段上不写东西) 一只长得像输入框的按钮,框里挂「2026年10-11月」那一句;点开出那一年的 12 个月,挑完点外面就收 半行就放得下,一张单摆两三个月份格子也不挤
dialog 弹出框多选 同一面盘搬到屏幕正中的弹出框里,格子大一号;改的是草稿,点「确定」才写进这一格,取消等于没挑 手机上、或那一屏本来就窄
inline 平铺点选 12 个月一直摊在这一格里,不用点开 想让「这个季度选了哪几个月」一眼看全;代价是吃掉一整行,属性面板会顺手把这一格铺满

这一类没有「自动」那一档(只有一档默认,摆两档等于让人猜),所以 carriesStyleChoice 把它算进"要摆挑选方式那一栏",carriesOptionSource 仍然不算它——那一句只管候选来源那四类。 明细表那一列同理,列上也能挑;明细格子里永远不给摊开(一行的高度放不下一个盘子)。

2.8 明细表那一列锁得上:column.readonly

用户那句原话是「表单的明细表中的字段,无法设置不可编辑」。查下来缺的不是运行时的判据, 而是设计器里的入口:列上那份 column.readonly 一直有人认(填单那一屏把它递给录入控件), 可界面上唯一能改它的地方是「自动带出」底下那颗**「带出后允许填写人修改」**——没配带出的列 压根锁不上,配过的列也只能反着说(勾上=不锁)。

现在明细列卡的第一行跟主表一样摆了「只读」,与必填并排(标题 / 类型 / 标识 / 必填 / 只读 / 删除 钉死在第一行)。三处读写的是同一份 column.readonly,不另发明第二个标记:

谁 认这一份的哪一句
填单那一屏(桌面与手机同一只组件) FormRenderer 把 column.readonly 递给 FormFieldControl,锁着的格子出只读态那一支;表头挂一枚锁(为什么点不动)+ 那一列铺一层底色(哪几格点得动)
设计器 FieldInspector 列卡上那颗「只读」+「自动带出」底下那颗「允许填写人修改」(反着说,仍写同一格);写了本行公式那一列的锁勾死解不开(公式列没有录入框)——§2.11 之后有出口:勾了「公式带入后允许修改」的那一列有框,锁也解得开
提交那道闸 formruntime._row_problems:锁着的列不卡必填,那一格里已经躺着的值照旧过格式那几关

锁上之后必填要让路,理由是同一句老话:必填卡的是人,而锁着的列根本没有录入框——那一格的值 归默认值 / 自动带出 / 关联带出 / 额度台账给,人改不动却永远被催「还没填写」,这张单就地卡在这一环, 跟「屏幕上没有那一格,却说请先填写它」是一种坏法。所以锁着的列不摆红星、属性面板里必填那颗灰掉 (勾还留着,解开锁就回来)。三条分寸:只让「必填」这一条;只认 readonly 这一个标记(写了本行公式 那一列没勾只读,公式算不出值仍是配置坏了,照旧拦);整张明细表那一层的环节权限一个字没动—— 环节把整张表设成只读走的还是 effective_perm(FormRenderer.isLocked),列上这一层只在表本来摊开 给人填时说话。

锁着的列管的是"人改不改得动",不管"这批值收不收":提交时按环节权限过滤写入的是 formruntime.editable_keys,粒度是整张表(那一列的值由开放接口或脚本直接写进来,不会被这一层挡)。 设计器在锁着又没配任何值的来路时会当场说一句(columnLockedWithoutSource:默认值 / 自动带出 / 本行公式 / 关联带出的目标列 / 额度逐行控写的那几列都算来路),因为那一列从此谁也填不进东西。 钉在 FieldInspector.column-readonly.spec.ts、FormRenderer.tableCellReadonly.spec.ts 与 scripts/check_table_column_readonly.py。

2.9 明细表提交之后可以先收着:readonlyStyle

用户那句原话是「表单中的明细表在填写的时候是展开状态,流程提交后我希望明细表都是收折的状态, 给我一个地方可以配置」。缺的不是渲染能力(只读那一支本来就会把整张表画出来),而是没有那个地方: 一张报销单摆两三张明细表,审批人进来先翻三屏表格才找到自己的签名框,而设计者对此一个字都说不上。

配置落在明细表那一格身上(field.readonlyStyle),入口是属性面板明细表那一支的「流程提交后的展现」:

档 只读那一屏(提交后 / 审批环节看单 / 已办 / 单据详情) 填单那一屏
留空 / expanded 整张摊开,连段头都不多摆一行——存量表单的画法一个字不变 摊开
collapsed 先给一行段头「共 N 行 · 合计 X」,点它才摊开,再点收回 摊开

四条分寸是刻意的:

  1. 只管读。填单那一屏永远摊开:收着的表里没有录入框,人没法往里敲字, 把这一档做成"什么时候都收"就等于把明细表变成一个不能填的东西。判据 utils/formRuntime.ts:tableReadonlyCollapsed 只在 FormRenderer 只读那一支被问一次。
  2. 打印那一份永远摊开。纸上没有"点一下摊开"这回事,收着的那些行等于根本没印出来, 而缺的那一半在纸面上看不出缺——这一条比"看着清爽"重要。判据复用现成的 flattenTabs (打印页是唯一传它的地方),不另发明第二个"这是打印"开关。
  3. 人手动点开那一份不写回表单。段头上的开合记在组件里(字段名 -> 这一刻摊开与否), 换一张单、刷一次页面就回到配置说的那一档:审批人点开看一眼是他这一趟的事, 不该顺手把全公司以后看单的样子改掉,更不该因为谁点一下就把表单定义弄脏。
  4. 只认一处渲染。全项目只读明细表的画法只有 FormRenderer 那一份(桌面、审批详情、 单据详情、介入面板、试跑弹窗共用),所以这一档配一次就在所有只读屏生效; 明细列 / 行数 / 环节权限那三套口径一个字没动。

手机端不吃它:那边早有自己那一档——MobileFieldStyle 的 card(收成一行,点开逐条) 与 list(在节里逐条摊到底),且明细格默认就是 card。两份开关各说一件事(手机看的是配好的版式, 电脑看的是这张表在只读屏的默认开合),不互相覆盖,免得同一件事两处各说一遍。

钉在 FormRenderer.tableReadonlyStyle.spec.ts(四屏各是什么样)与 FieldInspector.tableReadonlyStyle.spec.ts(只有明细表摆这一栏、挑回默认那档就把键摘掉、 换类型收掉残骸)。这一档是纯展现,后端不读它,clean_formats / clean_option_source 也都不收它(不在 FORMAT_KEYS / LIMIT_KEYS 清单里),存下去就是字段上一个键。

2.10 明细列与主表字段同权,最多一行的表先把那一行摆好

用户那两句是「明细表里面的列,我希望也可以和主表字段一样可以进行各种配置」与「明细表最多只有 一行的时候,我希望可以自动帮我带出一行」。

先说结论:一列就是一个字段。查下来缺的不是运行时的判据——FormRenderer 把列上那份对象原样 递给 FormFieldControl,所以列本来就认得 placeholder / maxLength / pattern / min / max / accept / cascadeFrom 这些键,只是设计器里没地方写。于是这一轮没有另发明一套"列配置"的 schema:配置全写在列上那一份对象上、与主表同一个键名,补的是入口和那两道闸。

一列能配的 写在哪 谁读它
占位提示 column.placeholder 同一只录入控件(列与主表共用的那只),填进去就是原生 placeholder
列说明 column.help 表头列名后那一枚提示(table-column-help),指针停在列名上就出,不占格子高度
字数上限 / 校验正则 column.maxLength / column.pattern 界面上 maxlength 挡体验,提交那道闸判(value_problems,正则仍整格匹配)
取值上下限 column.min / column.max <input type="number"> 只标红不拦人,提交时 _range_problem 按同一份上下限再判一次
步长 column.step 只摆给数字列:原生数字框的箭头与滚轮每次调多少,留空 = 浏览器那个 any(金额那只框自己钉了 0.01,没这一栏)
附件三个限制 column.accept / maxFiles / maxSizeMb 上传前 AttachmentUploader 挡,提交时 _file_problems 判
级联自 column.cascadeFrom 本表另一列选了什么,这一列的字典项只留它下面那几项
隐藏此列 column.hidden visibleTableColumns:填单与看单两支都连表头都不摆(第三段单说)
列宽 / 对齐 / 合计 column.width / align / aggregate 表格自己那三样,第二段单说
外部取数(逐行) column.fetch 与主表那一格同一套配置与执行器,按行各跑一次,见 §2.12

入口收在「更多配置」里,但收了也念得出。 列卡第一行仍是钉死的那几样(标题 / 类型 / 标识 / 必填 / 只读 / 删除),外加新摆的上移 / 下移 / 复制——以前调一次列序等于删了重加。其余那一长串 收进一个折叠栏(column-more-toggle),规矩跟侧栏 SidePanel 一样:门关着时,入口那一行就是 唯一的可见状态,所以配过几样写在角标上(「已配 2 项」),且只数这一列类型用得上的那些(步长只数数字列 那一格,金额那只框压根没这一栏)——换类型 该收掉的残骸不占位置,否则人以为配过什么,其实那一栏压根没摆出来。用不上的格子干脆不摆:归本行 公式算的那一列没有录入框,占位提示与上下限轮不到它;文本列的合计只有「不合计」与「计数」两档。 换列类型时带走不走的旧配置一并清掉(changeColumnType 收展现格式、字数与正则、附件限制、级联、 合计那几群),与主表 changeType 同一份清单,后端 clean_formats 对明细列做的是同一件事—— 留下的老写法会藏在新控件底下继续生效。

表格自己那三样是纯展现,不进提交那道闸。

  1. 列宽 width:这一列的最小宽度(自动 + 96/120/160/200/260/320/400 七档),表头那行字 放不下时还会再宽一点,整张表超出容器仍走横向滚动。判据 columnMinWidth;没配过的列照类型自动 分配,存量表单一个字节都不动。
  2. 对齐 align:auto(不写类,跟着表格默认靠左)/ 靠左 / 居中 / 靠右。判据 columnAlignClass。
  3. 合计 aggregate:求和 / 平均 / 最大 / 最小 / 计数,选中的列在表尾多摆一行念这个数 (TableAggregateRow.vue)。非数与空格子不进统计,小数位跟着那一列自己的 precision 写; 计数那一档任何列都能配,其余四档只认 number / money——给文本列配求和会算出一堆 0, 所以界面上压根不摆那几档,后端也拦。段头(§2.9 收折那一行)上原本的「合计 X」现在优先听 点名:哪一列显式配了 sum 就念哪一列,没配才回落到「第一个数字列」,且标签与数字问同一列—— 以前不点名,段头写着「运费」、念的却是「金额」那一列的数。

这三样后端只在设计期判配置本身认不认识(列宽在 60-640px 之间或留自动、对齐与合计是合法值、 那四档没配在非数字列上、min 不大于 max),一个字不进 validate_submit:它们不改任何一格的值。

hidden 这一样只管屏幕上摆不摆,得说清。 藏起来的列连表头都不出现,但值照常保存、照常导出、 照常参与本行公式与关联带出,也不卡必填——column_not_for_people(勾了只读、整列藏起来,两样 都是"人改不动这一格",而必填卡的是人,与 §2.8 同一把尺子)。红星不摆、表头宽度也不给那颗星留位, 属性面板里必填那颗灰掉(勾还留着,取消隐藏就回来)。设计器在藏着又没配任何值的来路时会说一句 (默认值 / 自动带出 / 本行公式 / 关联带出 / 额度逐行控写都算来路):那一列从此谁也填不进东西。 这一样是给机器留的——项目编码、物料 ID 那类"带出来给公式和回写用、人不需要看"的列。 手机端那一份读单(components/oa/mobile/useFormPlan.ts)跟着同一份口径:藏着的列不进逐条那几行, 摘要那一行「合计 X」也优先念列上点了求和的那一列——同一张单子在电脑上念一个数、在手机上念另一个数, 比两边各念各的更让人不敢信。钉在 useFormPlan.spec.ts。

最多一行的表自动带出那一行。 maxRows === 1 的明细表压根没有"再加一行"这回事(右上角那颗 + 一到一行就灰了),可格子还是得点一下 + 才出现——一张空表看着就像不能填。现在进这一屏就补 一行,补的这一步与点 + 走同一条路:同一份 emptyRow、同一份 rowSeed、同一遍 applyRowFormulas,所以默认值、自动带出、本行公式都按老口径落,不多算一次也不少算一次。三条边界 是刻意的:只在填单那一屏补(只读态与打印不许给单据添行);环节把这张表设成只读、或整格藏起来 时不补(那一屏根本没有录入框,补出来的行只是把 data 弄脏);落库前 normalise_rows 照旧把一格 没填的空行剔掉,所以补出来的那行没人碰,也不会多存一条空记录。设计器在「最多行数」那一栏下说破 这件事(table-single-row-hint),别的行数不啰嗦。

钉在 FieldInspector.columnMore.spec.ts(角标数几样、每一样写进列上哪个键、用不上的格子不摆、 换类型收残骸、列序与复制)、FormRenderer.tableColumnDisplay.spec.ts(藏着的那一列数不出来、 列宽与对齐落到 <th>/<td> 上、表尾念的数、最多一行自动补)、formRuntime.tableColumnConfig.spec.ts (判据本身)与 scripts/check_table_column_config.py(21 句:藏着的列不卡必填、上下限提交时判、 格式那几问不再跟着必填走、列宽对齐合计只在设计期判)。

2.11 公式带进来的那个数可以让人改:column.formulaEditable

用户那句原话是「表单中明细表中引用公式带入的值,为什么不能编辑?我需要可编辑」。查下来这不是 坏掉,是一直以来的有意画法:列上一写公式,那一格同时失去两样东西。

  1. 屏幕上没有录入框——FormRenderer 认 column.formula 那一支,摆的是一句现算的文本 (cellFormulaText),判据是 columnHasNoInput(§2.8、§2.10 那把尺子加一句"归公式算")。
  2. 数据上守不住——applyRowFormulas 每轮改动都把这一列整列重算,主表那一格一动, rowFormulaSignal 那道 watch 还会再重算一遍。就算界面上硬塞一个框,敲进去的数也会在 下一轮重算里被盖回公式那个。

只补第 1 件的功能是假的(改得动、留不住,比不让改更气人)。所以这一档两件事一起管,落在列上 一个新键 formulaEditable:没写 = 老画法,几百张存量表单的明细表一个字不变。

谁 认这一档的哪一句
填单那一屏(桌面与手机同一只组件) columnFormulaEditable 为真 → 那一格出 FormFieldControl,公式先把数摆在框里;表头从一枚锁换成一枚 fx
重算 applyRowFormulas 跳过"这一列点了这一档 且 行上躺着凭据"的那一格,其余照旧整列重算
设计器 列卡「本行公式」底下那颗「公式带入后允许修改」;公式一清空这一档跟着撤掉;这一档生效后那枚「只读」锁也解得开了
提交那道闸 一个字没动:那一格现在有框了,必填照卡、值照过格式那几关;公式列的默认值照旧不复活

凭据落在行上:row._manual = ['payAmount'](列标识的数组),与关联带出那一份 _link 同一层, 下划线开头 = 导出、打印、明细导出都看不见它。它必须一路不丢才算数:编辑中的整型 (trimRows / normaliseRows)与落库前的整型(后端 formruntime.normalise_rows)都把它跟 _link 一起留着,否则下一环的人重新打开这张单,昨天改的数就悄悄变回公式算的那个。

三条分寸是刻意的:

  • 只豁免改过的那一格,不豁免整列。没动过的格子照旧跟着公式走,主表那个运费一涨, 没人碰过的那几行该变的还是变。
  • 清空那一格 = 交回公式,行上那颗「恢复公式值」(formula-reset-*)点一下走的是同一条路: 撤凭据 + 重算。手工覆盖一旦没有退路,比不让改更难用。
  • 锁与隐藏压过这一档。columnNotForPeople(勾了只读、整列藏起来)在前,formulaEditable 在后,判据只 columnFormulaEditable 这一处,填单与设计器读同一把尺子;属性面板里那一档 在已勾只读时灰着点不动,并说一句为什么。

这一列的数仍然只有前端会算(compute_formulas 只管主表 type=formula 那一格),所以走接口 直接提交的单子得自己把这一列算好——这一点与公式列一直以来的规矩相同,tableColumnFormulaHint 里那句"由前端算"没说两遍。钉在 formRuntime.formulaEditable.spec.ts(判据本身、凭据一路不丢)、 FormRenderer.formulaEditable.spec.ts(那一格真是录入框、改过的那一格不被盖回、清空与恢复都交回公式、 没点这一档仍是文本)、FieldInspector.columnFormulaEditable.spec.ts(这一档只写一个键、公式 清空就撤、锁解得开)与 PYTHONPATH=. python3 scripts/check_table_formula_editable.py(12 句: 凭据不丢、这一档不锁列也不放宽校验、默认值没复活、设计期不报错)。

2.12 明细列也能逐行取数:column.fetch

用户那句是「明细表中的字段是否可以配置取数,取我配置的外部数据源」。真实场景:收款明细每 一行填了收款人,开户行与银行帐号要按这一行那个人去 ERP 查。以前只有主表字段挂得上 fetch(fetch_fields 见着 type == "table" 就跳过),列上那一格只能人填或走关联带出。

没有新键:列上写的那份 fetch 与主表字段是同一个形状、同一个执行器(binding.entries 那一套多源 / merge / args / picks / onError / revalidateAfter / freezeAfterStart), 只是逐行各跑一次,值写进这一行的这一列。挂不得上走的是同一句 canCarry(type,'fetch') ——装得下一个数或一句话的那些列能挂(文本、多行、数字、金额、日期时间、月份、年份、手机、 邮箱、身份证、网址、下拉、单选、评分),多选 / 部门 / 附件 / 日期区间 / 开关那几类主表本来就 挂不上,列上同样挂不上。归本行公式那一列没有录入框,配了也没人看得见。

谁 认这一档的哪一句
设计器 列卡「更多配置」底下那块「外部取数」,用的就是主表那只 FetchPanel。「带出去向」的下拉只有这张表的其它列;配完之后角标上「已配 N 项」把它算一样(columnExtraConfigs 数了 fetch);这一列勾了「只读」而没配来源那句黄字提醒,在配了取数之后自动收声——那一格的答案是查出来的,本来就该锁着
入参读哪一格 作用域 = 整张单 + 这一行,与主表字段同名的列以本行为准,{form.x} 既能读主表也能读本行的列。跟本行公式(applyRowFormulas)吃的是同一份作用域,配的人不用记第二套写法
带出去向落哪 只落这张明细表的其它列。写主表那一格等于让最后一行去盖表头:三行的表盖三次,谁赢看运气
填单那一屏 FormRenderer.runRowFetches 按行各取一次给人看,一张表攒完补丁再一次性写回(逐行各写一次会把前面几行刚取回的那份按旧快照盖掉)。「多久算旧」到点重取按行各算一份——入参指纹的键是 表名#行号#列名;freezeAfterStart 那一档逐行一起冻结
提交那道闸 后端 fetch.apply_form → _apply_rows 按同一份配置逐行再取一次并覆盖,前端塞不进假值;跑的是 data 里当前那几行——删掉的行不再取一次,新加的那行当场补得上
取不到数怎么报 「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:ERP 连接超时」。整张表在这一环被藏起来时 onError=block 降级成不挡(环节权限挂的是表不是列),取数照发、留痕照记
留痕 data["_fetch"]["收款明细.bankAccount"],底下 rows: [{row:1,…},{row:2,…}]。键必须是「表名.列名」——两张表可能有同名列,同一列每一行都得留得开
删列 删掉一列时指向它的 picks 一起清(utils/formPrune 按这张表剩下的列名滤,那句「掉在地上的指向」挂在 列名.带出键名 上);运行时也只往还在的列写,与主表那几处共用同一把闸(binding.live_target)

三条分寸是刻意的:

  • 行的增减还是人说了算。这一档是"已有的 N 行各自去问一次",不是"一条查询生出 N 行"—— 后者(结果集控件)仍然没做,边界见 sql-autofill-design.md §6 第 4 条。
  • 一行一调。十行十次外呼,再叠 revalidateAfter 是十次乘以刷新次数,数据源上的缓存 TTL 与 rate_limit_qpm 要先抬到量级上。
  • 权威在服务端,与主表那一格同一条红线:外部回来的值只提供一个值,不决定流转。

方案与更细的口径在 form-data-integration-design.md §9.2。 钉在 PYTHONPATH=. python3 scripts/check_row_fetch.py(34 句:逐行取数与覆盖、入参作用域、 带出去向只认本表、点行号的报错、整表隐藏时降级、留痕摊得开行号、设计期那几道闸门)与前端 formFetch.rowFetch.spec.ts、FormRenderer.rowFetch.spec.ts、 FieldInspector.columnFetch.spec.ts、formPrune.spec.ts。

2.13 选择类字段能挂好几套候选来源:optionRoutes

用户那句是「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段来判断 我该组件中该用什么数据源」。以前 optionSource 是一维一答,换一家只有摆三格 + 显示条件 (三个字段名 = 三份导出列 + 三套环节权限)或者去对面求一个聚合接口。

没有新字段类型、没有新接口:字段上多挂一份有序清单 field.optionRoutes(最多 8 条), 每一条 = 一个触发条件(when,与 visibleWhen 同一份结构化条件)+ 一套候选来源配置 (dict / dataSource / process / manual 各带自己那几格)。自上而下第一条成立的用它, 一条都不成立回落到字段自己那一份——老表单没挂清单,走的正是这条路,一个字节不用改。 同一寸在「取一个值」那一头也有:fetch.sources[].when(单源老写法也能挂)。

谁 认这一档的哪一句
设计器 多选那几格「同一个字段的几家」(各挂一条「某字段 = 某一个值」)时,属性栏给一颗「并成一格」:条件搬进清单、来源各归各条、指着旧名字的带出跟着搬(utils/formMerge.ts,判据不新增)。单格配置在属性侧栏「候选来源」下面那一栏「同一格换一家候选」(design/OptionRoutesEditor.vue):挑一格点「一家一档」,它有几个取值就铺几条卡片、条件替写好;外部那几家在第一家的卡片里配好带出后点「套给其余几家」;字典那一条上那颗按钮直接把人送到「字典带出」那块。「外部取数」面板里每条源还多一颗「什么时候调这一条」
渲染与取候选 先摊成一张视图再喂给既有函数:前端 optionSource.optionFieldView → formLinkage.effectiveOptions,后端 dicts.option_view → dicts.effective_options。视图只换来源那一维,pickerStyle / multiple / linkFill 原样留着
判越界 跟着命中那一条走:constrainsValues(field, data) ↔ dicts.constrains_values(field, data)。这一分钟是字典(要把关)、下一分钟可能是外部数据源(不把关)
字典带出、翻名字、级联筛候选 全部读视图,所以取的是命中那一本的附加值与那一条自己的「显示 / 存值」;命中那一条不是字典时字典带出一个字都不写
预取与删前检查 路由里那几本字典一起进预取清单(codes_of),也算「哪些表单在用」(dicts.used_by_forms / fetch.used_by_forms);漏一处就是删掉一把只挂在路由里的字典、那一格当场空
上游 路由的 when 与那一条的 cascadeFrom 并进 conditionDependencies / condition_dependencies,那一格一改就重算候选与失效值
保存那一刻 api/design.py:clean_option_source → dicts.clean_routes:每条只留属于它那一种来源的那几格、全勾状态不留、第 9 条起截掉、一条不剩把键抹掉;主表字段与明细列同一句。挂了这份清单也算「这一格有候选来源」——那道「选项类字段未配置任何选项」不再拦它(form_problems ↔ validateFields 两边同一口径),因为「先选分类再问那一家」的那一格常常故意把自己那一份留空
脏条目 当没配:认不出的来源、空条目一律丢掉,宁可回落,也不留一只永远为空的挑选器

那一条候选还能自带一份带出(optionRoutes[].fill,只给外部数据源那一条):「换一家」 从来不只是换一份候选清单,而是换一整套答案——挑的是 ERP 那家供应商,开户行与信用额度就得回 ERP 查。 以前要配出这个结果得把同一条判据抄两遍(候选那一格写「差旅问 ERP」,取数条目再写一遍),漂开的 症状最难查:候选换了家、带出还是上一家的。现在那一条自带「问哪一家 / 带什么入参 / 哪几个键写进 哪几格」,后两样留空就跟着这一条走;运行时摊成一条普通的取数条目丢给同一个执行器(同一个入参写法、 同一份留痕、同一档 onError),只多一个 fillOnly 记号——只写「带出去向」那几格,绝不盖这一格 刚被人在候选里挑中的那一个值;一条都不成立或命中的那条没自带,照旧读字段上那份 fetch。 字典那一家走 autoFill、流程单据那一家走 linkFill,那两条本来就跟着各自命中的对象走, 不再各挂一层。所以「一家外部数据源 + 一家数据字典」这一对最常见的配法是各写各的:外部那一条在卡片里 配「这一家的带出」,字典那一条在「联动」面板的「字典带出」里配。带出读的是命中那一本字典的附加值 (applyAutoFill ↔ apply_auto_fill 都先摊视图),命中那一条不是字典时一个字都不带;字段自己没挂 字典、路由里挂着字典时 autoFill 不再被当上一家的残骸洗掉,两处都没字典才洗掉并说一句「这一档不起 作用」;那一栏现在对「只有路由挂字典」的格子也出现,能带哪些列是那几本附加值列的并集。见 option-source-routing-design.md §5.1。 界面上是那张卡片下面多出一栏「这一家的带出」,设计期门牌写「第 N 条候选来源的带出」。

顺带两档都在这轮补上(同一批反馈):field.allowOutsideValue(带回来的值不在候选里也收下, 默认关;勾上之后页面不清值、提交不判越界、界面上补一行候选);回看那一屏改为按 存过的那份值评条件、因显示条件不成立被收走的必填格不再卡提交。

方案、为什么以前只能一个、以及保留的那一寸,见 option-source-routing-design.md;钉在 PYTHONPATH=. python3 scripts/check_option_routes.py(不碰库)、 PYTHONPATH=. python3 scripts/check_option_route_fill.py(那一家的带出)与前端 optionSource.routes.spec.ts、formFetch.when.spec.ts、FormRenderer.optionRoutes.spec.ts、 design/OptionRoutesEditor.spec.ts、design/FetchPanel.when.spec.ts、optionSource.fill.spec.ts、 formFetch.routeFill.spec.ts、design/OptionRoutesEditor.fill.spec.ts(带出那一栏的接线), 改名与删格子时跟着搬的落点在 formRename.spec.ts、formPrune.spec.ts。

3. 配错了在哪一步说

时机 判什么 在哪
设计器保存 类型不认识、纯排版勾了必填、该不该有标题、正则编译不过、字数上限离谱、附件三个限制越界、空白高度出格、明细列类型不支持、外部页面没挑页面 / 页面被删 / 参数是那个页面用不上的、标签页没配页 / 页签没名字 / 页签标识重复 / 外部页面那一页上还压着格子 / 摆了不止一个标签页、明细列那几样新的:列宽不在 60-640px 也不是「自动」、对齐与合计的写法不认识、非数字列配了求和(§2.10)、上下限写反;列上那份 fetch 与主表同一套闸门(§2.12):源不存在 / 已停用、入参引用了不存在的格子、带出去向落到主表字段或落到自己 前端 utils/formLayout.ts:validateFields(明细列那一串走 utils/formRuntime.ts:validateTableField)与 utils/formRuntime.ts:embedConfigProblems;后端 formruntime.validate_schema(含 embed.problems 与 column_display_problems)+ api/design.py 的字段校验
保存落库前 换了类型就收掉上一类留下的配置:展现格式按 FORMAT_OWNERS,限制按 LIMIT_OWNERS api/design.py:clean_formats
填单时 maxlength、accept、个数与大小、年份与月份的原生控件 FormFieldControl 与 AttachmentUploader(只为体验,不是闸门)
提交时 必填、正则(整格匹配)、长度、月份/年份写法、多选月份那串里每一项的写法、星期取值、时间段与日期区间的先后、附件类型/个数/大小、数字与金额的取值上下限(界面上只标红,拦不住人)。列上配了逐行取数的,这一趟先按同一份配置逐行重取再判(§2.12)。明细行里锁着(readonly)或藏着(hidden)那一列不卡必填(§2.8、§2.10),已躺着的值照判;而且格式那几问不再跟着必填走——以前整段套在「没勾必填就跳过」里,于是非必填的列填什么都没人看,那三道限制等于只在浏览器里说了算 后端 formruntime.validate_submit(主表 value_problems,明细行 _row_problems,两者同一份判据)
只读 / 打印 / 导出 每一类念成一句人话 FormFieldControl 只读那一支、api/export.py:cell_text、service/titles.py:_field_text。embed 无值,导出与打印里天然什么都不落——那条地址上挂着一次性免登短码,落进导出件等于把钥匙抄进表格

正则按 fullmatch 判:半匹配会让 \d{6} 放过 abc123456def,配的人以为挡住了、其实没挡。 这句也写在属性面板那栏的提示里。

4. 加一类字段要动哪几处

  1. frontend/src/types/index.ts:FieldType 加一类,值装得下单个值就顺手加进 TABLE_COLUMN_TYPES;
  2. frontend/src/utils/formLayout.ts:FIELD_TYPES 排进左侧那一列该在的位置;
  3. components/oa/design/FieldLibrary.vue 的 META:没登记 typecheck 直接红 (Record<FieldType, ChipMeta | null>,不想单列就写 null,别删——手写签名就是被"删"过一次);
  4. components/oa/FormFieldControl.vue:编辑态控件 + 只读态怎么念;
  5. utils/formRuntime.ts ↔ backend/app/service/formruntime.py:值形状、必填判定、提交校验;
  6. utils/fieldCapabilities.ts ↔ backend/app/service/threshold.py / quota.py:归组,决定能不能挂阈值与额度;
  7. utils/routeExpression.ts:条件搭建器该给什么控件;
  8. backend/app/api/design.py:FIELD_TYPES、LAYOUT_ONLY_TYPES、LIMIT_OWNERS;
  9. api/export.py 与 service/titles.py:落地成什么文本;
  10. i18n/locales/zh.ts 与 en.ts:fieldTypeXxx 加两段说明——少一份翻译不会报错, 只会在英文界面上印出裸的 key,i18n/localeParity.spec.ts 替两边数一遍;
  11. 跑 pnpm vitest run——utils/fieldCatalog.spec.ts 会替前后端两边数一遍。

5. 唯一口径在哪

说什么 前端 后端
有哪些类型、左侧怎么摆 utils/formLayout.ts:FIELD_TYPES + design/FieldLibrary.vue:META api/design.py:FIELD_TYPES
值形状与必填 utils/formRuntime.ts service/formruntime.py
能挂什么面板、能比什么 utils/fieldCapabilities.ts service/threshold.py + service/quota.py
明细列能用哪些类型 types/index.ts:TABLE_COLUMN_TYPES service/formruntime.py:TABLE_COLUMN_TYPES
明细列锁不锁(只读) 一份 column.readonly:FieldInspector 那两处的开关 + FormRenderer 递给录入控件 service/formruntime.py:_row_problems(锁着的列不卡必填)
明细列能配什么(与主表同权) 一份 column.*:design/FieldInspector.vue 列卡那一栏「更多配置」+ utils/formRuntime.ts(visibleTableColumns / columnNotForPeople / columnHasNoInput) service/formruntime.py:_row_problems(藏着与锁着都不卡必填、格式照判)+ column_not_for_people
明细列在表格上怎么摆(列宽 / 对齐 / 合计) types/index.ts:TABLE_COLUMN_WIDTHS / TABLE_COLUMN_ALIGNMENTS / TABLE_COLUMN_AGGREGATES + utils/formRuntime.ts:columnMinWidth / columnAlignClass / columnAggregate service/formruntime.py:COLUMN_WIDTH_MIN~MAX / COLUMN_ALIGNMENTS / COLUMN_AGGREGATES(column_display_problems 只在设计期判)
最多一行的表自动补那一行 FormRenderer.vue:singleRowTables(与点「+」同一份 emptyRow + rowSeed + applyRowFormulas;只读、锁着、整格藏起来的表不补) —(normalise_rows 照旧剔空行,后端不必知道这件事)
明细表只读那一屏收不收折 一份 field.readonlyStyle:FieldInspector 那一栏 + utils/formRuntime.ts:tableReadonlyCollapsed(只读那一支问一次,打印走 flattenTabs 强制摊开) —(纯展现,后端不读,两个 clean 都不收这一键)
条件里的控件与比较符 utils/routeExpression.ts engine/conditions.py
空白格之外谁必须有标题 utils/formLayout.ts:LABELLESS_TYPES api/design.py:LABELLESS_TYPES
有哪几页、谁在哪一页 utils/tabPages.ts(含伪装给 iframe 那一格的 key 口径) service/tabpages.py(同一份措辞与页数上下限)
谁把它们钉在一起 utils/fieldCatalog.spec.ts(读后端源码比清单)+ i18n/localeParity.spec.ts(比中英词条) —