unis-oa/docs/data-binding-unification-de...

24 KiB
Raw Permalink Blame History

候选来源与外部取数:不合并那两格,合并它们底下的那一层

相关: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 内核比对表 + 交叉规则 + 带参数搜索