21 KiB
关联带出:挂上审批单之后,把那几张单里的值写进这一张单的明细表与主表
相关:option-source-design.md(「候选来源 = 流程单据」这一格 是怎么来的,
relation为什么退化成其中一档)、 data-binding-unification-design.md(取数写法与合并 口径共用的是哪一层,为什么路径解析只许有一份)、 form-data-integration-design.md(「从另一个流程带数据」 那条源——它带的是这一张单去读那一张单,这一篇带的是挂在这一张单上的那几张单)。 这一篇讲一件事:关联审批单挂上之后,那些单子的数据怎么落到当前表单的格子里, 包括挂好几张的时候该怎么办。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 需求 | 关联审批流程之后,把那边单据里的值写进这一张单的主表字段或明细表;挂多张也要能带 |
| 配在哪 | 就配在「候选来源 = 流程单据」那一格上:字段多一个 linkFill,不新增字段类型、不新增一栏开关 |
| 从哪儿进 | 四个入口进的是同一栏(§2.5):设计器顶上「关联带出」总览、画布上那两枚角标、明细表属性里的「带进这张表的关联字段」、那一格自己的属性面板 |
| 从哪取 | pick:work.单号 这类单据本体,data.金额 这类对方表单字段,写法与「从另一个流程带数据」一字不差(同一份 fetch.pick_path,含 [字段=值] 筛行与 sum() 聚合) |
| 写到哪 | to:主表字段名,或 明细表key.列key。两类去向行为不一样,这是整件事的核心 |
| 挂一张 | 两路都一样:那一格 / 那一行取那一张单的值 |
| 挂多张(主表) | 「几个数变成一个」:按配的那一档合(first 默认 / join 拼接 / sum / min / max),口径就是外部取数那一句 binding.merge |
| 挂多张(明细表) | 「一单一行」:按关联顺序补行,取消关联的删行,行上记 _link = 那张单的 job |
| 两类单要一起挂 | 挂两个关联字段(报销单一格、采购单一格),各配各的映射;带进同一张明细表也各带各的行——删行只认「这一行的来源还挂在不在别的格子上」 |
| 人在明细表里改过 | 没配带出的那一列一个字不动;配到带出的那一列按来源盖回去;关联没变时整趟不动,人删掉的那一行不会在下一环被复活 |
| 什么时候算 | 每次提交都算(engine._apply_form_runtime,排在公式之前),明细那一趟只在关联那串值变了时重排 |
| 谁说了算 | 后端。填单页那份即时预览(POST /work/relation-values + utils/linkFill.ts)只用来显示,前端往那几格里塞什么都白塞 |
| 带出来的格能必填吗 | 能。带出排在必填校验之前,靠它过闸才是正经用法;带不出值时必填真的会把提交挡住 |
| 越界与脏数据 | 挂着的那张单查不到了(未发起就删了 / 单号写歪):不替它编一行,主表那一格跳过它,不报错也不挡人 |
| 谁能配 | 只有主表字段。明细列里那一格挂的也可以是单据,但「这一行的那张单 → 另一张表的几行」在界面上没人能预期,那一层要带数据走「从另一个流程带数据」 |
| 老表单 | 一个字都不用改:没有 linkFill 就是今天的行为;换了候选来源,那份配置跟着上一家一起被清掉 |
| 新接口 | 一个:POST /work/relation-values(只为预览;提交路径上一个都不多) |
| 验收 | PYTHONPATH=. python3 scripts/check_link_fill.py(纯函数,不连库,含两格带同一张明细表)、PYTHONPATH=. python3 scripts/check_link_fill_submit.py(真提交,连库,31 项)、npx vitest run src/utils/linkFill.spec.ts src/components/oa/FormRenderer.linkFill.spec.ts src/components/oa/design/LinkFillOverviewPanel.spec.ts src/components/oa/design/LinkFillPanel.reveal.spec.ts src/views/oa/design/FormDesignerView.linkFillEntry.spec.ts |
| 唯一口径在哪 | 后端 backend/app/service/linkfill.py;前端镜像 frontend/src/utils/linkFill.ts;设计器那一栏 components/oa/design/LinkFillPanel.vue(属性面板与总览弹窗共用它,不存在第二份编辑器) |
1. 为什么是「字段上的一层配置」
「挂上关联之后,那些单子里的值落到这一张单的哪里」这件事,直觉上有三种做法,都不对:
- 做成一张新单据(子流程 / 表单模板):把对方的字段抄一遍摆在自己表单上。结果是同 一个金额在三处存着,对方的单改了这里不会跟着改,谁也不认错。
- 做成一个新字段类型「带出」:那一格只能装带出来的值,于是「带出来的金额」和 「我自己填的备注」得是两类格子,明细表那一列还得再来一类。字段类型本来只管 装单个值还是一串值,别让它再管值的来源。
- 在流程上配一张映射表(像「从另一个流程带数据」那样挂在源上):那条源的主语是 「我去读那一个流程里的某一单」,条件(哪个流程、按什么筛、取哪一条)都得自己配; 关联带出的主语是这一格已经挂着的那几张单,条件就在这一格里,再配一遍只会配歪。
所以它长在这一格上:optionSource 说候选从哪儿来,optionMap 说看哪一列存哪一列,
linkFill 说挑中之后的那些单据,值往哪里写。三者都是字段上的正交配置,都只在
clean_option_source 那一趟里被收干净——linkFill 直接进 SOURCE_OWNED_KEYS[process],
换了来源就跟着残骸一起被抹掉,与 dictCode / dataSourceCode 同一分寸。
2. 配置长什么样
{
"key": "orders", "type": "relation", "optionSource": "process",
"linkFill": {
"process": "<可选:设计器按哪个流程列字段名,不限制能挂谁的单>",
"rules": [
{ "pick": "work.serial", "to": "src_serial", "agg": "join", "separator": " / " },
{ "pick": "data.amount", "to": "total", "agg": "sum" },
{ "pick": "data.amount", "to": "items.amount" },
{ "pick": "data.reason", "to": "items.note" }
]
}
}
pick 读的是对方那张单:service/processdata.py 本来就把一张单据整形成
{"work": {…}, "data": {…}} 喂给取数那一层,这里共用同一份整形与同一条路径解析,
所以 data.报销明细.sum(金额)、data.明细[部门=研发部].金额 这些写法照用。
to 写的是这一张单,先整串认主表字段名,认不出才按第一个点拆成 表.列
(主表字段名允许带点,禁了等于改一遍所有老表单,所以把歧义定死在「整串优先」这一侧)。
一条规则只写进一格;两条抢同一格在保存那一刻就报「后一条永远盖掉前一条」。 上限:一格 30 条规则、一次 50 张单(超了是配错了,不是配少了)。
2.5 入口:四个地方,进的是同一栏
配置长在关联那一格上,这是数据该待的地方;入口不能只长在那儿。第一次用这件事的人问的
从来不是「linkFill 怎么写」,而是「我在哪儿设」,而她可能站在三个位置上问:想先把整张表单
核对一遍的人、已经挂上单据想接着补映射的人、站在明细表那一侧问「这几列谁来填」的人。只给
一个入口等于只答第二个人。四个入口,进去的是同一栏:
| 站在哪儿 | 看得见的东西 | 点下去到哪儿 |
|---|---|---|
| 设计器顶上 | 「关联带出」那颗,角标写 N 条 / N 格待配 / 还没挂 |
总览弹窗 LinkFillOverviewPanel.vue:挂单据的格子配没配都列,每行说清几条、限定哪条流程、落到哪几格,就地展开改 |
| 画布上 | 关联那一格标「关联带出」(悬停:几条 → 落到哪儿),明细表那一格标「被带出」(悬停:被谁带的) | 双击那一格 = 选中它并把带出那一栏滚到眼前 |
| 明细表属性里 | 「带进这张表的关联字段」那一栏:哪一格 → 哪几列,一条一行 | 「去那一格」跳到那个关联字段并展开那一栏;还没人带时列出的是可以去配的那几格 |
| 关联那一格属性里 | 「候选来源」那一行(角标写来源类型与几条带出) | 弹窗里摊开的那一栏,就地改(见 designer-panel-dialogs.md) |
三条钉住的分寸:
- 总览不另造编辑器。它吃的是属性面板里那份
LinkFillPanel——同一份落点清单、同一句 「按同名自动配」、同一套校验措辞,只是摊在不选中任何格子也开得动的地方。两处各写一份, 早晚变成两套说法。 - 「跳到那一格」要真到位。选中那一格只是第一步:那一栏现在藏在「候选来源」那扇门里,
人到了还得自己找门、开门、再往下滚。所以那一下同时记下「跳的是哪一格」
(
revealLinkFill+revealLinkFillKey),被跳到的那一格先把门打开、再滚到眼前并描 一圈,选中一变就作废——否则下一个点开的关联字段跟着闪。门是design/SidePanel.vue那个reveal入参开的,不是这一栏自己特殊。 - 落点那句摘要只算一次。
linkFillWhereNames/describeLinkFillWhere把名字收在一处, 角标的悬停说明、面板里那句「挂几张补几行」、总览那一行念的必须是同一份账。
「写进对应的字段」这句话最短的路是按同名自动配(autoLinkFillRules):对方表单里的字段名
(或显示名)跟这张表单上同名的那一格配起来,对不上的不动、已经配过的不抢、对方那张明细表不猜。
落点清单里不给挑「另一格关联审批单」——那一格存的是挂着哪几张单,把带出来的值写进去等于
把刚挑上的关联抹掉,下一趟提交连它自己都要带不出东西(NOT_TARGET_TYPES 与 SKIP_TARGETS
同一份清单);老表单真有这么写的照旧算得出,只是设计器不再递这个选项。
3. 主表那一路:几张单变成一个值
主表那一格只装得下一个值,挂了三张单就得说清「三个数怎么变成一个」。做法是照搬
外部取数那一套合并档(first / join / sum / min / max),落到
binding.merge 那一句——与「同一个字段从三个源取值怎么合」用的是同一把尺,不另造说法。
sum / min / max 要求那一格装得下数(number / money / formula),否则保存时说得出来。
这一路与明细剩几行无关:人把明细里带出来的行删了一半,sum 出来的还是那三张单的
金额合计,因为主表那几格读的是关联的那串单,不是明细表。要「按明细那几行合计」,
用公式去 sum(items.amount),那是另一件事。
4. 明细那一路:一单一行
明细表装得下多行,于是「挂几张带几行」是天然形状。每一行带一格 _link = 带它来的
那张单的 job,这是这一行是谁带出来的唯一凭据:
| 这一次提交里 | 怎么办 |
|---|---|
| 新挂上一张单 | 在末尾补一行,行上每一列都在(没配的列留一个形状正确的空),配到的列取对方的值 |
| 取消一张单的关联 | 那一行跟着删(_link 对上才删) |
| 还挂着、行还在 | 只刷配到带出的那几列,其它列一个字不动;人排的次序不动 |
| 还挂着、行被人删了 | 补回来(加在末尾)——这一行属于那张单,人的删除留给「取消关联」去表达 |
人自己加的行(没有 _link) |
一动不动,也不占 _link 的账 |
挂着 maxRows |
补完裁到上限,与 normalise_rows 同一口径 |
_link 以下划线开头,等于声明「这是服务端自己写的留痕」:导出、打印、明细导出只认
配好的列,看不见它;engine.without_trace_keys 会在页面回传时把这类键丢掉;
normalise_rows 为它单开了一个口子(那一格不在列清单里,却是认行的凭据,整表时丢掉
就等于下一次带出认不出旧行,会把人改过的行当新行重排)。
row_is_empty 也认它:对方那张单里这一列本来没填,带出来的行可能是全空的,
但行还是那一张单的,按空行丢掉就等于把关联弄丢了。
一张明细表可以被两个关联字段各带几行。「挂两类单子」在真实表单上就是两格——报销单一格、
采购单一格,两格里的字段名根本不是一套,各配各的映射才对;而它们带出来的行落在同一张表上。
于是删行的凭据不能只看自己这一格:那一行的来源只要还挂在别的关联字段身上
(那一串值存的可能是 job,也可能是单号,绕一层换成 job 再比),这一格就不许动它——
否则后处理的那一格会把前一格刚补的那几行当成「自己这边取消关联了」删干净
(后端 linkfill._protector ↔ 前端 syncRows 的 keep)。主表那几格同理只按自己那一格
挂着的那串单算,两格各写各的落点;两条带出跨格抢同一格时按字段顺序,后者覆盖前者。
5. 什么时候重算:只在「关联那串值变了」时重排行
整趟对账只在关联那串值与上一次不一样时做。判据是 data["_linkfill"][字段名]——
上一次带出用的是哪一串,服务端自己写进留痕;这一次现读的那串与它对不上,才重排。
不这么做会怎样:带出发生在每一次提交上,如果每趟都对账,第二环的处理人只要提交一次, 他在第一环里手工删掉的那一行就被复活了。于是这条分寸写死在两处(前后端同一句判断):
- 关联没变 → 明细一行都不重排,人也就能改得,连配到带出的那一格都改得(改完就是 这一单的数,不再被盖);
- 关联变了 → 整趟对账:补的补、删的删、留下的行按来源刷新配到的那几列。
为什么记「这一格存着的那串值」而不是「查得到的那几张单」:挂上一张暂时查不到的单 (草稿被删、单号写歪)也算「关联变了」,得重排一次;按查得到的算会让这一轮什么也没发生, 等那张单哪天又查得着了,行早就跟关联对不上了。
主表那一路每趟都算(它只是几个数合成一个,没有「把人的活儿重做一遍」的问题), 明细那一路才要这一道闸。
6. 谁说了算:后端排在必填之前
_apply_form_runtime: autoFill → fetch(外部取数)→ linkfill(这一层)→ 公式 → 额度 → 阈值 → 必填校验
预览那一趟带一道可见性闸,引擎那一份不带。POST /work/relation-values 照
GET /work/summaries(也就是这一格回显本来就走的那条路)的分寸:只回与当前登录人相关的
那几张单,不相干的静默少回——这一格不能变成翻别人单据的口子。多认一档「确实挂在正在填的
这张单上」(请求带上 work):办理环节的人常常与对方那张单无关,而那些单是发起那一环替他
挂上的,少了这一档,带出那一栏对他就是一片空白。引擎那一路压根没有「谁在看」这个参数
(works_by_values),所以第二环提交照样算得出值——显示可以比落库保守,反过来不行。
排在这里有三个理由:公式要读到刚补好的那几行明细(sum(items.amount) 这类);额度与
阈值读的是带出之后的数;必填校验排在最后,所以「关联带出来的那一格」可以直接勾必填,
带不出值时那一趟提交真的被挡下——这是正经用法,不是巧合。
权威在后端意味着前端那一份只是显示。填单页上挑完关联要立刻看见行补出来,做法是:
utils/linkFill.ts.linkFillPicks把这屏上所有pick并成一句,POST /work/relation-values一次问回来[{job, value, values: {pick: 值}}](路径解析只在后端有一份,前端再镜像一遍 就是第五份解析器,而这一层刚花力气收成一份);applyLinkFill把回体交给与后端同一分寸的镜像实现,写回modelValue;- 触发只盯一句
linkFillSignal(各关联字段此刻那串值压成的字符串),别的格子动一下 不重问;同值不重发,防抖 300 ms,连着挑几条只发最后一趟;几个关联字段并成一趟 问(值去重、pick去重),回来的账按value分回各格;发出去之前记下此刻那串关联, 回来时人已经改过就不 apply(与外部取数那一路同一脾气); - 提交之后服务端那一份覆盖一切。界面上那一栏写得明明白白:手改那一格没用。
分账认的是「问出去的那一句」,不是 job。 那一格存 job 还是存单号由
optionMap.valueKey 说了算(费用报销单上「请选择出差备案流程」存的就是单号
CCBAYZJ20261110000002),于是预览发出去的那一串本身就可能是单号。回体里 job
永远是那张单的号,value 才是这一格存下来的那一句:只按 job 认领,一张也对不上号,
明细表一行都不补、主表那几格全空,而提交时引擎那一份算得出来——界面空着、数据里有
是最难查的那一种。钉这一条的是 FormRenderer.linkFill.spec.ts 里「那一格存的是单号」
那一条,与 scripts/check_link_fill.py 的「预览取值」。
7. 边界与校验
保存这一刻挡下来的四类毛病(linkfill.problems ↔ utils/linkFill.linkFillProblems,措辞一字不差):
来源不是「流程单据」(存得下来但永远不带)、pick 看不出要从哪一列取、to 指的格子
不在表单上了(格子名会被复用,把别的单的数盖到同名新格子上比少带一格危险)、
sum / min / max 配上装不下数的那一格。两条带出抢同一格也说得出。
clean_option_source 那三处收残骸:明细列上的 linkFill 整份丢掉;换了候选来源跟着
上一家一起丢;写歪的规则、认不出的合并档在 clean 里收掉,一条有效规则都不剩时整格抹掉
(留一份空 rules 只会让下一任以为配过什么)。
查不到的那张单(未发起就被删——engine.delete_unstarted 是把 oa_work 那一行
整个删掉的,归档表里也没有):主表那一格跳过它继续算剩下的,明细不替它编一行,不报错、
不挡人。它带来的那一行在关联变化时跟着 _link 对不上而删掉。
8. 已知不做
- 明细列上的关联带出:那一格挂的也可以是单据,但「这一行的那张单 → 另一张表的几行」
是一行生一批行,明细表本身放不下这件事,界面上没人能预期。那一层要带数据走
「从另一个流程带数据」(
fetch),它本来就是为「按当前行的条件去读一条」设计的。 - 反向回写:只往这张单里带,不改对方那张单。带出去的数在对方改了之后要不要跟着变, 答案是「下一次提交时跟着变」,不是实时。
- 带出链:关联带出的目标格可以同时是字典带出 / 外部取数的目标,但不进「关联带出 → 另一个关联字段的关联」这种环——链子长到要收敛判据时,多半是该在对方那张单上做一个 汇总口径,而不是在这里抄几十列。
9. 落点
| 层 | 位置 |
|---|---|
| 后端权威 | backend/app/service/linkfill.py(配置整形 / 校验 / 取值 / 落库四段) |
| 引擎挂钩 | backend/app/engine/engine.py:_apply_form_runtime(一行:linkfill.apply) |
| 行口径 | backend/app/service/formruntime.py(ROW_LINK_KEY、max_rows_of、normalise_rows、row_is_empty、validate_schema) |
| 保存整形 | backend/app/api/design.py(SOURCE_OWNED_KEYS、clean_option_source) |
| 预览接口 | backend/app/api/runtime.py(POST /work/relation-values)、schemas.RelationFillBody |
| 前端镜像 | frontend/src/utils/linkFill.ts |
| 设计器 | frontend/src/components/oa/design/LinkFillPanel.vue(挂在 OptionSourcePanel.vue 里,总览弹窗也吃它) |
| 填单预览 | frontend/src/components/oa/FormRenderer.vue(linkFillSignal → runLinkFills) |
| 设计器入口 | frontend/src/components/oa/design/LinkFillOverviewPanel.vue(顶上工具栏那颗,见 §2.5);画布那两枚角标在 FormSheetCanvas.vue,明细表那一侧的清单在 FieldInspector.vue(table-link-fill 那一栏) |
| 入口那几笔账 | frontend/src/utils/linkFill.ts(linkFillSourceFields / linkFillTotalRules / linkFillWhereNames / describeLinkFillWhere / linkFillIntoTable / autoLinkFillRules) |
| 删字段 / 改名 | frontend/src/utils/formPrune.ts、formRename.ts 跟着 linkFillTargets 一起清 |
| 验收 | 后端 check_link_fill.py(不连库)+ check_link_fill_submit.py(真提交);前端 utils/linkFill.spec.ts、components/oa/FormRenderer.linkFill.spec.ts、design/LinkFillOverviewPanel.spec.ts、design/LinkFillPanel.reveal.spec.ts、views/oa/design/FormDesignerView.linkFillEntry.spec.ts |