24 KiB
候选来源与外部取数:不合并那两格,合并它们底下的那一层
相关:option-source-design.md(候选来源 × 挑选方式)、 form-data-integration-design.md(五种取数形态)、 external-data-simplification.md(字典吃外部数据源)、 option-source-routing-design.md(这两层各自补上的那句 「什么时候才用」:候选来源那一头的
optionRoutes清单,与取数这一头的fetch.sources[].when。 共用同一份条件判据,也共用同一份「设计期看全量、运行时按条件筛」的分工)。这一篇回答一个被反复问到的问题:一个组件既有「候选来源」又有「外部取数」, 这两个不是一件事吗?能不能合成一个? 结论是先说清楚为什么不能合成一格, 再把它们真正重复的那一层收掉。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 是不是同一件事 | 不是。候选来源回答「这一格能选什么」(值域,人的动作是挑),外部取数回答「这一格的值是谁写进来的」(取值,人的动作是不用填) |
| 能不能合成一个 | 不能。合成之后「选中的值必须在候选里」这条把关就没有归属了:候选来自字典要判、来自 ERP 搜索不判,而取数写进来的值压根不是"选的"。这两条口径已经在 constrains_values / selection_problems 上分得很干净,合起来只会重新搅浑 |
| 一格能不能同时挂 | 能,而且是正事:候选来自 ERP 物料源、值由另一条取数从合同带出;或者关联审批单挂字典(候选=字典项)、再由取数按工号带出那本字典里的一个编码 |
| 真正重复的是什么 | 不是那两格,是它们底下的四样:入参写法解析、「源还在不在/类型对不对」的校验、多源合并、以及设计器里「挑源 + 填入参 + 挑带出去向」那个控件 |
| 重复到什么程度 | 写法解析后端 4 份、前端 5 份;源的健康校验 4 套各说各话;「挑源+入参+去向」的面板逻辑 3 份;「外部列表→候选」另有一条平行路(字典同步) |
| 怎么改 | 抽一层取数内核(service/binding.py + utils/binding.ts + SourceBindingEditor.vue),fetch / 候选来源 / 额度 / 阈值 / 流程带数据全部改吃它;字段上仍然是 optionSource 与 fetch 两个键,一个都不合并 |
| 顺带要补的洞 | 三处:选择类字段同时挂两者时提交才炸且没人提前说;候选来源指向的源不做存在性校验;候选来源那一路不能带参数 |
| 老表单 | 一个字都不改。内核是从现有代码里抽出来的,不是新写一套;存储形状不动 |
| 风险 | P1 那一步动的是六个消费方共用的解析与校验,验收靠"同一份输入两边结果逐字相同",不靠感觉 |
1. 先回答那个问题:为什么是两个东西
判别只看五件事,任何一条对不上就不是一件事:
| 判别 | 候选来源 optionSource |
外部取数 fetch |
|---|---|---|
| 谁在动作 | 人挑。界面给一批候选,点中一个(或几个) | 系统写。人不填,格子里显示的是「上一次取到的」 |
| 什么时候发生 | 填单过程中,随搜索发生 | 依赖格变化时预取(只为看得见的显示),提交时后端再取一次并覆盖 |
| 值的形状从哪来 | 候选项的 value(字典项编码 / 单据 job / 源给的编码) |
源返回的单个值(pick 那条路径),再按 merge 合成 |
| 服务端判不判越界 | 手填 / 字典判,流程单据 / 外部源不判(手上只有搜出来那一页) | 不判——值不是人选的,判它等于判上游 |
| 取不到怎么办 | 下拉是空的,人自己会看到;不拦提交 | 按字段配的 onError:keep / block / zero,可以挡提交 |
最后一行是分水岭:候选来源失败是体验问题,外部取数失败是业务风险(没有余额依据就别放这张单)。 一个会把填单页变成一个空下拉,一个会在提交链路里挡人——这两件事塞进同一格配置, 配的人就再也说不清「这一格取不到数的时候,我是想让人等,还是想挡住他」。
反过来,两样一起挂是真实需求,不是设计漏洞。仓库里现成的两例:
select+ 候选来源=dataSource(ERP 物料,按需搜)+ 外部取数(选了合同号,把合同里的默认物料编码写进这一格);relation+ 候选来源=dict(只允许挂"报销类"那几本字典口径,见 option-source-design §2)+ 外部取数带出上级单据的编号。
所以「合并」的正确方向不是把两格并成一格,而是让两格吃同一套底层件。
2. 直觉没错:重复的确在下面这五处
| # | 重复的东西 | 现在写了几份 | 位置 |
|---|---|---|---|
| 1 | {form.x} / {const:} / {auto:} / {work.x} 这套入参写法 |
后端 4 | quota.py:53-56 FORM_REF/AUTO_REF/WORK_REF/CONST_REF + resolve_text:111;fetch.py:203 render 自带一份 fullmatch 正则(:219)与 _raw_ref_value:229;mapping.py:29-35 另一套 token 解析;threshold.py:191 蹭 quota.FORM_REF,但 {auto:} 走自己那句 |
| 1 | 同上,前端镜像 | 前端 5 | formFetch.ts:18-19 与 resolveFetchExpr:53;formThreshold.ts:24;quotaConfig.ts:404;formWriteback.ts:421 附近;paramRows.ts:133 |
| 2 | 「引用的源在不在 / 停没停 / 类型对不对 / 方向是不是往外写 / 带出的键声明过没有」 | 4 套 | fetch.py:977 _entry_problems;dicts.py:252 remote_problem;processdata.py:138 validate + match_problems:155;quota_source.py:871 problems。四句"源不存在"的措辞、四道判据的取交集都不一样 |
| 3 | 多个源合成一个值 | 2 + 镜像 | fetch.py:839 merge_values(first/sum/min/max/join,按分算)与 quota_source.py:358 sum_hits(latest/sum)各一套;前端镜像在 formFetch.ts mergeFetchValues |
| 4 | 设计器里「挑源 → 列入参 → 每填入参 → 挑带出去向 → 报错提示」 | 3 份 | FetchPanel.vue(358 行,最完整)、OptionSourcePanel.vue 里数据源那一截 + 试搜一页、QuotaSourceEditor.vue / ProcessSourcePanel.vue 的对应段落 |
| 5 | 「外部列表 → 候选」有两条平行路 | 2 | 一条是字典绑源再同步(dicts.py:292 sync / ensure_fresh:393,全量、可级联、可带出、可翻名);一条是候选来源直连搜(data_sources.py:341 /data-source/options,新鲜、无级联、无翻名)。两条都吃同一张 oa_data_source,能力却不对等,见 §3.3 |
第 1 项是最值钱的那处:口径漂移在这个仓库里是被反复写进注释防的("与后端同口径""两边说法一模一样"), 每多一份解析就多一处"改一处漏两处"。第 5 项是最容易被误当成"该把两格合并"的那处—— 它确实像重复,但重复的是供给方式,不是候选来源与外部取数。
3. 现在会咬人的三处
3.1 选择类字段同时挂两者:填单页正常,提交才被拦
链路是:engine.py:448 fetch.apply_form 先按配置覆盖这一格的值,
engine.py:474 之后才 validate_submit →
formruntime.py:305 selection_problems 用候选清单判越界。
于是「select + 候选来源=字典 + 外部取数带回一个字典里没有的编码」=
提交时一句 「某某」的取值已不在可选范围内。这句话对填单的人是完全看不懂的:
那一格不是他填的,他也没得选。而设计器里两边各自校验得很干净(fetch.problems
不看候选、option_source_problems 不看 fetch),保存一路绿灯。
前端还有个加重项:FormRenderer.vue:1191
dropStaleSelections 只在 setValue(人手改)时跑,取数写入走的 applyWrites 不跑它——
界面上那个值好好地留着,提交才炸。
3.2 候选来源指向的数据源不做健康校验
formruntime.py:785 只判 dataSourceCode 非空。
源被删、被停用、配成了单值型(kind=fetch)、方向是往外写(direction=out),
全都存得下来,直到有人点开那个下拉看到空的——而同一句判据在
dicts.py:252 remote_problem 里已经写全了,抄一次就行。
3.3 候选来源那一路带不了参数,字典那一路也带不了
/data-source/options 把入参硬编成 {"keyword": keyword}
(data_sources.py:352),而 run() 里
_missing_args(fetch.py:527)会把请求体里引用了、
却没传的入参直接判 blocked。所以「只显示所选品类下的物料」这种筛选,
挂在候选来源上做不出来;字典那条路虽然有 source_args,同步时却是
fetch.render(db, source_args, {})(dicts.py:321)——
data 是空的,{form.x} 取不到东西。两条路都没有"按这张单的上下文筛候选"。
4. 目标设计:一层内核,两种角色
L1 源注册表 oa_data_source(provider=http/mock/process,kind=fetch/search)……… 不动
L2 取数内核 binding:写法解析 / entries 归一 / merge / 失败策略 / 引用与源校验
L3 两种角色 supply(供给候选:optionSource) derive(供给值:fetch、额度总额、阈值右值)
L4 落值把关 constrains_values / selection_problems / 提交时后端重算覆盖 / _fetch 留痕 … 不动
红线:L3 两种角色不合并,它们只是共用 L2。L4 那套"搜出来的不判越界"的口径原样保留。
4.1 后端:app/service/binding.py(新,从现有代码抽)
| 收进来的 | 从哪来 | 谁改成吃它 |
|---|---|---|
resolve(expr, data, work, actor) / resolve_args(args, data, …) / refs(expr) |
fetch.render + quota.resolve_text + threshold.resolve 三份合一 |
fetch / quota / quota_source / threshold / processdata / mapping |
entries(cfg)(单源老写法 → 多源清单,上限 8) |
fetch.field_sources:802 |
fetch / 候选来源 / 额度 |
merge(mode, values, separator) |
fetch.merge_values:839(quota_source.sum_hits 保持自己的聚合语义,只共用"按分算"那把尺) |
同 fetch |
validate(db, field, cfg, keys, *, want_kind) |
fetch._entry_problems:977 + dicts.remote_problem:252 + processdata.match_problems:155 合并 |
fetch.problems / dicts / 候选来源 / 额度 |
missing_args(row, args) |
fetch._missing_args:707 |
fetch.run / 候选来源搜索 |
fetch.py 瘦成只做执行:权限 → 缓存 → 入参齐不齐 → 熔断 → 限流 → 真调 → 解析 → 留痕。
"配置说的是什么"全部交给 binding。这一刀之后,fetch.py 那 1110 行里至少 200 行是搬走而非新写。
落地时两处按实况改了口径(动完代码才看清的,比在纸面上列清单时准):
quota_source.problems与processdata.validate查的是流程还在不在、条件字段还认不认得, 不是「这张DataSource还在不在 / 停没停 / 是不是列表型」——§2 表第 2 行把它们算成了同一套, 其实数据源健康判据只有fetch._entry_problems、dicts.remote_problem、候选来源三份, 现在收成binding.source_problem一句就结束了。两处的流程检查照原样留着,各有各的措辞与判据。mapping.py不改成吃 binding:它是往外发那一条链上的模板语言,{form.x}只是其中一个前缀, 外面还套着{item.x}/{attach:…}/each+map的循环节点,取不到值抛的是RenderError(发报文的错必须挡住发送,而 binding 的规矩是"认不出就当字面量")。 强行并进来要么把出站那条链的把关拉松,要么把内核撑成两套语义,两边都比现在难读。
4.2 前端:utils/binding.ts + components/oa/design/SourceBindingEditor.vue
binding.ts:resolveExpr/resolveArgs/entries/mergeValues/formRefs/argsKey收成一份,formFetch.ts、formThreshold.ts、quotaConfig.ts、paramRows.ts改成薄封装再导出(老调用点不动,避免全仓改 import)。SourceBindingEditor.vue:把FetchPanel里「源下拉 + 入参逐行 + 带出去向 + 单行报错」那一段抽出来, props 就是(entry, source, targets)。FetchPanel保留它自己的多源清单与merge/onError;OptionSourcePanel的数据源那一截改成用它(外加它自己的"试搜一页");QuotaSourceEditor里流程那半截下一步跟上。
面板数量不减少:设计器里仍然看得见「候选来源」和「外部取数」两栏。减少的是重复实现和配错的机会。
4.3 候选来源这一路补齐参数(唯一的新键)
// select / radio / checkbox / relation 上,optionSource = dataSource 时生效
{
"optionSource": "dataSource",
"dataSourceCode": "erp_material",
"dataSourceArgs": { "category": "{form:material_category}" }, // 新增,形状与 fetch.args 一模一样
"pickerStyle": "dialog"
}
/data-source/options改成POST,收{ code, keyword, args };老GET保留一个版本再撤, 移动端与开放接口不至于同一次发布里断掉。- 入参解析走 L2,
{form.x}的引用检查复用 fetch 那一句(引用不存在的字段、引用自己,都当场说)。 clean_option_source的SOURCE_OWNED_KEYS[dataSource]加上dataSourceArgs, 换来源时跟着一起清——理由和dictCode那条一字不差。- 阈值要用业务系统的数仍然走「替人补一格
fetch」(fetchHolderField):外部值只有落进work.data才进得了条件分支与审批人视野,这条绕行是对的,内核统一之后照样保留。
4.4 供给方式统一(可选的 P3)
把「这一格的候选怎么来」收成一只接口,四种来源各是一个 provider:
| provider | search(keyword, args) | labels(values) | constrains | freshness |
|---|---|---|---|---|
manual |
本地过滤 options |
本地 | 是 | — |
dict |
本地过滤字典项(含级联过滤) | 字典 | 是 | — |
dict + 绑了源 |
同上 | 字典 | 是 | sync / ensure_fresh(就是今天的 §2.5 那条路) |
process |
GET /work/related |
单据标题现拼 | 否 | 实时 |
dataSource |
/data-source/options |
搜过的现拼,搜过的记着 | 否 | 源的 cache_seconds |
这张表今天散在 dicts.effective_options、useDictOptions、useDataSourceOptions、
OptionPicker 四处的分支里。收成一只接口之后,"外部列表→候选"两条平行路就变成
同一个 provider 的两种 freshness,§3.3 那种能力不对等不会再长回来。
5. 要新增的把关(交叉规则)
| 规则 | 在哪判 | 说什么 |
|---|---|---|
选择类字段同时挂 fetch 与判越界的候选来源(manual / dict) |
设计器黄字 optionSourceProblems + 保存 validate_schema |
「这一格的值由外部取数写入,而候选来自字典,取回的编码必须在字典里,否则提交会被判越界——请给字典补上这些项,或把候选来源改成外部数据源」 |
| 候选来源指向的源不存在 / 停用 / 不是列表型 / 方向是 out | 同上,直接复用 dicts.remote_problem 那四句 |
与字典绑源时说的是同一句话,不另起炉灶 |
候选来源的 dataSourceArgs 引用不存在的字段或引用自己 |
同上,复用 fetch 的入参检查 | 与外部取数那一句一模一样 |
| 提交时取数写入的值确实不在候选内 | selection_problems |
换成一句看得懂的:「「某某」由外部取数带回的值不在候选范围内(候选来自:某字典)」 |
| 明细列同样适用 | validate_schema 那一圈 option_source_problems(column) |
主表与列一视同仁,现有代码已经是这个形状 |
保存时挡还是警告:前三条挡(配歪了的表单填单人一定撞上,和现有 option_source_problems
同一分寸);第四条只把话说清楚,不改变现有拦截行为。
6. 路线
落地状态(2026-10-20):P0 / P1 / P2 已合入,P3 仍未做——按 §6 末尾那句判断, P3 等真的有人要"按上下文筛候选"时再动。逐条比对与校验口径由
backend/scripts/check_binding.py守着 (写法解析 / entries 与 merge / 源健康判据 / 候选来源交叉规则 / 前后端措辞对齐), 前端那一份在frontend/src/utils/binding.spec.ts与OptionSourcePanel.spec.ts。落地时按 §4.3 / §5 补齐的两条与修掉的两处口径不一致:候选入参「引用了这一格自己」 单独说一句(
binding.arg_ref_problems(self_ref=…),只对候选这一路开——外部取数那边 「按这一格现在的值重新取一次」是有意的配法);设计器那面的源探针改在全量清单里找, 之前"取一个值的那种源"会被说成「源不存在」、而真被删掉的源反而一句不说。
P0 把关(半天,零形状变更,先合) ✅
option_source_problems 补源的健康校验 + 交叉规则三句 + selection_problems 那句改写;
前端 optionSourceProblems 同步。这一步不碰执行链路,出问题回滚也就是几行提示。
落地在 formruntime.option_source_problems(多出的三类:源健康、候选入参引用、交叉规则)、
selection_problems 那句改写,以及前端 optionSourceProblems 的同三条。
P1 抽内核(1~2 天,纯搬代码,行为必须逐字不变) ✅
binding.py / binding.ts / SourceBindingEditor.vue 落地,六个消费方改吃它。
验收:同一批表达式与同一批配置,抽前抽后 resolve / entries / merge / problems
输出逐字相同(一份比对脚本 + 现有 formFetch.spec.ts);npx vue-tsc --noEmit 干净。
搬的时候有两处故意没保持"逐字不变",都是两边本来就不一致、必须选一边的那种:
① 拼接写法 {form.a}-x 后端过去原样发给上游、前端却会拼,现在两边都拼;
② 花括号里的空格 { form.a } 两边过去一种认一种不认,现在都认。
P2 候选来源参数化(1 天) ✅
dataSourceArgs + POST /data-source/options(老 GET 留着)+ clean_option_source 补键
- 设计器里在候选来源面板内直接复用
SourceBindingEditor的入参那截 + "试搜一页"带上下文。POST那条落地时顺手修了老 GET 的一个显示 bug:搜索失败与"一条都没搜到"回的是同一个形状, 面板恒显示"一条都没搜到";现在返回体带ok/itemCount,失败时说的是失败。 明细表的列只做了后端校验(validate_schema把列名当作候选入参可引用的键), 列上的入参编辑 UI 没做——列宽放不下那一截,等有真实需求再加。
P3 供给方式统一(可选) — 未做
provider 接口收敛四处分支,字典绑源那条路获得与直连搜同一句健康提示;
ensure_fresh 与 cache_seconds 的口径合并成一处说明。
P0 之后就可以停。 P1 是这批改动里唯一"现在不抽、以后每次都要改六处"的那一项, 建议紧接着做;P3 等下一次真的有人要"按上下文筛候选"时再动。
7. 明确不做
- 不把
fetch并进optionSource,也不合并成一个"数据绑定"大面板。 §1 那五行判别就是理由: 两样在"谁在动作""失败要不要挡人""判不判越界"三处相反,合成一格等于把三个决定推给填单的人去猜。 - 不做候选多源合集。 取值有多源合成(
fetch.sources+merge)是因为"几个数加起来"是真需求; 候选拼两个源没有稳定的排序与去重口径,真要合请在源那一侧做一个聚合接口。 - 不改存储形状。 已有的
optionSource/pickerStyle/dictCode/dataSourceCode/relationProcess/fetch一个不动,老表单继续按 option-source-design §0 那套推导读。 - 不让前端值说了算。 提交时后端重算覆盖这条不动,内核统一不影响它。
- 不新建表。 源注册表、留痕表、字典表都够用。
- 不动出站映射那套模板语言(
mapping.py)。理由见 §4.1 末尾:它跟内核只是长得像, 语义(错就抛、不挡就发不出去)与作用域(item/attach/each)都不是一回事。
8. 影响文件
| 层 | 文件 | 动作 |
|---|---|---|
| 内核 | backend/app/service/binding.py | 新增:解析 / entries / merge / 校验 / missing_args |
| 执行 | backend/app/service/fetch.py | 搬出配置解析,只留执行与留痕 |
| 同源件 | quota.py / quota_source.py / threshold.py / processdata.py / dicts.py / mapping.py |
改吃 binding;dicts.remote_problem 变成 binding 校验的一个调用方 |
| 把关 | backend/app/service/formruntime.py | option_source_problems 补全 + 交叉规则 + selection_problems 那句 |
| 清洗 | backend/app/api/design.py | SOURCE_OWNED_KEYS[dataSource] 加 dataSourceArgs |
| 接口 | backend/app/api/data_sources.py | POST /data-source/options 收 args |
| 口径 | frontend/src/utils/binding.ts | 新增;formFetch.ts 等四个改薄封装 |
| 控件 | frontend/src/components/oa/design/SourceBindingEditor.vue | 新增;FetchPanel / OptionSourcePanel 接上 |
| 候选 | frontend/src/composables/useDataSourceOptions.ts | 搜索带上解析后的 args |
| 候选 | frontend/src/utils/optionSource.ts | 源健康 + 候选入参引用 + 交叉规则三句 |
| 守卫 | backend/scripts/check_binding.py | 新增:内核解析 / entries 与 merge / 源健康判据 / 交叉规则 / 前后端措辞对账 |
| 测试 | frontend/src/utils/binding.spec.ts(新)、OptionSourcePanel.spec.ts、OptionPicker.spec.ts、formFetch.spec.ts |
内核比对表 + 交叉规则 + 带参数搜索 |