# 流程中间环节写回:某几个环节审批完成后反写字段,怎么配 > 三层配置模型、发件箱、幂等与冲销的总设计在 [outbound-integration-design.md](outbound-integration-design.md)。 > 本文只回答一个问题:**流程里某几个环节审批通过之后要把字段反写给业务系统,界面上到底要配哪几处、每一处是什么语义**。 > 配套阅读:[integration-master-plan.md](integration-master-plan.md)(总路线)、[form-data-integration-design.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](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`,随流程导出一起搬环境): ```jsonc { "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`, 每一块都是上面那个形状,各判各的: ```jsonc { "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` 发,顶层那一串会被静默忽略,所以保存时也要说一句。 **同一份映射要在批完 / 退回 / 撤回三个时刻都发**(上游那个状态字段只是值不一样)时,不复制模板, 一条规则里把时刻写成数组: ```jsonc { "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`: ```jsonc { "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](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](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](goback-target-writeback-design.md)。 ## 14. 「退回到哪一环才发」与「这一退是谁按的才发」(2026-10-28) 「本环节被退回时」原本是**一视同仁**的:不管退到发起人还是退到上一环节,命中的都是同一批挂载。 现在那一条规则上多了两格,都只在勾了「被退回时」时才算数,**两格都不写 = 任何退回都发**(存量配置一字未动): ```jsonc { "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 同步)