unis-oa/docs/process-intervention-design.md

17 KiB
Raw Blame History

流程干预:把卡住的单子救回正轨

流程监控页原来写着「管理员可查看并干预全部流程与待办」,能用的手却只有三只:催办、把某一条 待办改派给别人、把整条流程作废。这三只手写的是「这一环谁在办」,没人写「这张单子现在该不该走、 该往哪走、填错了怎么办」。真实的求助是另外几句:

  • 「材料要重新核一下,这两天先别往下走」——只能作废。作废不可逆,核完还得让发起人重新填一张。
  • 「走到财务了才发现部门那一环选错了人」——退回得由当值审批人自己点,管理员插不上手。
  • 「金额多打了一个 0」——为了改一位数把整条流程退回重走,前面每个人都得再点一次同意。
  • 「这一单压了三条并行待办」——催办要一条一条点,改派也要一条一条点。

这一篇定的就是干预这一层:五个动作、一套留痕口径、一个面板。

1. 五个动作,各管一件事

动作 管什么 单据动没动 引擎入口
挂起 / 恢复 让这条路先停在原地,别在此期间被批出去 不动,只是冻住 engine.suspend / engine.resume
干预改道 换路:把整张单子搬到别的那一环重走 动,落点换了 engine.move
整单催办 压着几条催几条,不用逐条点 不动 engine.press_work
整单改派 当前每条待办都换成指定的人(部门整体接手 / 集体休假) 不动,只换人 engine.transfer_work
修正表单数据 填错的那一处直接改,不为它退一整轮 不动,只改内容 engine.fix_data

原有的催办、单条改派、终止都收进同一个面板,不再散在表格行上:干预一张单子时这些动作是 「看一眼现在卡在谁手里,然后决定动哪一下」,把它们摊在行上等于让管理员自己排顺序。

2. 挂起:不是流程的一种结局,是运行中的一个开关

oa_work 上加的是 paused / pause_reason / pause_actor / pause_time 四列, 没有给 status 添「挂起」这个取值。理由很实在:归档判定、办结迁移、统计分析、 _finish_if_idle 的空闲判断全都按 status 走,多认一个状态等于把这三处都改一遍, 而且「挂起后恢复」还要把状态改回去——一个布尔开关干得干净得多。终止一张挂起的单子照样使, 因为它看的是 status == running。

挂起究竟冻住了什么,口径写死在引擎里,不靠界面自觉:

  • 待办办不动:execute_task / go_back / add_task / reset_task(撤回)撞上挂起直接抛错, 错误语里带上是谁、什么时候挂的、为什么——处理人看到「办不了」却不知道为什么,比办不了更烦人。
  • 本人不能自己转办:transfer(admin=False) 被挡。挂起通常正是要查清楚再决定给谁, 让处理人自己把待办甩出去会把这单子的线索弄断。管理员代改派(admin=True)照样使得, 而且建议就这么用:先把人换好,再恢复。
  • 催办没有意义,一并挡掉。
  • 超时不计时:mark_expired 跳过挂起的待办(判据是 Task.pause,不额外连一次 oa_work)。 resume 时把冻住的那段时长整体加回每条待办与单据的 expire_time。不挪时限的话, 挂一周再恢复,一睁眼每条待办都超时,催办与「超时自动处理」会一起炸开。
  • 延时环节不醒:wake_delays 的候选直接排除挂起的单据,醒过来也只会开出一批办不动的待办。

待办本身不藏起来:Task.pause 只是标记,待办列表里照样看得见,行上挂「已挂起」, 待办详情页把处理面板换成一句说明。把待办从列表里抹掉是更省事的做法,但处理人会以为自己 漏办了,然后来找管理员。

3. 干预改道:管理员的手术刀,边界写在引擎里

改道跟审批人的「退回」是两把不同的刀。退回只能往上游走、必须是当值审批人本人点、环节上勾了 「不允许退回」就点不动;改道前后都去得、由监控权限的人发起、不看环节开关——管理员存在的意义 就是把卡住的单子救活。因此它得有自己的边界,不能只靠界面少放几个按钮:

  • 只落到人工环节。判断、分支、汇聚、延时、脚本、结束那些由引擎自己走,落到那里等于把单据 停在一个没有待办的地方,看着像卡死。
  • 并行 / 拆分开着的时候拒。work.joins 里还有没收的票箱,说明此刻有若干条分支同时在路上, 改道会把它们并成一条、落单的那几条分支从此没有归宿。这种单子请先在出问题的分支上用「退回」, 或者等其余分支办完。错误语把这句原话还给调用方。
  • 当前待办一律「结掉进已办」而不是直接删。谁手里被收走了几条、当时为什么收,审批记录里 要答得上来;processing_type 记 move,与终止那类一样在轨迹上显示成非人工签收。
  • 清掉「谁已经批过」的记忆(dedupSince 基线时间),跟退回同一个道理。不清的话, 目标环节那位「前面批过」的审批人会被去重规则直接跳过,改道完单据自己就往前跑了—— 管理员以为停在了财务,其实已经走过去两环。
  • 顺手清干净:在路上的 token、汇聚票箱、依次审批的排队队列、上一次退回留下的「直返」约定。 留着任何一样,改道后的单据都可能带着上一条路的残余状态走。
  • 目标环节解析不到处理人就整笔回滚。宁可让管理员回去把这一环的审批人配好再来一次, 也不能留下一张「停在环上却谁都没有」的单子——那比原地不动危险得多。
  • 还挂着在跑的嵌入子流程时先停手(2026-11 补)。父单停在调用环节时自己没有待办,待办全在 子单上,而改道清空 token 会把等子单回来那张票一起清掉——子单从此没人认领,办完也回不去。 默认拒并说清是哪张子单、卡在谁手上,勾了「一并终止」才 cascade_children 动手。

改道之后旧环节还剩什么、已经推出去的消息各自什么下场,是另一篇: intervention-todo-and-message-settlement-design.md (去向卡、operator=actor 留在已办行上、rerouted 那一档可勾渠道事件,判据 check_intervention_move.py)。上面那句「processing_type 记 move」在那一篇里补齐了 读的一侧:前端两张处理方式表认得 move,已办那一列不会再印出裸的原值。

4. 修正表单数据:跟办单同一把尺

改表单走的是与审批人办单同一个口径:只收页面交上来的那几项,下划线开头的系统留痕 (_fetch / _quota / _formulaErrors / _outbound)由服务端自己写,页面盖不掉; 改动按「字段:旧值 → 新值」算成差异,写进流转日志,同时知会当下手里有待办的人与发起人。

之所以要专门知会:表单字段会驱动后面的条件必批与分支判断,「中途被人改过又不留痕」等于 流转方向被悄悄换了还没人负责。管理员改的更要写清楚——被改的人往往最后才知道。

4.1 改完表单,标题与三张列表一起对齐

表单里那一格「流程标题」(type: title)就是 work.title 的出处,所以管理员改掉那一格、 或者改掉标题规则引用的那几格,都算改标题。引擎走的是与审批人办单同一句 titles.refresh, 重算出来之后连同在途的待办与待阅一起改名(engine._refresh_title)。少了这一步就是用户 报的那个现象:面板里明明改好了、上面那张卡片的标题也换了,列表上那一行还写着老那一句—— 待办列表、待阅列表、监控列表读的都是各行自己那一份 title(为的是列表不必回查单据)。

两条分寸一起钉着:

  • 反向的闸:规则没开「表单变了重算标题」(refresh=false)时,改普通字段不该替这张单 重取名字,只有直接改标题那一格才换。对齐不等于每次修正都顺手改名单。
  • 已办 / 已阅不动:那是历史快照,那个人当时批的就是那一句,事后替他改名字反而对不上内容。

保存之前面板上还先预告一句「保存后标题会变成 …」(POST /job/{job}/title/preview,只读不写库, 可见范围与 /admin/work/{job}/data 同一道数据范围筛)——改标题这件事看不见摸不着,说出来比让人 改完再去列表里核对一趟便宜。判据在 backend/scripts/check_intervention_title.py。

5. 权限与数据范围:一码到底,没加新权限点

六个干预接口全部挂既有的 monitor:work,数据范围与「终止」共用同一道筛 (_ensure_in_scope 按发起人身份判)。没有新增 monitor:intervene:

  • 库里已有的角色拿到的都是 monitor:work,新加一个点会让这些人一觉醒来发现「只能看不能动」, 而页面描述写的还是「可查看并干预」——这种静默降级最难查。
  • 「能看见这张单」和「能动这张单」在监控页本来就是同一句话。真要拆,应该连着监控页的 只读形态一起做(列表能看、面板置灰),而不是先发一个没人会去勾的权限点。

6. 留痕:三处都要落,缺一处就查不清

落在哪 写什么 谁去看
oa_work_log 新增四种 type:suspend / resume / dataFix 是当前环节旁挂的引擎事件,move 是一条真的换环节记录(自带 干预改道 路由) 单据详情的审批记录、轨迹图
oa_operation_log 谁调的接口、动的哪张单、改道去哪、改了哪几个字段、动了几个人的待办 「操作日志」页,事后追责
oa_notification 挂起 / 恢复 / 改道 / 改数据知会当前处理人与发起人;改道额外告知被收走待办的人 处理人的站内信

站内信用的是新事件名 control,故意不进 channels.EVENTS:挂起、改道这种动作在站内看一眼 就够,跟着「新的待办」往邮箱和群里刷,一天下来没人会再看邮件。前端审批记录里四种新类型都登记了 文案键与图标,SYSTEM_LOG_TYPES 收进来才会出现在时间线上——没这一步,挂起过两天的单据 在记录里就跟没挂过一样。

7. 界面:一个面板,两个入口

components/oa/InterventionPanel.vue 是唯一的那个「干预的地方」。它按管理员读一张单子的顺序排: 这张单是谁的、停在哪、谁压着几条 → 然后才给手。

  • 顶部:状态、单号、发起人、发起时间;挂起时是一条琥珀色横幅(谁、何时、为什么)。
  • 页签「当前处理人」:逐条列出压在谁手里、等了多久、超没超时;行上能催办、能改派, 工具条上是整单催办 / 整单改派。改派用的是行内展开的选人框,不叠第二层弹窗—— 叠上去以后「刚才是给哪一条改的」就看不见了。
  • 页签「干预改道」:环节下拉(只列人工环节,当前环节标出来)、代价说明、原因、确认。
  • 页签「修正表单」:复用 FormRenderer 渲染本环节实际用的那张表单,界面只标「改了 N 处」, 交上去的也只有这几项。
  • 底部动作条:挂起 / 恢复(随状态换脸)、终止、关闭。终止做成就地展开的确认条, 理由同上——弹窗叠弹窗以后,谁压着谁全凭 z-index 运气。

入口两处,判据同一句(monitor:work + 单据在途):流程监控的行操作「干预」, 以及单据详情页头部那枚「干预」。后者是必要的——管理员往往是从通知或链接进的单, 不该为了换个路再回列表里捞一遍。

处理人那一侧只多一样东西:待办详情页在挂起时把处理面板换成「这条流程已被管理员挂起, 暂时办不了;恢复后从这一环继续」,并挂上原因。按钮凭空消失而不说为什么,是这类功能最容易挨骂的地方。 监控列表加了一个「只看挂起」筛选,导出跟着这个筛(CSV 的状态列会写「运行中(已挂起)」)。

8. 接口

全部在 /api/v1/admin/work/{job}/... 下,monitor:work + 数据范围,都要一个 opinion:

POST  /admin/work/{job}/suspend     挂起            {opinion}
POST  /admin/work/{job}/resume      恢复            {opinion}
POST  /admin/work/{job}/move        干预改道        {activity, opinion}
POST  /admin/work/{job}/data        修正表单数据    {data, opinion}
POST  /admin/work/{job}/press       整单催办        {opinion}
POST  /admin/work/{job}/transfer    整单改派        {identities, opinion}

面板自己不新开读接口:它要的东西(单据、待办、环节清单、表单定义、轨迹) GET /job/{job} 早就是全的,再开一个「干预上下文」接口只会多一处要跟 get_job 对齐的口径。

9. 还没做,以及为什么先不做

  • 按分支改道:并行开着的时候直接拒,而不是做一个「只改这一条分支」的复杂版本。 真实的并行卡死多半是整条路配错了,先给出正确姿势(退回 / 等分支跑完)比给一把更利的刀稳妥。
  • 管理侧撤回已办:reset_task 已经允许管理员撤回别人的最后一步,但那是「本人手滑」的救济, 跟干预不是一回事,等它想进面板时再一起设计提示与留痕。
  • 只读监控角色:见第 5 节,要连着界面一起做。
  • 批量干预:勾选十张单一起挂起看着诱人,实际最容易出事的是「筛错了一批」, 而监控页的筛选与导出已经能保证「屏幕上就是这些行」——真要做,先给批量操作配一张预检清单。
  • 挂起时冻结在途延时/子流程:延时醒不了已经覆盖住了;子流程是另一张单,有它自己的 status 与干预入口,不去动父挂子停那种联动。

10. 怎么验

仓库里不留测试代码(见 README「自检」)。这一层当初是按一张自建自删的临时库 (unis_oa_itest,走 seed.run 种出来的演示流程「请假申请 / 费用报销」)跑通的, 断言落在这几处,改引擎时照着复跑:

  1. 挂起:四列落库、待办 pause、status 仍是 running、suspend 日志、站内信; 办单 / 催办 / 退回 / 加签 / 本人转办 / 整单催办全部被挡,mark_expired 不判超时。
  2. 恢复:标记清干净、待办解冻、resume 日志、每条待办与单据的 expire_time 整体后挪同样长。
  3. 改道:落点正确、旧待办按 processing_type=move 进已办、move 日志、token 与票箱清空、 dedupSince 写上;非人工环节与不存在的环节被拒;并行开着时被拒。
  4. 改数据:值生效、_ 开头的留痕盖不掉、日志写成「字段:旧值 → 新值」;无变化与空内容被拒。
  5. 挂起中改道:新派出的待办仍然 pause;挂起中的单子仍能终止归档;已结束的单一律拒绝干预—— 办结 / 终止之后 oa_work 那行会被搬进归档表,所以 _running_work 先回查一眼 WorkCompleted,好把「这单早走完了」和「查无此单」分成两句话说。
  6. 整单催办:并行压着几条就催几条、每条 press_count 各 +1、每人收到一条催办提醒。
  7. 改数据改到标题那一格:单据、在途待办、待阅三处一起改名,监控列表按新标题搜得到这张单; 规则开了自动重算时,改它引用的字段照样重算一句并写回那一格;refresh=false 时改普通字段 不许替这张单重取名字。这一条有常驻判据:PYTHONPATH=. python3 scripts/check_intervention_title.py。
  8. 改道留下的残留与已推送消息的下场:旧环节待办一次收干净并进已办(行上写着是谁收的)、 站内信当场收尾、子流程要么拒要么一并终止、停在半路的第三方表态作废、点开旧卡片答得出 这一步的去向。常驻判据:PYTHONPATH=. python3 scripts/check_intervention_move.py, 口径见 intervention-todo-and-message-settlement-design.md。

外加仓库里那三条守卫:check_globals.py、check_route_guards.py、 check_schema_snapshot.py(改了 models.py 记得先 dump_schema.py 再回归), 前端 pnpm typecheck / lint:check / build。