unis-oa/docs/node-writeback-config.md

78 KiB
Raw Permalink Blame History

流程中间环节写回:某几个环节审批完成后反写字段,怎么配

三层配置模型、发件箱、幂等与冲销的总设计在 outbound-integration-design.md。 本文只回答一个问题:流程里某几个环节审批通过之后要把字段反写给业务系统,界面上到底要配哪几处、每一处是什么语义。 配套阅读:integration-master-plan.md(总路线)、form-data-integration-design.md(入站那半)。

0. 一页看完

问题 结论
「部分环节审批完成后回写」这件事有配置入口吗 只有 L3 环节挂载(每种环节都能挂,一条规则可挂多个模板)。模板页那一格只管三条终态;存量那批「模板自己点名到达某环节」的配置照旧发,模板页上给了一个把它们搬进环节的按钮
配模板的时候就被追问「什么时候发」,可我还不知道它挂在哪个环节上 这一格现在只问终态:办结 / 终止 / 作废可以多勾,也可以一条都不勾——不勾不是没配完,是时机还没定(写回模板本来可以先只管"发什么")。环节那一刻的时机在流程设计器的挂载那一格;模板页底部当场列出「什么时候真的会发」,两处合起来才算答案(§1 §3)
一个环节能配几条写回 想配几条配几条:一条规则 = 一个时刻 + 一批模板 + 一批条件 + 一个失败策略,各判各的(writeback.blocks)。只有一条规则时存的还是平铺的老形状,存量配置与流程导出件都不换形状(§2)
创建、归档那一刻也要回写 都归环节挂载管:创建挂在发起环节上(那一刻只有「提交单据时」)、归档挂在结束环节上(那一刻只有「走到结束(归档)时」)。作废有三条路,见 §5.5
「审批完成后」怎么表达 环节挂载上多一个 trigger:到达本环节时(arrive,旧口径)/ 本环节审批通过后(leave)/ 本环节被退回时(goBack)/ 本环节被撤回时(recall)。想要「Y 批完就发」,就把模板挂在 Y 自己身上并选 leave,不用再挂到 Y 的下一环节
退回、撤回那一刻也要通知上游 还在同一格,勾上就行:「被退回时」挂在被退回的那一环(按退回的那一环),「被撤回时」挂在被撤回那条已办所属的那一环(发起环节也有这一刻 = 发起人撤回自己的提交)。一条规则可以同时勾好几个时刻,一份映射管四刻(§1 §1.5 §13)
只有部分单据要回写 挂载上加 when(结构化条件,与设计器里的条件显隐、条件分支同一份数据结构),不满足就整条不发,也不留报文
一张表单按字段值发给不同业务系统 就在这个环节的挂载上说:每个模板各带一格条件(integrations 那一项写成 {"code": ..., "when": {...}}),条件互斥即可;要连办结那三条终态一起分流,就把条件写在模板上(send_condition)。都不改流程、不改代码(§4)
时刻配错了会不会静默失效 会,所以保存时就挡:发起环节只会被提交、结束/作废环节只会被到达,另一个时刻根本不存在,配上去等于这条写回一条都不发;「被退回时 / 被撤回时」还要看这一环有没有那颗按钮(allowGoBack / allowRecall),
按钮关了配在这里同样一声不响。界面上干脆不给这个选项(§1.5)
发不出去要不要卡住 on_failure=block 这次真的生效:卡住这张单后续环节的办理,直到写回成功或人工确认;branch(自动改走补救路线)这一期仍不生效,见 §6
后期再接一个业务系统要改代码吗 不要:L1 注册数据源 → L2 配映射 → L3 挂环节,全程界面。要改代码的只有五种情况,列在 §8
撤回重提 / 退回重走为什么不再发 默认幂等键把第二次并进第一条,发件箱不留痕,界面上就像没调用。对面按单号幂等更新的写回,在模板上勾**「重复到达时重发」**(refire_revisit,§5.2;它对挂在环节上的模板同样有效)
同一个模板能不能只发其中几个字段 能:挂载那一格带 fields(面板上的「要发的字段」),范围跟着报文存,重推不越界(§4.5)
这次补了什么 §7 那张表十四处,七组:能配吗(空转配置:模板选「到达某环节」其实从不发;只有审批环节能挂:创建与归档配不了;一个环节只能配一条:两种时机凑不到一起)、配错了会不会静默失效(存与读两种拼写、时刻与环节对不上、同一份报文发两次)、界面承诺过头(挡住处理人)、条件管太宽(挂载的 when 顺手摁掉别人的模板)、问错了时候(配模板时就被追问环节时刻,于是模板自己绑死一条流程的环节 id)、配好了又会烂(那些校验只管保存那一次,环节 id 换了、模板删了没人回头看过 → §7.5 全库配置体检:接口 + 集成页横幅 + 一个当闸门的脚本)、按钮配了不响(界面上有「退回」「撤回」两颗钮,
报文里却没有这两个时刻——go_back / reset_task 压根不走 _advance,那两条动作一个字都不发 → §13)

1. 先对齐这五种「什么时候发」

触发点 在哪配 数据是哪一刻的 典型用途
三条终态(办结 / 终止 / 作废) L2 模板 trigger_events(可以多勾,也可以一条都不勾),不挂环节,按绑定表单自动找齐 归档前最后一次落库的 work.data 凭证、台账:单已定局,最安全
到达某环节 L3 挂载 trigger=arrive(旧写法是 L2 模板 trigger_event=activity,只给存量配置留着) 进入该环节那一刻(含上一环节刚改完的值) 付款指令:流程一踏进付款环节就通知资金系统
本环节审批通过后 L3 挂载 trigger=leave 本环节审批人改过的值已落库、路由已选定、还没进下一环节 「部门经理批完就把状态和审批意见回写 ERP」
本环节被退回时 L3 挂载 trigger=goBack(挂在按「退回」的那一环上,不是收单那一环);还能再按退落到哪一环(goBackTo)与这一退是谁按的(goBackVia,第三方调接口退的单独一档)各筛一道(§14) 退回人这次的修改已落库、单子正要被打回去 「审批不通过就把状态与意见回写 ERP,让对面把那张待结算的单解挂」

| 本环节被撤回时 | L3 挂载 trigger=recall(挂在被撤回那条已办所属的环节上;发起环节这一刻 = 发起人撤回自己的提交) | 撤回那一刻(撤回不改表单) | 「对面刚按刚才那条草稿建了单,我这边撤回了,得通知它删掉」 | | 这条流程被终止时 | 既不挂环节、也不在模板上:流程设计 → 流程信息 → 终止 那一格(oa_process.terminate_config.writeback,时刻固定 trigger=terminate) | 终止那一刻的 work.data(归档前最后一次落库的值) | 「只有这一条流程被终止时要通知上游解挂」——写成模板上的终态勾选会被同表单的另一条流程跟着发,挂环节又挂不上(终止不是画布上的一环),§5.5 |

还有一种情况不在这五种里,也不该在这里找:嵌进来的那一页,人没保存就返回了,要通知对面 把按预留单号建起来的那张草稿删掉(embed-configuration-guide.md §2.4)。 那一刻还没有这张单,而模板的报文、条件、幂等键、发件箱全都以单号为前提——所以它不是一条模板, 配在那条「可嵌入页面」上、发在那一趟嵌入会话上。界面把这件事写在两处:「什么时候发」那一格下面直接把 这一档的去处说破,选中的数据源若已被某条嵌入页面用作那个出口,字段下面会当场警告并送人回那条记录 (再建一条办结时模板,办结那一刻也会往同一个删除接口发一句,通常正是要避免的那种事故)。

arrive 与 leave 的区别不是措辞:arrive 是「谁把单送到我这儿我都发」,退回重走会再发一次(幂等键会挡住重复,见 §5), 而 leave 是「我批完、而且确实是往外走才发」——goBack(退回 / 驳回)那一刻不触发(那一刻该发什么写在 goBack 这个时刻上,§13),因为它不是"审批完成"。 挂在环节自身的 leave 还有一条好处:本环节有多个出口(条件分支、多条路线)时只配一次, 不用在每一个下游环节都挂一遍模板。

「本环节审批通过后」指的是这一环节真的办完了:或签一人办结、会签最后一票、依次审批最后一人、按比例会签达到放行线, 这些都算;前面几票办完但环节还没结束的不算。前置加签的回转、超时自动跳过同样按"离开该环节"处理。 发起人提交单据算离开「发起」环节,所以挂在发起环节上的 leave 就是「提交即回写」。

两条常被问到的口径在这儿说死:

  • 同一个环节要两种时机都有(到达时通知一次、批完再回写一次):在这个环节上再加一条规则就行 (writeback.blocks,§2)。两条规则各有时机、模板、条件与失败策略,同一张单可以同时命中「到达时」那条 和「审批通过后」那条。只有一条规则时配置仍旧平铺在顶层,存量配置与导出件都不换形状。
  • 一条规则勾好几个时刻("trigger": ["leave", "goBack", "recall"]):这是"同一份映射、只有状态值不同"那一类回写的正解, 不必复制三份模板。goBack / recall 在幂等键里各多一截时刻段,与「通过后」那条天然分得开;arrive 与 leave 的键一个字节都不变(存量单第二次命中仍旧并回原来那条),它俩挂同一个模板仍旧算撞键(§5 §13)。
  • 别拿同一个模板挂进同环节的两条规则:两条报文的编码、事件、环节全一样,幂等键也一样,第二条会被当成 重复报文吃掉。要分流就各用各的编码,保存流程时这句会点名是哪两条规则撞了(§5)。
  • 模板自己声明的「到达某环节」与挂载并存时互不吃掉:被挂载点名的模板按挂载的时机发,没被点名的按 「到达时」发(§3)。同一个模板别既声明又挂载,那样只会按挂载的时机发一次。
  • 三条终态的模板不要挂到环节上:trigger_event 是办结 / 终止 / 作废的模板,被挂进环节后会在 这一环节和进终态那一刻各发一次,两条报文的幂等键不一样(事件段不同),上游只会当成两笔业务。 保存流程时这条会被挡下来:要么到集成页把这条模板的终态勾选去掉(时机就只听这个环节的), 要么为终态那一刻另发一个编码。

1.5 每种环节都能挂,但"有哪几个时刻"不一样

写回挂载不是审批环节的专属:引擎那两个触发点(到达 / 往外走)写在 _advance 的类型分发之前,与环节类型无关。 所以设计器里每种环节都有一格「写回挂载」,右栏摘要那一行直接写「没挂写回 / 写回 N 个模板」。 例外只有「被退回时 / 被撤回时」这两刻:它们是两颗人工按钮,没有按钮可按的环节压根没有这一刻(见下表最后一列)。

环节 能选的时刻 说明
发起 提交单据时(就是 leave)/ 本环节被撤回时(recall) 单号、标题、表单数据都已落定,"创建时就建上游单据"配在这里。发起环节不会被「走到」,所以没有「到达时」;也没有上游可退——画到发起环节上那条「退回修改」是到达发起环节,不是从它退回,所以它没有 goBack
审批(人工) 到达本环节时 / 本环节审批通过后 / 本环节被退回时 / 本环节被撤回时 完整语义见 §1:或签一人办结、会签最后一票、依次审批最后一人都算"通过",退回不算。后两刻还要求各开着「退回」(allowGoBack)/「撤回」(allowRecall)那颗按钮
分支 / 并发 / 聚合 / 拆分 到达本环节时 / 本环节往外走时 这些环节没有审批人,leave 就是它判定完、自动流出去那一刻——条件分支按结果分流写回就配在这儿
脚本 / 取数 / 子流程 / 定时 到达本环节时 / 本环节往外走时 脚本跑完往外走那一刻发,能把脚本刚算出来的字段带出去
结束 走到结束(归档)时(就是 arrive) 这一刻在 _finish_work 之前:单据还没进终态,{work.status} 取到的是 running。只想要"定局之后"就改用「办结时」的模板(§5.5)
作废 走到作废环节时(就是 arrive) 同上,只是这张单马上要变 canceled。要顺带冲销已发凭证,用配了「冲销模板」的终态模板(§5.5)

五种时刻里只有「这条流程被终止时」不属于任何环节:它配在流程信息面板上,所以每一种环节的「写回挂载」 那一格里都看不见它,反过来说它也不需要点名环节(§5.5)。它仍复用环节挂载那套读法与形状 (mapping.mount_plan / mount_blocks / mount_triggers,时刻取值多一个 TRIGGER_TERMINATE), 条件、按模板分流的字段子集、失败策略、整批 when 与单格 when 全部照旧生效。

时刻与环节对不上时那条写回一条都不会发、而且不报错,所以:界面上不给选(那一格里只摆这一刻能勾的几个), 保存流程时挡、全库体检也报(手改 JSON、导入别处的流程、后来又把按钮关了,都可能配出这种死配置)。 判据只有一份:mapping.TRIGGER_ACTIVITY_TYPES / TRIGGER_ACTIVITY_FLAGS,前端 formWriteback.ts 镜像同一份(§13)。

2. 端到端:报销单「部门经理批完回写 ERP」

  1. L1 接口注册(系统设置 → 数据源,同系统只做一次):方向选「往外写」,填地址、鉴权、超时、 success_path=code / success_value=0 / ref_path=data.voucherNo。测试环境先打开影子模式——报文照渲染照留档,就是不打出去。
  2. L2 写回模板(流程设计 → 集成写回):选数据源、绑定报销表单,「什么时候发」三条终态都不勾—— 这一刻要发的写回由环节说了算,模板这一格本来就答不上来(勾了终态反而会在这一环节和办结那一刻各发一次)。逐行配映射: {form.xxx} 取表单字段、{work.serial} 取单号、{cents:form.amount} 元转分、明细表用 each 逐行、 枚举走数据字典 dictMap。用「按表单字段生成映射」把二十行一次性铺出来,再改上游字段名。
  3. L3 环节挂载(流程设计器 → 选中部门经理环节 → 「审批通过后写回」):勾上模板,触发时机选「本环节审批通过后」, 失败策略按需选「挡住处理人」,需要只发大额单就点「满足条件才发」加一条 applyAmount > 10000。
  4. 校验与试跑(模板页「校验与试跑」):挑一张历史报销单预览报文(不发送),再 dry-run 打一次测试环境。
  5. 保存流程。走到部门经理点同意 → 同一事务里落一条发件箱报文 → 后台线程发出去 → 成功按 ref_path 回显凭证号、 按 result_write 把凭证号写回表单;失败按 1m/5m/30m/2h/6h 退避重试,用满进死信并发待阅。

再来一条「借款单财务复核后回写」:同一个 L1、复制一份 L2 改两行映射、挂到那条流程的复核环节,二十分钟。

环节配置里存下来的就是这一小段(oa_activity.config.writeback,随流程导出一起搬环境):

{ "writeback": {
    "integrations": [                            // 一个环节可挂多个:多系统各发一条,按这里的顺序发
      "erp_expense_sync",                        // 只点名 = 这个环节每张单都发它
      { "code": "mes_reimburse",                 // 或者点名 + 这一格自己的条件:按字段值分流到不同系统
        "when": { "match": "all", "rules": [{ "field": "payWay", "op": "eq", "value": "对公" }] },
        "fields": ["amount", "status"] }         // 或者只发这个模板映射里的某几行(§4.5)
    ],
    "trigger": "leave",                          // arrive(默认)| leave | goBack | recall
                                                 // 也可以一条规则勾好几个时刻:["leave", "goBack", "recall"]
    "when": { "match": "all", "rules": [{ "field": "applyAmount", "op": "gt", "value": 10000 }] },
    "onFailure": "block",                        // 覆盖模板默认;写 on_failure 也认
    "failRoute": ""                              // 见 §6;写 fail_route 也认
} }

integrations 两种写法都认,老配置一行都不用改;界面上就是勾完模板后,那一行右边多一颗漏斗按钮。

一个环节要配多条规则(两种时机都有、或者两套互不相干的条件)时,顶层换成 blocks, 每一块都是上面那个形状,各判各的:

{ "writeback": { "blocks": [
    { "integrations": ["mes_notice"], "trigger": "arrive" },        // 谁把单送到这儿都通知 MES
    { "integrations": [                                             // 批完之后按结算方式分流
        { "code": "erp_pay",  "when": { "rules": [{ "field": "payWay", "op": "eq", "value": "对公" }] } },
        { "code": "fund_pay", "when": { "rules": [{ "field": "payWay", "op": "eq", "value": "现金" }] } }
      ],
      "trigger": "leave",
      "when": { "rules": [{ "field": "applyAmount", "op": "gt", "value": 500 }] },
      "onFailure": "block"                                          // 失败策略是每条规则自己的
    }
] } }

三条口径:一条规则时不用 blocks(面板写回的就是平铺形状,两块以上才换形状); 同一模板被两块选中 = 两条幂等键完全相同的报文,前一条只要还在途 / 已成功 / 结果未知,后一条就被幂等键挡回同一条记录 (等于那一块白配,只有前一条已经是死信时才会换修订版重发),所以保存时直接点名; blocks 与顶层 integrations 同时写时只按 blocks 发,顶层那一串会被静默忽略,所以保存时也要说一句。

同一份映射要在批完 / 退回 / 撤回三个时刻都发(上游那个状态字段只是值不一样)时,不复制模板, 一条规则里把时刻写成数组:

{ "writeback": {
    "integrations": ["erp_state"],
    "trigger": ["leave", "goBack", "recall"]      // 三个时刻 = 三条报文,幂等键分得开(§13)
} }

报文里想知道"这一刻是哪一颗钮",就取 {action.*}(§13):状态字段填 {action.phase_name}、 把审批意见带回上游填 {action.opinion},都不必为三个时刻各配一份模板。

键名两种拼写都认:设计器写进 config.writeback 的是驼峰(跟环节配置里 taskValues / ccRules / routeDecisions 一个习惯),手工拼的 JSON 与导出件习惯用下划线。读取口径只有一处 (mapping.mount_of / mount_failure_policy / mount_fail_route),设计期与运行期共用, 不再出现"界面存 onFailure、运行期读 on_failure、于是谁都没错但什么都没发生"。

3. 「什么时候发」只有三处能配,模板页那一格不算环节入口

这一刻在哪 在哪儿配 能配的东西
这张单走进终态(办结 / 终止 / 作废) 集成页的模板:「什么时候发」那一格 三条可以多勾,也可以一条都不勾(= 这条模板自己不自动发)。按绑定表单找齐,同表单的每一条流程都会发
流程走到某个环节的某一时刻 流程设计器选中环节 →「写回挂载」 时刻(到达 / 办完之后 / 被退回 / 被撤回)、要发哪几个模板、整批条件、每一格的条件、要发的字段、失败策略
只有这一条流程被终止的那一刻 流程设计器 → 流程信息(meta 面板)→「终止」 终止那一刻发哪几个模板、整批条件与单格条件、要发的字段子集、失败策略(oa_process.terminate_config.writeback,§5.5)

环节那一刻不在模板页配。以前那里也有一档「到达某环节」,要人在配模板的时候挑一条流程里的一个环节—— 可那一刻他还没决定这张模板要挂在哪儿,只能挑一个最像的顶上;而环节 id 是每条流程自己的主键, 复制流程、按版本恢复、导到别的环境都会换掉它,于是绑在模板上的那条写回悄无声息地不再发, 发件箱里连一条记录都不留。环节时机挂在环节上(oa_activity.config.writeback)才对得上"随流程导出搬环境"。

模板上那两格(trigger_event=activity + event_key)只为存量配置继续发而留着,界面上不再让新配置选: 打开这样一条模板时,那一格单独摊开写清它现在指着哪个环节,并给一个「搬到这个环节上」的按钮 (POST /design/integrations/{code}/mount)——写挂载与撤声明在同一事务里,中间不会出现 "两边都没配、这一环节一条都不发"的那一档;搬之前先过一遍保存流程时那把尺子(mapping.mount_problems)。

两条仍然有效的口径:

环节挂载点名了的模板,什么时候发听挂载的;挂载没点名、而模板自己声明了「到达某环节」的,按「到达时」发。

mount.integrations 里出现过的模板编码,从模板自带触发那条路不会再发一次(同一环节、同一模板、同一次触发只有一条报文, 幂等键也挡一道)。这条规则的设计期与运行期是同一把尺子(mapping.mount_problems / outbox.enqueue_node), 界面上不用背,只在挂载面板上写一句人话。

配套的一句:挂载上的 when 与 on_failure 也只管挂载自己点名的那批模板。旧写法「到达某环节」那条不归这个挂载管, 本环节的单据条件顺手摁掉别人的报文,就又是个"配置看着对、就是没动静"。

还有一句给配模板的人:「一条都没勾」是合法状态,界面上会当场写"这条模板现在一条都不会自动发", 并给出下面这份清单——两处绑定点合并出来的那一份,模板自己那份配置说不出这个答案。

4. 「部分」有两种:部分环节、部分单据

  • 部分环节:只在需要的那几个环节挂模板,其余环节不挂就是不发。别为了"整条流程都发"去挂发起环节之外的每一环—— 写回点越多,退回时要冲销的越多(§5)。

  • 发往哪个系统(在环节上分流):integrations 里每一项都能带一格 when——「这个环节的这个模板才发这种单」。 同一环节挂 ERP 和资金系统两个模板,ERP 那格写 结算方式 = 对公、资金系统那格写 结算方式 = 现金, 一张单只会命中一个;这一格的条件只管本环节这个模板,同一个模板挂在别的环节上不受它影响。

  • 发往哪个系统(连终态一起分流):模板上的「哪些单才发」(send_condition)。绑定表单管的是"这条写回认哪张单", 这一格管的是"同一张单里哪几笔要发",所以它跟着模板走:挂在环节上、模板自己声明到达、三条终态,都按它筛单。 一张报销单按「结算方式」决定进资金系统还是 ERP,就这么配: ERP 模板 条件 结算方式 = 对公、资金系统模板 条件 结算方式 = 现金,两个模板都挂在同一环节上(或都 配成办结触发),互斥的条件保证一张单只会命中一个。三个细节:条件不成立的那条根本不入库(发件箱里 干干净净,不是发失败);冲销报文不看这个条件(东西已经发出去了,冲销不能被拦在半路); 人工重推也不看(人点重推是明确决定,机器别再拦一次)。

  • 部分单据:挂载上的 when。判据是结构化条件,和表单的条件显隐、条件必填、抄送规则、路由条件完全同一份数据结构 (后端 dicts.condition_ok,前端 ConditionBuilderDialog),运营在设计器里已经会配这些,不用学新东西。 when 不满足时这个挂载点名的模板整批不入队,发件箱里干干净净——它是"这单不该发",不是"发失败了"; 挂在别处的、以及模板自己声明触发的那批不受影响(§3)。 三道条件各管一段,都过才发,顺序是挂载整批 → 这一格 → 模板自己:

    挂在哪 管什么 什么时候用
    规则 when 这个环节的这一条规则里那批模板要不要发 「这一环节只发放大额的单」
    integrations[].when 这一条规则里的这个模板要不要发 同一环节按字段值分流到不同系统
    模板 send_condition 这条写回在任何触发点认哪几笔单(含三条终态) 分流规则要跟着模板走、办结也按它筛

    想知道某张单为什么没发出去,按这三条从上往下核对;三条都不成立时发件里一条记录都不留。 一行字段级的条件(某个字段为空就不发这一格)仍然写在 L2 映射行的 when 上,两层互不干扰。

4.5 同一个模板,这一格只想发其中几个字段

一条写回模板常常被两个地方共用:办结时整份推给 ERP,走到付款环节只要把「金额 + 状态」递过去一次。 为了这点差别再复制一份模板,以后改字段就是改两处、还容易漏一处。所以挂载的每一格都能带 fields:

{ "code": "erp_pay", "fields": ["amount", "status"] }   // 这个环节只发映射里这两行

fields 里写的是模板映射行的目标字段名(L2 那张表的 to),面板上就是勾中模板之后展开的那一列复选框: 不勾 = 整份发(老配置一个字都不变),勾几个发几个,全勾与不勾同义(所以勾到只剩一个时界面不让再点掉)。 范围只在这一个环节的这一格生效——同一个模板挂在别的环节、模板自己声明到达、三条终态,都照旧整份发。

三条口径:存进报文的是入队那一刻勾的那几行(oa_outbound_message.field_scope),所以人工重推 按当时的范围重渲染,不会把人明明没勾的字段悄悄发回去;映射行自身的 when 照旧生效, 先按这一格筛掉一半、再按行级条件筛掉另一半;保存流程时校验字段名——指了模板映射里没有的目标字段会被点名, 免得"勾了个不存在的行"变成静默少发一格。

5. 重复、幂等与退回

情形 会发生什么 配置上该怎么做
同一环节被走两次(退回后重走 / 撤回后重新提交) 第二次入队撞幂等唯一键:已有成功/在途/结果未知的报文 → 不再发第二条,只把那条现有报文返回,发件箱里一条新记录都不留。并回不等于发旧值:那条还没发出去的(pending / 等重试的 failed)按当下最新的字段值重渲染,已成功的与结果未知的不动(§5.2) 对面是「按单号更新」这类幂等写回 → 在模板上勾**「重复到达时重发」**(§5.2);对面是凭证这类发两遍就重复的 → 保持不勾,需要时配 reversal_code 先冲销,或人工在集成页重推(修订版 +1)
一个环节挂两个模板 两条报文,键里带 {code} 所以互不吃掉 别改默认幂等键;自定义键里 {code} 与 {event_key} 是必填段,保存时会挡
环节在并行 / 拆分支线里 同一张单会走到这个环节 N 次,幂等键是 {job}:{event}:{event_key},只发第一条(渲染读的是整单 work.data,分支行数据不在里面,发 N 份一样的报文比发一份更危险) 这一期把写回点设在分叉之外;真要按明细行回写,等"报文按分支行渲染"这条做完再挂(§8)
在「什么时候发」里找不到「没保存就返回」 那一刻还没有单据,这一档不是模板:它配在那条「可嵌入页面」上(§1 末尾) 「外部数据源」→ 那条嵌入页面 →「这一页被放弃时,通知对方」
模板的「什么时候发」勾了终态、又被挂进环节 这一环节发一次、进终态那一刻再发一次,两条报文幂等键不同,上游当成两笔 保存流程时直接挡(§1):到集成页把这条模板的终态勾选去掉,或为终态那一刻另发一个编码
中间环节写回后单据被终止 / 作废 已成功的报文按 reversal_code 自动冲销;没配就只挂 needs_reversal 提醒人工去上游作废 中间环节写回必须想清楚冲销,这是"能晚则晚"的真正理由(§5.5)
同一条报文被两条规则点名(同一模板挂进同环节的两条规则) 幂等键完全相同,第二条直接吃掉,看起来像"少发了一条" 分流要用不同编码;保存流程时按「第几条规则」点名(§2)
一条规则勾了两个时刻(["leave","goBack"]) 两个时刻两条报文:goBack / recall 的幂等键在事件段里多一截(activity:goBack),与「通过后」那条分得开,各发各的 就是一份映射勾三个时刻,别复制三份模板;要按时刻发不同内容,映射里取 {action.phase}(§13)
同环节两条规则都勾「被退回时」、又是同一个模板 落点桶(goBackTo)与来源桶(goBackVia)两边都可能被同一次退回命中才算撞键;一条只管退到发起人、一条只管退到上一环 = 分流,不算重复 真要在同一个落点上各发一条,就到集成页把这条模板的幂等键加上 {target}(要按来源分开就加 {via});保存流程时按「第几条规则」点名(§14)
一张单被退两次(退到不同环节,或一次 OA 一次第三方) 默认幂等键不看落点与来源 → 仍旧只发一条,对面不会被同一个状态打两遍 要"退到 A 一条、退到 B 一条"就在自定义键里写 {target},要按来源分开就写 {via}。加进键就是换键,历史报文不再算重复(§14)
退回之后重走、再批完 第二次「通过后」撞的还是第一次那条键(arrive / leave 的键里没有时刻段,存量口径一字未变)→ 并回,不另发 对面按单号更新就勾「重复到达时重发」(§5.2)。"退回时发一条、批完再发一条"靠的是时刻不同,不是靠勾重发

5.2 「撤回后重新提交,为什么上游没再收到一次」

这是"配置看着对、就是没动静"最常见的一种,而且发件箱里干干净净——第二次入队被幂等键并进了第一条, 既不报错也不留痕,所以从界面上看就像"根本没调用"。真实的一次报销单流转:

时刻 发生了什么 发件箱
18:01:55 退回后重新提交,发起环节「提交单据时」命中 一条 event_key=cr_begin、revision=1、success
22:24:58 又退回、又提交,同一环节再次命中 什么都没有:幂等键 {source}:{code}:{job}:{event}:{event_key}:{revision} 一段都没变

幂等键里唯一会动的是 revision,而它只在"上一条已经是死信 / 已被冲销"这类状态下才会往前跳。 默认口径是每张单每个写回点只成功一次:凭证开出去就是开出去了,重走一遍不该再来一张。

对面是按单号更新(PATCH /api/reimbursements/oa/by-flow-number/{号} 这种)就不一样了: 发起那一刻建的那条记录,退回改了金额再提交,对面躺着的还是旧值。这种写回在模板上勾 「重复到达时重发」(oa_integration.refire_revisit,对环节那一刻的报文有效——挂载点名的那批也算): 再次走到同一环节时,即便上一条已经 success,也按 revision + 1 新入一条、真打一次, 对面据修订版认出是同一张单的新版本。三条边界:

  • 只放行"已成功"那一种撞键:上一条还在途(pending/failed)或结果未知(unknown)时照旧并回那一条, 绝不自动补发第二遍——那是"两张凭证"的来路(§17.1);
  • 并回那一条不等于发旧值:还没出门的报文(pending / 等重试的 failed)在第二次命中时按当下最新的 单据值重渲染(outbox.refresh_pending),报文响应栏留一句「值已刷新」。否则"退回改了金额再提交、 而上一条还排在发件箱里"就成了这次修改永远同步不到对面,而界面上只是"没多一条记录"。请求仍然只有一次: 幂等键、修订版、发件箱行数都不动。已经 success 的那条是"对面收到过什么"的事实,不回改; unknown 那条也不动(补发就是两张凭证)。范围只放环节写回(event=activity)——送审那一路的批次号、 附件清单是调用方当场给的 extra,不在 work.data 里,重渲染会把它们洗掉;
  • 自定义幂等键必须带 {revision}:不带就换不出新键,勾了也白勾,保存模板时直接挡; 真插不进(手工改库改出来的)也不让一次审批 500,入队就地并回上一条;
  • 挂在发起环节上的 leave 同样吃这条规则:退回、撤回都会把单子送回发起环节, 再次提交就是第二次「提交单据时」,面板上那句提示写的就是这个。
  • 「通过后」与「被退回时」不靠这一项区分:默认幂等键只在 goBack / recall 那两刻补一段时刻, arrive / leave 的键一字不变(§13)。所以"同一刻第二次命中要不要再发"仍旧只由这一项决定—— 退回一次、批完一次各发一条是两个时刻,跟勾不勾重发无关。

5.5 办结 / 终止 / 作废那一刻发什么,以及已经发出去的凭证怎么冲销

三条终态不挂环节:在模板的「什么时候发」里勾办结 / 终止 / 作废(三条可以多勾,一条模板就能同时管办结与终止, 不用再复制两份映射),按绑定表单自动找齐(没绑表单的模板视为通用)。

面板底部那块「办结 / 终止 / 作废那一刻发什么」把这个表单上配了终态的模板列出来,哪个环节都没挂也能一眼看全。

5.5.1 「终止时」还有第二个入口:只给这一条流程配

三条终态的模板按绑定表单自动找齐,这带来的正是它的好处也是它的限制:同一张报销表单挂了两条流程 (比如「员工报销」与「领导报销」)时,"终止时要通知上游"这件事没法只给其中一条流程配——模板勾了终止, 两条流程终止时都会发。而终止又不是画布上的一环,挂不到任何一环上,L3 那一格帮不上忙。 所以流程自己留一格:流程设计 → 流程信息(meta 面板)→ 终止(存 oa_process.terminate_config.writeback), 只在这一条流程被终止时发。

比的是 模板自己勾终态(trigger_events) 流程那一格(terminate_config.writeback)
生效范围 绑定这张表单的所有流程 就这一条流程
时刻取值 三条终态可以多勾(办结 / 终止 / 作废) 固定 terminate 一个时刻
条件 / 字段子集 / 失败策略 模板上那道「哪些单才发」 挂载上的整批 when + 单格 when + 每模板字段子集 + on_failure,与环节挂载同一套读法
报文上的辨认 event=terminated、event_key='' event=terminated、event_key=terminate、phase=terminate
谁先入队 outbox.enqueue_event outbox.enqueue_terminate,同一事务、紧接着,仍都在 db.delete(work) 之前(报文要用还没搬走的 work.data 渲染)
冲销 那一刻同样走 handle_reversal 冲销与这一格无关:它只管发,冲销照旧按原模板上填的「冲销模板」处理

同一个模板两处都配就各发一条,不会互相吃掉:幂等键里 event_key 那一段不一样(terminate 对空), 天然两个键。这不是 bug 也不是重复发送,但九成是配的人没意识到自己配了两遍,所以设计器选模板时就地点名 (那一格下面直接写出「这个模板还勾了终止,那一刻会各发一条」)。终止那一刻 {activity.id} 取到空串 (没有环节),{action.phase_name} 是「流程终止时」,{action.opinion} 是终止原因(界面接口上已改成必填)。

这一格是第三处绑定点,三处可见性一处都不许漏(漏一处就等于界面在那儿撒谎):

  • 模板页底部那份「什么时候真的会发」(GET /design/integrations/{code}/firing)如今合并四处: 模板勾的终态 + 旧写法点名的环节 + 环节挂载 + 这一格终止挂载(terminateMounts)。只合前两处时, 一条只被这一格点名、自己什么终态都没勾的模板,在这屏显示"还没有触发点,一条都不会自动发", 而它其实每被终止一次就发一次;
  • 保存流程就报三种病,判据与运行期逐条对得上(mapping.mount_code_problems):模板被删了、 被停用了、绑的是另一张表单——那一条模板那一刻都发不出去,别存进去当没看见;
  • 全库体检(GET /design/integrations/audit)也扫这一格,单独归一类「终止挂载」并给流程设计器的 入口:模板是保存之后才被删、被停用的,保存那道闸这辈子都碰不到这种病(§7.5 同一条理由)。

作废要分三件事,配法不一样:

想要什么 怎么配 落库会看到什么
只通知上游「这张单作废了」 建一个「作废时」触发的模板(终止同理建「终止时」的) 一条 event=canceled 的报文
顺手把之前发出去的凭证冲掉 在原模板上填「冲销模板」指向一个反向报文模板 自动多一条 cancels=原报文 id 的反向报文,原报文状态变「已被冲销」
原模板没填冲销模板 —— 只在原报文上挂 needs_reversal 标记,集成页置顶喊人。机器不猜这张凭证该不该作废
作废之前先做点别的(比如先让人确认) 在流程上画一个「作废」环节,把写回挂在它身上(时刻只有「到达」) 挂在作废环节上的报文 event=activity,终态那条照发,两条互不替代

两条边界要记住:冲销报文不看模板上那道「哪些单才发」(东西已经发出去了,冲销不能被拦在半路), 人工重推也不看(人点重推是明确决定);影子模式的报文根本没打到上游,所以不参与冲销。

6. 失败策略:block 这次是真的,branch 仍然不是

策略 现在的行为
continue 照旧:流程继续走,报文后台重试,重试用满进死信并发待阅,集成页置顶
block 卡住这张单后续环节的办理:报文没落到 success 之前,任何人在待办页点同意都会被告知「这张单有一笔必须成功的写回还没落地」并附模板名与失败原因。放行只有三条路——后台重试成功、集成页重推(要填原因)、结果未知的走人工确认判成功。把模板停用是留给运维的逃生口:停用即不再卡人,同时也不再发新报文
branch 仍不生效。自动改走补救路线要求"在流转那一刻就知道写回结果",与发件箱异步投递的前提冲突(要它就得把外部调用搬回流转请求里)。这一期把 branch 的界面入口撤掉,已存在的配置按 block 执行并在流程保存时明确提示,不再让人以为改道已经生效

block 卡的是人,不是流转:单据照样进到下一环节、照样生成待办、审批记录照样看得懂,只是办不动。 这样退避重试、死信通知、报文快照、人工重推这套东西一行都不用改,也不会出现"单停在半路没人知道"。

7. 这次一共补的十四处

# 问题 修法
1 模板「什么时候发」选到达某环节、填了环节 id,其实一条都不会发:outbox.enabled_templates(EVENT_ACTIVITY) 没有任何调用方,界面上还强制你填 id enqueue_node 在到达环节时把这批模板一并捞出来发(按绑定表单过滤);模板页那个自由文本的环节 id 换成流程 → 环节下拉(GET /design/integrations/activity-options),保存时校验这个环节 id 真实存在、并提示它属于哪条流程
2 表达不出「本环节审批通过后」:引擎只在 _advance 到达 target 时入队,想按 Y 环节触发只能挂到 Y 的下一环节,多出口要挂 N 处 挂载加 trigger;_advance 循环顶部对 source(正在离开的环节)入队 leave,与 arrive 一样在类型分发之前、同事务。一处钩子覆盖提交、审批、超时唤醒、子流程回收、拆分支线
3 「挡住处理人」只是记在报文上,界面自己也写着"不会真的卡住环节" outbox.blocking() + execute_task 入口闸门 + 待办页顶部横幅(GET /job/{job} 多回一段 writeback)
4 挂载层没有单据级条件;分叉内环节的重复问题没人提醒 挂载加 when(设计期 mapping.mount_problems 查字段是否存在于本环节表单,运行期 dicts.condition_ok 判定,
且只管挂载点名的那批);分叉内环节"一张单只发一条"的边界写进面板提示,不再让人以为每行都会发
5 挂载上的失败策略存的是驼峰、读的是下划线(onFailure vs on_failure):界面上选了「挡住处理人」,运行期永远读不到,一路静默按模板默认走 mapping 一处读法两种拼写都认(mount_failure_policy / mount_fail_route),outbox 与 mount_problems 都从这儿拿;面板上那个值也照常回显,不再让人以为选了就该生效

| 6 | 一个环节只有一段 writeback,两种时机 / 两套条件配不到一起,只能把写回挪到别的环节上凑 | 挂载支持多条规则(blocks):mount_blocks 一处读法,只有一条规则时仍旧平铺(存量配置与导出件零改动);mount_plan 按时刻挑块,整批条件、每一格的条件、失败策略都跟着命中的那块走;面板上「再加一条规则」,跨块重复选同一个模板保存时点名 | | 6b | 写回挂载只在人工环节上有那一格:创建时要建单、归档时要回写、脚本环节要按结果分流,全都配不了 | 「写回挂载」进 GROUPS_BY_TYPE 的每一种环节(面板也从 manual 分支里挪出来,不再被 v-else-if 链锁死);发起环节给「提交单据时」、结束/作废环节给「到达那一刻」,时刻配反的那一种界面不给选、保存时挡 | | 6c | 作废那一刻该发什么、已发凭证怎么冲,全靠口口相传;配没配冲销在流程设计器里看不见 | 面板底部列出这个表单上配了办结/终止/作废的模板,并就地标出「没配冲销」;运行期行为见 §5.5 | | 6d | 挂在环节上的模板如果「什么时候发」还是三条终态之一,会在这一环节和终态各发一次,两条报文幂等键不同,上游当成两笔(凭证会开两张) | mapping.mount_problems 在保存流程时点名并给出两条出路;前端 mountProblems 同一句话镜像 | | 10 | 撤回重提 / 退回重走第二次走到同一写回点时一条都不发、也不留记录:按单号幂等更新的接口拿不到改过的字段值,而人在界面上只看得见"没调用" | 模板上加**「重复到达时重发」(refire_revisit,仅「到达某环节」生效):上一条 success 时按 revision + 1 重新入队真发;在途 / 结果未知仍旧并回那一条;自定义幂等键没带 {revision} 时保存被挡,运行期插不进去也不炸审批(§5.2) | | 11 | 同一个模板在 A 环节要整份发、在 B 环节只要两行,只能复制模板改映射,以后改字段改两处 | 挂载每一格带 fields(面板「要发的字段」):按映射行的 to 筛渲染行,范围随报文落 field_scope,人工重推按原范围重渲染;指了不存在的目标字段时保存流程被挡(§4.5) | | 12 | 问错了时候:模板那一格逼人在"还不知道要挂哪个环节"的时候挑一个环节,而环节 id 是每条流程自己的主键——复制流程、恢复版本、换环境都会换掉它,那条写回从此静默不发、发件箱一条记录都不留;同时 trigger_event 是个标量,「办结和终止都要通知上游」只能把模板复制两份,两份映射从此各改各的 | 「什么时候发」收成两处:模板那一格只剩三条终态的清单**(trigger_events,可多选、可全空;读法只有 mapping.terminal_events_of 一处,空清单回落老标量,存量零迁移),环节时刻只在 L3 挂载上配;旧写法给一个「搬到这个环节上」的按钮(写挂载 + 撤声明同一事务),旧写法又勾终态 → 保存就挡;GET /design/integrations/{code}/firing 把两处合并成「什么时候真的会发」摊在模板页。「重复到达时重发」也不再被模板自己勾的触发点吃掉(挂在环节上的那批以前存进去就是 False)(§1 §3) | | 13 | 上面那些校验只在保存那一刻生效,而这一片的病绝大多数躺在"上一次保存时还是好的"那些行里:环节 id 被复制流程换掉了、挂载点名的模板被删了、终态与挂载又两头点名——一处都不报错,发件箱一条记录都不留,只有单子走到那一刻才发现。顺带一处同族的:JSON 数组列不能写 DEFAULT,补列那一步靠 db._backfill_literal 猜模型默认值的形状,而它认 default=list 的方式(arg is list)在 SQLAlchemy 2.0 里永远不成立,于是新加的 trigger_events(以及当年的 data_unit_ids)在每一行存量里都存成 {},每次启动念一句警告、永远修不掉 | 加全库配置体检(§7.5):integrations.audit(db) 复用同一把尺子(模板走 _problems、挂载走 mount_problems)扫一遍,GET /design/integrations/audit 摊在集成页顶部那条横幅上,每条都带跳转目标;scripts/check_writeback_config.py 先报现库再造一遍病自证。回填改成把那份默认值真调一次看形状(default=list 被包了一层 wrapper,得先剥 __wrapped__),这一列也补进启动自检的清洗名单 seed.JSON_LIST_COLUMNS | | 14 | 界面上明明有「退回」「撤回」两颗钮,报文里却没有这两个时刻:想要"这张单被打回去了也告诉上游一声",只能把写回挪到收单那一环的「到达时」,归属当场错位(对面分不清是正常到达还是被打回),而且退回并不会触发那一环的 arrive——go_back() / reset_task() 自己派待办,压根不走 _advance,那两个时刻一条报文都不入、发件箱零记录 | 时刻从两种扩到四种(mapping.TRIGGERS,设计期与运行期共用一把尺子),钩子加在 go_back(挂在被退回那一环)与 reset_task(挂在被撤回那条已办所属那一环)里,与动作同一事务;幂等键只给这两刻补一截时刻段,存量键一字不变;新增 {action.*} 取值;一条规则可勾多刻;面板那一格从单选换成勾选框并按环节类型与 allowGoBack/allowRecall 过滤,死配置保存时与全库体检都点名(§1 §1.5 §13) |

7.5 配置体检:保存那道闸之外,还得有人回头扫一遍

§7 那十四处修的全是"保存的时候挡住"。但这一片真正的失效长成另一副样子: 上一次保存时它是对的,之后环境变了。

病 为什么保存那道闸管不到 现场症状
模板上那句「到达某环节」指向一个已经不存在的环节 存的是某一条流程自己的环节主键:复制流程、恢复版本、导到另一套环境都会换掉它,而模板那次保存早就过去了 一声不响,发件箱零记录
环节挂载点名的模板被删了 / 停用了 / 绑到别的表单上了 病在别人那一边:删模板的人看不见这一环,改表单的人也不知道 走到那一环节一条都不发
挂在环节上又勾了终态 两个时刻各发一次,两条报文幂等键不同 上游当成两笔,凭证开两张
勾了「重复到达时重发」而幂等键没带 {revision} 勾完之后只改过幂等键,或者这行是导入进来的 第二次走到这一环节,什么也没发生
「被退回时 / 被撤回时」配在了没有这一刻的环节上,或配在按钮已被关掉的环节上 按钮是这一环的配置,关掉它的人不知道有别的写回指着它;导入的流程件更是直接带进来 走到那一环节一条都不发,phase 那一列一片空白(§13)

所以这一层只有三件事,都不新写判断:

  1. 一把尺子扫全库:api/integrations.audit(db),模板走 _problems(与保存模板同一条路,含"环节 id 还在不在"), 挂载走 mapping.mount_problems(与保存流程同一条路)。两张表都是几十行的配置表,全扫也就几十次查询。
  2. 摊在界面上:GET /design/integrations/audit(读接口,design:integration),集成页顶部那条横幅逐条点名, 模板那一类点一下就跳进这条模板的编辑器,挂载那一类给流程设计器的入口。横幅只报数不解释: 每一条文案本身就带着出路(这是 §7 那一列文案的复用,不是新写一套话术)。 体检读不到(比如只有读权限)就当没说,不弹错——它是附加的一格,不能把模板列表一起拖倒。
  3. 跑在闸门上:python3 scripts/check_writeback_config.py。它先按现库报一份(部署到新环境第一件事就该看见), 再故意把每种病各造一遍——体检工具自己没人验过,它那句"一切正常"和最初的"没人发现"是同一种失效。 现库有病就退出码非 0,只想看报告加 --report。

8. 仍然要写代码的五种情况

上游要特殊签名(加一个 auth_type)/响应不是 JSON(加一个 parser)/传输不是 HTTP(加一个 transport)/ 转换函数缺了(八个不够用,每个几小时)/一次业务要串多个接口(别造编排引擎:在流程上挂三个环节各发一条,流程就是编排器)。 另外两件事同样属于"要写代码"而不是"要配一下":§6 的 branch 需要"环节挂起—写回落地—续流"这套引擎能力;拆分支线里按明细行各发一条,需要发件箱把报文渲染上下文换成那一行(现在读的是整单 work.data)。

9. 验收清单

  • 模板选「到达某环节」并挑一个真实环节 → 流程走到该环节即入队发信;换成不存在的 id 时保存被挡;
  • 环节挂载 trigger=leave → 本环节同意后才发;同一环节上「到达时」那份与「审批通过后」那份互不串台(到达时不会把 leave 那份带出去);
  • 同环节被退回重走 → 第二次同意不再发第二条(幂等键撞上已有的在途 / 成功 / 结果未知报文,只回那一条);
  • 本环节按「退回」→ 挂在被退回那一环上的 goBack 入队一条,leave 一条都不入,收单那一环的 arrive 也不入, 退回本身照样办得动;按「撤回」→ 挂在被撤回那条已办所属环节上的 recall 入队一条,表单没被改过(撤回不改表单);
  • 一条规则勾 ["leave", "goBack", "recall"] → 三条报文、三个幂等键(新两刻的键里多 :goBack / :recall, leave 那条仍旧是老形状);同一模板勾 arrive + leave 仍旧算撞键、保存被挡; 人工重推保留原来那个时刻与按钮快照,只跳修订版;
  • 映射里写 {action.route} / {action.opinion} → 退回那一刻取到的是这条退回线在设计器里的名字与这一次的意见, 三条终态那一刻渲染成空串;写成 {action.不存在的字段} → 保存模板被挡,界面与后端各说一遍;
  • 非人工环节勾「被退回时 / 被撤回时」、或把 allowGoBack / allowRecall 关了还配着那一刻 → 保存流程被挡、 全库体检也报;界面上这两格根本不出现(已经存着脏值时照旧摆出来并喊一句死配置);
  • 勾了 goBackTo: ["@starter"] → 只有退回到发起人那一刻发这一条,退到上一环节时这一条不入队、不留报文、不算失败;勾了 goBackVia: ["oa"] → 第三方调 /open/* 退回来的那一单不发这一条(报文里 {action.via} 取到的是 open);两格都不写的 存量配置仍旧任何退回都发;勾了一个这一环永远退不到的落点、通道名写错、写成 []、没勾「被退回时」却写了这两格 → 保存流程被挡、全库体检也报(§14);
  • when 不满足 → 发件箱里没有这条记录(不留死信),而挂在别的环节 / 模板自己声明触发的报文照发;
  • 一张表单按字段值分流:在环节挂载上分流 → 只命中条件成立的那个模板,另一个连报文都不入库; 在模板上分流 → 节点写回与办结那一刻都按同一道条件筛;
  • 挂载整批条件与某一格的条件同时存在 → 整批那条压过每一格(不满足时这一环节一个都不发, 但模板自己声明「到达本环节」的别的模板照发);
  • 模板条件或某一格的条件指了不存在的字段、或挂了空条件 → 保存模板 / 保存流程被挡;
  • 终态模板被挂进环节 → 保存流程被挡;没挂环节的终态模板照旧在办结那一刻发一条;
  • 一个环节两条规则(到达时 + 审批通过后)→ 到达时不会把 leave 那条带出去,批完时才按各自条件分流; 第二块自己配的 onFailure=block 真的落到报文上并卡住这张单,报文落地后放行;
  • 第二块的整批条件不成立 → 这一块的模板一个都不入库,第一块照发(块与块互不牵连);
  • 同一模板被两条规则都选中 / blocks 与顶层 integrations 同时写 / 某一条规则没勾模板 → 保存流程被挡,提示点名到第几条;
  • 发起环节挂写回 → 提交那一刻入队(event_key 是发起环节 id);结束环节挂写回 → 归档那一刻入队;
  • 时刻配反(发起环节选「到达时」、结束或作废环节选「审批通过后」)→ 保存流程被挡;界面上这两个选项根本不出现;
  • 单据走作废环节 → 「作废时」的终态模板入队;配了冲销模板的原报文自动发反向报文并标成「已被冲销」, 没配的那条只挂「需人工作废」标记;办结那一刻不会把作废那条一起发;
  • 面板存下来的 onFailure(驼峰)与手写的 on_failure → 两种拼写都在保存时校验、运行期都真生效(报文的 on_failure 落的是 block);
  • on_failure=block 且上游打不通 → 下一环节审批人点同意被挡、提示带模板名与原因;集成页重推成功后可正常办理;把模板停用后立刻放行;
  • 拆分支线上的环节 → 一张单只入队一条,面板上把这句写在明面上;
  • 同一环节走两次(撤回重提 / 退回重走)→ 不勾「重复到达时重发」时第二次并回上一条、发件箱不多行; 勾上则新增 revision + 1 一条并真的再打一次;上一条还在途 / 结果未知时勾了也不补发; 自定义幂等键没带 {revision} 又勾了这一项 → 保存模板被挡;
  • 映射里写 {activity.id} → 提交时是发起环节、到达时是到达的那一环(同一份报文里的环节名仍是上一环)、 审批通过后是本环节,且与这条报文的 event_key 同一个环节;人工重推照原来那一环;终态那一刻是空串; 写成 {activity.别的东西} → 保存模板被挡,界面与后端各说一遍;
  • 挂载那一格勾了「要发的字段」→ 报文里只有那几行,field_scope 记下这个范围,人工重推仍按这个范围渲染; 同一个模板挂在别的环节、模板自己声明到达、三条终态照旧整份发;勾到只剩一行时界面不让再点掉; 指了模板映射里没有的目标字段 → 保存流程被挡;
  • 「什么时候发」勾两条终态(办结 + 作废)→ 那一刻各入一条,没勾的终止一条都不入;只有老标量的存量行照旧在办结那一刻入队; 一条都不勾 → 存得住、三条终态一条都不入、模板页「什么时候真的会发」写"还没有触发点";把环节的时刻(leave)误填进这一格 → 保存被挡,不是被清洗掉;
  • 旧写法「到达某环节」的模板 → 模板页摊开说清它指着哪个环节;点「搬到这个环节上」之后:环节挂载里有它、模板那一格变成不自动发、 到达那一刻真的入队一条;再搬一次被挡;旧写法 + 勾终态 → 保存被挡;
  • 挂在环节上、自己写着不自动发的模板 → 勾得住「重复到达时重发」(存进去仍是 True);勾了它而幂等键没带 {revision} → 保存被挡;
  • 第二次命中撞上一条还没发出去的报文 → 不另起一条(幂等键与修订版都不变),但那条报文换成最新字段值, 响应栏留「值已刷新」;已 success 的那条即使后来字段又改了也不回改;unknown 那条不动;
  • 全库配置体检(§7.5)→ 现库那份报得出来;模板指向已消失的环节 / 终态格里混进环节的时刻 / 勾了重发却没带 {revision} / 冲销模板被删 / 挂载点名已删的模板 / 挂在环节上又勾了终态 / 分支环节配「被退回时」/ 按钮关了还配那一刻 → 八种病各造一次,每一种都被点名;同一模板勾两个时刻(leave + goBack)这一条新用法不被误判成重复, 而 arrive + leave 同模板仍旧点名;干净的那条模板不冤枉;每条结论都带着能跳转的目标; 挂载那一层的病落在流程上(不是模板上);脏成 {} 的 trigger_events 被启动自检洗回数组;
  • 流程那一格终止挂载(§5.5.1,scripts/check_terminate_control.py D 组)→ 终止那一刻入队一条, 报文认得出是终止发的(event=terminated / event_key=terminate / phase=terminate 且渲染得出单号); 办结那一刻一条都不误发;挂载上的条件不成立时不入队、不留死信;模板绑的是另一张表单不发; 模板被停用也不发(界面那句「已停用,终止那一刻不会发出去」必须是真的); 同一模板既挂这一格又勾了终态 → 两条报文、两个幂等键,不静默吃掉一条;配了冲销模板时终止自动反向冲一条;
  • 这一格的三种可见性(同上 F 组)→ 保存流程点名三种病(模板被删 / 被停用 / 绑错表单),没病的那条不冤枉, 还没定表单时不判绑错表单那条;GET /design/integrations/audit 扫到它并单独归「终止挂载」一类; GET /design/integrations/{code}/firing 的 terminateMounts 带上它,没被任何一格点名的模板那一栏是空的 (IntegrationView.trigger.spec.ts / IntegrationView.audit.spec.ts 各钉一条);
  • 集成页那条横幅(IntegrationView.audit.spec.ts)→ 有病才出现、条数与逐条点名都对、 模板那一类点一下跳进编辑器、挂载与终止挂载那一类给流程设计器入口、体检读不到时不弹错也不拖倒列表;
  • 前端 npx vue-tsc --noEmit 干净、vitest 113 份 1259 项全绿(含 IntegrationView.trigger.spec.ts、 IntegrationView.audit.spec.ts 与新加的 formWriteback.moments.spec.ts(14 条)/ WritebackPanel.moments.spec.ts(7 条),以及终止那一组的 terminateConfig.ts(18 条)/ approvalRecord.terminate(8 条)/ ApprovalRecord.terminate(5 条)/ ProcessDesignerView.terminate(8 条)/ WorkDetailView.terminate(9 条)/ CreatedListView.terminate(3 条))、 后端 scripts/check_writeback_trigger.py(30 项)、scripts/check_writeback_revisit.py(36 条)、 scripts/check_outbox_wake.py(13 条:入队提交当场叫醒、回滚与无变化的并回不空叫、值变了要刷新也叫醒、一轮发干净一张单)、 scripts/check_writeback_action.py(42 条,§13)、scripts/check_writeback_config.py(17 项)、 scripts/check_seed_repairs.py(23 项)、scripts/check_schema_bootstrap.py(20 项)、 scripts/check_terminate_control.py(55 项,全程内存 sqlite,一条语句都不碰生产库)、 check_schema_snapshot.py、check_schema_bootstrap.py、check_globals.py 全绿;eslint 这一层本次改到的文件干净, 只剩 NodeInspector.vue 那十条 vue/no-mutating-props——它们是仓库既有欠账(HEAD 版本同样十条),不在这次范围里。

11. 两处报文取值的口径(2026-10-24 用真流程验出来的,别再靠猜)

scripts/check_writeback_revisit.py 跑一条真流程(发起→复核→总监→归档,影子模式数据源)把这两句钉住了:

  • 「到达本环节时」那一刻,报文里的 {work.activity_name} / {work.current_activity_names} 读到的还是上一环—— work.activity 这个游标要到 _arrive_manual 才翻过来,而报文入队排在它之前。所以想在"到达时"的报文里 说明"这是哪一环",别拿 {work.activity_name},用下面那一格。
  • 要在报文里点名"这是哪一环",写 {activity.id}(还能取 name / alias / type)——2026-10-24 补的取值写法 (mapping.ACTIVITY_FIELDS)。它取的是触发这条报文的那一环,与幂等键里的 {event_key} 是同一个环节, 上面那条游标问题绕开它:提交单据时是发起环节、到达时是到达的那一环(同一张报文里环节名那格仍是上一环)、 审批通过后是本环节,人工重推也照入队那一刻那一环渲染(改过图、单子挪了位置都不换)。三条终态不挂环节, 那一刻渲染成空串,不报错也不卡办理。对面拿它调 POST /api/v1/open/nodes/{流程编号}/{环节 id}/decide (node-open-approve-design.md)。环节 id 只在所属流程内有意义, 复制流程、导到别的环境都会换掉它——所以它只能随报文现给,谁都不该抄下来长期存着; 要现号就调 POST /api/v1/open/nodes/locate,那边的接口卡片已经把整条地址填好了。
  • 模板声明的「发到哪个环节」与环节挂载指的环节不是同一个时,两处各发一次(幂等键里 event_key 不同, 上游收到两笔)。想只在挂载那一刻发,就把模板的「发到哪个环节」也指到同一个环节;这条不是重复入队的 bug, §3 那句"挂载点名的模板什么时候发听挂载的"只管同一环节上的时机选择。

最后更新:2026-10-24({activity.*} 取值写法:报文里终于能点名是哪一环;「什么时候发」拆成终态清单与环节挂载两处:配模板的时候不必再猜环节;§7.5 全库配置体检:那些"上一次保存时还是好的"、之后环境变了才烂掉的行,从此有人回头扫)

12. 方法被模板盖掉、常量成了字符串(2026-10-26 生产上这两条叠在一起咬人)

发件箱里躺着一条 404:404 page not found,而数据源测试那一栏是绿的。两个坑叠在一起:

  • 模板上的「方法」压过数据源上的方法:mapping.render_for 取的是 template.method or source.method or "POST"。集成页模板编辑器里那个「方法」下拉,在模板没写过方法时 显示的就是 POST,于是"打开模板看了一眼、点了保存"就把数据源上那条 PATCH 改成了 POST。 对面那个 Go 服务在这个地址上只注册了 PATCH(改)与 DELETE(删草稿)两条路由, POST 撞的是路由层的 404,和"这张单找不到"那种业务 404({"code":404,"message":"未找到对应 OA 流程编号的报销单"}) 根本不是一回事——看 body 是不是 404 page not found 就能分开这两件。 而「数据源测试」发的是数据源自己那份 method + body_template,压根不经过模板, 所以"测试通过、真写回 404"是这条链路的固有现象,不是偶发。判据一句话:发件箱「发往」那一行的方法 是不是数据源上那一个;模板改过方法之后,存量那条失败报文不会自己换方法重发(重试发的是入队那一刻 存下来的那一份),要在集成页点「重推」才会按新模板重渲染(修订版 +1)。
  • {const:1} 渲染成字符串 "1":写回与取数原本各有一份写法解析,取数那份会把能当 JSON 标量读的常量 给原类型,写回那份只会给字符串。对面 is_review_allowed 是 *bool,带引号实测直接 400 invalid request: boolean value must be 0, 1, false or true。现在两边共用 binding.const_literal(mapping.Ctx.value_of 的 const 分支):{const:1}→1、{const:true}→true, 读不动的({const:13%}、{const:[1,2]})照旧原样给,混在句子里(共 {const:1} 项)照旧拼成字符串, 这四条由 scripts/check_binding.py 钉住。不等发版的临时写法:那一格填派生值脚本 int(value)。

顺带一句:想把单号塞进路径之前先确认对面收不收——{...} 在「接口路径」那一格里不会被替换 (url_for 拼的就是原字符串,写 {form.processNo} 会把花括号一起发出去),报销那个服务要的是 body 里的 oa_flow_number。反过来,取数那一条通道上的「接口地址」是替换的(fetch.render_url, 参数写在查询串与路径段上都行,值按 URL 编码),别把两句读成同一句:判据是这条源往外写还是往里取, 见 external-data-simplification.md §1.5。

最后更新:2026-10-26(§12:模板上的「方法」会盖掉数据源那个,且数据源测试测不到这一层; {const:…} 在写回里终于和取数同一个类型口径;scripts/check_event_prune_race.py:清理脚本删掉事件行的 那一瞬间不再把整轮投递带崩)

13. 「本环节被退回时 / 被撤回时」这两个时刻是怎么来的(2026-10-28)

问得最多的一句:既然有「到达本环节时」和「本环节通过后」,凭什么不能有「本环节被退回」「本环节被撤回」? 答案不是"不该有",是引擎里从来没有那两个钩子。

arrive / leave 都挂在 _advance 上(循环顶部对正在离开的 source 入队 leave、派发待办之前对 target 入队 arrive,两处都在环节类型分发之前,所以每种环节都能挂)。而退回与撤回根本不走 _advance: go_back() 与 reset_task() 自己写审批记录、自己调 _arrive_manual 派待办,压根不经过那两个入队点, 于是那两个时刻一天到晚一个字都不发——这不是配置能绕过去的,绕过去的写法(挂到收单那一环的「到达时」) 连归属都是错的。

新时刻 钩子在哪 挂在哪个环节上 那一刻的表单是什么
goBack(本环节被退回时) engine.go_back(),在 _arrive_manual 派发之前、与退回同一事务 按「退回」的那一环(origin),不是收单那一环 退回人这次的修改已落库
recall(本环节被撤回时) engine.reset_task(),同样在派发之前、与撤回同一事务 被撤回那条已办所属的环节;发起环节提交出去的那条也撤得动(发起人撤回自己的提交) 撤回不改表单,取到的还是原来那份

三条口径钉死在这儿,别再回退:

  • leave 的语义一个字没动:退回不触发 leave(否则"批完就开凭证"会在退回时白开一张),撤回也不触发; 被退回那一环重走之后再批完,才算一次 leave。同理 arrive 也不触发——退回与撤回都不经过 _advance, 所以收单那一环的「到达时」同样不会发,别指望它替 goBack 说话。
  • 幂等键只给这两刻补一段:goBack / recall 的事件段变成 activity:goBack / activity:recall, 于是同一份模板勾「通过后 + 被退回 + 被撤回」= 三条互不吃掉的报文,一份映射管四刻; arrive / leave 的键一个字节都不变,升级之后在途的旧单第二次命中仍旧并回原来那条, 不会有人平白多收到一张凭证。要在自定义键里自己分时刻,用新增的 {phase}。
  • 报文里说得出是哪一颗钮:{action.phase}(arrive / leave / goBack / recall)、 {action.phase_name}(中文那一句,直接能当状态值发出去)、{action.route} / {action.route_alias} (那条线在设计器里的名字与别名:按退回时取的是这一次真正走的那条退回线,超时自动驳回取的是系统自动选中的那条)、 {action.decision}(这条出口的决定语义,如 approve / reject / goBack;环节上 routeDecisions 的覆盖也算数,与引擎当场判退回用的是同一份)、 {action.opinion}(审批意见,截 500 字——发件箱是账,不是正文仓库)。三条终态与集成页手工送审那一路 没有按钮,这些取值渲染成空串,与 {activity.x} 在终态那一刻同一口径,不报错也不卡办理。 按钮那一份快照随报文落 oa_outbound_message.action_data,人工重推照原样重渲染; 时刻本身落 oa_outbound_message.phase,发件箱列表与报文详情因此写得出"这一条是被退回时发的那一条"。

哪些环节能勾哪一刻(mapping.TRIGGER_ACTIVITY_TYPES / TRIGGER_ACTIVITY_FLAGS 一份, 前端 utils/formWriteback.ts 镜像同一份):goBack 只给审批环节、且这一环开着 allowGoBack; recall 给审批环节与发起环节、且开着 allowRecall;其余环节没有人工按钮,这两刻勾不出来。 配成勾不出来的样子(手改 JSON、导入别处的流程件、或者后来才把按钮关掉)= 一条都不发的死配置: 保存流程时 mapping.mount_problems 点名,全库体检(§7.5)同样点名,界面上那一格不摆这一项、 但已经存着脏值时仍旧摆出来并喊一句(不能让人以为值被面板吃掉了)。

验这一片的是 scripts/check_writeback_action.py(42 条):跑一条真流程把 leave / goBack / recall 三个时刻各发一条、{action.*} 每一格取到什么、幂等键到底长什么样、人工重推保留原时刻与按钮快照、 没勾「重复到达时重发」时第二次命中照旧并回、退回既不触发 leave 也不触发收单那一环的 arrive、 撤回不改表单,外加九种死配置在保存时被点名。设计器那一格由 WritebackPanel.moments.spec.ts 与 formWriteback.moments.spec.ts 钉住(四时刻的顺序、勾第二个存数组、 只勾一个时不让点掉、没有那一刻的环节不摆这一项、按钮关了不摆但脏值仍旧摆)。

再往细一层「退回到哪个环节才发」「这一退是谁按的才发」见 §14(goBackTo / goBackVia 两格), 判据与来龙去脉在 goback-target-writeback-design.md。

14. 「退回到哪一环才发」与「这一退是谁按的才发」(2026-10-28)

「本环节被退回时」原本是一视同仁的:不管退到发起人还是退到上一环节,命中的都是同一批挂载。 现在那一条规则上多了两格,都只在勾了「被退回时」时才算数,两格都不写 = 任何退回都发(存量配置一字未动):

{ "writeback": {
    "integrations": ["erp_state"],
    "trigger": ["leave", "goBack"],
    // 只有退回到「发起人」或「部门经理」那一刻才发这条 goBack
    "goBackTo": ["@starter", "act_dept_manager"],
    // 且只发审批人在 OA 里点的那些;第三方自己调接口退回来的不要再回发一条回声
    "goBackVia": ["oa", "oa_confirm"]
} }
  • 认什么:认引擎这一次真正算出来的落点(go_back 里 _resolve_goback_target 的结果), 不看画布上那条 decision=goBack 线的终点,也不看待办下拉里人挑的那一项——线只是画布上的说法, 下拉只是建议,真正落哪儿还可能被环节上的 goBackTarget 钉死。
  • goBackTo 三档混着勾(任一命中即发):@starter 退给发起人、@prev 退到上一环节 (= 候选清单第一个,人不挑时引擎自己选的那一个)、环节 id。两种拼写(goBackTo / go_back_to)都认。
  • goBackVia 认的就是引擎那四条通道,不另立词表:oa 待办页那颗按钮、oa_confirm 外部表了态 人在 OA 横幅上点头、open 第三方直接调 /open/tasks/{id}/execute 或 /open/nodes/…/decide、 embed 嵌入页 decide 与引擎替父单点的子流程。第三方退回不是另一件事:那几路最后全都汇进 go_back(),同一处算落点、同一处入队,所以这两格对人和对接口一视同仁。
  • 两格是 AND:先过来源、再过落点,任一没过这一刻这条规则就当没存在过。与 when 的关系是 再往后一道(时刻 → 来源 → 落点 → 整批条件 → 那一格的条件)。
  • 报文取得到:{action.target} / {action.target_name} / {action.target_alias} 说退到哪一环, {action.via} / {action.via_name} 说这一退走的哪条通道;四个时刻都带来源(到达那一刻带的是 把单子送到这一环的那颗钮走的通道)。发件箱那一行与详情也写明「退回至:财务复核 · 来源:第三方开放接口」。
  • 别和环节配置上那两个老键搞混:goBackConfig(那颗按钮能挑到哪几个环节)、 goBackTarget(按出口名把落点钉死成某一环)、本次新增的 goBackTo(落到哪几环才发这条写回)。
  • 幂等键默认不动:...:activity:goBack:<本环节>:<修订版>,落点与来源都不进键——一张单退两次 仍旧只发一条。要各发一条就自定义键里写 {target} 或 {via}(新增的两个取值,加进键就是换键)。
  • 候选清单只有后端一份:那一格里能摆什么,问 POST /process/processes/{id}/goback-options (engine.goback_universe:绕开回头线的上游可达 ∩ goBackConfig 收窄 + 永远挂着的发起人)。 前端自己再算一遍图,就会出现"下拉里给得出、点确定被引擎拒掉"。
  • 不做什么:撤回那一刻没有这两格(落点永远是本环节自己);超时自动退回与延时自动流转记成 oa (那一路没有"按的人",也不该因此绕开 OA 按钮锁定);不拆到单个模板那一格(要"退到 A 发模板 1、 退到 B 发模板 2"就再加一条规则,各带各的 goBackTo);goBackVia 只筛退回这一刻, 「通过后」要按来源分开发,暂时先取 {action.via} 在报文里分岔。

验这一片的是 scripts/check_writeback_goback.py(56 条):跑一条真流程把五种退回各走一遍 (OA 退发起人 / OA 退上一环 / 第三方走画布那条 goBack 线 / 第三方退到上一环 / 同一张单退两次), 逐条数哪份规则发了哪份没发,外加 {target} 分得开而默认键分不开、人工重推保留落点与来源、 goback_universe_for 那份候选清单、九种死配置在保存时被点名、桶相交才算撞键。设计器那两格由 WritebackPanel.goBackTo.spec.ts 与 formWriteback.goBackTo.spec.ts 钉住。

最后更新:2026-10-28(§14:「退回到哪一环才发」goBackTo 与「这一退是谁按的才发」goBackVia—— 落点认引擎算出来的那一个、来源认引擎那四条通道,第三方调接口退回与人在 OA 里点走的是同一个钩子; 两格是 AND、都不写等于任何退回都发;默认幂等键不动,{target} / {via} 可选进键;撞键改成两桶都相交才算; §1 §5 §9 §13 同步)

上一轮:2026-10-28(§13:「本环节被退回时 / 被撤回时」两个新触发时刻——goBack 挂在按退回的那一环、 recall 挂在被撤回那条已办所属那一环,钩子在 go_back / reset_task 里;幂等键只给这两刻补一段、 存量键一字不变;新增 {action.*} 取值与 {phase};一条规则可勾多个时刻;§0 §1 §1.5 §2 §5 §7 同步)