unis-oa/docs/approval-dedup-design.md

25 KiB
Raw Permalink Blame History

同一张单上同一个人只签一次:口径、边界与设计期体检

状态:已落地。运行时口径在 backend/app/engine/engine.py(approval_flags / repeat_policy / ahead_scope / _approved_persons)与 backend/app/engine/lookahead.py,设计期体检在 backend/app/service/dedupaudit.py,界面在流程设计器(ProcessDesignerView.vue + components/oa/design/DedupAuditPanel.vue)。README「引擎能力 → 流转语义」那几条是本文的浓缩版。

0. 一页看完

  • 一张单上同一个人出现在好几个环节是常态(发起人自己也是初审人、总监在两个环节都要签)。 配的时候只需要回答一个问题:这单他签几次、签在哪一次——所以界面上是一档策略四选一, 不是两个各开各的开关。
  • 两条规则方向相反但不互相抵消:往回看(前面真批过 → 这一环自动过)以已办为凭, 往前看(后面还要他批 → 这一环跳过)不产生已办。于是同一个人这一单一定至少真签一次。
  • 「批过」认的是亲手表态:或签里被系统代结的、转办出去的、走回头线出去的那一票、开始环节那一张 「提交」,都不算(_approved_persons)。回头线认 definition.is_back_route——goBack、reject, 以及没标语义但绕回自己那条边,与图遍历、审批记录、前瞻同一把尺子。
  • 路由上写的条件也算图的一部分:条件分支按这一单的表单收敛成引擎真会走的那一条,退回路由不算 往前走,免审条件只按人判。以前这些都摊平成「可能走」,配得再死的分支也只换来一句 「后面有一条分支不经过他」。
  • 新增的是设计期就能看见结果:POST /process/processes/{id}/dedup-audit 拿画布上 当前这份设计(含还没保存的改动)试算一遍,右栏「审批体检」页签逐个人给结论,画布上的环节 挂角标,工具栏那个红色数字是还没管住的组数,发布前再拦一句。发现「会签两次」时可以直接 一键改成建议的那档,改完体检自己重算,当场看见红点变绿。

1. 四档策略,不是两个开关

存储沿用原来那两个键(不迁移、不动老数据):

位置 往回看 往前看
流程级 approval_config dedup: none|all dedupAhead: none|all|any(all/any 是口径,不是开关)
环节 config skipApproved?: boolean skipAhead?: boolean(+ skipAheadScope 单独改口径)

界面上折成一档策略,四选一:

策略 含义 折算出来的两个开关
each 每次都签 每一环都派待办 两个都关
first 只签第一次 真签过一次之后,后面再遇到他的环节自动过 往回看开
last 只签最后一次 前面先跳过,签在后面那一次 往前看开
once 只签一次 两头都收:能提前跳的跳掉,真签过一次之后后面也自动过 两个都开
  • 折算是同一份口径的两个实现:后端 engine.repeat_policy、前端 utils/approvalDedup.ts。
  • 继承按方向一个个来:环节只钉了往回看那半边时,往前看照旧跟流程默认走。所以右栏显示的 是算完流程默认之后真正生效的那一档,只钉一半时下面会写明为什么和单独钉的那档不一样。
  • 「跟随流程设置」=把那两个键删掉(不是写成 false)。写成 false 是显式要求「这一环不许跳」。
  • last 不是 once 的省流版:有躲不掉的环节(起草环节、退回到达的环节一律不许往前看跳过, 命中必批规则保下的人也不跳)时,last 会签两次。想让人只签一次就选 once。

2. 「前面批过」认什么

_approved_persons() 只把这四种历史当成「批过」,比「手上有一条已办」严一档:

  1. TaskCompleted.processing_type == 'normal':或签 / 按比例会签凑够票后被系统结掉的那几张、 转办、加签、终止,都不是他亲手表的态。把他算成批过,等于一张单上凭空少一个真签字。
  2. 走回头线出去的那一票不算:他把单子打回去,不等于他批完了,后面再遇到得真看一遍。判据是 definition.is_back_route(_route_is_back 拿历史票上的路由名找到那条边再判),不是 decision == "goBack"——设计器那颗「驳回」下拉写的是 reject,只认 goBack 时驳回的人在 这一问里被当成同意过的人。
  3. 开始环节那一张「提交」不算:那是把表交上来,不是谁批了一步。
  4. DEDUP_SINCE_KEY 基线之前的老票不算:退回重走要重新表态。

第 2 条是给没经过退回入口的路由补的口径——往回走本身已经把 dedupSince 推到此刻,但 「环节上配了多条路由、其中一条是退回」这类图里,光靠基线盖不住。

2.1 驳回之后重走:这一段整个重算(2026-11-09)

基线由 _advance 在走出去之前推,不再只挂在 go_back() 上。理由是"按下一条线往外走"这件事 只在 _advance 表达一次——界面提交、开放接口代点头、超时自动驳回、第三方回写全都从这儿过; 挂在 go_back 上时,画成「驳回(reject)」的那条线根本没走 go_back,基线压根没推。

现场(费用报销单,2026-11-09 15:45):财务经理 14:41 点驳回,发起人 15:45 重新提交,紧接着 同一秒里财务经理 / 财务总监 / 补充确认信息 / 总经理 / 部门主管一路「自动跳过 · 同意」, 理由清一色「审批人去重:某某前面已经批过」——连驳回的那位自己都被算成批过,一张刚被打回去的单 几乎没再看一眼就自己走完了。两个判据各治一半:基线(第 4 条)挡住"上一轮"那几票, 第 2 条挡住"这一轮里没经过 go_back 的那张驳回票"。

第 3 条补的是同一处的第二个洞:第一次发起时压根没有开始环节的已办(hold_at_begin、界面发起 都不写),退回来再提交时多出来一张,两次算出来的"批过的人"不一样,就会出现「刚点完提交, 自己那个确认环节被自己免掉」这种第一次压根没发生过的跳过。

按路由语义判、不按时间判:completed_time 是 MySQL datetime,只存到秒, 同一秒里按下的那颗钮拿时间戳挡不住。

同一轮之内的去重没被动:上一轮批过的人要重新表态,这一轮刚批过的人照常免掉—— 「驳回后就不许再去重」会把功能改成另一个极端,那张截图上扎眼的是驳回前那几票被算进来了。

审批记录那条轨道跟着同一把尺子:utils/approvalRecord.ts 里「这一单走过哪些环节」也只记本轮, rewindsWork 在走回头线、绕回已走过的环节、管理员改道那三个时刻把它清零(落点已知就连落点一起 留下)。不清零时同一张单还会再错一次颜色——15:45 那一步「提交」的落点是上一轮走过的补充确认信息, 于是它和驳回后真签的那几步全被染成红底,往前走的路读起来像一路驳回。钉在 components/oa/ApprovalRecord.spec.ts 的「驳回与改道之后重新往前走」那三例上。

3. 「后面还要他批」凭什么敢跳

engine/lookahead.py 是纯图分析,不碰库、不猜运行时;要读库、算表单的两件事由调用方以回调 传进来(upcoming 的 routes / droppable)。默认口径 all 要求后面每一条走得通的路径 都一定经过他才免掉前面这一环,「走得通」是这一轮的重点:

  • 条件分支按这份表单收敛(engine.forecast_routes,口径同 _pick_choice):引擎只会走 第一条成立的那条分支,前瞻就只按那一条算;适用条件不成立的出口(route_guard_ok 会拦的那几条) 先剪掉。以前把所有出口都当可能走,画了条件分支就等于永远「有一条路不经过他」,设计者把分支 配得再死也免不掉重复签字。
  • 条件算不出来=说不准,那条出口留着:字段还没填、式子写坏了,都不能当成「这条走不了」。 引擎放行时算不出来按不成立拦下,前瞻时反过来——把一条可能走得通的路当成走不通,就等于敢在 说不准的地方免掉一个人的签字。
  • 退回路由不算往前走(含环节上 routeDecisions 改标的那几条):退回是把单子打回去,不是 批完,退回去重走哪几环说不准。把它当正常出口,几乎所有配了「驳回」的流程就再也免不掉重复签字。 口径与试跑 service/simulator.py:_forward 一致。前面那一环会不会因此少一次「他本来可以驳回」? 会——但「往后看跳过」本来就意味着这一票挪到后面那一次去表,他在后面那一环照样能驳回。
  • 或签(any)、按比例会签凑够票就把别人结掉了,不算「他一定会批」;环节就他一个人时才算。
  • 免审条件只按人判:这一环配了免审规则,只有「这条规则可能碰到他」(整环都免、名单说不准、 或者就叫到他名字)才算这一环不一定有他;规则点的是别人,他这一票照样跑不掉。规则碰得到谁算在 engine.rule_reach,只按规则点名的人算、不去跑它的条件(条件要等这一单的表单填出来才算得准), 前瞻与设计期体检共用这一份。
  • any 是「有一条后续路径可能用到他就跳」,省待办更狠,但分支一拐弯他可能一次都没批过, 激进口径必须显式配出来才生效(写个不认识的值一律退回 all);
  • dedupAheadKeepOne:整环的人都被前瞻免掉时,留第一个人在这一环签,不让整环一个人都没留下。

4. 设计期体检:画完就能看见谁被跳过

运行时早就有这套规矩,缺的是在设计器里看见结果。以前要判断「张三会不会被自动跳过」, 只能真发一单,或者自己在脑子里走一遍图。service/dedupaudit.py 把同一套判定挪到设计期跑一遍: 拿画布上当前的环节与路由(含还没保存的改动)+ 组织现在的找人结果试算,逐个环节给结论。

刻意不复算规则:三个开关、前瞻口径直接调 engine.repeat_policy / ahead_scope / approval_flags(延迟 import 防环)。只有「后面这一环躲不躲得开」是这里按图自己算的, 口径与 lookahead 的必经判定一致——成环、没走完、解析不出人,一律按「不敢断定」处理。

4.1 画布上的重复分三种,确定程度完全不同

形状 结论 为什么
一前一后(后面那个能从前面走到) 判得准 策略管不管得住,静态就能算
互斥分支(互相走不到,也没有并行环节同时展开两支) branch 不算重复 这一单根本不会都走到
并行 / 数据拆分的两支(会同时展开) watch 待确认 运行时两边都派待办,去重两头都够不着
分支条件对不上(走到前一环的前提与通往后一环的分支互相矛盾) 不算重复,单列 impasses 同一张单根本走不到一起,但要写清凭什么排除

4.2 图分析在问什么

_Graph 一次建图,边带着路由上写的条件(conditions.parse 读过的式子)与决定值,问五件事: reachable(结构上可达,条件一律当可能走)、possible(按条件走得到的可达,用来判「这一对到底 重不重复」)、must_pass(往后每一条走得通的路是否必经,带环检测与步数上限)、concurrent (两个环节会不会被同一个并行/拆分同时展开)、order(按最浅深度排的展示顺序,用来把「谁在前 谁在后」说清楚)。判不出来的那一支在两种问题里都站在保守一侧:问「能不能走到」时不敢说不可能, 问「必经吗」时不敢说一定——所以「判不准」只会多问一句,不会把一次真重复悄悄抹掉。 entry(node) 给「走到这一环得先满足什么」,分支条件要能用,靠的就是它把上游的前提带下来。 上限 MAX_NODES=300 / MAX_WALK=20000,再离谱的图也不卡。

4.3 四种结论

逐对判 double(两处都要他签)/ later(后面那环自动跳过)/ earlier(前面这环自动跳过)/ unknown(判不准),再折回人和环节两层:

  • 按人汇总成一个 verdict:open 还会签两次 / watch 要人确认 / covered 都管住了 / branch 落在互斥分支上不算重复;
  • 按环节汇成角色:sign 要他签 / skip 自动跳过 / double 照旧要签 / watch 判不准, 并附一句「凭什么叫他签两次、凭什么跳」(另一处环节名也带上)。

判定的先后顺序和引擎一致:先问往前看、再问往回看。前瞻跳掉的那一环不产生已办, 所以往前看成立时轮不到往回看表态。

判不成重复的两种情形分开记:branch 是图的结构上互斥(互相走不到、又没有并行祖先), impasses 是分支条件对不上——后者是按配的条件算出来的,所以每条都带 entry(走到前一环的前提) 与 blockers(通往后一环的那条出口要什么)。一句「不会两次都走到」得能追到凭据。

「不敢跳」也要说清是哪一条:ahead_unproven 那一对带 blockers,点名「哪个环节的哪条出口 不经过他、这条要看哪个字段」(hint 是字段名,detail 是这条条件的一句话);确实没写条件的分支 标 blank,那是画出来的两条路、不是条件没配好。必经证成了、只是后面那一环说不准(或签、免审 碰得到他),措辞换成另一句——两种原因别混成「有一条分支」。

一对重复带三个字段,别把它们混成一件事:outcome 是落法、certain 是这两个环节的人 现在定没定得下来、settled 是**「管住了」这件事换成人还成立吗**。总评只看 settled:往回看 认的是「他在这张单上真批过一次」,运行时换成谁都管得住,所以它管住的一对即使名单是试算出来的 也算 covered;往前看认的是「后面每条路都要他批」,这句话依赖后面那一环落到几个人身上, 只有后面那个环节动态时才降级成 watch(前面那环自己动态不影响这条结论)。

cause 说清是哪一档没管住,界面上那一键修法照它挑:policy_off 两档都没开 / ahead_unproven 往前看开着但后面有条分支不经过他 / first_node 前面那环是起草环节躲不掉 / concurrent 并行同展 / must_rule 后面那环配了必批规则。前三种是「开一档往回看就管得住」, 后两种不是配置没配好,一键修法不碰它们。

4.4 找人算不出人时降级,不硬判

发起人上级、上一环节处理人、表单字段、找人脚本这类环节要等这一单真跑起来才定得下来 (RUNTIME_KINDS)。这类环节标 dynamic:照样用样例身份试算出人来给人看,涉及它的那一条 带上「这条是试算」。但降级降的是「判得准不准」,不是「管没管住」——一档真管得住的策略 不该因为名单是试算的就报成「要人确认」(此前正是这一条把明明配了 last 的流程一直挂在橙灯上, 改哪儿都不亮)。环节自己的 notes(还没配找人方式、脚本要等表单填完、按某个人试算)原样 带出去,界面上收在「试算说明」里。

4.5 界面

  • 入口:工具栏「审批体检」按钮(带红点=open + watch 组数)、右栏第四个页签,两处同一个动作。
  • 面板:上面说清「流程默认那一档 + 按谁试算 + 什么时候算的、画布改过就标待重算」, 中间最多四个数(重复出现 / 会签两次 / 要人确认,最后再补一个「按条件走不到」—— 有被分支条件排除掉的配对才占一格,没有就不显示,免得看成一盏新警灯),下面逐个人一卡: 环节链按流程顺序排开, 颜色区分要签 / 跳过 / 照旧要签 / 判不准,点环节直接跳到画布上那一环并居中。用到分支条件的 那条结论挂一个「按分支条件判」标,底下补两行小字:走到前面那一环的前提、以及挡路的那几条出口。 另有一叠收起来的「按分支条件走不到一起」,逐条说明凭什么不算重复——排除了却不说,设计者只会 以为体检漏了一笔。
  • 一键修法:有「开一档往回看就管得住」的对子时挑一个最小改动推给用户——流程默认还是 each 就建议改 first(比直接上 once 保守,往后看会连前面该签的那环一起跳掉,不该由体检 替人做主);已经是 last 就建议改 once;往回看开着了还漏,说明是后面那一环自己钉死了 「不许跳」,那就只把挡路的几环退回跟随流程设置。挑对象看的是 cause,橙色的 watch 组里 那种「往后看不敢跳」的对子同样给修法——以前只对红色 open 出声,于是配了 last、被分支 卡住的那一类只能看着灯亮干瞪眼。改完画布变了 → 体检自己重算 → 角标当场减少。 口径在 utils/dedupAudit.dedupRecommendation。
  • 发布前:算过且还有 open,发布确认框里补一句「还有 N 个人会在这张单上签两次」。 只问一句、不挡路——重复签字也可能是故意的(两个人各签一道同名同姓的巧合也算正常)。
  • 自动补算只在页签开着时:拖一下框不该打后端;结论与当前画布对不上时标「待重算」, 要不要重算由人点。

4.6 接口

POST /api/v1/process/processes/{id}/dedup-audit
     权限 design:process
     body { activities?, routes?, approval?, asIdentity? }   # 全部可选:没传的那部分读库里的设计稿
     → { policy, ahead_scope, keep_one, as_identity_name,
         nodes[]: 每个手工环节的生效开关与试算名单,
         groups[]: 逐个人的结论(nodes / pairs / verdict / doubles / unclear / branch / conditional),
                  每条 pair 带 outcome / certain / settled / cause / reason / conditional / entry / blockers[],
         impasses[]: 按分支条件走不到一起的那几对(entry / blockers / reason),
         stats: { manual, resolved, people, groups, open, watch, branch, conditional, impossible } }

`blockers[]` 一条是一个出口:`at`(哪个环节)、`route`(哪条路由)、`to`(通向哪儿)、
`hint`(要看哪个字段)、`detail`(这条条件的一句话)、`blank`(没写条件)、`goback`(退回路由)。

activities / routes 认下划线与驼峰两种写法,环节上多带的 x / y / form 一律不看; 画布传来的那份优先,所以「还没保存的改动」也算得出来。响应形状与前端 types/index.ts 里那组 DedupAudit* 类型逐字对齐。

5. 边界与不做的事

  • 不替人改配置。体检只报结论 + 给一个可以按下去的建议,从不自己动环节;建议也只有一个, 不做「一键全部修好」那种一屏复选框。
  • 不承诺运行时的准确。试算用的是此刻的组织和此刻的表单,真跑起来时上级换了人、 表单填了另一个人,名单就会变。所以动态找人一律降级,界面上也一直写着「按谁试算」。 路由条件同样按此刻的表单算:跳掉前面那一环之后,如果经办人又把那个字段改了、分支拐到不经过他 的那一条,这一单就少他这一票——跟「后面那一环的名单按此刻组织算」是同一类已知误差, 要绝对稳就在这一环把前瞻关掉。
  • 不算并行分支上的重复该不该跳。并行两边都派待办是引擎行为,体检只把它标成「要人确认」, 要不要为此改掉拆分形状是设计问题,不是去重能救的。
  • 不做历史单据的回溯体检。发布后的流程版本照旧按当时那份配置走,体检只对着画布上这份草稿。
  • 不动存储、不动老配置。四档策略是界面上的折算,两个键的老写法继续有效。

6. 代码地图

关心的事 在哪
生效的那三个开关 engine/engine.py: approval_flags
折成一档策略 engine/engine.py: repeat_policy ↔ utils/approvalDedup.ts
前瞻口径 engine/engine.py: ahead_scope ↔ utils/approvalDedup.ts: aheadScopeOf
「真批过」的名单 engine/engine.py: _approved_persons
历史票上那条出口算不算往回走 engine/engine.py: _route_is_back ↔ engine/definition.py: is_back_route
往回走时把「谁批过」清到此刻 engine/engine.py: _advance(DEDUP_SINCE_KEY)
同一条基线在审批记录那一侧:本轮走过哪些环节 utils/approvalRecord.ts: rewindsWork ↔ 上一条
往后看怎么跳、哪些环节躲不掉 engine/lookahead.py
路由条件读成可比对的式子(decide / pick / 矛盾检查) engine/conditions.py
往后看时哪些出口当下真走得通 engine/engine.py: forecast_routes(口径同 _pick_choice)
免审 / 必批规则碰得到谁 engine/engine.py: rule_reach
设计期体检 service/dedupaudit.py、api/design.py: audit_duplicate_approvers
体检结论折成建议 / 画布角标 utils/dedupAudit.ts
体检状态与自动补算 composables/useDedupAudit.ts
体检界面 components/oa/design/DedupAuditPanel.vue

本仓库不留测试代码,所以这三块是落地时按 backend 目录下的临时脚本逐条跑真库验的(整体回滚、 库里不留数据),要点记在这儿,改动时照单子复查:

  • 图形状:一前一后(判得准)、互斥分支(不算重复)、并行 / 拆分同展(降级待确认)、成环、 必经走不通、动态找人降级、activities 缺省时读库兜底;
  • 条件参与判定(本轮补的三张用例单):条件分支没前提 → double + ahead_unproven 且点名那条 没写条件的出口;走到前一环的前提把分支收窄成一条 → earlier + covered;前一环挂着退回路由 → 照样 covered;后面那一环或签两人 → 不敢跳,措辞说「说不准轮到他批」;后面那一环的免审规则 只点别人 → 不拖住整环;两档都没开 → double + policy_off;前提与分支条件互相矛盾 → 进 impasses 并给出 entry / blockers;只有退回之后才会再遇到他 → 仍然报成重复(判不准不许 变成漏报);forecast_routes 与 _pick_choice 对齐(成立的分支赢过写在前面的默认分支、 算不出来的条件两条都留、人工环节只剪适用条件不成立的出口);
  • 两边口径同步:拿试跑(service/simulator.py,全程只读)跑同一份合成流程,条件成立时那一环 要写出「审批人去重:X(后面还要在「Y」批)后面还要批一次,本环节自动通过」——设计期说已管住、 运行时却不跳,就是两边口径分了家;
  • 接口形状:/dedup-audit 返回的每一个键都对得上 types/index.ts 的 DedupAudit*, 并且吃得下设计器发的那份带 x / y / form 的环节与带 decision / expression 的连线; 只传 approval 时图回退到库里的设计稿;流程不存在报 404;
  • 运行时口径:或签凑票被系统代结、转办、加签都不算「批过」,真批过之后后面那一环才自动跳过 (engine._approved_persons 的注释就是这份清单);
  • 驳回之后重走:scripts/check_dedup_rerun.py 拿真流程真待办跑两遍(标 reject 的驳回线、 连语义都没标但绕回自己那条边各一遍),逐环节看派到谁手上:驳回前批过的人各归各环重新表态、 驳回那位自己也要真收到待办、同一轮里刚批过的那个人照常被免掉、发起人自己那一环不被 「刚点的提交」免掉,一路走到归档;
  • 降级只降判准:同一组重复在 each / last / once 三档下分别应当报成 double+policy_off / double+ahead_unproven / later+covered,且动态名单只把前两种带到 watch,later+covered 必须是 covered(印章使用申请流程按部门负责人+执行董事试算即是这条 的实景:13 个部门扫下来 open/watch 都是 0)。

最后更新:2026-11-09