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

605 lines
71 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 流程中间环节写回:某几个环节审批完成后反写字段,怎么配
> 三层配置模型、发件箱、幂等与冲销的总设计在 [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`(挂在**被撤回那条已办所属的环节**上;发起环节这一刻 = 发起人撤回自己的提交) | 撤回那一刻(撤回**不改表单**) | 「对面刚按刚才那条草稿建了单,我这边撤回了,得通知它删掉」 |
**还有一种情况不在这四种里,也不该在这里找**:嵌进来的那一页,人**没保存就返回**了,要通知对面
把按预留单号建起来的那张草稿删掉([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) |
时刻与环节对不上时那条写回一条都不会发、而且不报错,所以:**界面上不给选**(那一格里只摆这一刻能勾的几个),
**保存流程时挡**、**全库体检也报**(手改 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. 「什么时候发」只有两处能配,模板页那一格不算环节入口
| 这一刻在哪 | 在哪儿配 | 能配的东西 |
| --- | --- | --- |
| 这张单走进终态(办结 / 终止 / 作废) | 集成页的模板:「什么时候发」那一格 | 三条可以多勾,**也可以一条都不勾**(= 这条模板自己不自动发) |
| 流程走到某个环节的某一时刻 | 流程设计器选中环节 →「写回挂载」 | 时刻(到达 / 办完之后)、要发哪几个模板、整批条件、每一格的条件、要发的字段、失败策略 |
**环节那一刻不在模板页配**。以前那里也有一档「到达某环节」,要人在配模板的时候挑一条流程里的一个环节——
可那一刻他还没决定这张模板要挂在哪儿,只能挑一个最像的顶上;而环节 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 办结 / 终止 / 作废那一刻发什么,以及已经发出去的凭证怎么冲销
三条终态**不挂环节**:在模板的「什么时候发」里勾办结 / 终止 / 作废(**三条可以多勾**,一条模板就能同时管办结与终止,
不用再复制两份映射),按绑定表单自动找齐(没绑表单的模板视为通用)。
面板底部那块「办结 / 终止 / 作废那一刻发什么」把这个表单上配了终态的模板列出来,哪个环节都没挂也能一眼看全。
**作废要分三件事**,配法不一样:
| 想要什么 | 怎么配 | 落库会看到什么 |
| --- | --- | --- |
| 只通知上游「这张单作废了」 | 建一个「作废时」触发的模板(终止同理建「终止时」的) | 一条 `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` 被启动自检洗回数组;
- 集成页那条横幅(`IntegrationView.audit.spec.ts`)→ 有病才出现、条数与逐条点名都对、
模板那一类点一下跳进编辑器、挂载那一类给流程设计器入口、体检读不到时不弹错也不拖倒列表;
- 前端 `npx vue-tsc --noEmit` 干净、`vitest` 77 份 895 项全绿(含 `IntegrationView.trigger.spec.ts`、
`IntegrationView.audit.spec.ts` 与新加的 `formWriteback.moments.spec.ts`(14 条)/
`WritebackPanel.moments.spec.ts`(7 条))、
后端 `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 项)、
`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 同步)