unis-oa/docs/relation-link-fill-design.md

21 KiB
Raw Permalink Blame History

关联带出:挂上审批单之后,把那几张单里的值写进这一张单的明细表与主表

相关: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) 这类);额度与 阈值读的是带出之后的数;必填校验排在最后,所以「关联带出来的那一格」可以直接勾必填, 带不出值时那一趟提交真的被挡下——这是正经用法,不是巧合。

权威在后端意味着前端那一份只是显示。填单页上挑完关联要立刻看见行补出来,做法是:

  1. utils/linkFill.ts.linkFillPicks 把这屏上所有 pick 并成一句,POST /work/relation-values 一次问回来 [{job, value, values: {pick: 值}}](路径解析只在后端有一份,前端再镜像一遍 就是第五份解析器,而这一层刚花力气收成一份);
  2. applyLinkFill 把回体交给与后端同一分寸的镜像实现,写回 modelValue;
  3. 触发只盯一句 linkFillSignal(各关联字段此刻那串值压成的字符串),别的格子动一下 不重问;同值不重发,防抖 300 ms,连着挑几条只发最后一趟;几个关联字段并成一趟 问(值去重、pick 去重),回来的账按 value 分回各格;发出去之前记下此刻那串关联, 回来时人已经改过就不 apply(与外部取数那一路同一脾气);
  4. 提交之后服务端那一份覆盖一切。界面上那一栏写得明明白白:手改那一格没用。

分账认的是「问出去的那一句」,不是 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