# 候选来源与外部取数:不合并那两格,合并它们底下的那一层 > 相关:[option-source-design.md](option-source-design.md)(候选来源 × 挑选方式)、 > [form-data-integration-design.md](form-data-integration-design.md)(五种取数形态)、 > [external-data-simplification.md](external-data-simplification.md)(字典吃外部数据源)、 > [option-source-routing-design.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](../backend/app/service/quota.py:53) `FORM_REF/AUTO_REF/WORK_REF/CONST_REF` + `resolve_text:111`;[fetch.py:203](../backend/app/service/fetch.py:203) `render` 自带一份 fullmatch 正则(:219)与 `_raw_ref_value:229`;[mapping.py:29-35](../backend/app/service/mapping.py:29) 另一套 token 解析;[threshold.py:191](../backend/app/service/threshold.py:191) 蹭 `quota.FORM_REF`,但 `{auto:}` 走自己那句 | | 1 | 同上,前端镜像 | 前端 5 | [formFetch.ts:18-19](../frontend/src/utils/formFetch.ts:18) 与 `resolveFetchExpr:53`;[formThreshold.ts:24](../frontend/src/utils/formThreshold.ts:24);[quotaConfig.ts:404](../frontend/src/utils/quotaConfig.ts:404);[formWriteback.ts:421](../frontend/src/utils/formWriteback.ts:421) 附近;[paramRows.ts:133](../frontend/src/utils/paramRows.ts:133) | | 2 | 「引用的源在不在 / 停没停 / 类型对不对 / 方向是不是往外写 / 带出的键声明过没有」 | 4 套 | [fetch.py:977](../backend/app/service/fetch.py:977) `_entry_problems`;[dicts.py:252](../backend/app/service/dicts.py:252) `remote_problem`;[processdata.py:138](../backend/app/service/processdata.py:138) `validate` + `match_problems:155`;[quota_source.py:871](../backend/app/service/quota_source.py:871) `problems`。四句"源不存在"的措辞、四道判据的取交集都不一样 | | 3 | 多个源合成一个值 | 2 + 镜像 | [fetch.py:839](../backend/app/service/fetch.py:839) `merge_values`(first/sum/min/max/join,按分算)与 [quota_source.py:358](../backend/app/service/quota_source.py:358) `sum_hits`(latest/sum)各一套;前端镜像在 [formFetch.ts](../frontend/src/utils/formFetch.ts) `mergeFetchValues` | | 4 | 设计器里「挑源 → 列入参 → 每填入参 → 挑带出去向 → 报错提示」 | 3 份 | [FetchPanel.vue](../frontend/src/components/oa/design/FetchPanel.vue)(358 行,最完整)、[OptionSourcePanel.vue](../frontend/src/components/oa/design/OptionSourcePanel.vue) 里数据源那一截 + 试搜一页、[QuotaSourceEditor.vue](../frontend/src/components/oa/design/QuotaSourceEditor.vue) / [ProcessSourcePanel.vue](../frontend/src/components/oa/design/ProcessSourcePanel.vue) 的对应段落 | | 5 | 「外部列表 → 候选」有两条平行路 | 2 | 一条是字典绑源再同步([dicts.py:292](../backend/app/service/dicts.py:292) `sync` / `ensure_fresh:393`,全量、可级联、可带出、可翻名);一条是候选来源直连搜([data_sources.py:341](../backend/app/api/data_sources.py:341) `/data-source/options`,新鲜、无级联、无翻名)。两条都吃同一张 `oa_data_source`,能力却不对等,见 §3.3 | 第 1 项是最值钱的那处:口径漂移在这个仓库里是被反复写进注释防的("与后端同口径""两边说法一模一样"), 每多一份解析就多一处"改一处漏两处"。第 5 项是最容易被误当成"该把两格合并"的那处—— 它确实像重复,但重复的是**供给方式**,不是候选来源与外部取数。 ## 3. 现在会咬人的三处 ### 3.1 选择类字段同时挂两者:填单页正常,提交才被拦 链路是:[engine.py:448](../backend/app/engine/engine.py:448) `fetch.apply_form` 先按配置覆盖这一格的值, [engine.py:474](../backend/app/engine/engine.py:474) 之后才 `validate_submit` → [formruntime.py:305](../backend/app/service/formruntime.py:305) `selection_problems` 用候选清单判越界。 于是「`select` + 候选来源=字典 + 外部取数带回一个字典里没有的编码」= 提交时一句 `「某某」的取值已不在可选范围内`。这句话对填单的人是**完全看不懂**的: 那一格不是他填的,他也没得选。而设计器里两边各自校验得很干净(`fetch.problems` 不看候选、`option_source_problems` 不看 fetch),保存一路绿灯。 前端还有个加重项:[FormRenderer.vue:1191](../frontend/src/components/oa/FormRenderer.vue:1191) `dropStaleSelections` 只在 `setValue`(人手改)时跑,取数写入走的 `applyWrites` 不跑它—— 界面上那个值好好地留着,提交才炸。 ### 3.2 候选来源指向的数据源不做健康校验 [formruntime.py:785](../backend/app/service/formruntime.py:785) 只判 `dataSourceCode` 非空。 源被删、被停用、配成了单值型(`kind=fetch`)、方向是往外写(`direction=out`), 全都存得下来,直到有人点开那个下拉看到空的——而同一句判据在 [dicts.py:252](../backend/app/service/dicts.py:252) `remote_problem` 里已经写全了,抄一次就行。 ### 3.3 候选来源那一路带不了参数,字典那一路也带不了 `/data-source/options` 把入参硬编成 `{"keyword": keyword}` ([data_sources.py:352](../backend/app/api/data_sources.py:352)),而 `run()` 里 `_missing_args`([fetch.py:527](../backend/app/service/fetch.py:527))会把请求体里引用了、 却没传的入参直接判 blocked。所以「只显示所选品类下的物料」这种筛选, 挂在候选来源上**做不出来**;字典那条路虽然有 `source_args`,同步时却是 `fetch.render(db, source_args, {})`([dicts.py:321](../backend/app/service/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 候选来源这一路补齐参数(唯一的新键) ```jsonc // 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`](../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](../backend/app/service/binding.py) | 新增:解析 / entries / merge / 校验 / missing_args | | 执行 | [backend/app/service/fetch.py](../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](../backend/app/service/formruntime.py) | `option_source_problems` 补全 + 交叉规则 + `selection_problems` 那句 | | 清洗 | [backend/app/api/design.py](../backend/app/api/design.py) | `SOURCE_OWNED_KEYS[dataSource]` 加 `dataSourceArgs` | | 接口 | [backend/app/api/data_sources.py](../backend/app/api/data_sources.py) | `POST /data-source/options` 收 args | | 口径 | [frontend/src/utils/binding.ts](../frontend/src/utils/binding.ts) | 新增;`formFetch.ts` 等四个改薄封装 | | 控件 | [frontend/src/components/oa/design/SourceBindingEditor.vue](../frontend/src/components/oa/design/SourceBindingEditor.vue) | 新增;`FetchPanel` / `OptionSourcePanel` 接上 | | 候选 | [frontend/src/composables/useDataSourceOptions.ts](../frontend/src/composables/useDataSourceOptions.ts) | 搜索带上解析后的 args | | 候选 | [frontend/src/utils/optionSource.ts](../frontend/src/utils/optionSource.ts) | 源健康 + 候选入参引用 + 交叉规则三句 | | 守卫 | [backend/scripts/check_binding.py](../backend/scripts/check_binding.py) | 新增:内核解析 / entries 与 merge / 源健康判据 / 交叉规则 / 前后端措辞对账 | | 测试 | `frontend/src/utils/binding.spec.ts`(新)、`OptionSourcePanel.spec.ts`、`OptionPicker.spec.ts`、`formFetch.spec.ts` | 内核比对表 + 交叉规则 + 带参数搜索 |