unis-oa/docs/integration-master-plan.md

36 KiB
Raw Permalink Blame History

外部系统集成总方案:表单取数、预算与备用金额度、审批后反写

一份总方案收拢四件事,其余三份是细节展开:

细节文档 管什么
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 <─┘  状态变更同事务入队
       ▲                     │
       └── 后台发送(现有调度线程 · 退避 · 死信 · 一键重推 · 对账)

四个共享件,四条需求全部踩在上面,只做一份:

  1. oa_data_source 数据源注册表:外部系统的地址、鉴权、超时、成功判定、密钥只进不出。入站的 fetch 与出站的 L1 用同一张表(direction 区分),密钥托管、域名白名单、禁跟随重定向、oa_data_source_call 审计各写一遍。
  2. 表达式沙箱 expressions:公式、条件分支、映射里的派生值、环节脚本共用一个沙箱,沙箱内永不做 IO。这是"设计器里写的东西不会拖垮引擎"的根。
  3. 调度线程 + 排期判定:现有的 _scheduler_loop 与 service/sync_jobs.py(四档排期、迟到宽限、重试预算、管理页)同时服务镜像同步、额度提醒、出站发送、对账。不加 MQ、不加第二个调度框架。
  4. 数据字典:选项、级联、带出、跨系统枚举翻译(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. 今天就能配的(零开发,半天)

  1. 非资金类反写:流程「结束」前插一个服务调用环节,配 url / method / headers / timeout / resultPath,上游返回的凭证号会留在单上,打印导出都能用。
  2. 给它加个兜底:服务调用后接一个条件分支,判 <resultPath>_error 非空 → 走「集成失败-人工处理」环节。失败从静默丢失变成有人接手,纯配置。
  3. 预算/额度类展示与软控:字典项附加值放 {"total":..., "used":...},「字典带出」带进两格只读字段;明细合计用公式 total(expenses, amount);再来一个只读公式字段算可用;「超预算说明」配条件必填「可用 小于 0」,并让条件分支把这种单子自动送到财务环节。
  4. 别做的事:把密钥写进环节 headers(每次发布流程都会把整份设计 deepcopy 进版本快照,等于每版留一份副本且能随导出搬走);指望数字字段的 min/max 当预算闸门(提交时后端不校验它)。

这四条能把大部分日常需求先接住,同时给后面的开发攒真实数据:invokeResult_error 一个月出现几次,直接决定 R4 要不要做重。

4.5 上游系统还不存在时,排期这样改

现实更新:其它业务系统尚未开发,一个取数接口都没有。这反而让事情简单,三处调整:

  1. 最硬的前置问题自动消解。"上游已用含不含在途"暂时没有上游可问 → 额度口径先定 basis=local_all(总额由财务导入、占用与核销全在 OA),开工不再被它挡住。等业务系统出现时 按契约补上 usedIncludesFrozen,切换只是改数据源配置 + 一次性重算流水。
  2. M2 提到第一位,M1 降级。额度台账现在完全自给自足(预算总额 Excel 导入 + 本地占用核销), 不依赖任何外部接口就能把 R2 / R3 做完并真实上线;而入站取数、镜像同步、fetch 执行器 在拿到真实接口前只能对着桩跑,价值降级——M1 只保留数据源注册表这一层骨架(M2、M3 都要用)。
  3. 多出一份必须现在就写的交付: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、按服务商带预设)。 弹窗四个页签:

  1. 连接:名称 / 编码 / 所属系统 / 通道(真接口 / 样例响应) / 方法 / URL / 请求头 / 鉴权类型与密钥 / 超时 / 重试 / 缓存秒数 / 限流;选了样例就换成一个样例响应文本框(填一份 JSON,等价于自己家的假接口);
  2. 入参:两列表「参数名 ← 取值」,取值三种写法(常量 / {form.字段} / {auto:系统值}), 字段一律下拉选(从绑定表单的字段列表取),不让手打 key;
  3. 响应解析(样例驱动,能不能真配起来全在这一页):点「拉取样例」或粘一段响应 JSON → 界面渲染成 JSON 树 → 在树上点节点设为「列表根节点」「值取哪个键」「名称取哪个键」「附加值取哪几个键」, 单值场景就是点「阈值/余额」那个键。不让人手写 data.balance 这种字符串路径;
  4. 用途与策略:用途多选(下拉选项 / 远程搜索 / 单值带出 / 写回)、失败降级 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.py 81 条);M1 里除了镜像表 (oa_external_record 与 dicts.items_of() 未命中回落)之外都落了,并且多做了原计划里没有的 provider=mock 样例通道与阈值规则两块——上游一个接口都没有的情况下,这是唯一能把 「取数 + 阈值 + 额度」整条链路今天配完验通的办法(§4.5 与入站方案 §5.4 的 provider=mock);M3 已落地(发件箱、写回模板、映射渲染器、预览 / dry-run / 报文历史、导入导出、死信通知、冲销链、响应回写,验收 tests/oa_outbox.py 89 项),剩下对账差异清单与灰度压测那几项见反写方案 §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 条)

开工前置(不答就动不了)

  1. 上游预算接口能否按科目 + 年度查可用/已用;已用含不含在途;有无冻结接口。
  2. 每个要反写的接口能否支持幂等键 / 作废 / 改单 / 按时间段查询——决定冲销与对账能否配置。
  3. 金额是否等于明细合计;审批环节能否改金额(额度按"能改"设计,每次办理重算占用)。

口径类(影响行为,不影响开工)

  1. 取数失败默认 keep(不阻断填单)还是 block;预算类字段建议显式 block。
  2. 超预算与超冲是软控(提示 + 多走环节,推荐)还是硬挡;备用金多冲的钱怎么平(现金退回 / 结转 / 挡死)。
  3. 写回时机:中间环节就写还是统一办结后写(推荐能晚则晚);备用金能否一人多笔、一张冲销单能否冲多笔。
  4. 写回模板治理选"只增不改"还是"允许改 + 影响提示"(财务类建议前者);模板由 IT 还是业务顾问配。

范围类

  1. 外部数据要不要按人 / 部门收口(如销售只能搜自己名下客户);要的话在数据源上声明权限码并由后端强制注入入参。

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