47 KiB
候选来源、显示与存值、挑选方式:把「关联审批单」和「下拉框」合成一件事
相关:external-data-simplification.md(字典怎么吃外部数据源)、 form-data-integration-design.md(五种取数形态)、 data-binding-unification-design.md(这一篇的候选来源 与「字段上的外部取数」为什么是两个配置项、它们底下共用的是哪一层)、 relation-link-fill-design.md(来源 = 流程单据那一格挑中之后的 那几张单,值怎么倒过来写进这一张单的主表字段与明细表)、 designer-panel-dialogs.md(这一栏在界面上长在哪儿:属性侧栏 只留一行入口,候选来源、显示映射、关联带出那三块摊在同一扇门里), option-source-routing-design.md(同一格挂好几套候选来源, 按这张单上的值换一家:
optionRoutes那份有序清单与「带出的值也收下」那一档)。 这一篇讲三件事:一格的候选从哪儿来、这一行给人看哪一列 / 往数据里写哪一列、 用什么姿势挑,以及为什么这三件事本来就该是一件事。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 改之前什么样 | 三条互不认识的路:选项手填在 options、选项来自字典 dictCode、关联审批单自己一条 relationProcess。外部数据源想当选项来源,还得先同步进字典绕一圈 |
| 于是缺了什么 | 下拉框想要「能搜索、带副标题的弹出框」没有入口;关联审批单想挂一张物料字典也没有入口;样式在代码里写死,一类字段一个样 |
| 改之后 | 三个正交的配置:optionSource(手填 / 字典 / 流程单据 / 外部数据源)× optionMap(显示哪一列 / 存哪一列)× pickerStyle(下拉选项 / 弹出框 / 平铺,或 auto 让它自己选) |
| 谁能用 | select / picker / radio / checkbox / relation 五类,主表和明细表的列同一套口径 |
| 存什么 | 还是那几个老字段。optionSource 只把「这一格走的是哪条路」写明;optionMap 只改存哪一列,落地位置一个字没动,不配就是各来源以前写死的那一列 |
| 长什么样 | 四种来源 × 三种姿势,编辑态都是同一只输入框(全局 .field-trigger,Select 与 ComboTrigger 共用一份样式);只有「平铺」按它的本意摊成一排 |
| 老表单 | 一个字都不用改:没写 optionSource 时按老写法推(relation = 流程单据,有 dictCode = 字典,其余 = 手填),推出来的行为跟今天完全一样 |
| 新接口 | 没有。流程单据走现成的 GET /work/related + GET /work/summaries,外部数据源走现成的 GET /data-source/options,字典走 POST /process/dicts/values |
| 越界校验的边界 | 手填 / 字典判「值必须在候选里」;流程单据与外部数据源不判——服务端手上永远只有搜出来的那一页 |
| 唯一口径在哪 | 前端 src/utils/optionSource.ts + src/utils/optionMap.ts,后端 backend/app/service/dicts.py(source_kind_of / constrains_values / stored_of / shown_of)。控件只有一只:components/oa/OptionPicker.vue;设计器只有一栏:components/oa/design/OptionSourcePanel.vue |
| 同一格换一家 | field.optionRoutes:一份有序清单,每条 = 一个触发条件 + 一套候选来源配置,自上而下第一条成立的用它,都不成立回落到上面这三格——「报销类型是差旅时问差旅字典、是招待时问 ERP 的费用科目」不必再摆三格(见 option-source-routing-design.md) |
| 带回来的值不在候选里 | field.allowOutsideValue(默认关):勾上之后外部取数 / 关联单据带出 / 字典带出写进来的那个值不清、不拦,界面上补一行候选站着 |
| 第四维(只做给看) | field.picker:下拉那一档与弹出框那一档各看哪几列(主显示列 / 副标题几列 / 行尾徽标),外加弹出框的搜索框开关、搜索列、每页条数、标题。纯展示——存出去的值一个字节都不变(见 §8) |
| 那一行还能读对方表单 | 来源 = 流程单据时,显示列 / 副标题 / 徽标 / 存值列都能写 data.字段名,读的是那条流程表单里的某一格(点了才读正文、最多 8 列)(见 §12) |
| 这一格算谁的单 | field.relationScope:created(默认,只列我发起的)/ related(我发起、我办过、我被抄送)。只管候选列不列它,已经挂上的照旧回显(见 §12) |
| 左侧两格组件 | 「下拉框」(select) 挂表单自己的数据(手填选项 / 数据字典),「下拉选择」(picker) 挂别处的数据(外部数据源 / 流程单据)。同一只挑选器,两种定位;定位只是给挑的清单,不是技术边界(见 §8) |
| 关联审批单去哪了 | 它就是「来源 = 流程单据、姿势 = 弹出框」那一格。原来的 RelationPicker.vue 删了,弹窗那套(搜索、单号 · 流程 · 发起人、状态角标)原样搬进 OptionPicker |
| 一串值怎么来 | select / picker 上一句「可以选好几个」,这一格存的就是一串。三种姿势都装得下一串,包括多选下拉(Select 自己会画勾选框:勾完不收起、挑中的挂在框里、窄格子收进「+N」)(见 §8) |
1. 三件事本来就是一件事
「这一格能点什么」以前由字段类型决定:select 去 options / dictCode 里捞,
relation 去单据表里捞,想换一种就得换字段类型。可真正在做表单的人脑子里的问题是分开的三问——
候选是什么东西(我写死的几个词?字典里的一本分类?上次那张报销单?ERP 里的三万个物料?)、
这一行给人看哪一列、往数据里存哪一列(念名称还是编码?落 ERP 主键还是物料编码?)、
怎么把它挑出来(点开一列点一下?弹个框搜一下?摊在一排上看完再点?)。
radio 和 checkbox 能平铺不能弹出框、relation 只能弹出框、每一格存哪一列由代码写死——
这些都不是设计,是当年各写各的留下的巧合。
所以这次不新增字段类型,也不给 select 打补丁,而是把三问各自做成一维:
候选来源 optionSource manual ─ dict ─ process ─ dataSource
显示与存值 optionMap 看哪一列 labelKey ─ 存哪一列 valueKey
挑选方式 pickerStyle auto ─ dropdown ─ dialog ─ inline
三维各自可选,组合的合法性由 styleChoicesOf 一处判(不给装不下的组合出现在下拉里,
后端 clean_option_source 再兜一道)。字段类型退化成只回答一件事:这一格装单个值还是一串值。
months 多选月份不在那四类来源里,却共用第三维:它的候选是那一年那 12 个月,
谈不上手填 / 字典 / 单据 / 数据源,但「用什么姿势挑」问的是同一件事,于是字段上照用 pickerStyle。
两处不一样,都是有意为之:
- 这一类没有
auto:它只有一档默认(dropdown下拉多选),下拉里再摆「自动」等于让人猜默认在哪儿。 口径在utils/formRuntime.ts:monthsStyleOf↔service/formruntime.py:months_style_of, 平铺那一档摊开是 12 个格子、要吃掉一整行,所以不能当默认。 - 判「这一格要不要摆挑选方式那一栏」问
carriesStyleChoice(= 有候选来源的那几类 + 多选月份), 别再问carriesOptionSource——那一句只管来源。后端clean_option_source也为它单开一条: 按"这一类没有候选来源"的捷径走,会把pickerStyle连残骸一起抹掉,配的人挑了弹出框、 存一次就默默掉回下拉。回归PYTHONPATH=. python3 scripts/check_months_style.py(17 句)。
2. 四种来源各存什么值
| 来源 | 这一格存的 | 候选怎么来 | 取值越界判不判 |
|---|---|---|---|
manual 手填选项 |
选项的 value |
就写在字段的 options 上 |
判 |
dict 数据字典 |
字典项 value |
dictCode 那本字典(字典自己可以是手工的,也可以是从外部数据源同步下来的) |
判,含级联上级过滤 |
process 流程单据 |
对方单据的 job |
GET /work/related(relationScope 限这一格算谁的单,默认只列我发起的,管理员也一样;related 才是「我发起 / 我办过 / 我被抄送」那一片,见 §12),relationProcess 可限定只看某个流程,relationStatuses 限定只看哪几种状态(默认只给归档通过的,见 §11) |
不判 |
dataSource 外部数据源 |
源给的编码 | GET /data-source/options,即列表型源 + 关键词按需搜,限流 / 缓存 / 留痕都在后端 |
不判 |
表里那四列都只是默认:同一条候选的别一列也能当值、当显示文字,改不改由 §4 那一维定。
「不判」这条是这次最容易做错的地方。selection_problems 与 dropStaleSelections 的原话是
选中的值必须在能选的项里,那对全量清单在手里的来源成立;对搜出来的来源,"能选的项"只是
搜索结果的第一页,照它清值会把人十分钟前正常选中的那张单子悄悄清成空,照它拦提交就是
「界面让人选、提交说非法」。所以两边各有一句同样的判断:
前端 constrainsValues(field)、后端 dicts.constrains_values(field)。
反过来,relation 挂上字典之后反而多了一层把关:以前它是"引用别的单据",没有候选清单可言;
现在候选是字典项,级联、字典项附加值带出、越界校验、导出翻译全都跟着来了。
3. 三种姿势,谁能挑哪几种
| 姿势 | 长什么样 | 适合 | 谁能挑 |
|---|---|---|---|
dropdown 下拉选项 |
一只 Select,选项多于 5 条自动出搜索框;来源是搜出来的那种改成远程搜索。勾了「可以选好几个」就是多选:行首一颗勾,勾完不收起,挑中的挂在框里 |
名字短、条数不多 | 全部 |
dialog 弹出框 |
还是那只输入框(多选时已选的挂在框里,点一下摘掉),点开才是弹窗:搜索框、行首一颗勾选框(多选方框、单选圆圈,勾中的那一行当场描边加底色)、一行两到三样信息(单号 · 流程 · 发起人 / 编码 · 规格)、右侧状态角标;多选时列表上方还有「已选 N 条 / 全选本页 / 清空」,勾中几条不必数卡片 | 候选多、光看名字认不出、要勾好几个 | 全部 |
inline 平铺选项 |
一排 radio / checkbox 点选,不用点开 | 三五条选项,看完就点 | 来源是手填或字典的格子 |
三种姿势画的是同一只盒子。 样式定义在全局 .field-trigger(style.css),Select 与
ComboTrigger 都吃它:一样的圆角、内边距、聚焦光环,框尾一样是箭头(搜着挑的来源换成放大镜)。
弹出框那一档以前画的是一排标签牌加一个「+挑选」按钮,于是同一张表单里「来源=字典」那一格是下拉、
「来源=单据」那一格是按钮,看着像两种东西——现在区别只在点开之后。
唯一不画成输入框的是「平铺」:摊成一排 radio / 多选点选就是它存在的理由,auto 也只给
radio / checkbox 默认这一档。
auto(默认)按来源和类型给:radio / checkbox 平铺;来源是流程单据、或这一格存一串值
又挂的是搜出来的来源,给弹出框;其余给下拉。
只剩一条硬规矩,界面上直接不给、保存时也挡:
- 搜出来的候选不给平铺。摊开的前提是知道一共有多少,ERP 的物料没人知道。
「一串值的格子不给下拉」这一条以前也在,它当时说得对——一只 Select 只装得下一个值。
现在那只下拉自己会画勾选框了(§8),第二项有地方放了,这条规矩就跟着取消:
三种姿势都装得下一串值,勾不勾「可以选好几个」不再改变能挑哪几种,只改变默认是哪一种。
「这一格是不是一串值」仍然只有一处判据(holdsListValue / holds_list_value):checkbox 与
relation 天然是,select / picker 由字段上那个「可以选好几个」开关变成是。
4. 第三维:显示哪一列、存哪一列
一条候选不止一列能当值:字典项有编码和名称,外部数据源回来的那行还多带几个附加值,
一张单据有 job、单号、标题、流程名、发起人。以前存哪一列是代码替所有人定死的
(字典存 value、单据存 job、数据源存源给的 value),于是「这一格想存物料编码而不是
ERP 主键」「条件里想按单号比」都得绕路,绕不过去就只能换字段类型或再同步一本字典。
field.optionMap 把那两列交回配表单的人:labelKey 决定下拉与回显念哪一列,
valueKey 决定往数据里写哪一列,两个都写成点路径(value / job / extra.spec),
能挑的就是这一来源本来给得出的那几列:
| 来源 | 能存哪一列 | 默认存 | 默认显示 |
|---|---|---|---|
| 手填选项 | 每个选项自己填(设计器里一条两格;明细列那一串选项下面另有一串存的值) | value |
label |
| 数据字典 | value / label / extra.<键> |
value |
label |
| 流程单据 | job / serial |
job |
title |
| 外部数据源 | 源给的 value / label / extra.<键> |
value |
label |
四条口径值得写下来:
- 一切按存的那一列算。判越界(
formruntime用stored_of比)、字典带出、标题与导出的 翻译(option_labels)、条件分支与字段联动的候选值、给 AI 起草的合法取值清单(drafts)、 写回报文里的枚举翻译(mapping.dict_map→dicts.find_item)认的都是这一列; 前端渲染认的是同一份optionMap(utils/optionMap.ts投影),不会出现「界面显示甲、提交存了乙」。 - 级联的上级先翻回编码再比归属(
parent_codes/dicts.parent_codes):上级那一格也能配成 存名称,照存的值直接比parent会一个都匹配不上;翻不出就原样用,跨字典的上级同样原样用。 - 回显认不出的值原样念。搜出来的来源(单据、数据源)手上只有搜过的那几条,换了列又没搜过 就只显示存着的值;单号那一列本来就给人读,不额外编一个名字。
- 列名写歪不炸。
valueKey: job挂在一本字典上认不出时退回默认列渲染,设计器与option_source_problems各说一句,保存时clean_option_source把这份映射收干净: 跟默认一模一样的不留,认不出的列不认。
配的时候不用猜结果:那一栏下面拿一条真候选演一遍——字典取这本的第一项、数据源默默搜一页 拿第一条、单据取一张真单据,写出一句「例:这一格显示「螺栓 M8」,保存 M1」。取不到就只说列名, 不编一条假的骗人。
两条边界也说清:cascader 层级字典不参与这一维——它要靠 parent 一路串上去,值必须是编码;
「选人」「选部门」那两格存的登录账号与部门路径是权限判断的输入,让它们改存名称等于把
审批人判定的口径交给一张表单去改,所以那一类候选固定列,不给这一维。
5. 配歪了会怎样
设计器里那一栏一边配一边说(optionSourceProblems):来源选了字典却没挑字典、
选了数据源却没挑源、样式跟这一格不搭,都在面板下面出一行黄字;保存那一刻
formruntime.validate_schema 用同一套话再说一遍,主表和明细列一视同仁,接口直传、
AI 起草、流程副本那几条不进设计器的路也是这个结果。
换来源时上一家那几格跟着清(前端 optionSourcePatch、后端 clean_option_source)。
不清的后果很具体:从字典换成外部数据源,dictCode 还躺在字段上,而后端读候选优先认的就是
字典编码——于是界面显示新源搜出来的候选,提交时按老字典判越界,同一格两套口径。
清的理由也因此只有一条:这一格的候选由谁供给,就只留谁那几格。
clean_option_source 只动明写过 optionSource 的字段。老表单没写这个字段,
按老写法推出来的来源就是它自己的来源,那时候清别的键等于替历史做主。
反过来,用上了却被人删掉的那一条不能从下拉里消失(withMissingOption):字典或数据源删了,
字段上那个编码还在生效,而下拉按值找不着对应项就会显示成「还没选」——配的人以为没配,
填的人照旧提交。所以那一行照样列出来,只是标一句「字典已删除 / 源已删除」。
6. 落地清单
| 层 | 文件 | 干什么 |
|---|---|---|
| 口径 | frontend/src/utils/optionSource.ts |
来源推导、可选姿势、换来源要清哪些键、设计期检查。纯函数,不碰 i18n 也不发请求 |
| 口径 | frontend/src/utils/optionMap.ts |
三维里「显示 / 存值」那一维:能挑哪几列、点路径取值、候选投影、级联上级翻回编码、设计期检查 |
| 控件 | frontend/src/components/oa/OptionPicker.vue |
三种姿势 × 四种来源,编辑与只读同一套;单据与外部源的已选值按现成接口回显,念不出就显示原值 |
| 那只盒子 | frontend/src/components/oa/ComboTrigger.vue + style.css 的 .field-trigger |
弹出框那一档的输入框外壳:单选念一句话,多选把已选的挂在框里;Select 也改用这一份样式,两只控件不再各画各的 |
| 显示 / 存值 + 各档看哪几列 | frontend/src/components/oa/design/OptionMapEditor.vue |
「显示为 / 存为」两栏(数据口径)+「下拉里 / 弹出框里」两档各看哪几列与弹出框的搜索(展示口径)+ 拿一条真候选演的结果;主表用全量,明细列那一处只摆「显示 / 存值」(showDisplay=false) |
| 数据源候选 | frontend/src/composables/useDataSourceOptions.ts |
按需搜一页 + 顺手记住搜过的标签 |
| 设计器 | frontend/src/components/oa/design/OptionSourcePanel.vue |
来源 → 就地配它自己的东西 → 挑选方式,外加数据源「试搜一页」;配完想直接看填出来的样子,/design/forms/{id}?view=preview 一步进预览 |
| 左侧两格 | frontend/src/components/oa/design/FieldLibrary.vue + utils/optionSource.ts 的 OFFERED_SOURCE_KINDS |
「下拉框」与「下拉选择」两格各自悬停说一句分工;offeredSourceKinds / sourceKindChoicesOf 决定这两格里各能挑哪几种来源(已经在用的那一条永远留着) |
| 接线 | FormFieldControl.vue / FieldInspector.vue / LinkagePanel.vue |
选择类字段一律走 OptionPicker;原来散在中间的选项编辑器、联动面板里的字典来源、关联审批单那块流程范围,合成上面那一栏 |
| 明细列 | FieldInspector.vue 列编辑区 |
一列一张卡,卡里摊成一张 12 栏网格:标题 / 类型 / 标识 / 必填 / 只读 / 删除钉在第一行,来源 + 挑选方式与它那几格跟着并排(字典下拉保留「能选到什么」那一行预览,只是挪到了字典那一格下面);用不上的格子不摆,后面的往前靠(那一列锁不锁见 form-field-catalog.md §2.8) |
| 后端把关 | service/dicts.py / service/formruntime.py |
source_kind_of / holds_list_value / constrains_values / effective_options / stored_of / shown_of / project_options / option_map_problems / picker_display_problems / option_source_problems |
| 后端清洗 | api/design.py::clean_option_source |
保存时按来源收掉不属于它的键,与 clean_formats 同一位置同一套道理 |
| 导出 | api/export.py |
来源不是流程单据的关联格不再拿单据名册去翻,按候选来源翻标签 |
7. 没做的事,以及为什么
- 一格多个候选来源的合集。外部取数那边有
fetch.sources多源合成,那是取值; 候选来源是挑东西,两件事。真要「ERP 物料优先、没有就用字典」, 正确的位置是让字典绑那张数据源(见 external-data-simplification.md)。 - 外部数据源的值翻译回标签。没有「按一批编码取标签」的接口,所以只翻搜见过的; 其余显示原值。一屏红字拦不住一个陈旧引用,只会让人以为整张表单坏了。
- 条件分支里把
relation当可比较字段。它仍旧是 opaque 类型; 挂上字典之后理论上能比了,但条件分支的候选值那一套要跟着改,等真有人在路由上用到再说。
8. 再加一层:两格下拉组件、可以选好几个、每档各看哪几列
这一层是在上面三维之上加的,三条约束撑住了它:不新增第五种来源、不新增第二只控件、 不改一个存出去的值。
左侧摆成两格组件。 需求是「下拉框 = 数据字段 + 手填选项,下拉选择 = 数据源 + 关联审批表单」。 做法是把字段类型分成两格、把来源清单按定位切开,而不是做两套配置面板:
| 左侧那一格 | 字段类型 | 给挑的来源(OFFERED_SOURCE_KINDS) |
定位 |
|---|---|---|---|
| 下拉框 | select |
手填选项 / 数据字典 | 挂表单自己的数据 |
| 下拉选择 | picker |
外部数据源 / 流程单据 | 挂别处的数据(一张列表型数据源、本平台别的流程的单据) |
「关联审批单」(relation) 不再单列一格——它的本事整个是「来源 = 流程单据」那一格,
再摆一格只是多一个要分清的选择;老表单里那一类字段照旧渲染、照旧能改。
offeredSourceKinds 是给挑的清单,sourceKindsOf 才是技术边界,两者故意不是一份:
历史上就有「下拉框挂了数据源」的配法,服务端要是照定位把它判死,那一格读出来的来源会换成
另一条,界面与校验当场分成两套口径。所以 sourceKindChoicesOf(field) 在设计器下拉里
永远补上「这一格此刻已经在用的那一条」,optionSourceProblems 才去说那句「这类字段挑不了这种来源」。
一条空的新格子也不该推成「手填选项」——sourceKindOf 先认字段上有没有配过候选的痕迹
(dictCode / options),什么痕迹都没有才轮到定位说话。
「可以选好几个」是一个开关,不是一种新组合。 multiple 只出现在 select / picker
(前后端同一份清单:MULTIPLE_PICKER_TYPES),生效在一处:holdsListValue(field)
(后端 dicts.holds_list_value)。默认挑哪一种姿势、导出与回显按一串值还是单个值念、
额度与外部取数那两头打不打架,全都问这一句。它和额度、外部取数、阈值条件打架
(那三头都只认一笔 / 一个值),保存那一刻就说。
多选下拉:给这只 Select 加了复数,没有再发明一只控件。
Select 的 modelValue 是泛型(T)——单选取标量、多选取一串,回抛的
update:modelValue 跟着同一个 T 走,几百处单选调用一个字都不用改。加进去的东西只有四件:
| 加在哪 | 加什么 | 为什么是这件 |
|---|---|---|
Select |
multiple |
值是一串:行首画勾选框、点完不关弹层(连着勾三项是常态,关一次就得多点一次)、清空发 [] 不发 null |
Select |
框里那一排标签 | 用全局 .field-tag,与弹出框那一档同一个长相;一颗一个 ×,明细那种窄格子里只留一颗、其余收进「+N」 |
Select |
known |
搜出来的来源手上只有这一页,多选又允许跨页挑:已选项被下一次搜索冲掉之后,框里还得念得出它叫什么 |
OptionPicker |
下拉那一档接 multiple |
发出去的值与弹出框那一档一模一样,都是同一串 |
勾完不关弹层这一点顺带解决了一件老麻烦:一本几百项的字典里挑三项,以前是
「点开 → 搜 → 勾 → 关 → 再点开 → 再搜」,现在搜一次连着勾完。
多选那一档也吃 picker.dropdown 那三列(主显示 / 副标题 / 徽标)——标签念的仍是主显示列。
后端只跟着改了两处「一票否决」:clean_option_source 不再把一串值上的 dropdown 撤掉、
option_source_problems 不再说那句「一只下拉放不下」。存出去的值、判越界那套、导出、
条件分支一概没动——它们问的都是 holds_list_value,跟用哪只控件没关系。
「看哪几列」做成第四维,并且只做人看的那一半。 optionMap 那两格定的是数据口径:
改了它,判越界、导出、条件分支、外部系统认的值都跟着变。field.picker 定的是展示口径:
field.picker = {
dropdown: { labelKey, noteKeys[], badgeKey }, // 下拉那一档
dialog: { labelKey, noteKeys[], badgeKey }, // 弹出框那一档
search, searchKeys[], pageSize, dialogTitle // 弹出框的用法
}
三格缺省各自回落:labelKey → optionMap.labelKey → 该来源默认列;noteKeys 没写 =
用该来源默认那几句(单据是「单号 · 流程 · 发起人」,数据源是多带出来的那几个键),
写成 [] 才是明确不显示;跟这一行标题重复的那一列在投影时去掉。搜索框默认开着
(候选是搜出来的那两条一律开、关不掉;本地候选按条数自己收放),搜索列没配就把这一格
用得上的那几列都算上——「按名称搜得到、按编码搜不到」最容易被当成 bug。
本地筛得动的(手填 / 字典)这几列真参与过滤;数据源与流程单据是上游按关键词搜,
界面上那一句就照实说。
因为这一维不碰值,后端只需要认识它(picker_display_problems 说哪一列不会显示、
clean_picker 收掉跟默认一模一样的那几格),校验、导出、条件、写回一概不用改。
9. 这套口径在哪儿被验过
前端那几份口径测试(npx vitest run src/utils/optionMap.spec.ts src/components/oa/OptionPicker.spec.ts src/components/common/Select.spec.ts src/components/oa/design/OptionSourcePanel.spec.ts,
都带 @vitest-environment jsdom):
一份盯「显示 / 存值」这一维的纯口径(没配映射必须一模一样、挑别的列之后存什么显示什么、
级联上级存名称时先翻回编码),
一份按「四种来源 × 三种姿势」逐个渲染并断言发出去的值(含只读态把 job 念回标题、
存单号时发出去的是单号、不论来源编辑态都是 .field-trigger 那只盒子),
一份盯 optionSource.ts 那几条口径(老表单怎么推、换来源清哪几格、哪几种姿势可挑)
和设计器里换来源那一下(发没发 optionSource、面板切没切过去、删掉的字典还看不看得见)。
后端那条保存回路是对着跑起来的库验的:建一张临时表单、读回来逐个字段比、再删掉——
optionSource / pickerStyle / dataSourceCode 原样存住,多选格子上的 dropdown 存得住,
挂在搜出来的来源上那个 inline 照样被丢掉,文本框上误挂的三格全清,
没写 optionSource 的老字段一个键都没多。
第四维这一层再加三份:OptionMapEditor.spec.ts 盯「两档之间不串台」(在弹出框那一档勾一列
不会改掉下拉那一档、跟默认一模一样的那几格不往字段上写、showDisplay=false 那一处只剩两格),
OptionPicker.spec.ts 盯「下拉里只写名称、弹出框里多写编码 · 规格,而发出去的值没变」
「徽标换成配的那一列」「每页条数落到取单据那一页」「搜索框的开关与搜索列真的参与本地筛」,
OptionSourcePanel.spec.ts 盯这两格组件的定位清单(下拉框挑不到外部数据源、已经在用的那一条
不凭空消失)、multiple 那一下(三种姿势都还挑得动、本地多选默认落回下拉、发出去的 patch
只有 multiple 这一格),
Select.spec.ts 盯那只下拉加复数之后最容易被挤坏的地方(单选点完还是发单值并收起弹层、
多选连着勾不关弹层、摘标签与清空发的是什么、窄格子里「+N」、跨页挑中的靠 known 念名字),
以及换来源时只清「看哪几列」那几格、搜索与每页条数留着。
10. 挂上来的那几张单点得开(2026-11)
关联审批单选完只看得见一串名字,想看那张单得记住单号回列表里搜——PC 与手机都撞这堵墙。
这一层不加配置项:「来源 = 流程单据」这一条来源,名字本身就是链接,落在 /work/:job
(路由名 work-detail)。判据与实现只此一处,frontend/src/components/oa/OptionPicker.vue:
workHref(job)按路由名解析,将来路径改了不必回来改这里;没挂 router 的场合(组件单测、 内嵌预览)退回路径写法。注入用的是inject(routerKey, null)而不是useRouter()—— 后者不带默认值,没挂 router 时会在控制台留一条 warning。- 四个来源里只有
process那一支给PickRow.href,字典与外部数据源没有单据可开,一个链接都不加。 optionMap改存了别的列(单据编号、限定流程之后对方表单里那一格)时,先经knownIndex翻回 job 再拼地址;手上还没这份缓存,就把存着的值原样报给摘要那一句,连同「这一格存的是哪一列」 (by)与「限的是哪条流程」(process)一起,由后端按同一列认回单据(§13)。认不出是哪张单 就不给地址——一个开不去的链接比一句念得出单号的死文字更坑人(processHref)。
链接画在哪儿,跟着「这一格此刻是什么样子」一处一处补:
| 那一格此刻 | 点哪儿 | 怎么画 |
|---|---|---|
| 只读 · 一串值 | 标签牌上的名字 | 真 <a target="_blank">(牌子在 div[role=button] 里,套得住 a) |
| 只读 · 单个值 | 那一句话,多条时逐句分开,不是一整段死文字 | 同上 |
| 编辑 · 弹出框 | 挂在框里那排标签的名字 | 同上,@click.stop 不让它顺手把挑选弹窗也打开 |
| 编辑 · 下拉多选 | 框里那颗标签的名字 | Select 的触发器本身是 <button>,套不住 a:span[role=link][tabindex=0] + window.open,回车一样点得开 |
| 编辑 · 下拉单选 | 框里那一句话 | 走 Select 已有的 selected 插槽,仍是真 <a> |
手机端三处都跟着这一份实现走,不另写一套。审批那一屏本来就走 FormRenderer → OptionPicker,
自动就有了;「完整单据」那一屏(mobile/MobileFormReader.vue)原来只念 useFormPlan.fieldText
算出来的文本,关联那一格于是把 job 原样摊在 390px 的屏上——现在那一格单独走 OptionPicker
的只读态,念回标题,也点得开。/work/:job 是 PC 与手机共用的那一条路由(WorkDetailView
自己按设备切 MobileWorkView),所以一个地址两头都打得开;开在新标签页是有意的——
从填单那一屏跳走会把手上还没提交的这张单弄丢。
2026-11-18 把剩下那两处补齐了:手机上摘要那一屏(mobile/MobileFormSummary.vue,两版共用
同一条逐格链子)与两屏里明细的那一列。收成一只组件 mobile/MobileRelationValue.vue
(就是只读态的 OptionPicker + 一遍路由视图),判据 useFormPlan.opensWork(field, data),
三处吃同一份——标题与落点不可能在两屏长出两副样子。为什么收成组件而不是各摆一遍:
「这一格此刻按哪一套候选来源工作」那一句每处都得过,漏一处就是「标题按 A 家翻、落点按 B 家拼」。
细节与那两条分寸(摘要里整段摆、空着的那一格不走这一条路)见
mobile-approval-layout.md §4.2。
字号:单据标题动辄「某某某发起的某某流程」再加单号、流程名、发起人,默认的 .field-tag(12px)
在窄格子里两三个就占满一行。source === 'process' 时这一排牌子收一档(.picker-dense:11px,
内边距与图标跟着缩)。类名挂在只读那一块的根上,下拉与弹出框两档透给 Select / ComboTrigger
的根节点;规则本身写在全局 style.css 里、挨着 .field-tag,不写成组件里的 scoped 样式——
牌子是这两只通用控件画的,收在全局一处,既不用赌 scoped 样式穿不穿得进子组件,也不用给它们
各加一个「要不要小字」的开关。全局那条 .field-tag 一个字没动:人员选择器与附件还要它
本来的样子。
顺手修掉一个真 bug:resolveJobs 要先经 knownIndex 把存着的值翻回 job,而那一趟
watch(immediate) 以前挂在 knownIndex 定义之前——「改存单号」的那一格一进来就撞 TDZ,
吃一个 unhandled rejection,摘要再也取不到。症状只是念不出标题,所以一直没人看见。
钉在这儿的行为:OptionPicker.spec.ts「关联的单据点得开」(只读两档的 href 与 target、
弹出框点名字不顺手开弹窗、下拉那颗标签走 window.open、存单号时链接仍落在真 job 上、
字典与外部数据源一个链接都不给、挂了 router 时按名字解析)、Select.spec.ts
「框里那颗标签点得开」(有 href 才画链接、known 里补的落点也算数、回车开单但不改选择)、
MobileFormReader.spec.ts「手机上关联的那几张单」(念回标题 + /work/J1、问不到摘要退回存着的值、
空着仍留一行破折号)、MobileFormSummary.spec.ts「关联的流程点得开」与
MobileFormReader.spec.ts「明细里那一列关联的流程也点得开」(摘要那一屏与两屏的明细列同样念回标题、
挂条件路由时命中那条才翻、空着的那一格不抢这一条行)。
当时留下一件没做的:「存为」一改成单据编号(或对方表单里那一格),这一格就点不开了——
回显那一趟问 /work/summaries,手上只有存着的那个值,而后端只按 job 查,空手回来,
标题念不出、processHref 也就给不出地址。这一件在 §13 补上了。
11. 挂上来的单得是走完的那一种(2026-11-10)
「关联已审批流程」这个名字承诺的是已经批完的单子,而它当时的候选是把两张表混在一起搜的:
在办表 oa_work(只有 running)加归档表 oa_work_completed(completed 是走完归档通过、
terminated 是被人中途终止、canceled 是作废)。于是报销单能挂上一张走到一半被终止的借款单,
而"被终止"这件事往往发生在挂上之后——审批人点开对照时才发现依据是一张没走完的单子。
配置项就一格:relationStatuses,三档的清单,界面上是一排复选框。
| 档位 | 给人看的说法 | 落到库里 |
|---|---|---|
completed |
已办结归档 | 归档表 status == 'completed' |
running |
还在办 | 在办表 |
closed |
已终止 / 已作废 | 归档表 status in ('terminated', 'canceled') |
定下来的几件事:
- 默认只给
completed。没配过的表单一个新字段都不加,读出来就是这一档——名字说 「已审批」,候选就该是审批完的。要放宽(比如借款单还在走就想先挂上)在设计器那一排勾上, 三档全勾等于不限,接口上就是不加状态条件。 - 这一档只管候选列不列它,不判已存的值。单据是挂上之后才被终止的,按这一档拦提交等于
回头骂填单的人;回显走
GET /work/summaries,按 job 直接问摘要,照旧念得出标题和 「已终止」那个角标。这与 §2 那句「搜出来的来源不判越界」是同一条分寸。 - 摊到两张表时谁不沾就不查谁:只勾归档通过那一档,在办表一个候选都出不了,
那条 UNION 分支整个不发出去(
relation_status_tables回None就是"这张表别查")。 - 接口上不加新参数:还是
GET /work/related?status=…,只是这一句现在收逗号分隔的档位, 也认历史那种单据状态原值(terminated归到closed),老调用方读出来还是同一批单子。 - 换候选来源时这一档跟着
relationProcess一起清(前端optionSourcePatch/ 后端clean_option_source),换成字典还留着一份"单据状态"是看不见的东西里最容易骗人的那种。 - 勾到一种都不剩在保存那一刻挡:「至少勾一种状态:一种都不勾,这一格永远搜不到候选」。 运行时真读到空清单仍退回默认那一档,不让一只已经存下来的表单变成永远为空的挑选器。
- 措辞前后端各写一份(后端在
service/dicts.py,由formruntime转调),check_binding.py第 5 段逐句对。
设计器那一排复选框之外,填单弹窗在搜索框底下写一句「这一格只列已办结归档的单据」: 搜不到自己那张单的人,第一反应是"我没权限"或者"系统漏了单子",多写这一行比让人回设计器翻便宜。 §12 又添了「这一格算谁的单」那一档,弹窗底下这一句跟着合成一句(「只列我发起的单据 · 只列已办结 归档的单据」),两档各说一句、各说各的事。
钉在这儿的行为:后端 PYTHONPATH=. python3 scripts/check_binding.py
(「关联审批单能挂哪几种状态的单据」那一段:默认值、认不出的档位、老写法的状态原值、
两张表怎么摊、几句校验措辞);前端 OptionPicker.spec.ts
「来源=流程单据:候选只列哪几种状态的单据」(默认只问归档通过的、配了放宽就问那两档、
弹窗里那句说明、换了档位重捞一页、已选单据不受这一档影响)与 OptionSourcePanel.spec.ts
「关联审批单能挂哪几种状态的单据」(那一排复选框、勾回默认就把键抹掉、取样例按同一档取)。
12. 那一行念得出是哪张单,候选只列我发起的(2026-11-17)
两条都是配「关联流程」的人当场提的,原话摆在这里比任何理由都直白: 「展示字段我希望是可以选择到表单中的字段进行展示,这样在下拉选择流程的时候可以清楚知道是哪个流程」、 「选择流程范围不应该是已办,而是只有我发起的流程,不应该把我所有已办的流程展示出来」。
12.1 那一行多一头列名:data.字段名
来源 = 流程单据时,候选行只有单据本体那四列(标题 / 单号 / 流程名 / 发起人)。挂过五六张
「某某发起的报销申请」之后,那几列在同一只挑选器里根本分不出人——配的人要的是
「报销金额 12,000 · 出差日期 2026-11-01」这种一行,而那种东西躺在对方的 work.data 里。
| 定下来的事 | 为什么 |
|---|---|
| 列名按前缀认,不写死清单 | data. 那一头有什么列由那条流程的表单决定,写不进一份固定枚举。设计器拿现成的 GET /design/data-sources/process-fields(关联带出问的是同一句)列清单,标签写「表单字段 · 报销金额(费用报销表单)」 |
只有 process 读得到表单 |
判据只有一处:form_column_path(kind, key)。字典与外部数据源挂 data.x 是配错人——它们的附加值走 extra.,两头不串 |
| 点了哪几列才读正文 | /work/related 原本 with_data=False,压根没碰表单正文。现在接口收一句 fields=,点了才把正文捞回来、且只留点名的那几列;没点时摘要连 data 这个键都不回 |
| 翻成人话与导出同一把尺 | 走 exportfmt.cell_text:字典编码落「差旅费」而不是 CL01,附件落文件名,明细表压成一行,签名落「已签名」。认不出字段定义的列走 scalar_text,一列收在 120 字之内 |
| 回的形状就是点路径 | 后端嵌着放({"data": {"明细": {"0": {"金额": "300"}}}}),前端 pickKeyOf 一段一段点下去就取得到,两边不另造一套写法。深层列名按 fetch.pick_path 那一套:明细要点就得写下标,不写下标不悄悄拿头一行糊过去 |
| 上限与整表冲突一处收 | 一行最多读 8 列(MAX_RELATION_DISPLAY_FIELDS,接口的 fields 与字段上配到的列过同一份清洗);整表(data.明细)与其中那一格(data.明细.0.金额)同时配上时先落的算,后到的不覆盖 |
| 存值列也指得过去 | valueKey: data.立项编号 挂得住(关联立项单存它的编号而不是 job)。代价照 §4 那句:改了存哪一列,老数据不回溯翻译 |
「显示 / 存值」那两栏、下拉那一档与弹出框那一档的三格(主显示 / 副标题 / 徽标)、搜索列,
都接了这一头,不各配一套。前缀故意与隔壁那篇 relation-link-fill-design.md
里 linkFill.pick 写的 data.amount 是同一句:两边问的是同一个东西(对方那张单的表单正文),
就不该各有一套写法。OptionPicker 换列名或换范围就重捞一页,顺手把缺要点的那几列的
旧摘要从缓存里踢掉——不然配完回到只读那一头,标签牌上还念着上一次那份没有正文的行。
12.2 这一格算谁的单:relationScope
relationStatuses(§11)问的是这张单走到哪儿了,这一档问的是这张单算不算你的。
两件事以前挤在同一条 SQL 里:候选是「我发起 / 我办过 / 我被抄送」那一片的并集,于是挑历史单时
一大半是别人发起、我只是顺手批过的单子。
- 默认
created(只列我发起的),related才是老口径。这是一次行为变更:没配过的老表单 读出来就是created,理由就是上面那句原话。 - 管理员也照收。
_visible_work_filter放过管理员说的是他看得见别人的单,而这一档问的是 「这张单算不算你发起的」——一条事实,跟谁在查没关系。放过管理员会让同一只挑选器在两个人口中 列出两批单子,配表的人在自己账号下试出来的手感就骗人。 - 只收候选,不收已存的值:回显走
GET /work/summaries,不跟着这一档收窄。改版前挑上的、 别人代挑的那几张单还得念得出名字,不能因为挑不进来了就念成一串 job。与 §11 那一档同一分寸。 - 接口上两句分开传(
status=与scope=),合成一句只会让下一任配的人以为它们是一件事。 - 换候选来源时这一档跟着
relationProcess一起清;挂条件路由时它属于process那一条自带的 三格(ROUTE_OWNED_KEYS)——漏一份就是「存进去即失效」那种看不见的坏。
钉在这儿的行为:后端 PYTHONPATH=. python3 scripts/check_relation_scope.py
(档位读法与脏值、路由上那一档不被当残骸清掉、那一条 SQL 在两张表上各长什么样、管理员不放过、
列名清洗与前缀、FormDisplay 落出来的那一份文本、摘要里那个 data 键、前后端常量与措辞);
前端 OptionPicker.spec.ts「来源=流程单据:候选按「谁发起的」收」「那一行读对方表单里的哪几格」
与 OptionSourcePanel.spec.ts、OptionMapEditor.spec.ts 里那两截新的清单与那一档下拉。
13. 点不点得开,与「存为」选哪一列无关(2026-11-18)
原话是:「下拉选择组件我也希望可以实现选择流程可以跳转,并且不需要考虑选择存的字段才对。
关联审批流程组件也是一样。」两句撞的是同一个根因,而它是 §10 那条边界留下的:落点 /work/:job
要靠「存着的值 → 哪张单」翻出来,而存的是哪一列由配表的人说了算(optionMap.valueKey:
job 默认 / serial 单据编号 / 限定流程之后的 data.某列)。回显那一趟问的是
GET /work/summaries,它从前只按 job 查——「存为」一改成单据编号,那一格当场退回一串
读得懂、点不动的死字(配的正是这一档)。
| 定的事 | 为什么 |
|---|---|
界面上不再自己猜,把这一格存的到底是哪一列报出去(by),连同限定的流程(process) |
认法由后端一处持有;前端只说「我存的是这一列」,不必为每一列各写一份翻回 job 的逻辑 |
job / serial 走索引等值,两张表的 serial 都要有索引 |
已经挂上的关联单据九成套在归档表里(关联的都是走完的单),而 oa_work_completed.serial 从前没索引:那句按单号走的查询等于每次开单倒扫一张只长不删的表。ensure_indexes() 启动时补,sql/schema.sql 那份同步改 |
data.某列 只在限定了流程时认 |
表单正文里那一格没索引可依,process 有:范围收到那一条流程里再点 JSON。设计器里这一列本来也只有限定了流程才挑得到(OptionSourcePanel 那份 formFields 跟着 relationProcess 加载),两头对得上;没限定流程就当这一档没配,不扫全表 |
data.某列 比的是那一格的原文 |
存值列存的是「界面念出来的那一面」(exportfmt.cell_text 翻过的人话),字典、附件、明细那类「库里存码、界面念名」的列两边不是同一个字。认不到就少回一条:念得出存着的值、点不开,也比点进一张不相干的单强 |
| 认的顺序 job > 单号 > 表单那一格 | 万一有人把单号起成了别张单的 job,认 job 的那一格不该翻到错的那张单上({**by_form, **by_serial, **by_job}) |
| 同一张单被两个名字各认中一次只回一条 | 界面按值去重摆标签,回重了只是白搭一趟 |
| 点路径只认对象键与数组下标 | 取数那一头的筛行(明细[名称=甲].金额)与聚合(.sum(金额))写法,MySQL 的 JSON 路径点不动,认不了就整档不认(_form_json_path) |
| 字典与外部数据源照旧一个链接都不给 | 那两条没有「本平台的一张单」可开。要跳去对方系统得另配一列落点模板,那是另一件事 |
组件定位那一头本来就没差别:「关联审批单」(relation) 与「下拉选择」(picker,来源=流程单据)
共用同一只 OptionPicker,链接挂在候选行上(只有 rowOfProcess 填 href),所以两种定位一起好,
不存在「只有某一种组件点得开」。明细里那一列同理——列定义与主表格子走的是同一套 optionMap 口径。
钉在这儿的行为:FormFieldControl.relation.spec.ts(默认存 job / 存单号 / 存 data.某列 三种配法
都念回标题、链接都落回那个真 job,报出去的 by + process 一字钉死;字典与外部数据源不给链接)、
OptionPicker.spec.ts 与 MobileFormReader.spec.ts 里那几句 workSummaries 的入参、后端
PYTHONPATH=. python3 scripts/check_relation_scope.py「回显认哪几个名字」那一节(含
_form_json_path 认不了筛行与聚合写法、那个 serial 索引在模型与 sql/schema.sql 两份里都在)。