35 KiB
OA 写回业务系统:可配置化设计
需求与结论对照、总架构与总路线图见 integration-master-plan.md。 「流程里某几个环节审批完成后回写」这一件事怎么在界面上配,单独写在 node-writeback-config.md(触发时机、单据级条件、卡控口径与边界)。
回答两件事:审批通过后怎么把数据反写回 ERP / 财务 / MES,以及怎么做到"再加一个写回接口不用改代码、不用发版"。
配套阅读:form-data-integration-design.md(入站:外部数据进表单)、quota-control-design.md(额度台账,核销对账复用本文 §8)。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 为什么不能照接入站那套 | 入站错了顶多数据旧几分钟;出站错了是上游多一张或少一张凭证,要人对账 |
| 配置化的三层 | L1 接口注册(系统地址 / 鉴权 / 超时,IT 配一次)→ L2 写回模板(OA 字段 → 上游字段的映射,业务顾问配)→ L3 流程挂载(在流程设计器把一个写回模板挂到某个环节或终态上)。新增一次写回 = 配一层 L2 + 挂一层 L3,零代码 |
| 映射语法刻意做小 | 取值只有三种写法({form.x} / {auto:x} / 字面量)+ 一小组转换函数 + 字典值映射 + 结构化条件;条件复用 dicts.condition_ok,派生值复用 expressions 沙箱,枚举翻译复用数据字典,一个新语言都不造 |
| 唯一正确的投递骨架 | 本地发件箱 + 幂等键 + 退避重试 + 死信 + 对账。绝不在流转请求里同步调外部并指望它成功 |
| 事务口径 | 状态变更与发件箱记录同一事务:不允许"单过去了消息丢了",也不允许"单没过凭证先发" |
| 一个会咬人的坑 | 办结后 oa_work 那行会被搬进 oa_work_completed 再删掉,发件箱必须自带渲染好的 payload,发送时不许回查原表 |
| 一个必须知道的语义 | 引擎运行读的是活配置(oa_activity.config),oa_process_version 只是发布快照、不参与运行。已入队的报文有 payload 快照不受影响,但已发起、还没走到写回环节的单据会按新配置发——治理口径见 §12 |
| 期次 | W0 发件箱骨架(1 周)→ W1 配置层(1.5 周,做到不改代码就加写回)→ W2 幂等 / 冲销 / 对账(1.5 周)→ W3 治理(1 周) |
1. 出站与入站的四个不同
| 入站(取数) | 出站(写回) | |
|---|---|---|
| 失败代价 | 数据旧几分钟 | 上游多/少一张凭证,财务差异 |
| 正确性靠 | 后端重算覆盖前端 | 幂等 + 重试 + 对账 |
| 谁驱动 | 人的交互(点字段) | 流程事件(提交 / 办结 / 作废) |
| 时效要求 | 要快(人在等) | 要最终成功,快慢无所谓 |
2. 三层配置模型
L1 接口注册 oa_data_source(direction=out) 「ERP 凭证接口长什么样、钥匙是什么」 IT / 集成管理员,一系统一次
L2 写回模板 oa_integration 「这张单要发哪些字段、怎么取值、成功怎么判」 业务顾问,一接口一次
+ 这张单走进终态时要不要发(可以多勾 / 也可以不勾)
L3 流程挂载 oa_activity.config.writeback 「这条流程在哪个环节发、哪个时刻发、失败要不要卡住」 流程设计者,一流程一次
「什么时候发」不归模板管,归触发点管(2026-10 收的口径)。配一张模板的时候,人只知道自己要
发什么,还没决定它挂在哪个环节上——那一刻被追问"什么时候发",只能挑一个最像的顶上。所以模板
这一格只回答"这张单走进终态(办结 / 终止 / 作废)时要不要发",可以多勾几条,也可以一条都不勾;
一条都不勾不是没配完,是时机还没定:这条模板要么被挂在某个环节上,要么只在集成页人工重推。
环节那一刻的时机、条件、要发的字段、失败策略全在 L3 那一格——那里才知道环节是谁,而且这段配置
随流程导出一起搬环境。模板上残留的 event_key(旧写法"到达某环节")只为存量配置继续发而留着,
新配置不再往那儿写;模板页给了一个按钮把它一次搬进环节(写挂载与撤声明同一事务,中间不留空档)。
起点档:先别写代码,现成的「服务调用」环节就够一档
三层配置模型是目标形态,但 L3 这件事今天已经存在:在流程「结束」环节之前插一个
invoke(服务调用)环节,配 url / method / headers / timeout / resultPath,
引擎到达该环节时就把 {job, work, serial, title, process, activity, data, operator}
POST 出去,响应按 resultPath 原样写进 work.data(engine._run_invoke)。
上游返回的凭证号会留在单上,打印、导出、条件分支直接能用。
再补一个纯配置的兜底:失败时引擎会写 <resultPath>_error 进 work.data,
而条件分支读的就是 work.data——服务调用后面接一个条件分支,判那个 error 键非空
就走「集成失败-人工处理」环节。静默丢失当场变成有人接手。
这一档适用于:非资金、可重放、上游自己能挡重复、失败可人工补的场景。 它的四个已知边界就是本方案存在的理由——同步阻塞在流转请求里;每次到达该环节都发一次 (退回重走即重复,上游无幂等就是两张凭证);没有重试也没有重放入口;地址与密钥写在环节 配置里,会随每次发布的流程版本快照留一份副本并能随导出搬走。
从起点档升级到 L1/L2 只有两个动作:裸 url 换成引用 oa_data_source(拿到密钥托管、
超时重试、白名单、审计),直接发换成人队后台发(拿到重试、死信、一键重推、对账)。
配置习惯不变,运维不用学第二套。
分层的意义是改动半径:上游改了字段名 → 只动 L2;新增一条流程要写回 → 只动 L3,复用已有模板;换测试环境地址 → 只动 L1 的域名白名单与密钥。三层各自有权限、各自有校验、各自有变更历史,互不牵连。
3. 数据模型
3.1 L1 接口注册(复用入站方案的 oa_data_source,加出站列)
ALTER TABLE oa_data_source ADD COLUMN direction VARCHAR(8) NOT NULL DEFAULT 'in'; -- in|out|both
ALTER TABLE oa_data_source ADD COLUMN success_path VARCHAR(128) NOT NULL DEFAULT ''; -- 成功判定的点路径,如 code
ALTER TABLE oa_data_source ADD COLUMN success_value VARCHAR(64) NOT NULL DEFAULT ''; -- 该路径等于什么算成功,如 0
ALTER TABLE oa_data_source ADD COLUMN message_path VARCHAR(128) NOT NULL DEFAULT ''; -- 上游错误信息在哪
ALTER TABLE oa_data_source ADD COLUMN ref_path VARCHAR(128) NOT NULL DEFAULT ''; -- 上游凭证号在哪
ALTER TABLE oa_data_source ADD COLUMN batchable TINYINT(1) NOT NULL DEFAULT 0;
L1 只管协议与鉴权,不认识任何业务字段。密钥沿用 oa_ai_provider 的只进不出(接口只回 secret_set),域名白名单、禁跟随重定向、超时与重试上限都在这一层。
L2 为什么还要填「方法 / 路径」(配置页被问得最多的一句):L1 那一行注册的是一个系统——一份服务地址、
一份密钥、一份超时与限流、一份熔断与健康度统计;L2 那两格才是接口。mapping.url_for 把模板的 path
拼在数据源地址后面(method 留空回落数据源的 method,path 留空就直发数据源那个地址),于是同一个系统的
建凭证 / 查凭证 / 冲销共用一份密钥与一份白名单。反过来把整段地址写进 L1,就变成了"一个接口一张注册":
密钥与域名白名单要配 N 份、集成页按数据源聚合的成功率与熔断被切碎、删源时的引用检查要逐个核、
换环境要改的条目乘以接口数。一个系统一张源,一个接口一条模板就是这条分界线。
配套的两句话:往外写的源上那几格入参与解析规则不参与出站(outbox.send 只读 headers、鉴权、超时、
成功判定和 url + method,报文由 payload.fields 渲染),所以界面把「解析」整页收掉、
并把「入参」那页注明只给「测试连通」用;L1 那一栏对往外写的源改称服务地址,填到系统为止,
路径交给模板——两边都填成完整地址会被拼成 https://erp/api/budget/balance/api/voucher/create 这种没人认的串。
3.2 L2 写回模板
CREATE TABLE oa_integration (
id VARCHAR(32) NOT NULL PRIMARY KEY,
code VARCHAR(64) NOT NULL,
name VARCHAR(255) NOT NULL,
enabled TINYINT(1) NOT NULL DEFAULT 1,
source VARCHAR(64) NOT NULL, -- L1 的 oa_data_source.code(direction=out|both)
biz_form VARCHAR(32) NOT NULL DEFAULT '', -- 绑定表单:设计器按表单筛模板,并据此校验字段引用
trigger_events JSON NOT NULL, -- 「什么时候发」里终态那几条:可多选,空=自己不自动发
trigger_event VARCHAR(24) NOT NULL DEFAULT 'completed', -- 老那一格:镜像清单第一条;只剩 activity(旧写法)/manual 会停在这儿
event_key VARCHAR(32) NOT NULL DEFAULT '', -- 旧写法 trigger=activity 时的环节 id(新配置一律挂 L3)
send_condition JSON NOT NULL, -- 哪些单才发这一条:结构化条件,空=每张单都发(见 §5)
payload JSON NOT NULL, -- 字段映射(见 §4),渲染结果就是发件箱里的 body
idem_rule VARCHAR(191) NOT NULL DEFAULT '{source}:{job}:{event}:{revision}',
result_write JSON NOT NULL, -- 响应回写 work.data:[{pick, to}]
on_failure VARCHAR(8) NOT NULL DEFAULT 'continue', -- continue|block|branch
fail_route VARCHAR(64) NOT NULL DEFAULT '', -- on_failure=branch 时走的路线 id
retries INT NOT NULL DEFAULT 5,
max_age_hours INT NOT NULL DEFAULT 0, -- 超过就不必再补发的业务时限,0=不限
reversal_code VARCHAR(64) NOT NULL DEFAULT '', -- 冲销用哪个模板(见 §6)
recon_code VARCHAR(64) NOT NULL DEFAULT '', -- 对账用哪个模板(见 §8)
sample JSON NOT NULL, -- 最近一次试跑的报文,给同行做参考
remark TEXT NOT NULL DEFAULT '',
creator VARCHAR(32) NOT NULL DEFAULT '', creator_name VARCHAR(255) NOT NULL DEFAULT '',
UNIQUE KEY uk_integration_code (code), KEY idx_integration_form (biz_form, enabled)
);
映射存成 JSON 而不是拆成明细表:和本仓库一致的做派(oa_form.content、oa_activity.config 都是 JSON + 一份 form_problems 式校验),改起来是一次整体保存,也能随流程导出一起搬环境。
3.3 L3 流程挂载
环节配置里多一段(沿用 oa_activity.config 这个 JSON,不新增表):
{ "writeback": {
"integrations": ["erp_voucher_create"], // 一个环节可挂多个模板:多系统各发一条,互不影响
"on_failure": "block", // 覆盖模板默认:这个环节卡住处理人并给重试按钮
"fail_route": "to_finance_manual" // 或走一条人工补救路线
} }
终态写回(办结 / 终止 / 作废)配在流程上而不是环节上,同一段结构。
4. 映射语法:小到你三天能讲完
payload 是一组映射行,每行「上游字段 ← 怎么取值」:
{ "method": "POST", "path": "/api/voucher/create",
"fields": [
{ "to": "header.companyCode", "from": "1000" }, // 字面量
{ "to": "header.sourceNo", "from": "{work.serial}" }, // 系统值
{ "to": "header.bizDate", "from": "{auto:today:YYYY-MM-DD}" },
{ "to": "header.dept", "from": "{form.costCenter}" }, // 表单字段
{ "to": "header.amount", "from": "{cents:form.applyAmount}" }, // 转换函数
{ "to": "header.summary", "from": "{auto:processName}-{auto:creator}" }, // 拼接
{ "to": "lines", "each": "{form.expenses}", "map": { // 明细表逐行
"subject": { "from": "{item.expenseType}", "dictMap": "erp_subject_map", "pick": "subject" },
"amount": { "from": "{cents:item.amount}" },
"remark": { "from": "{item.note}" } } },
{ "to": "header.attachments", "from": "{attach:form.invoice:urls}",
"when": { "match": "all", "rules": [{ "field": "invoice", "op": "notEmpty" }] } } // 条件发送
] }
取值只有五种写法,其余一律当字面量:{form.x} / {item.x}(明细行内)/ {work.x} / {auto:x}(那 10 个已落库系统值)/ {fn:...} 转换函数。
其中 {work.x} 与 {form.x} 直接吃引擎现成的表达式上下文(data / work / user / variables,见
engine.py:545),work 下面可用的是 id / job / serial / title /
process / creator / creator_identity / creator_unit——不新增一套上下文,配置页照着这份键名列就行。这不是新语言,是把已有三样东西接起来:
- 条件发送直接复用结构化条件
dicts.condition_ok(condition, data)(dicts.py:235),和设计器里的"条件显隐/条件必填"是同一种数据结构、同一份实现,前端已经会渲染这种条件; - 派生值(金额含税换算、字符串切割这类映射表写不出来的)用
transform字段挂一段受限脚本,走现成的expressions沙箱(__builtins__已清空,expressions.py:264)。沙箱里不允许有 IO——这是入站方案就定下的规矩,写回脚本只算值,不发请求; - 枚举翻译(OA 的"差旅费" → ERP 的"660001")走数据字典:新建一个
erp_subject_map字典,字典项附加值里放上游编码,运营自己维护。这是整个配置化里最省后续维护的一条,因为它把"业务口径变了"从发版变成了改字典。
转换函数就这九个,缺了先不加:cents(元→分)、yuan(分→元)、date(fmt)、trim、upper、default(v)、join(sep)、bool(trueValue)、account(选人字段的身份 → 登录账号,见 sql-autofill-design.md 2.1)。够不够用取决于你们上游,不够时加一个函数是一次开发长期复用(见 §11)。
5. 触发与投递
- 入队:引擎在改状态的那次提交里
outbox.enqueue(),把 L2 渲染好的 payload 与幂等键一起落库,与单据状态同事务。落点在create_job/execute_task/ 归档三终态,与额度占用同一个位置,顺序固定。 - 发送:挂在
main.py:_scheduler_loop现有线程上,秒级 tick(默认 15s,可配;2026-10-24 起这一档只是兜底,见下面「什么时候醒」),每轮取 20 条按(job, id)排序且同一 job 只取队首——保证同一张单严格有序(冻结必须先于办结写回),不同单并发。本系统单进程 uvicorn,进程内一把锁够;注释里写清多副本时换FOR UPDATE SKIP LOCKED。 这条口径要求 id 就是入队先后,所以发件箱主键用models.new_time_id()(时间在前 + 随机在后)而不是new_id()那个随机 uuid:拿随机主键排出来的"队首"是随机一条,冲销可能排在原报文前面。另外next_attempt_at用整秒(models.localnow_second()):DATETIME 是秒级精度,带毫秒会被 MySQL 四舍五入抬到下一秒,刚入队的报文会在自己那一秒里被判成"还没到点"。 - 什么时候醒(2026-10-24 改):报文与单据状态同事务提交,
outbox._mark_wake在Session.info上记一笔,after_commit那一刻把调度线程叫醒(同进程置main._scheduler_stir事件,跨副本发一条cache.TOPIC_OUTBOUND广播), 所以正常路径是入队当场就发——实测同一次提交入队的报文从"最多等一个轮询周期"(用户实测中位 19s、最长 75s) 变成 20ms 量级。15/60 秒那一档轮询退回它该待的位置:叫醒信号丢了、别的副本没连 Redis、进程重启过这三类兜回来。 入队当场叫而不直接发,是为了守住"绝不在流转请求里同步调上游"那条底线(§0):审批人不该因为上游超时白等一次。 - 一轮把这张单排着的发干净(同期改):
due()仍对同一张单只给队首一条(严格有序没放宽),run_due()改成发完一条重新取队首、直到这一轮没有可发的为止(上限还是 20 条)。 以前一次调用只发一条,一张单挂两个写回点就要等两个轮询周期——界面上"待发送 / 0 次 / 0ms"挂着一整分钟, 人只会读成"回写没成"。 - 队首挡住后面是有意的,不是遗漏:同一张单严格按入队顺序发,意味着前面那条一直失败时,后面那条再健康也发不出去(
dead已放弃的不算,它不挡路)。这正是"冻结没落地就别结核销"要的效果;代价是一张单上挂多个模板时,一个写坏的上游会拖住这张单的其余写回。要放行只能走页面上的重推或死信处理,不给自动插队的口子——插一次队就有一次上下游对不上。 - 哪些单才发(
send_condition,2026-10-19 落地):模板自带一道结构化条件(与表单条件显隐、路由条件、 写回挂载的when同一份数据结构,判定同样走dicts.condition_ok)。绑定表单管的是"这条写回认哪张单", 这一格管的是"同一张单里哪几笔要发",于是一张表单按字段值发给不同系统只要给每个系统一个模板、 各写一条互斥的条件,不用改流程也不用改代码。节点写回、模板自己声明的到达触发、三条终态都认它; 条件不成立是"这单不该发",发件箱里不留痕。冲销报文不看它——东西已经发出去了,冲销不该被条件拦在半路; 人工重推也不看它,人点重推是明确决定。 - 退避:
1m / 5m / 30m / 2h / 6h,超过retries转dead;attempts与next_attempt_at落表,重启不丢;max_age_hours到了就不再自动补发(三个月前的凭证今天补发多半是事故)。 - 死信:
dead在集成页置顶并给处理人发待阅(复用engine.notify),页面上能看报文、改完模板点重推。人是最后的兜底,这条必须在界面上成立。
发件箱表沿用前一版设计(oa_outbound_message:自带 payload、work 只作展示不做外键、uk_ob_idem 唯一键挡重复、external_ref 存上游凭证号、cancels 指向被冲销那条),不再重复。
6. 幂等、修订号与冲销(都做成配置)
idem_rule模板化,默认{source}:{code}:{job}:{event}:{event_key}:{revision},随X-Idempotency-Key发出;上游不支持幂等时靠唯一键挡重复入队、靠status=success挡重发。键里{code}与{event_key}两段都不能省:同一张单可以挂多个模板(凭证创建 + 归档通知),同一个模板也可以挂在两个环节上;少了哪一段,后入队的那条都会被uk_ob_idem当成重复静默吃掉——上游少一张凭证,而发件箱里干干净净,是最难查的一种事故。设计期对少写{code}的自定义键直接报问题;revision只在退回补正后重新提交 / 人工改单重推时递增,上游据此识别同一张单的新版本;- 冲销也配模板:
reversal_code指向另一条模板(它自己的trigger_event不参与判断——冲销是"照着这条模板发一次",一般配成manual免得自己也被终态事件发出去),引擎在终止 / 作废时自动生成一条新消息,cancels指向原消息、原消息转reversed。没配reversal_code的模板,遇到需要冲销的场景就只在集成页报一条待处理提醒(needs_reversal),不猜该怎么做。影子模式的报文不参与冲销:它根本没打到上游,给它配一条反向消息等于凭空发一次真请求:
能触发冲销的只有在途单被终止和流程走到作废环节两种——办结之后的单据是归档件,POST /job/{job}/terminate 只肯 terminate status=running 的单,别指望"办结之后再作废"这条路径存在。真需要那个动作,就把它做成一条挂在环节上的写回,而不是等归档后补。
| OA 侧发生 | 上游已有凭证 | 动作 |
|---|---|---|
| 办结 | 无 | 新增 |
| 终止 / 作废 | 有 | 有 reversal_code 自动冲销;没有则记一条待处理,人工在上游作废 |
| 退回补正 | 有 | 先冲销,改完重推(revision+1) |
| 已办撤回 | 有 | 同上 |
写在中间环节,等于给每个退回点埋一个冲销需求。所以默认推荐:trigger_event=completed,能晚则晚。
7. 结果处理与回写
- 成功判定在 L1:
success_path+success_value(如code == 0);不满足就是失败,message_path里那句原样进last_error,让人看得懂为什么失败; ref_path提出上游凭证号存进external_ref,单据详情页显示「已写入 ERP:Voucher 2026-10-0001(12:03)」;result_write把响应里的字段回写进work.data(沿用invoke现成的resultPath语义),回写目标字段必须在该环节配成只读或隐藏,否则审批人改了值下一环节又被响应覆盖,设计器保存时挡这条;- 回写字段落库后就是普通字段:条件分支能读、打印单能印、导出能带——不需要任何新机制。
8. 对账配置
recon_code 指向一条查询类模板(带 {auto:today:YYYY-MM-DD} 这类时间参数),排期任务按天调上游"按时间段查询",与 status=success 的出站记录比 external_ref 与金额:上游查无此单、或号对不上,进差异清单。差异只报警不自动改(自动改两边互相覆盖),清单交给财务点「重推」或「已人工处理」。上游没有查询接口就退化成"OA 只能自证已发 + 附响应摘要",这一点必须在评审时说清楚,别等上线才发现没法对账。
9. 配置期工具(不改代码的底气在这节)
- 报文预览:给模板选一个真实单据(或手工填一版数据),当场渲染出将要发送的 JSON,不发送;
- 试跑 dry-run:真发一次到测试环境,报文与响应留在模板的
sample上,同行照着抄; - 报文历史:每条发件箱记录都能看当时的 payload、响应、耗时、第几次重试——排错不靠猜;
- 导入导出:L1 + L2 是一套 JSON,测试环境配好导出、生产导入,只换密钥和域名。"改代码"最常见的来源就是没有这个;
- 按表单字段一键生成映射:选好数据源和表单,"生成映射"就把每个字段铺成一行(金额自动转分、
明细表自动逐行、附件格自动发 id,前面再带上单号 / 发起人 / 业务日期三行系统值),剩下按上游的
字段名改那一列就行。一张二十个字的单子逐行手敲映射,是这件事上最耗时的段落,而九成报文的口径
就是"字段名照搬";生成出来的行仍然过同一把校验尺子(
utils/formWriteback.autoMapRows)。 - 复制成模板:配第二、第三个系统时照着改,比从空白开始快一个数量级;编码强制确认, 因为它是导入导出的身份、也是幂等键的一段。
- 配置分两层:常改的(数据源、表单、映射、响应回写)在明面上,一年改不了一次又配错的 (幂等键、重试次数、补发时限、冲销与对账模板、失败策略)收在一个默认收起的"高级"里, 但已配过非默认值的模板打开时会自动展开——藏起来等于没人知道它在那;
- 保存即校验(前后端同一把尺子,与
form_problems/validateFields一个规矩):模板引用的表单字段存在、to路径合法、dictMap字典存在、each指向的是明细表、回写目标字段在该环节不是可编辑、trigger_event=activity时环节存在、「哪些单才发」引用的字段在这张表单里存在(且不许挂一条空条件冒充"只发一部分"); - 变更留痕:模板改动记操作人与前后差异(复用操作日志口径),改坏了能看是谁改的、改回上一版。
10. 端到端:新增一次写回,全程不碰代码
以「报销办结后在 ERP 生成凭证」为例:
- L1 注册
erp_api(地址、鉴权、密钥、success_path=code、success_value=0、ref_path=data.voucherNo)——同系统只做一次; - L2 新建模板
erp_voucher_create,选 L1、选绑定表单,逐行配映射,明细用each,费用类别挂erp_subject_map字典; - 报文预览挑一张历史报销单看一眼,dry-run 打测试环境,通过;
- L3 在报销流程的「凭证归档」环节挂这个模板,失败策略选
block; - 保存。流程走到那一环节即自动生成发件箱消息、按退避重试、失败进死信、成功回显凭证号。
之后再来一条「借款办结写 ERP」——同 L1、抄一份 L2 改两行映射、挂到那条流程上,二十分钟。
11. 仍然要改代码的五种情况(一次开发,长期复用)
| 情况 | 为什么要写代码 | 一次性成本 |
|---|---|---|
| 上游要特殊签名(HMAC / 时间戳 / 加密串) | 鉴权算法不能配出来 | 加一个 auth_type,几小时 |
| 响应不是 JSON(XML / 定长报文) | 需要解析器 | 加一个 parser,半天 |
| 传输不是 HTTP(SFTP / DB 直连 / MQ) | 换 transport | 一个 transport,一两天 |
| 转换函数缺(复杂金额口径、编码转换) | 函数不能凭空有 | 每个几小时 |
| 一次业务要串多个接口(先建凭证→传附件→提交) | 一期一个模板 = 一次调用 | 别造编排引擎:在流程上挂三个环节各发一条,流程就是编排器 |
最后一条是有意的取舍:一旦支持"一个模板里串多个调用 + 取中间结果",就要发明分支、变量、补偿,等于在 OA 里重写一个集成平台,而流程引擎本身就是干这个的。
12. 一个必须现在定的语义:活配置 vs 在途单
引擎运行读的是 oa_activity.config 这份活配置,oa_process_version 只在发布时留档、不参与运行(代码里 ProcessVersion 只有设计接口在用)。对写回意味着:
- 已入队的消息安全:payload 在入队时就渲染并快照在发件箱里,之后改模板不影响它;
- 在途但还没走到写回环节的单据不安全:会按新模板发。多数时候这正是想要的(改错了马上生效),但字段口径变更时会出现"同一批单前后发的不一样"。
治理口径二选一,要选一个:A. 模板只增不改(改口径就发新 code、在流程上换挂载,老单继续走老模板,最干净,代价是模板会变多);B. 允许改,但改 fields 时提示"当前有 N 张在途单会受影响",让改的人自己确认。我倾向 A 给财务类接口、B 给其余。
13. 安全与权限
- 入站方案 §8 那一套全量复用:密钥只进不出、域名白名单、禁跟随重定向、超时 / 重试 / 限流 / 熔断、
oa_data_source_call审计; - payload 是出域数据:模板页必须列出"会把哪些字段发给 X 系统",身份证、银行卡默认禁;
- 权限分三档:
design:datasource(L1,IT)/新增design:integration(L2 模板与试跑重推)/已有的流程设计权(L3)——别让业务顾问能改密钥,也别让 IT 能改业务映射; X-Idempotency-Key参与签名,防重发;- 所有
manual手功重推记操作人与原因,进操作日志。
14. 落地清单
W0 骨架(约 1 周):oa_outbound_message + service/outbox.py(enqueue / due / mark);_scheduler_loop 发送分支 + 退避 + 同 job 串行;_run_invoke 改为渲染入队;集成页列表 / 详情 / 重推(排期区照 SyncScheduleView.vue)。做完能用手工配 JSON 的方式跑通一条写回,这是最小可信闭环。
W1 配置层(约 1.5 周,本期真正的交付):oa_integration + 模板管理页(映射行编辑、each、when、dictMap);映射渲染器(复用 expressions 沙箱与 dicts.condition_ok);报文预览 + dry-run + 报文历史;导入导出;前后端两份校验;design:integration 权限码四处同步(permissions.py / constants/permissions.ts / i18n / README 权限表与「27 个」计数)。W1 做完,"加写回不改代码"才成立。
W2 可信(约 1.5 周):X-Idempotency-Key + revision;死信与通知;reversal_code 冲销链与退回 / 撤回 / 作废三处联动;ref_path 回显与 result_write 回写;对账排期任务 + 差异清单。
W3 治理(约 1 周):批量办结压一次上游验限流;模板变更留痕与回滚;额度核销与出站对账打通(quota-control-design.md §8);灰度开关(先对某条流程开)。
已经落地到哪一步(2026-10-14):W0、W1 与 W2 的幂等键 / revision / 死信通知 /
reversal_code 冲销 / ref_path 回显 / result_write 回写全部建完(当时的 89 项验收脚本
backend/tests/oa_outbox.py 随 backend/tests/ 一起在 2026-10-15 移出仓库,见 README「自检」,
留的静态守卫是 backend/scripts/check_*.py)。两条人工兜底口径在实现时收紧了:
结果未知(unknown)的报文不给"重推",必须先走"人工确认"把结果落定——直接重推是赌上游没记账,
赢了两张凭证、输了还是一张;手工重推必须填原因,否则接口直接拒(§13 那句"记操作人与原因"落到接口上)。
还差的是:§8 的对账排期任务与差异清单、on_failure=branch 真去改走补救路线
(要它就得把外部调用搬回流转请求里,与发件箱异步投递的前提冲突;这一期把界面入口撤了,
存量配置按 block 执行并在保存流程时明说)、模板变更留痕与回滚、批量办结压一次上游、灰度开关。
权限码计数以 GET /auth-roles/catalog 为准(README 写的是 30 个)。
中间环节写回落地(2026-10-19):本文原先只把写回点画在"办结 / 终止 / 作废"三条终态上,
"某几个环节审批完成后各回写一次"其实配不出来。补了三处——模板自带的「到达某环节」触发
(此前填了环节 id 也一条不发,因为没人调那批模板)、环节挂载上的 trigger=arrive|leave
(leave 才是"本环节审批通过后",退回不算)、挂载上的 when(只有部分单据要回写)。
on_failure=block 也从"只记在报文上"变成真的卡住这张单后续环节的办理(卡人不等流程停在半路,
退避重试、死信、重推一整套照旧),待办页顶部同步出一条红条说明为什么办不动、去哪儿处理。
细节、语义边界与验收清单见 node-writeback-config.md。
验收脚本必须覆盖:办结入队即成功;上游 500 退避后重发但不重复;进程重启后待发不丢;同 job 顺序正确;改模板后在途单按新模板、已入队报文不变;作废触发冲销、没配冲销时只提醒;幂等键重复入队被唯一键挡;对账差异被抓到;死信发出通知;payload 里不含密钥与禁用字段;明细表 50 行映射条数正确。
15. 需要你拍板
- 上游能力清单:每个接口支不支持幂等键 / 作废 / 改单 / 按时间段查询?没有这张表 §6 §8 配不出来;
- 写回时机:中间环节就写(付款节点)还是统一办结后写?我倾向能晚则晚;
- 模板治理选 A 还是 B(§12):财务类接口我建议"只增不改";
- 谁配模板:IT 还是业务顾问?决定
design:integration给谁、模板页要做到多傻瓜; - 允许滞后:秒级、分钟级还是夜间批量?决定 tick 与重试预算。
16. 明确不做
- 不在流转请求里同步写外部并指望成功(这是本方案存在的理由);
- 不做表单字段级实时写回;
- 不引入 MQ / 新调度框架 / Redis;
- 不在模板里做多接口编排与中间变量,要编排就用流程挂多个环节;
- 不做双向自动同步:OA 是流程主系统,写回是"OA 说了算"的单向写,双向对撞必然出覆盖事故;
- 不让自动重推覆盖人工已修正的结论;
- 不在
expressions沙箱里加 IO。
17. 复核补充:二次审查发现的缺口(2026-10-14)
- 发送成功但状态没落库的窗口。进程在收到上游 200 之后、
mark(success)提交之前崩溃,重启后这条会再发一次——上游没有幂等能力就是两张凭证。处置:发送前先落sending状态并记attempt_started_at;重启后凡是停留在sending超过超时的,不许直接重发,先走"上游查询确认"(有recon_code就查,查不到才允许重发),没查询接口就在集成页标成「结果未知」等人确认。这一条必须有,否则 §6 的幂等只是半套。 - 上游常常没有测试环境,dry-run 打不出去。加 shadow 模式(数据源级开关):正常渲染 payload 并落发件箱与历史,但不真发,响应记为模拟。这样模板在生产库的真实数据上也能验证,且天然成为上线首周的灰度手段。
- 集成健康度没有出口。死信有通知,但"上游整体挂了""成功率掉了""正在熔断静默"只有翻日志的人知道。集成页顶部要有一块健康区:按数据源统计成功率、P95、连续失败数、当前是否熔断、结果未知的条数;连续失败超阈值时自动停用该数据源(新单不再入队并给出原因),恢复靠人工点或半自动探活。
- 配置变更要有发布态。映射把科目写错,保存校验挡不住(结构合法、语义错)。模板加
draft / published两态与双人复核(发布人 ≠ 创建人,复用权限点),发布才生效;配合 §12 的"只增不改"口径,财务类接口改映射必须走发布。 - 保留期与容量。
oa_outbound_message与流水只增不减:成功件满 1 年搬进归档表(与oa_work_completed同一思路),失败与死信不自动清;报文预览历史只留最近 N 条,防止 JSON 撑爆。
新增决策两条(并入 §15):(a) 有没有"结果未知"的处置方式——上游提供查询接口吗;(b) 模板发布要不要双人复核、谁能当发布人。
最后更新:2026-10-14