39 KiB
同一格挂好几套候选来源:按这张单上的值换一家(optionRoutes)
相关:option-source-design.md(一格的候选从哪儿来、显示与存值、 挑选方式那三维;这一篇是第四维「同一格换一家」), data-binding-unification-design.md(候选来源与「字段上的 外部取数」为什么是两格、共用的是哪一层内核;这一篇给那两层各补一句「什么时候才用」), field-self-visibility-design.md(显示条件、回看那一屏、 藏起来的必填格),form-field-catalog.md(字段属性清单)。
用户那句原话:「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段 来判断我该组件中该用什么数据源?」 这一篇讲四件事:为什么以前一格只能有一个来源、 现在这一格按什么顺序决定问谁要候选、命中那一家怎么把它那几列带进别的格子(§5), 以及顺手补上的两头——带回来的值不在这格候选里也能收下、配了显示条件之后回看那一屏与必填不再打架。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 需求 | 同一格候选能配好几套(多张外部数据源 / 多本数据字典 / 手填那几条混着来),按这张单上某个字段的值决定用哪一套 |
| 以前 | 一格一答:optionSource 只能是一个值。要换家只有两条路——摆三格再拿显示条件把另外两格藏起来(三格 = 三个字段名 = 三份导出列 + 三套环节权限),或者去对面求一个聚合接口 |
| 现在 | 字段上多挂一份有序清单 field.optionRoutes:每一条 = 一个触发条件(when)+ 一套候选来源配置。自上而下第一条成立的用它;一条都不成立回落到字段自己那一份——也就是改动前的行为 |
| 条件用什么写 | 就是联动那一份结构化条件({match, rules},与 visibleWhen 同一口径、同一个 conditionOk),设计器里拼得出来,前端算得出来,提交时后端再算一遍 |
| 上限 | 一格最多 8 条(MAX_OPTION_ROUTES,两边同一个数)。再多就不是「换一家」而是该做聚合接口了,而且清单越长越没人说得清哪一条会赢 |
| 脏条目 | 当没配:认不出的来源、配到一半的空条目、第 9 条起多出来的都丢掉。宁可回落,也不要让填单的人对着一只永远为空的挑选器 |
| 外部取数那一头 | 同一分寸:fetch.sources[].when(单源老写法也能挂)。设计期检查看全量清单,运行时只跑成立的那几条;一条都不成立=这一格这回不取数,不是失败,值留在原来那一份上 |
| 那一家的带出往哪儿写 | 外部数据源那一条自带一份 fill(源 / 入参 / 带出去向),运行时摊成一条取数条目跑同一个执行器,只多一个 fillOnly:只写带出去向,不盖这一格刚挑中的那一个值;没自带照旧回落字段那份 fetch。字典那一条走 autoFill,读的是命中那一本的附加值,命中不是字典那一条时一个字都不带(见 §5) |
| 带回来的值不在候选里 | 新增字段级开关 field.allowOutsideValue(默认关=老行为)。勾上之后:页面不清值、提交不判越界、界面上给那一行补一条候选让它站得住 |
| 回看那一屏 | 改成「按存过的那份值评条件」:条件成立摊开;条件不成立且这一格空着收掉;有值一律摊开。「提交流程之后所有字段都显示了」收掉的正是空着、又不适用这一单的那一行 |
| 必填不再死锁 | 因显示条件不成立被收走的系统带出格(auto / formula 勾了必填)不再算必填;勾了「默认隐藏」又没配条件的照旧仍然要有值 |
| 老表单 | 一个字节都不用改:没挂清单的格子走的还是原来那一条路,allowOutsideValue 默认关 |
| 新接口 | 没有。候选还是走现成的 POST /process/dicts/values / GET /data-source/options / GET /work/related,只是问哪一家由这一单的取值决定 |
| 真收过的一张单 | 生产上「出差备案申请」27 格里 16 格是四家同构字段,收成 4 格,逐家比对过,见 §12 |
| 唯一口径在哪 | 前端 src/utils/optionSource.ts(optionRoutesOf / matchedOptionRoute / optionFieldView / optionRouteProblems)+ src/utils/formFetch.ts(activeFetchEntries);后端 backend/app/service/dicts.py(routes_of / matched_route / option_view / route_problems)+ backend/app/service/binding.py(entry_active / active_entries) |
| 验收 | PYTHONPATH=. python3 scripts/check_option_routes.py(不碰库)+ 前端那五份 spec,见 §11 |
1. 为什么以前一格只能配一个来源
不是漏了一颗复选框,是那套设计的前提就是一格一答。三件事叠在一起:
- 「候选从哪儿来」被做成一维一答。
optionSource是一个枚举,effective_options(field, data, cache)的签名里没有「此刻」这一维——它只读字段上那一份配置, 算出「这一格能点什么」。要支持多套,就得先回答「同一时刻这一格按哪一套说话」。 - 「存的是哪一列」跟着来源走。
optionMap的合法列名按来源给(字典给value/extra.*, 流程单据给job/serial/title),判越界、字典带出、标题与导出翻译、条件分支的候选值全都 读同一份stored_of/shown_of。一格两答,「这一格存的是编码还是物料号」当场没有定义。 - 越界与失效值只有一条判据。
constrains_values决定「值必须在候选里」还是「对面说了算」: 手填 / 字典判越界,流程单据与外部数据源不判。两个来源同时在场,这句话就一会儿真一会儿假。
于是历史上换一家只有两条路,代价都实测过:
- 摆三格 + 显示条件:三个字段名 → 三份导出列、三套环节权限、三处必填与阈值, 办结之后「报销科目」这个概念在数据里裂成三列,报表要 UNION 回来;
- 对面做一个聚合接口:OA 这边一个字不用改,但排期在对面,而且聚合接口只有一套候选列, 「这一家想按物料编码存、那一家想按主键存」配不出来。
这一层给的是第三条路:顺序 + 回落。同一时刻仍然只有一套候选在场,上面那三条前提一条都不破。
2. 语义:有序清单,第一条成立的说话,全不成立回落
{
"key": "expenseItem",
"type": "select",
"optionSource": "dict",
"dictCode": "acct_common",
"optionRoutes": [
{ "source": "dict", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] },
"dictCode": "acct_travel" },
{ "source": "dataSource", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "meet" }] },
"dataSourceCode": "erp_meet", "dataSourceArgs": { "dept": "{form:dept}" },
"optionMap": { "valueKey": "extra.code", "labelKey": "label" },
"note": "招待这一头问 ERP 要费用科目" }
]
}
四条规矩,两边一字不差:
- 有序:自上而下第一条
when成立的用它。when缺省=恒成立,所以它天生是「其余情况」 那一档——放最前会压死后面所有条,设计器把这一条的按钮下面直接写成 「无条件(其余情况都用这一条,请放最后)」。 - 回落:一条都不成立就用字段自己那一份(
optionSource/dictCode/options/ …)。 回落这一句是整个特性的地基:老表单没挂清单,走的正是这条路。 - 只动来源那一维:命中之后摊出来的是一张视图(
option_view/optionFieldView), 只换optionSource与那一种来源自己那几格(外带那一条的optionMap)。挑选方式(pickerStyle)、 能不能选好几个(multiple)、关联带出(linkFill)、额度、阈值、显示条件这些与来源无关的格子 原样留着——「这一格怎么用人」和「候选从哪儿来」仍然是两件事。 - 脏条目当没配:
routes_of只留这一类型挑得了的来源、只留属于它那一种的那几格; 非数组、空条目、第 9 条起一律丢。丢完没剩就把optionRoutes这个键整个抹掉, 别留一份空清单让下一任以为配过什么。
这一层不新增任何一条候选口径。它只把「字段」换成「此刻那一份视图」,再喂给
source_kind_of / effective_options / stored_of / constrains_values 这些既有函数——
「命中哪一条」算错的可能性只有一处,不会多出一套「路由自己的候选算法」。
3. 两条链路必须算出同一个结果
界面按 A 家的候选渲染、提交按 B 家判越界,是这一整套最容易犯的错,所以每一处都改成先取视图:
| 这一格此刻要问谁 | 前端 | 后端 |
|---|---|---|
| 渲染哪一只控件、候选清单 | FormRenderer.routedField() → optionsOf → effectiveOptions |
dicts.effective_options(field, data, cache) |
| 级联上级筛候选 | formLinkage.effectiveOptions |
同上(cascadeFrom 也来自那一条) |
| 判越界(提交那一刻) | formLinkage.dropStaleSelections |
formruntime.selection_problems → _has_option_rule(field, data) |
| 要不要把关(手填/字典 vs 搜出来的) | optionSource.constrainsValues(field, data) |
dicts.constrains_values(field, data) |
| 字典带出取哪一本的附加值 | formLinkage.applyAutoFill(逐字段先摊视图) |
dicts.apply_auto_fill(逐字段先取视图) |
| 只读、标题、导出翻名字 | 候选清单自己念 | dicts.option_labels(field, value, cache, sep, data) |
| 手机「完整单据」那一屏(关联单据念标题) | MobileFormReader.routedField() |
—— |
| 上游变了要重算哪几格 | formLinkage.conditionDependencies(含路由 when 与路由 cascadeFrom) |
dicts.condition_dependencies |
| 一趟预取哪几本字典 | FormRenderer.dictCodes() |
dicts.codes_of / _field_dict_codes |
| 删字典前「哪些表单在用」 | —— | dicts.used_by_forms(只挂在路由里的字典也算在用) |
| 删数据源前「哪些表单在用」 | —— | fetch.used_by_forms(扫路由里的 dataSourceCode) |
| 设计期逐条体检 | optionSource.optionSourceProblems(含 ctx.rows 判源健康) |
formruntime.option_source_problems → 逐条 _source_config_problems(route_view(...)) |
设计器保存那一刻还有一步清洗(api/design.py:clean_option_source):每条只留属于它那一种来源的
那几格、relationStatuses 全勾不留、认不出的 optionMap 列退回默认、备注留着(只给配表单的人看),
一条有效都不剩就把整个键抹掉。主表字段与明细列走同一句。
翻名字那三条路(只读渲染、单据标题、导出)以前只吃字段自己那一份配置,现在统一带上这一单的值:
exportfmt.cell_text(..., data=)、titles._field_text(..., data=)、api/export.py、
detail_export.py 四处调用都传了 data;明细表里那一列按同一行里别的列命中,与桌面
routedField(column, row) 同一个口径。check_option_routes.py 第 10 段把这四处的 data=
钉在源码里——谁把它摘掉,那一段当场变红。
4. 外部取数那一头:条目上的「什么时候调这一条」
同一句话在「取一个值」那一头也缺:fetch.sources 那份多源清单是每一次都全跑,
「费用类型 = 差旅才问差标接口」配不出来,只能为每种组合各建一条源。补的是同一个形状:
{ "fetch": { "sources": [
{ "source": "travel_api", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] } },
{ "source": "erp_balance" }
] } }
两头分工,这一寸不能含糊:
- 设计期检查看全量(
binding.entries):那张源还在不在、入参引用掉没掉在地上、 条件点名的字段还在不在——都跟此刻的取值无关; - 运行时只跑成立的(
binding.active_entries↔formFetch.activeFetchEntries): 条件判定用的就是联动那一份conditionOk/condition_ok,不会界面上调了、提交时后端没调。
空命中的语义是「这一格这回不取数」,不是失败:一条都不成立时不走「取不到怎么兜」那一档、 留痕里不记失败、值留在原来那一份上。这与「配了源但源停了」是两件事——后者该拦人、该记失败。
5. 带出挂在「那一条候选」上(optionRoutes[].fill)
用户的第二句追问:「一个组件中为什么不能配置多个外部数据源、数据字典等等,我配置了多个 该如何设置带出的值填入对应的字段呢?」 换一家的意思从来不只是换一份候选清单,而是 换一整套答案——挑的是 ERP 那家供应商,开户行和信用额度就得回 ERP 查。
§4 那条路(fetch.sources[].when)配得出这个结果,但要抄两遍:候选那一格写「费用类型 = 差旅
问 ERP」,取数那一条再写一遍「费用类型 = 差旅问 ERP 开户行」。两处判据一旦漂开,症状是最难查
的那种——候选换了家、带出还是上一家的:界面上一切正常,带回来的值来自另一套主数据。
所以这一层把带出挂到那一条路由自己身上:
{ "optionSource": "dataSource", "dataSourceCode": "crm_vendors",
"optionRoutes": [{
"source": "dataSource", "when": { "rules": [{ "field": "expenseType", "op": "eq", "value": "travel" }] },
"dataSourceCode": "erp_vendors", "dataSourceArgs": { "dept": "{form.dept}" },
// 这一家自己的带出:问哪一家 / 带什么入参 / 哪几个键写进哪几格
"fill": { "source": "erp_bank", "args": { "code": "{form.vendor}" },
"picks": { "bank": "bankName", "limit": "creditLimit" } }
}] }
运行时它被摊成一条普通的取数条目丢给同一个执行器(同一个入参写法、同一份留痕、同一条
「带出去向那一格还在不在」的闸),只多记一个 fillOnly 记号。对面是前端
utils/formFetch.fetchConfigOf ↔ 后端 service/fetch.config_of,两边必须算出同一份,
否则就成了「界面上按 A 家带出、提交时按 B 家覆盖」。口径逐条:
- 只写带出去向:
fillOnly那一份不往这一格写值——这一格那一个值是人在候选里挑的, 取回来的数盖不得;picks里指着自己那一行的老配置也不写(fetch._run_entries(own_key=)↔formFetch.fetchPickWrites(hits, live, selfKey)),设计期还会单独说一句「不能把值带进自己」; - 命中那条自带就只跑它那一份:字段上那份
fetch这一回不再跑,同一格不被盖两次; - 回落不破:一条都不成立、或命中的那条没自带带出,读的就是字段上那份
fetch(= 改动前行为,老表单一个字节不改); - 源默认跟着这一条:
fill.source留空 = 就问这一条候选那一家;另填一家才另问 (「候选问 A 家的清单、那几列在 B 家」是真有的配法,不值得为它再摆一条候选路由); - 入参默认跟着这一条:
fill.args留空 = 沿用这一条筛候选那一份dataSourceArgs。 为什么还要单独一栏:候选的入参不许引用这一格自己(拿这一格筛这一格是个死圈), 而带出恰恰常常要{form.这一格}——「按刚选中的这一行去问另外几列」; - 失败策略 / 发起后冻结 / 多久算旧 / 分隔符四档一律沿用字段那份
fetch: 它们问的是「这一格怎么待人」,跟从哪家取数无关;合并方式(merge)不参与, 这一份本来就不往这一格写值; - 留痕照记:记在这一格名下(
data._fetch.<字段名>),形状与非路由带出一模一样, 事后看得出这一笔是哪家答的、有没有部分失败; - 设计期逐条体检:门牌写「第 N 条候选来源的带出」,走的是外部取数那同一套判据
(
binding.entry_problems)——源在不在、是不是取值型、带出的键在不在源声明的可带出键里、 入参引用掉没掉在地上、带出去向那一格还在不在,另加一句「不能把值带进自己」。
为什么 linkFill / autoFill 不跟着挂一层:字典带出读的就是此刻命中那一条的字典,
关联单据带出读的是实际挂上的那张单——那两条本来就跟着各自的对象走,再各配一份 fill
只会让人以为有两处要配。
5.1 字典躺在路由里时,那一头的带出走 autoFill
「一家外部数据源 + 一家数据字典」是生产上最常见的一对,而字典那一头的带出以前配不出来:
「联动」面板里那一栏 v-if="field.dictCode",只认字段上那本字典,字典只挂在路由里时整栏不出现;
就算从接口直传写了 autoFill,保存那一刻还会被当上一家的残骸清掉(clean_option_source 只认
字段自己声明的那一种来源);界面带出读的也是字段上那本 dictCode。三处叠在一起的症状是
界面带 A 本的附加值、提交带 B 本的,以及「怎么配都带不出来」。
四处一起改,口径只有三条:
- 带出跟着命中的那一条:
formLinkage.applyAutoFill与dicts.apply_auto_fill都先摊视图再读dictCode,命中哪一本就带那一本的附加值;命中的那一条不是字典(外部数据源那一家)时 一个字都不带——那一条要往别的格子上写东西走它自己的fill。少了这道闸,「没有字典就把这一格 自己的值搬过去」那一条兜底会把人刚挑中的编码盖到「名称」那一格上(对面前端 items 为空,本来 也什么都不写); - 不再当残骸:字段自己声明的不是字典、但候选路由里挂着字典(
dicts.dict_route_codes↔optionSource.dictRouteCodesOf)时,autoFill是那一档唯一的配法,保存那一刻留着它; 两处都没字典才洗掉,并且设计期说一句「配了字典带出,可这一格没挂数据字典(字段上与候选来源 那几条里都没有),这一档不起作用」——不让人以为勾上就万事大吉; - 那一栏跟着这几本字典出现:
LinkagePanel用的是「字段上那本 + 路由里那几本」的并集, 「能带哪些列」也把这几本的附加值列一起列出来(命中哪本取哪本,但一栏里得看全)。
附加值列名两本不一样时不用改配置:带出去向写「取哪一列」,命中的那一本没有那一列就不写, 不会因为换了家就凭空冒出一个值。
6. 带回来的值不在候选里也收下(allowOutsideValue)
下拉框的候选以前是硬边界:值不在清单里,页面 dropStaleSelections 把它清成空、
提交 selection_problems 判「取值已不在可选范围内」。可这一格的答案常常本来就是系统写的:
外部取数(fetch)、关联单据带出(linkFill)、字典带出(autoFill)三种带出都排在提交校验之前。
拿本地清单去判对面给的那个值并不讲理,而症状最难看:「明明带回来了,格子却是空的」。
给一颗字段级开关,勾上之后:
- 页面不清这一格的值(
dropStaleSelections跳过它); - 提交不判越界(
selection_problems跳过它); - 界面上给那个值补一行候选(标签就是值本身,不额外加标记)——不补就是一行空白,人不知道值还在。 这一行只用于显示,人选它和不改它存的是同一个值,不新增任何能选的东西。
三句设计期的话(两边同一句措辞):
- 值由带出写入、候选又来自手填 / 字典且没勾这一档 → 说交叉规则,一次给三条解法: 把带回来的值补进清单、把候选来源改成外部数据源 / 流程单据,或勾上这一档;
- 勾了这一档却什么都没带出 → 说「这一档暂时不起作用」,别让人以为勾上就万事大吉;
- 这一档只认真布尔值,且只属于有候选来源的那几类字段(
clean_option_source收残骸)。
那两句共同依赖一句判据:这一格的值是不是系统写进来的(formruntime.filled_by_label ↔
optionSource.filledByLabel)。它判的是有没有一条带出的落点在这一格上,不是「这一格有没有配
带出」——autoFill 与 linkFill 都配在发起那一格身上、写进的是别的格子,光看有没有配会把人挑的
那一格说成是系统写的(生产上「项目名称」配了字典带出,反被提醒「这一格的值由字典带出写入」);
fetch 同理,只有条目自带的 pick(取一个值写进这一格)或 picks 点到这一格才算,候选路由那一条
自带的 fill 是 fillOnly、永远不写自己。落点也可能在隔壁那一格身上:给了同表字段清单
(rows / ctx.peers)时,别的字段的 autoFill[].to、linkFill.rules[].to、取数 picks 与路由
fill 指着这一格,一样算「这一格由系统写」——否则一张靠隔壁带出喂值的下拉会被说成「这一档暂时不
起作用」,人把勾去掉,提交那一刻又被判越界,两头各骗一次。明细列那种 表.列 的写法不算指着主表
这一格。
默认关。它只影响「带回来的值」,不放开给人乱填:这一格由人输入时,控件仍然只能从候选里挑。
7. 顺手修的两头:回看那一屏与必填
同一批反馈里的第三条:「配了显示条件,提交流程之后回看页所有字段都显示;改成默认隐藏 + 显示条件, 表单校验又过不去。」两句是同一处判据的两端。
- 回看那一屏(
formRuntime.readbackHidden,只读渲染:单据详情 / 打印 / 手机完整单据): 环节明写 hidden → 收;环节给了其它权限 → 摊(那一环特意要看见它);勾了「默认隐藏」→ 按存过的那份值评条件;没勾默认隐藏但配了显示条件、按存过值评不成立、且这一格为空 → 收。 有值一律摊开——条件翻走了不代表那一笔没填过,收起来才是让存过的东西凭空消失。 - 必填不再死锁(
formruntime.hidden_by_condition↔formRuntime.hiddenByCondition):auto/formula这两类没有录入框、权限永远算只读,字段自己勾了必填说的是「必须算得出值」。 老判据连因显示条件不成立被收走的格子一起催「还没填写」——屏幕上没有那一格,提交永远过不去。 现在这一格不算这一笔;勾了「默认隐藏」又没配条件的(单据编号、金额大写)照旧仍然要有值。
保留的那一寸要说明白:有值但条件已翻走的格子,回看页仍然摊开。这是刻意的(少一行比多一行 难发现,而那一笔值确实存过)。真要按存过值全收干净,得再给一颗字段级开关,别默认改。
8. 在设计器里长在哪儿
配的人只需要记三件事,其余都是替他把字写进去:
- 「按哪一格换一家」:那一栏下面挑一个字段点「一家一档」,它有 N 个取值就铺出 N 条卡片,
触发条件(
when)当场替写好,备注也替写成那一档的人话; - 每家问谁:卡片里逐条挑各家的字典 / 数据源——这是唯一只有配的人才知道的信息;
- 带出去哪儿:外部数据源那几家,在第一家的卡片里配好「这一家的带出」,点 「把这一家的带出套给其余几家」(各家问的还是各家那一家);字典那几家,点卡片上那颗 「这一家的带出去『字典带出』里配」,门替他打开、那一块描一圈,带出只配一份。
生产上「出差备案申请」那四家(PMS / VDI 已经是字典,行政 / 定制 现在靠取数写名称)收拢成
一格时按这三步走,不必再摆八格拿显示条件轮流露面。最省事的走法是把那四家都变成字典:
行政 / 定制 那两张列表型数据源各存成一本「从数据源同步」的字典(DictType.source = data_source,
见 dict 那一头的说明),四家就都是卡片里的一条 dict,带出只配一份
「字典带出」,fetch.sources[].when 与 allowOutsideValue 都不用上。留着取数那一头也行
(就是 §4 那份条目条件),只是配的地方从一处变两处。
- 属性侧栏「候选来源」那一栏下面多一栏「同一格换一家候选」
(
components/oa/design/OptionRoutesEditor.vue):一条一张卡片,左边那颗按钮是触发条件 (点开的弹窗与「满足条件才显示」是同一只LinkageConditionDialog,能引用同表其它字段与本字段), 右边是上移 / 下移 / 删除;卡片里挑来源,来源下面就地配它自己的那几格(手填的选项 / 哪本字典带级联 / 哪个流程带状态档 / 哪张列表型数据源带入参),再加一条「显示为 / 存为」和一句备注。 「再加一家候选」的起点跟着上面那套固定来源走,配的人少挑一次;配满 8 条时那句提示替掉那颗按钮。 - 那一张卡片挑的是外部数据源时,下面再多出一栏「这一家的带出」(同一只
SourceBindingEditor, 带「带出去向」那一头):默认就问上面那一家、默认沿用上面筛候选那一份入参,都能就地改; 能挑的源只有取值型那几家,能写进去的格子里没有这一格自己。三张表都空 = 这一条只给候选, 写回时整块不留(pickFill还顺手做两处去重:与上面同一家不存source、入参与上面一模一样不存args)。 - 同一栏底部一颗复选框「带出的值不在候选里也收下」(
allowOutsideValue)。 - 「联动」面板里的「字典带出」那一栏不再只认字段上那本字典:候选路由里挂着字典的格子也出现,
可选的附加值列是那几本的并集(
LinkagePanel.vue,见 §5.1)。 - 「外部取数」面板里每一条源多一个按钮「什么时候调这一条」,配完在那一行摘要成人话,
旁边一颗 × 一句话摘掉(
components/oa/design/FetchPanel.vue)。 - 「并成一格」管的是来路那一头:多选上那几格「同一个字段的几家」(每一格都只挂一条
「某字段等于某一个值」的显示条件、指的是同一个字段、取值互不重复),属性栏就多出一颗按钮,
一次把那 16 格收成 4 格(
utils/formMerge.ts写配置,FormDesignerView.vue:mergeSelection只动画布)。判据一条没新增,存的还是optionRoutes[].when/fetch.sources[].when/autoFill/fetch.picks那几份本来就要存的东西。三条分寸写死在代码里: 留哪一格——内容最多的那一格(有字典的优先,只读取数格垫底),名字与标题都用它的, 因为导出列、报表、对外回写读的都是字段名,留一个比换一个新名字少坏一片;想换个中性名字, 并完再在属性面板改字段名,utils/formRename会把指着它的带出一起搬走。 先搬落点再删格子——fetch.picks与autoFill[].to记的都是别的格子的名字, 趁那几格还在表上搬才不会漏,漏一处就是「候选换了家、带出还写着上一个名字」;搬完顺手 去掉因此重复的那条带出,删完格子再走一遍formPrune清掉没有归宿的。 带回来的值要收得下——往别的格子写值的那几处落点也改了名字,那些格子自己有候选时, 当场替它们勾上「带出的值不在候选里也收下」,否则要等保存那一刻才被门牌拦住。 点完弹一句实话:清单里几家、取数条目几条、跟着搬的带出几处、删掉几格,外加「哪几家的 必填 / 只读跟着留下来的那一格变了」——并格躲不掉的就是这一句,不满意用工具栏那颗撤销。 - 「一家一档」与「套给其余几家」是写配置的便利,不是新的一层判据:它们写出来的就是
optionRoutes[].when与optionRoutes[].fill那几份本来就要存的东西,运行时一个字没改 (OptionRoutesEditor.vue的splitByField/copyFill,与手工改走同一句fillForRoute, 两边不会写歪成两份)。一家一档只认「当下数得出取值」的那几格(手填那几条、或一本数据字典), 取值比 8 家还多的那一格直接说「该在对面做一个聚合接口」,不硬铺。 - 卡片上那颗跳转把「字典那一家的带出在另一栏里配」这一寸藏处消掉:
OptionRoutesEditor→OptionSourcePanel→FieldInspector(开「联动」那扇门 + 计数) →LinkagePanel(描一圈那块,revealAutoFill)。 - 「挂了这一份清单」= 这一格有候选来源:保存那道「选项类字段未配置任何选项」的闸两边都改口
(
api/design.py的form_problems↔utils/formLayout.ts的validateFields)。收拢出来的 那一格常常故意把自己那一份留空——「先选项目分类,再问那一家要候选」,分类没选的那一刻 本来就没得挑;什么都没配的照旧要拦,老规矩没被一起放宽。 - 设计期检查一栏都不少:清单本身、那一条的来源配没配到底、那一张源停没停用、 候选入参引用掉没掉在地上,报错门牌写成「第 N 条候选来源:……」,不与字段自己那一份串门牌。
9. 老表单与迁移
一个字节都不用动:
- 没挂清单 →
routes_of回空,option_view原样返回字段本身; - 没写
allowOutsideValue→ 关,越界与清值行为与今天一字不差; - 外部取数条目上没有
when→ 恒成立,active_entries与entries给同一份清单; - 那一条候选没写
fill→ 这一格带的还是字段上那份fetch,与挂路由之前一字不差; - 清洗只在保存那一刻做,且不替历史做主:只动明写过这些键的字段。
10. 已知边界
- 路由不参与「这一格能不能配这个来源」的收窄:
sourceKindsOf那一份清单是唯一口径, 这一类型挑不了的那一条直接当没配(不是报错到保存不下来),设计期那一句只说一次; - 级联上级只属于字典那一条:换到别的来源时上一家的
cascadeFrom不进视图, 路由里那一条自己带的那一份才算; - 字典带出(
autoFill)仍然是字段级的:读法跟着命中那一条的字典走(§5.1),但配的地方 只有一处。两本字典的附加值列名不一样时,用那一条自己的optionMap,或把带出配在值域较宽的那一头 上——命中那一本没有那一列就不写; - 带出只有「外部数据源」那一条说得上:字典那一家走
autoFill、流程单据那一家走linkFill, 两条都读此刻命中的那一个对象;换来源时这份fill当残骸清掉(optionRoutePatch↔clean_routes); - 失败策略与冻结那四档没有「按条」一说:它们问的是这一格怎么待人,永远沿用字段那份
fetch。 真要「差旅那家取不到就挡提交、其余放过」,那种需求该在对面把两家合成一个接口; - 带出不参与这一格自己的值:
fillOnly那份不写这一格,merge因此也无从谈起; 想让取回来的值就落在这一格上(人不挑、系统直接写),那是字段级fetch的活,别挂到路由上; - 8 条封顶:超过就是「换一家」变成了「做聚合」,那种需求该在对面做一个接口;
- 手填且不带条件的候选本来就不判越界(后端
_has_option_rule只认会随别的字段变的那三类候选), 所以allowOutsideValue真正救的是字典那一头——页面清值那一步两边都管。
11. 验收清单
后端(不碰库,cd backend && PYTHONPATH=.):
python3 scripts/check_option_routes.py # 命中与回落、视图、清洗、把关与带出、上游、必填、条目条件、前后端常量与措辞
python3 scripts/check_option_route_fill.py # 那一家的带出:合成、只写带出去向、回落、失败策略、设计期、清洗、前后端对齐
python3 scripts/check_binding.py # 取数内核与候选来源那一份,含交叉规则那一句
python3 scripts/check_self_visible.py # 显示条件那一份判据
python3 scripts/check_hidden_field_rules.py
前端(cd frontend):
npx vitest run src/utils/optionSource.routes.spec.ts src/utils/formFetch.when.spec.ts src/components/oa/FormRenderer.optionRoutes.spec.ts src/components/oa/design/OptionRoutesEditor.spec.ts src/components/oa/design/FetchPanel.when.spec.ts
# §5 那一份
npx vitest run src/utils/optionSource.fill.spec.ts src/utils/formFetch.routeFill.spec.ts src/components/oa/design/OptionRoutesEditor.fill.spec.ts
# §5.1 那一份(字典躺在路由里时的带出)
npx vitest run src/utils/formLinkage.fill.spec.ts src/utils/optionSource.routes.spec.ts src/components/oa/design/LinkagePanel.routedFill.spec.ts
# §12 那一份(挂了清单就不必再自己抄一份选项;多选那几格并成一格)
npx vitest run src/utils/formLayout.routed-options.spec.ts src/utils/formMerge.spec.ts src/components/oa/design/FieldInspector.merge.spec.ts
12. 一张真实表单:出差备案申请 16 格收成 4 格
生产上那张「出差备案申请」(FormElement 927e88ea…,27 格)是这一层功能存在的理由本身。
四种项目分类各摆一行同构字段,配的是同一件事:
| 干的那件事 | PMS | VDI | 行政 | 定制 |
|---|---|---|---|---|
| 项目名称 | project_pms(字典 pms_project) |
project_scc(字典 SCC_Project) |
project_xz(只读取数 xz_code) |
project_dz(只读取数 Code_dz) |
| 项目编码 | project_code_pms |
project_code_SCC |
project_code_xz |
project_code_dz |
| 最终客户名称 | customer_name_pms |
customer_scc |
customer_xz |
customer_dz |
| 项目阶段 | project_stage_pms(字典 project_stage) |
project_stage_scc |
project_stage_xz |
project_stage_dz |
16 格各自挂一条「project_type 等于哪一个分类」的显示条件互相藏起来,代价是三个字段名家族、
三份导出列、四套环节权限——开始 那一环的 formPerms 里已经堆了 11 条指向早就不存在的字段名
(project_dms、project_jd_*、customer_name_dms……)。
收拢后是 4 格,project_type 决定问哪一家:
// 项目名称(select,必填)——分类挑哪一家,就换成那一家的候选
"optionRoutes": [
{ "when": { "...": "project_type == PMS" }, "source": "dict", "dictCode": "pms_project", "optionMap": {"labelKey": "label", "valueKey": "label"} },
{ "when": { "...": "project_type == VDI" }, "source": "dict", "dictCode": "SCC_Project", "optionMap": {"labelKey": "label", "valueKey": "label"} }
],
// 行政 / 定制那两家问的是「取一个值」那种源,列不出候选 → 条目条件,落点都写收拢后那一个名字
"fetch": { "sources": [
{ "when": { "...": "project_type == XZZH" }, "source": "xz_code", "pick": "project", "picks": { "code": "project_code" } },
{ "when": { "...": "project_type == DZKFXM" }, "source": "Code_dz", "pick": "project", "picks": { "code": "project_code" } }
]},
// 字典那两家的带出仍旧只有一份:命中的那一本有那一列才写,没有就一个字都不动
"autoFill": [
{ "pick": "value", "to": "project_code" },
{ "pick": "extra.customerName", "to": "customer_name" },
{ "pick": "extra.stageName", "to": "project_stage" }
],
"allowOutsideValue": true // 行政 / 定制带回来的名称不在这格的候选里,得收得下
设计器里有两条路走到这一张单:手动照 §8 那三步配(一家一档 → 逐条挑各家 → 带出只配一份),
或者框选同构的那四格点「并成一格」(§8 倒数第二条,一次把条件、来源、带出与落点都搬好);
backend/scripts/collapse_trip_form.py 把这张单照表上真实的字段算了一遍并逐家比对,
默认一个字都不改:
cd backend
OA_ENV=prod PYTHONPATH=. python3 scripts/collapse_trip_form.py --json /tmp/new.json # 看对照与校验
OA_ENV=prod PYTHONPATH=. python3 scripts/collapse_trip_form.py --write --perms # 确认过再落库
它会打印四家各自的「收拢前 / 收拢后」对照(问哪一家、候选几条、带出写哪几格、写进来的值),
走的是运行时那同一套判据(option_view / effective_options / apply_auto_fill /
fetch.apply_form),落库前再按设计器保存那一条路检一遍。生产库上跑的结果:
PMS 247 条、VDI 2473 条候选一字不差,project_code 带回来的值两边同一个,
行政 / 定制 两家两边都不落值——比对四家全「一致」。
收拢躲不掉的几件事,脚本都会当场说出来,别等填单的人发现:
- 必填与只读只剩一份:跟着当基准的那一家走。这张单上「最终客户名称」原来只有 PMS 必填, 收拢后四家都必填;「项目名称」原来行政 / 定制是只读取数格,收拢后跟着 PMS 变成可挑的候选格。
- 环节权限要重挂:那 16 条挂在消失了的字段名上,
--perms会把它们折到 4 格上 (认得出旧名字的搬走,认不出的报出来),其余环节没列上的格子按字段自己的配置走。 - 导出列、报表、对外回写读的都是字段名:16 个名字变 4 个,那几头得一起对一遍。
在途的老单不受影响——发起那一刻设计就冻在
oa_process_snapshot里了。 - 换一家不会把上一家带出来的值擦掉:
apply_auto_fill只在挑中那一刻写, 命中的那一本没有那一列就一个字都不动。所以 VDI 换成 PMS 之后,客户与阶段还留着 VDI 那份。 最干净的解法还是 §8 那句:把那几家都变成从数据源同步的字典、各家都带上那几列附加值, 这样每一家都把这三格重写一遍,谁都不留残值。 - 顺手发现的一个真问题:
xz_code/Code_dz那两条 SQL 比的是:project_type = '行政综合X项目'(字典的名称),而表单存的是编码XZZH/DZKFXM,所以这两家的名称与编码在生产上一直是空的; 今天这张单和收拢后一样空,收拢本身没有让它变坏。要么把 SQL 改成比编码,要么回到第 4 点那本字典。