36 KiB
外部系统集成总方案:表单取数、预算与备用金额度、审批后反写
一份总方案收拢四件事,其余三份是细节展开:
| 细节文档 | 管什么 |
|---|---|
| form-data-integration-design.md | 入站:外部数据怎么进表单(字典 / 镜像 / 远程搜索 / 字段级带出 / 快照口径) |
| quota-control-design.md | 额度台账:预算超支硬挡、备用金冲销余额 |
| outbound-integration-design.md | 出站:审批通过后反写业务系统,以及怎么做到不改代码就加写回 |
| 本文 | 需求→结论对照、统一架构、总路线图、共享件、风险、决策清单、验收 |
| integration-contract.md | 上游接口契约:业务系统尚未开发,接口形状由 OA 先定,含做不到时的降级表 |
1. 需求与结论对照
| # | 需求 | 结论 | 落点 |
|---|---|---|---|
| R1 | 表单里有些字段要取其它业务系统的数据 | 按数据量与时效分三条路,不要一律实时调:小而不变动字典、中大而稳定进镜像表、必须新鲜才走后端代理即时取 | 入站 §2 §3 §5 |
| R2 | 实时取预算;报销累计超支就不许提交并提示(第一、二次可提,第三次挡下) | 「实时取预算」只解决总额;挡下第三次靠 OA 自己的在途占用账。三张额度表 + 提交链路一个校验钩子,失败走现成的 EngineError → 中文提示 |
额度 §2 §4 §5 |
| R3 | 备用金冲销要提示已冲销多少、还剩多少,多冲给提示 | 与 R2 同一台机器:额度对象换成"某笔借款",总额由备用金单办结时生成,冲销单选中即带出三个数,多冲软提示或硬挡可配 | 额度 §3 §6 |
| R4 | 审批通过后反写业务系统,尽可能配置化、不要经常改代码 | 三层配置:L1 接口注册 / L2 写回模板(字段映射)/ L3 流程挂载。新增一次写回 = 配 L2 + 挂 L3,零代码。投递必须走本地发件箱,不在流转请求里同步调外部 | 出站 §2 §4 §10 |
| R5 | 能不能就在归档那步配个接口调用 | 能,今天就能配、零开发:现成的「服务调用」环节 + resultPath 回写。再补一个条件分支读失败键,静默丢失就变成了有人接手。非资金类到这就够 |
出站 §2 起点档 |
2. 统一架构
┌──────────── 表单设计器 ────────────┐
│ 字段属性:dictCode / autoFill │
│ fetch(外部即时取数) │
│ quota(额度控制) │
│ 公式 total() · 条件显隐必填 · 条件分支 │
└───────────────┬────────────────────┘
│ 保存即校验(form_problems / validateFields 同一把尺子)
外部系统 ──同步──> oa_external_record ─┐
外部系统 ──同步──> oa_quota.total ─────┤
▲ │ 后端提交链路(一次事务,顺序固定)
│ ▼
│ ①字段权限过滤 ②联动可见性 ③dicts.apply_auto_fill
│ ④fetch.apply_form ⑤compute_formulas ⑥quota.apply_and_check
│ ⑦_validate_form → 不过:raise EngineError → 界面中文提示
│ │
│ work.data(值快照 + _fetch 来源指纹)
│ │
外部系统 <──发件箱── oa_outbound_message <─┘ 状态变更同事务入队
▲ │
└── 后台发送(现有调度线程 · 退避 · 死信 · 一键重推 · 对账)
四个共享件,四条需求全部踩在上面,只做一份:
oa_data_source数据源注册表:外部系统的地址、鉴权、超时、成功判定、密钥只进不出。入站的fetch与出站的 L1 用同一张表(direction区分),密钥托管、域名白名单、禁跟随重定向、oa_data_source_call审计各写一遍。- 表达式沙箱
expressions:公式、条件分支、映射里的派生值、环节脚本共用一个沙箱,沙箱内永不做 IO。这是"设计器里写的东西不会拖垮引擎"的根。 - 调度线程 + 排期判定:现有的
_scheduler_loop与service/sync_jobs.py(四档排期、迟到宽限、重试预算、管理页)同时服务镜像同步、额度提醒、出站发送、对账。不加 MQ、不加第二个调度框架。 - 数据字典:选项、级联、带出、跨系统枚举翻译(OA「差旅费」→ ERP「660001」)都落字典。这一条把"业务口径变了"从发版变成改字典项,是长期维护成本最低的一环。
3. 关键取舍(全部已在三份文档论证,这里只留结论)
| 取舍 | 结论 |
|---|---|
| 快照还是引用 | 值和展示名都落 work.data 快照 + _fetch 来源指纹。单据是凭证,打印、导出、归档件必须能自证;只有显式配 mode: reference 才每次现取 |
| 实时调用放在哪 | 只在人交互的那一格放,且超时 5s 起、失败按字段级 onError 策略;列表、待办、打印、导出永不现取外部数据(批量场景现查是雪崩来源) |
| 外部值的可信度 | 前端带回来的外部值一律不算数,提交时后端按同参重算并覆盖,与 dicts.apply_auto_fill 同一分寸 |
| 外部值能不能决定流转 | 不能。条件分支与审批人只读 work.data 已落库的值;要按外部状态分流,就加一个服务调用环节把状态取成字段再判 |
| 金额存储 | 表单是 float 元,台账一律分(BIGINT),入口 int(round(v*100)),浮点做累计必漂 |
| 额度双扣 | 上游"已用"含在途 → basis=upstream_used(本地 settle 不再重复扣);不含 → local_all。口径不定不许开工 |
| 写回为什么必须落本地一条 | 同步直发丢了三样东西:重试、重放入口、幂等依据;最要命的是静默——现在失败只写 <resultPath>_error 然后继续流转 |
| 要不要做接口编排 | 不做。一次调用一个模板,多步用流程挂多个环节——流程引擎本来就是编排器,别在 OA 里重写集成平台 |
| 双向同步 | 不做。OA 是流程主系统,写回是单向写;双向对撞必然出覆盖事故 |
| 并发防超 | 台账行锁(照抄 next_serial 的 SELECT ... FOR UPDATE)+ 与单据同事务;死锁已有 _retry_on_deadlock 兜底 |
4. 今天就能配的(零开发,半天)
- 非资金类反写:流程「结束」前插一个服务调用环节,配
url/method/headers/timeout/resultPath,上游返回的凭证号会留在单上,打印导出都能用。 - 给它加个兜底:服务调用后接一个条件分支,判
<resultPath>_error非空 → 走「集成失败-人工处理」环节。失败从静默丢失变成有人接手,纯配置。 - 预算/额度类展示与软控:字典项附加值放
{"total":..., "used":...},「字典带出」带进两格只读字段;明细合计用公式total(expenses, amount);再来一个只读公式字段算可用;「超预算说明」配条件必填「可用 小于 0」,并让条件分支把这种单子自动送到财务环节。 - 别做的事:把密钥写进环节
headers(每次发布流程都会把整份设计deepcopy进版本快照,等于每版留一份副本且能随导出搬走);指望数字字段的min/max当预算闸门(提交时后端不校验它)。
这四条能把大部分日常需求先接住,同时给后面的开发攒真实数据:invokeResult_error 一个月出现几次,直接决定 R4 要不要做重。
4.5 上游系统还不存在时,排期这样改
现实更新:其它业务系统尚未开发,一个取数接口都没有。这反而让事情简单,三处调整:
- 最硬的前置问题自动消解。"上游已用含不含在途"暂时没有上游可问 → 额度口径先定
basis=local_all(总额由财务导入、占用与核销全在 OA),开工不再被它挡住。等业务系统出现时 按契约补上usedIncludesFrozen,切换只是改数据源配置 + 一次性重算流水。 - M2 提到第一位,M1 降级。额度台账现在完全自给自足(预算总额 Excel 导入 + 本地占用核销),
不依赖任何外部接口就能把 R2 / R3 做完并真实上线;而入站取数、镜像同步、
fetch执行器 在拿到真实接口前只能对着桩跑,价值降级——M1 只保留数据源注册表这一层骨架(M2、M3 都要用)。 - 多出一份必须现在就写的交付:integration-contract.md。
接口没定就是契约权还在我们手上,上游按 OA 舒适的形状实现(金额用分、幂等键、批量查询、
增量游标、作废与对账查询),能把后面所有适配层的复杂度推回去。反过来说,
契约每晚定一周,映射层就多一层要写的代码。同时 OA 按契约实现一个上游桩
(现在长在
tests/oa_fetch.py里,是个 60 行的Upstream类:余额、HTTP 状态、连错次数 都能从用例里改,不用重启),既跑自己的验收,也给上游当参考实现和联调靶子。
顺带一个架构红利:现在这个"财务手工导入 + OA 本地台账"的版本不是将来要扔的临时品—— 它本身就是未来的本地镜像与缓存层,真实系统接上时只改"总额从哪来"这一处。
4.7 配置界面:管理员在页面上配什么
目标形态是三块界面配完整条链路,不碰 JSON、不改代码。前端只做配置与即时反馈, 真正的调用永远在后端代理——浏览器直连业务系统会死在 CORS、密钥暴露、超时不可控、无审计这四件事上。
落地状态(写代码的与看文档的在这页对齐):三块界面都已经能用,配一条链路全程不碰 JSON。 与下面最初的设计稿有五处出入(逐条标在各段末尾,①~⑤),另有两件没做的列在小结里—— 别把这份文档当成"都已实现",也别把出入当成漏做。
页面一 · 外部数据源(/design/data-sources,权限 design:datasource)。列表 + 行内「测试」+
新增/编辑弹窗,范式直接照 AiProviderView.vue(它有列表、行内测试连通、密钥只回 secret_set、按服务商带预设)。
弹窗四个页签:
- 连接:名称 / 编码 / 所属系统 / 通道(真接口 / 样例响应) / 方法 / URL / 请求头 / 鉴权类型与密钥 / 超时 / 重试 / 缓存秒数 / 限流;选了样例就换成一个样例响应文本框(填一份 JSON,等价于自己家的假接口);
- 入参:两列表「参数名 ← 取值」,取值三种写法(常量 /
{form.字段}/{auto:系统值}), 字段一律下拉选(从绑定表单的字段列表取),不让手打 key; - 响应解析(样例驱动,能不能真配起来全在这一页):点「拉取样例」或粘一段响应 JSON →
界面渲染成 JSON 树 → 在树上点节点设为「列表根节点」「值取哪个键」「名称取哪个键」「附加值取哪几个键」,
单值场景就是点「阈值/余额」那个键。不让人手写
data.balance这种字符串路径; - 用途与策略:用途多选(下拉选项 / 远程搜索 / 单值带出 / 写回)、失败降级
keep|block、提示文案、启停。
弹窗底部常驻测试区:填一组测试入参 → 后端代理真调 → 左侧原始响应、右侧按解析规则出的结果
加耗时与是否命中缓存,失败时把上游 message 原样显示。样例通道(入站方案 §5.4)点测试同样出结果,一次也不外呼。
出入 ①:四页签摊成一张分区的长表单——字段本来就不多,跳页签反而让「改了 URL 忘了改取值路径」。 出入 ②:解析规则不是 JSON 树点选,而是把样例响应摊成一条条可点选的取值路径 (
fetch.sample_paths只列标量叶子与列表节点,界面preview.paths渲染,点一下就填进pick/itemsPath/mapExtra)。要的效果是"别让人手打data.balance",摊平成列表 与渲染一棵树在这件事上等价,少造一个交互件。 出入 ③:「测不过不许存」没做。测试通过与否只作为结果留在行上(列表页一眼看到 最近一次测试的成功/失败与耗时),保存本身不拦。拦的理由是样例通道和改到一半的源经常 本来就测不过,硬拦会把人挡在配置界面外面;这条留给真实接口接上以后再看要不要收。
页面二 · 字段绑定(components/oa/design/FetchPanel.vue,就在表单设计器的字段检查器里,
与现有「字典带出」同一层)。选「外部数据源」→ 下拉列出已启用的源 → 按该源声明的入参逐个指定取哪个字段
({form.x} / {auto:today:YYYY} / {const:...},写错字段名当场黄字点出来)→
再按该源声明的可带出键逐个勾「带进表单哪个字段」→ 失败策略 留空 / 挡提交 / 记零。
填单页面上入参一变就防抖预取一次(FormRenderer + utils/formFetch.ts),纯显示,判定仍在校验链路里。
出入 ④:「触发时机」这一档没做,落成"入参变了就取"这一种。三个时机里 「打开单据」与「仅提交」在真实诉求里几乎都是"早看一眼数",而提交时后端反正要按同一份入参 再取一次——把它做成配置项,等于让管理员去调一个不影响正确性、只影响等待感知的开关。 入参里带
{auto:dept}这类本地算不出来的写法时跳过预取,直接等提交时取。 另外没做互斥:一块面板上的「字典带出」和「外部取数」同时配在同一格上是允许的, 引擎按autoFill → fetch的顺序跑,外部取数覆盖字典带出(后写的算)。 真要互斥得先回答"谁该赢",现在这个答案至少是可预测的。
页面三 · 阈值规则(同一个检查器再一块,components/oa/design/ThresholdPanel.vue)。
落地比最初的设计稿少一半:一个开关 + 一句话说完一条规则 + 两个下场。
开关就是"这条规则配了没有"(关掉直接把 threshold 摘掉,不留一个配了一半的壳);
打开之后一行两格——「本格 [怎么比 ▼] [比什么 ▼]」:比较符复用 formLinkage 那套 ops 并收窄成
gt/ge/lt/le/eq/ne/empty/notEmpty(in / contains 对"到没到线"没意义,changed 比的是
"和刚打开单据时比有没有改过",阈值这一路没有那个基准);「比什么」是一个下拉,里面混着
同表单的兄弟字段和"一个固定数"——选字段写 rightField、选常量写 right,
不用先回答"我要比字段还是比常量";选了 empty / notEmpty 右边整块收起来。
命中以后的下场只给两个:挡住提交(默认)/只提醒。
出入 ⑤:动作四档收成两档,判定时机不再是配置项。 最初列的「红字提示 / 强制填写说明 / 阻断提交 / 走某条流程」里有两档压根不是开关——"必须写说明"是标记格上挂一条现成的
requiredWhen、"超支走总监"是条件分支读同一个格子(见下),界面上再摆两个勾只会让人 以为不勾就不生效。剩下的warn/block收成「只提醒 / 挡住提交」,默认挡: 会去配阈值的人九成就想挡,让他多点一次"只提醒"比让他在四档里挑一遍便宜。 标记格与提示文案收进「高级(可留空)」,不在第一屏。历史上存成mark(只写标记不吭声)的 旧配置读作只提醒——那本来就是它行为的可见版本,不悄悄升成挡提交,否则某张单会在没人 改过配置的情况下突然发不出去。
这里有一个平台限制必须现在知道:条件引擎的右值只能是字面量,比不了两个字段——
后端 dicts.compare 左边取 data[field]、右边取配置里的常量,前端 formLinkage.conditionOk 同口径。
所以「本次申请金额 > 可用余额」这种形状,条件分支与 requiredWhen 直接写是写不出来的。
落地选的是第三条路:既不在字段上偷偷造一个看不见的差值公式字段,也没把条件引擎改成
「右值取字段」(那个开关一改,visibleWhen / requiredWhen / 条件分支三处的语义都要跟着变,
前端 formLinkage 与后端 dicts 两份实现都要改,风险铺得太开)。改成单开一条阈值规则链路
app/service/threshold.py:比较运算复用 dicts.compare(原来是私有的 _compare,
改成公开的 compare() 让阈值复用,不写第二套 ops),只把「右边也可以是一个字段」这一件事补进来。
命中以后的下场三档选一(warn 格子下红字 / block 挡提交 / mark 只写标记——
后端三档都留着,界面上只给前两档,mark 留给已有配置读),
外加命中程度写进指定的标记格:数值比较写差额(超了多少、还差多少),非数值比较写 1,
没命中写 0。这个格子就是绕过"条件引擎比不了两个字段"的那把钥匙——
「超支必须写说明」是标记格上挂一条现成的 requiredWhen: short gt 0,
「超支走总监审批」是条件分支读同一个格子,两样都不用新机制。与额度把超支额落进
quotaOver 是同一招,不是巧合。
配置形状与界面字段见 app/service/threshold.py 的模块 docstring 与
components/oa/design/ThresholdPanel.vue;判定排在
quota.apply_and_check 之后、必填校验之前(额度与公式都算完了,读的是这次提交的真数;
要挡的话得赶在"请填写某某"之前把话说清楚)。
那句红字挂在谁后面是配置项(threshold.showAfter)。这一条是补出来的:阈值最爱配的
恰好是公式格(费用合计)和业务系统提交时现取回来的余额格,而这两类格子永远走只读那一支渲染,
红字以前只写在编辑态那一支里——命中了也一个字都不露,"只提醒"就成了"什么都不说"。
现在只读态照说,并且能把这句话挪到发起人真在看的那一格(一般是金额格)后面;
指定的那一格不存在或当前环节没显示就退回本格下面。挂在哪儿只影响看不看得见,
判定与文案一个字都不改;页面上这句红字的唯一出口是 utils/formThreshold.ts:thresholdNotes。
这一格在本环节被藏起来时挡不挡,也是配置项(threshold.onHidden,默认 skip)。
上面那句"红字只给渲染出来的格子说"本来就把答案摆在那儿了:没渲染的格子连挂红字的地方都没有,
可后端 apply_check 原来不看这一格露不露,命中就抛 EngineError——于是界面不说、后端真挡,
审批人点「同意」被一条屏幕上根本没出现的规则挡死,看不见、改不动、也没有那句话可照着改。
现在跟必填走同一把尺子(环节权限设成隐藏、字段自己勾了默认隐藏、联动条件没放行、整页标签页被藏,
都算:formruntime.effective_perm),三条分寸:默认 skip 且存量一条都没配过的表单跟着换
(故意的,那种单子卡在环节里比放过更糟);只降级挡不挡——判定照算、标记格照写,
条件分支读到的还是最新那一份;要每个环节都拦一道的流程把那一格翻回 block。
额度那一头(quota.onHidden)同一条尺子,hidden_keys / released_when_hidden 是那两份判据,
放行时钱照样占、台账照样记。
"不管什么条件"这一句要说满,得连挂在同一格上的另外四句一起改:额度那三句(这笔额度的
维度算不出来、这笔额度还没入账、这笔额度记在别人名下)与外部取数失败那一句
(fetch.onError=block)原本压根不看这一格露不露,命中就抛,于是"看不见就不挡"只对阈值
与超支成立。现在六句一起走这一把尺子,取数那一层因此也收 perms
(engine._apply_form_runtime 把它递给 fetch.apply_form):那一格在本环节没露脸时取数失败
只留一句日志,取数照旧发起、值留在原来那一份上,等它露出来的那一环再拦。取数那一句
没有 onHidden 开关——onError 就是它的开关(要软就 keep / zero),再叠一层只会让
下一个人不知道该看哪个。额度记在别人名下那一组放行时连账都不占:把这张单的钱挂到别人
头上,比这一环不拦人更糟。闸门(gate)不在这一改里:它挂在环节上
(oa_activity.config.gate),判的是外部核验台账与附件指纹,没有"配在某一格上"这层形状。
判据在 backend/scripts/check_hidden_field_rules.py(那几把尺子 + 真流程 + 那四句:
藏起来的环节能过、露出来的环节被挡、翻回 block 藏起来也挡、真链路那一趟把三处一起放行)。
再强调一次:页面上的即时判断(utils/formThreshold.ts 那份镜像)只用于提示,
提交时后端一定按同参重算再判一次,否则改一下前端就能绕过阈值——这条与「带出值以字典为准」是同一个分寸。
镜像两端的口径由 tests/oa_fetch.py::test_threshold_rules 与
src/utils/__tests__/formThreshold.spec.ts 各自钉住同一批断言(三个数进文案、
命中程度落格、没命中写 0),改一边不改另一边过不了测试。
界面配不到的:跨单据累计(第三次挡下)。界面上可以选额度定义、可以配阈值,但那本账必须在后端表里; "台账可配置"不等于"可以不建表"。
要新造的交互件只有一个:响应 JSON 树的点选器(components/common 里没有现成的)。
其余全部有现成件——条件编辑器三件(ConditionBuilderDialog / ConditionRuleEditor / ConditionValueField)、
公式对话框 FormulaBuilderDialog、远程搜索下拉 Select.vue 的 remote 模式、
按键防抖 useKeyedDebouncedSearch、排期与上次结果的界面 SyncScheduleView.vue。
这三页是运维工具,按密集表格 + 小圆角 + 图标按钮做,别做成营销式大标题页。
一个额外红利(还没做):上游还没开发(§4.5),界面上填的 URL、入参名、样例响应、点选的取值路径 本身就是一份活规格。加一个「导出接口说明」把当前配置渲染成一页 Markdown 发给对方, 比手写契约文档更不容易走样。这件是这三页里唯一还挂着没写的交付——现在给人看的是 integration-contract.md 那份手写契约,配置改了它不会跟着变。
明细表的列不能挂阈值(threshold_fields 明确跳过 type=table):阈值的粒度是"一张单一个判定",
明细行里每行一个余额是另一件事——那需要按行取数、按行判定、再把 N 行的结果汇总成一次能不能提交,
属于 §6 风险登记里"批量校验"那一档,别在阈值这里塞半个进去。
5. 总路线图
假设:1 名全栈,工期含表结构快照对账与验收脚本,不含上游接口方自己的开发等待。
走到哪了(2026-10):M0 的零代码配置可做;M2 额度整块已落地(三张表 + service/quota.py
- 提交链路钩子 + 管理页 + 设计器面板,
tests/oa_quota.py81 条);M1 里除了镜像表 (oa_external_record与dicts.items_of()未命中回落)之外都落了,并且多做了原计划里没有的provider=mock样例通道与阈值规则两块——上游一个接口都没有的情况下,这是唯一能把 「取数 + 阈值 + 额度」整条链路今天配完验通的办法(§4.5 与入站方案 §5.4 的provider=mock);M3 已落地(发件箱、写回模板、映射渲染器、预览 / dry-run / 报文历史、导入导出、死信通知、冲销链、响应回写,验收tests/oa_outbox.py89 项),剩下对账差异清单与灰度压测那几项见反写方案 §14;M4/M5 未开工。
| 里程碑 | 内容 | 工期 | 交付后能做什么 |
|---|---|---|---|
| M0 | 上面四条零代码配置 | 0.5 天 | 非资金类反写跑起来,软控预算上线 |
| M1 | 🔶 入站 P0 + P1:oa_external_record 镜像与同步、dicts.items_of() 未命中回落、oa_data_source 注册表(含出站 L1 列)、service/fetch.py、字段 fetch 属性 |
2.5 周 | 外部主数据进所有已有表单能力;字段级实时取数,含缓存、限流、审计、降级 |
| M2 | ✅ 额度 Q0:三张额度表、service/quota.py、提交链路 quota.apply_and_check、五个状态钩子、额度管理页、设计器「额度控制」面板 |
2 周 | R2 与 R3 达成:累计超支硬挡并给中文提示;备用金已冲销/剩余额度、多冲提示 |
| M3 | ✅ 出站 W0 + W1(另把 W2 的幂等键 / 死信通知 / 冲销链 / 响应回写一并做完了):oa_outbound_message 发件箱与后台投递、oa_integration 写回模板、映射渲染器、报文预览与 dry-run、导入导出、design:integration |
2.5 周 | R4 达成:加一次写回不改代码;同步调用换成入队后台发,有重试、死信、一键重推 |
| M4 | ⬜ 出站 W2 + 额度 Q1:幂等键与 revision、冲销链与退回/撤回/作废联动、ref_path 回显与回写、对账排期与差异清单、预算总额与已用定时同步 |
2.5 周 | 财务敢签字:不重复、不丢、能冲销、能对账 |
| M5 | ⬜ 收尾:远程搜索与 TTL 缓存熔断、超期未核销提醒、block_new_when_open 挡借用、额度看板、模板变更留痕、灰度开关 |
1.5 周 | 治理与体验补齐 |
合计约 11 周单人;M1 与 M3 的界面部分可并行,两人约 7 周。关键路径是 M1 → M2 → M3(M2 的 fetch 依赖 M1 的数据源注册表,M3 的 L1 复用 M1 同一张表)。想更早拿到 R2/R3,可以把 M1 的镜像同步砍到只做字典回落,M2 提前到第 3 周末,代价是大数据量场景仍受限。
6. 风险登记(都有对应处置)
| 风险 | 后果 | 处置 |
|---|---|---|
| 上游"已用"口径不明 | 双扣(有钱报不了)或漏扣(超支没人管) | 定为开工前置条件;先按 local_all 落,口径确认后重算流水切换,不需改结构 |
| 同步直发的静默丢失 | 上游少一张凭证,事后无人知 | 条件分支兜底(今天可做)→ M3 换发件箱 + 死信通知 |
| 重复触发写回 | 两张凭证 | 幂等键 {source}:{job}:{event}:{revision} + 唯一键;退回重走是已知触发路径 |
办结后 oa_work 那行被搬走 |
发件箱回查不到单据 | 发件箱自带渲染好的 payload 快照,work 列不做外键 |
| 引擎读活配置(流程版本快照不参与运行) | 改了写回模板,在途未达环节的单按新模板发 | 财务类接口"模板只增不改",其余改动时提示影响单数 |
| 密钥进流程 JSON | 随版本快照与流程导出扩散 | 一律走 oa_data_source 的 auth_secret(只进不出,接口只回 secret_set) |
| 上游无批量接口 | 提交 50 行明细打 50 次请求 | 数据源标 batchable;无批量则退化为"取不到只提示不卡提交",绝不循环单条 |
从 work.data 现算在途 |
每次提交按未索引 JSON 路径扫两遍表 | 已否决:仓库无 JSON 聚合先例,统计全走索引列;台账是必需品 |
| 上游总额下调 | 已占用变负,新单全挡 | 旧单不追溯,进「额度异常」清单人工看 |
| 单进程假设 | 多副本部署时进程内缓存与锁失效 | 缓存后端与取任务方式做成可替换,注释写明换 FOR UPDATE SKIP LOCKED |
7. 需要你拍板的(合并去重后 8 条)
开工前置(不答就动不了)
- 上游预算接口能否按科目 + 年度查可用/已用;已用含不含在途;有无冻结接口。
- 每个要反写的接口能否支持幂等键 / 作废 / 改单 / 按时间段查询——决定冲销与对账能否配置。
- 金额是否等于明细合计;审批环节能否改金额(额度按"能改"设计,每次办理重算占用)。
口径类(影响行为,不影响开工)
- 取数失败默认
keep(不阻断填单)还是block;预算类字段建议显式block。 - 超预算与超冲是软控(提示 + 多走环节,推荐)还是硬挡;备用金多冲的钱怎么平(现金退回 / 结转 / 挡死)。
- 写回时机:中间环节就写还是统一办结后写(推荐能晚则晚);备用金能否一人多笔、一张冲销单能否冲多笔。
- 写回模板治理选"只增不改"还是"允许改 + 影响提示"(财务类建议前者);模板由 IT 还是业务顾问配。
范围类
- 外部数据要不要按人 / 部门收口(如销售只能搜自己名下客户);要的话在数据源上声明权限码并由后端强制注入入参。
8. 验收总览
验收脚本自建上游桩、跑完把自己写的行删干净、挂进 scripts/run_all.py 的 ISOLATED。
oa_fetch 与 oa_platform 直接打在唯一的开发库上(夹具编码带运行戳、断言只筛自己的行、
一条 CREATE DATABASE 都没有);剩下几套还是「自建临时库 + 跑完删库」的老写法,由
scripts/run_all.py 统一建统一删,这一轮没动:
python3 backend/tests/oa_fetch.py # ✅ 入站取数 102 条:设计期闸门/密钥不回显/样例通道与换回真接口/
# 带出与篡改盖回/降级两档/缓存命中/限流/熔断/阈值三档/留痕/删除保护
python3 backend/tests/oa_quota.py # ✅ 额度 81 条:三次报销正好卡在第三次、并发两张只放过一张、退回释放、
# 办结不双扣、备用金超冲软硬两态、核销完自动关闭、幂等重放
python3 backend/tests/oa_outbox.py # ✅ 出站反写 89 条:办结与入队同一事务、报文快照不随模板变、
# 500 退避重发但只开一张凭证、停在「发送中」先当结果未知、
# 同单严格有序(幂等键带 {code} 与环节,多模板不会被静默吃掉)、
# 终止触发冲销 / 没配冲销只挂人工待办、死信喊人、
# 密钥与不该出域的字段不进报文、试跑不确认不真发
# 改模板的活配置语义、作废触发冲销、对账差异、死信通知、明细 50 行
python3 backend/tests/oa_platform.py # ✅ 平台化 99 条:消息渠道六个事件各渠道订阅、密钥不回显、
# 没邮箱落 skipped 不静默丢、群机器人一批发一条、退避重试用满进死信、
# HTTP 200 带 errcode 也算失败、测试发送只发给点按钮的人自己、
# 开放平台错密钥与不存在的 key 同一句话、停用即吊销、越权作用域被拒、
# 超限回 429、身份不存在不兜底、非处理人办不了别人的单、
# 事件推送签名可复算与死信重推、调度租约抢不到/交还不掉/过期可接管
# (跑之前先把调度租约让出来:本机开发实例带 OA_SCHEDULER=off 起)
python3 backend/tests/db_guard.py # ✅ 建库这道闸 37 条:一个环境一个库,库名写错不许凭空造库
外加两处一致性检查随 run_all 常态跑:scripts/check_schema_snapshot.py(表结构与 sql/schema.sql 对账)、scripts/check_route_guards.py(新接口有没有挂权限点)。权限码从 27 个变到 32 个(新增 design:datasource / design:quota / design:integration /
design:openapi / system:notify),四处同步改:permissions.py、constants/permissions.ts、i18n 中文名、README 权限表与那个计数。
9. 明确不做
前端不持任何外部凭证、没有自定义 URL 口子;不在 expressions 沙箱里加 IO;列表 / 待办 / 导出 / 打印不现取外部数据;不做通用 API 编排与响应体拼装;不引入 Redis / MQ / 新调度框架 / 新 HTTP 依赖(本仓库刻意只用标准库 urllib);不做双向自动同步;不让自动重推覆盖人工已修正的结论。
10. 建议的第一步
M0 那四条配置先做(半天,不动代码),同时把三件事的答案拿到:预算的在途口径、写回接口的幂等与作废能力、金额能否在审批环节改。这三条回来我就按 M1 → M2 → M3 排下去;如果 M0 跑一个月 invokeResult_error 几乎为零,M3 的投递层还能再往后压,钱花在额度和对账上。
11. 复核补充:二次审查发现的缺口
对自己的方案做了一轮红队审查,确认下面这些前面没覆盖,按"能造成多大伤害"排序。详细处置散在三份细节文档的新增小节里(额度 §12、出站 §17),这里只留台账。
会算错钱的三条:字段的「单位」不参与换算,只是显示后缀(formruntime.unit_problem 注释明确"只影响观感"),所以按万元填单子会安静地错,额度一律元口径 + 引用的字段禁止改单位后缀;dims 是单据级的一组键,一张单跨多个预算科目时表达不了按行分摊占用,要么业务上禁止跨科目单(推荐),要么做行级维度;备用金借款占不占预算没定,定了不占或占一次,否则与冲销双扣。
会丢数据或出重复的四条:发送成功但状态未落库时崩溃会重复发凭证,必须"先落 sending + 结果未知先查上游再重发";审批环节把金额改超支之后单据去向没定义(谁改谁处理 / 退回发起人 / 放行并标记,默认建议退回);期初初始化缺失——在途报销不自动占用、历史未冲销借款进不了台账,必须一次性 backfill 并让财务签字确认后才启用硬挡;待办交接把冲销单转给别人但额度属于原借款人,scope 判据定为按发起人。
运维会咬人的五条:发件箱与流水只增不减要定保留期;启动 ensure_columns() 自动补列但不回填数据、不管索引与改名,回填脚本得单独写;上游常常没有测试环境,要 shadow 模式;集成健康度缺出口(成功率、P95、熔断中、结果未知条数)与连续失败自动停用;映射配错科目这种语义错靠保存挡不住,模板要 draft/published 两态加双人复核。
决策清单追加五条(并入 §7 一起答):跨科目报销单允不允许;备用金借款占不占预算;审批环节改超支后单据怎么处理;上游有没有查询接口用于确认"结果未知";模板发布要不要双人复核。另加三条小项——多币种与税额口径、额度提示文案的多语言、额度页与备用金下拉是否受数据范围权限约束。
结论:架构、分层、分期不需要推翻,缺的集中在期初数据、流程语义(改金额 / 交接 / 跨科目)和运维出口三块。这四条决策不定,M2 就只能做成"提示"而不是"硬挡"。
最后更新:2026-10-14