unis-oa/docs/option-source-routing-desig...

39 KiB
Raw Permalink Blame History

同一格挂好几套候选来源:按这张单上的值换一家(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. 为什么以前一格只能配一个来源

不是漏了一颗复选框,是那套设计的前提就是一格一答。三件事叠在一起:

  1. 「候选从哪儿来」被做成一维一答。 optionSource 是一个枚举, effective_options(field, data, cache) 的签名里没有「此刻」这一维——它只读字段上那一份配置, 算出「这一格能点什么」。要支持多套,就得先回答「同一时刻这一格按哪一套说话」。
  2. 「存的是哪一列」跟着来源走。 optionMap 的合法列名按来源给(字典给 value / extra.*, 流程单据给 job / serial / title),判越界、字典带出、标题与导出翻译、条件分支的候选值全都 读同一份 stored_of / shown_of。一格两答,「这一格存的是编码还是物料号」当场没有定义。
  3. 越界与失效值只有一条判据。 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)三种带出都排在提交校验之前。 拿本地清单去判对面给的那个值并不讲理,而症状最难看:「明明带回来了,格子却是空的」。

给一颗字段级开关,勾上之后:

  1. 页面不清这一格的值(dropStaleSelections 跳过它);
  2. 提交不判越界(selection_problems 跳过它);
  3. 界面上给那个值补一行候选(标签就是值本身,不额外加标记)——不补就是一行空白,人不知道值还在。 这一行只用于显示,人选它和不改它存的是同一个值,不新增任何能选的东西。

三句设计期的话(两边同一句措辞):

  • 值由带出写入、候选又来自手填 / 字典且没勾这一档 → 说交叉规则,一次给三条解法: 把带回来的值补进清单、把候选来源改成外部数据源 / 流程单据,或勾上这一档;
  • 勾了这一档却什么都没带出 → 说「这一档暂时不起作用」,别让人以为勾上就万事大吉;
  • 这一档只认真布尔值,且只属于有候选来源的那几类字段(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. 在设计器里长在哪儿

配的人只需要记三件事,其余都是替他把字写进去:

  1. 「按哪一格换一家」:那一栏下面挑一个字段点「一家一档」,它有 N 个取值就铺出 N 条卡片, 触发条件(when)当场替写好,备注也替写成那一档的人话;
  2. 每家问谁:卡片里逐条挑各家的字典 / 数据源——这是唯一只有配的人才知道的信息;
  3. 带出去哪儿:外部数据源那几家,在第一家的卡片里配好「这一家的带出」,点 「把这一家的带出套给其余几家」(各家问的还是各家那一家);字典那几家,点卡片上那颗 「这一家的带出去『字典带出』里配」,门替他打开、那一块描一圈,带出只配一份。

生产上「出差备案申请」那四家(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 带回来的值两边同一个, 行政 / 定制 两家两边都不落值——比对四家全「一致」。

收拢躲不掉的几件事,脚本都会当场说出来,别等填单的人发现:

  1. 必填与只读只剩一份:跟着当基准的那一家走。这张单上「最终客户名称」原来只有 PMS 必填, 收拢后四家都必填;「项目名称」原来行政 / 定制是只读取数格,收拢后跟着 PMS 变成可挑的候选格。
  2. 环节权限要重挂:那 16 条挂在消失了的字段名上,--perms 会把它们折到 4 格上 (认得出旧名字的搬走,认不出的报出来),其余环节没列上的格子按字段自己的配置走。
  3. 导出列、报表、对外回写读的都是字段名:16 个名字变 4 个,那几头得一起对一遍。 在途的老单不受影响——发起那一刻设计就冻在 oa_process_snapshot 里了。
  4. 换一家不会把上一家带出来的值擦掉:apply_auto_fill 只在挑中那一刻写, 命中的那一本没有那一列就一个字都不动。所以 VDI 换成 PMS 之后,客户与阶段还留着 VDI 那份。 最干净的解法还是 §8 那句:把那几家都变成从数据源同步的字典、各家都带上那几列附加值, 这样每一家都把这三格重写一遍,谁都不留残值。
  5. 顺手发现的一个真问题:xz_code / Code_dz 那两条 SQL 比的是 :project_type = '行政综合X项目' (字典的名称),而表单存的是编码 XZZH / DZKFXM,所以这两家的名称与编码在生产上一直是空的; 今天这张单和收拢后一样空,收拢本身没有让它变坏。要么把 SQL 改成比编码,要么回到第 4 点那本字典。