26 KiB
业务系统对接契约 v0.1(由 OA 侧先定,供对方照着开发)
前提:其它业务系统尚未开发,没有取数接口。这份文档趁现在把接口形状定下来, 让上游按 OA 舒适的口径实现——晚一天定,就多一天按别人的形状写适配层。
配套:integration-master-plan.md 总方案;实现细节见 form-data-integration-design.md(入站)与 outbound-integration-design.md(出站)。
0. 三条最要紧的约定(现在定,以后改要换数据)
- 金额一律整数「分」(
long),不要用浮点、不要用字符串的元。OA 的额度台账就是分, 两边同口径可以省掉一整层换算与四舍五入争议。 - 业务主键由 OA 出:OA 把单据号
serial和幂等键X-Idempotency-Key发过来, 上游必须按这个键挡重复。上游内部主键可以自定,但要用refNo回传给 OA 存着。 - 时间一律
YYYY-MM-DD HH:mm:ss(东八区,不带时区后缀也行但要写死一个), 日期用YYYY-MM-DD,年度字段用YYYY四位数。跨系统对账最容易死在这上面。
其余统一约定:Content-Type: application/json; charset=utf-8;鉴权用一个固定请求头
(X-Oa-Api-Key 或对方惯用的等价头),不要 cookie / session / 跳转登录;响应外层固定
{ "code": 0, "message": "", "traceId": "", "data": ... },code=0 才算成功,失败时
message 必须是能给填单人看的一句中文(这句会原样出现在 OA 的提示里);
读接口 P95 ≤ 1.5s、绝对上限 5s(OA 默认 5s 超时,超了走降级);写接口 ≤ 3s;
限流按数据源协商并在 OA 侧配;生产/测试各一套地址与密钥。
1. OA 需要的读接口(入站)
1.1 按维度查预算(R2 的命脉)
POST /budget/query
{ "dims": [ {"company":"1000","budget":"CC100200","year":"2026"} ], // 支持一次多组,上限 50
"withUsed": true }
-> { "code":0, "data": { "items": [
{ "company":"1000","budget":"CC100200","year":"2026",
"total": 100000000, // 预算总额,单位分
"used": 42000000, // 已用,单位分
"frozen": 30000000, // 已被冻结但还没实花的,单位分(见下)
"usedIncludesFrozen": false, // ★ 关键一位:used 里含不含 frozen
"at": "2026-10-14 09:30:00" } ] } }
usedIncludesFrozen 这一位是整套额度口径的开关(对应额度方案里的 basis):
它是 true,OA 就只把自己本地的在途占用加上去;是 false,OA 就自己记已核销。
这一位必须由上游给准确答案,猜就会双扣或漏扣。若上游一时给不出 frozen,
先恒传 0 并把 usedIncludesFrozen 设为 false,OA 走"全记本地",不会卡住上线。
1.2 主数据:分页 + 增量 + 搜索(三合一即可)
POST /masterdata/query
{ "type": "costCenter", // costCenter | budgetSubject | supplier | material | employee …
"keyword": "华东", // 空=不过滤;至少要 2 个字
"cursor": "", // 上一页返回的游标,首页空串
"since": "2026-10-13 00:00:00", // 只要这个时间之后有变化的;空=全量
"limit": 500 }
-> { "code":0, "data": { "items": [
{ "value":"CC100200", "label":"华东销售一部", "parent":"EAST", "enabled": true,
"extra": {"taxRate":"13","owner":"张三"}, "updatedAt":"2026-10-13 11:00:00" } ],
"cursor":"eyJvZmZzZXQiOjUwMH0=", "hasMore": true, "totalEstimate": 3120 } } }
要求:value 稳定不复用(停用就置 enabled=false,不要删除、不要换新值,
否则在途单据的名字翻不出来);extra 只放要展示的附加值,别塞大对象;
分页游标由上游自己定,OA 不解释;since 增量是强烈建议项,没有它 OA 只能天天全量拉。
1.3 按值反查(只读态、打印单、导出用)
POST /masterdata/values
{ "type":"costCenter", "values":["CC100200","CC100300"] } // 上限 200
-> { "code":0, "data": { "items":[ {同 1.2 的行形状} ] } }
2. OA 需要的写接口(出站)
2.1 冻结 / 释放额度(能把"第三次挡下"做得更准)
POST /budget/freeze Header: X-Idempotency-Key: oa:{serial}:freeze:1
{ "serial":"BX20261000123", "dims":{...}, "amount": 3000000, "reason":"报销提交预占" }
-> { "code":0, "data": { "freezeNo":"FZ000088" } }
POST /budget/unfreeze Header: X-Idempotency-Key: oa:{serial}:unfreeze:1
{ "serial":"BX20261000123", "freezeNo":"FZ000088" }
没有这两个接口也能上线:额度全记 OA 本地即可,只是上游看到的可用数会滞后。 有,则两边看到的是同一笔冻结,别人从 ERP 里也报不走这笔钱——强烈建议做。
2.2 写单据 / 生成凭证(出站主链路)
POST /document/create Header: X-Idempotency-Key: oa:{serial}:voucher:1
{ "serial":"BX20261000123", "bizType":"expense", "bizDate":"2026-10-14",
"company":"1000", "dept":"CC100200", "amount":3000000, "creatorAccount":"10086",
"lines":[ {"subject":"660001","amount":1000000,"remark":"高铁"} ],
"operator":{"identity":"...","name":"..."} }
-> { "code":0, "data": { "refNo":"Voucher-2026-10-0001", "status":"posted" } }
三条硬要求:幂等(同一把键重复请求,必须返回第一次那条,而不是报错、更不是生成两张);
返回 refNo(OA 会显示在单据上并用于对账);code != 0 时 message 是能给人看的一句话。
2.3 作废 / 冲销
POST /document/cancel Header: X-Idempotency-Key: oa:{serial}:cancel:1
{ "serial":"BX20261000123", "refNo":"Voucher-2026-10-0001", "reason":"单据作废" }
没有这个接口,出站就只能统一在办结后写——中间环节写了,退回就没法收。 这一条直接决定 R4 的触发点设计,请在契约冻结前给明确答复。
2.4 按时间段查询(对账用,也是"结果未知"的唯一救命的)
POST /document/query
{ "bizType":"expense", "from":"2026-10-13 00:00:00", "to":"2026-10-14 00:00:00",
"cursor":"", "limit":500 }
-> { "code":0, "data": { "items":[ {"serial":"BX20261000123","refNo":"Voucher-2026-10-0001",
"amount":3000000,"status":"posted","createdAt":"2026-10-13 21:02:11"} ],
"cursor":"...", "hasMore": false } } }
必须支持按 OA 的 serial 单条精确查({"serial":"..."}),否则 OA 发送后崩溃、
不知道有没有成功时无法自证,只能人工去上游翻。这是出站方案里"结果未知"处置的前提。
3. 如果某项做不到,OA 侧的降级(提前对齐,别上线时才发现)
| 缺什么 | OA 的退路 | 代价 |
|---|---|---|
无 frozen / 无冻结接口 |
额度全记 OA 本地,上游总额定时同步 | 上游侧看到的可用数滞后一个同步周期 |
used 口径说不清 |
按 false 处理,全记本地 |
上线后若发现上游也记了,需一次性重算流水 |
无增量 since |
每天全量拉 + 按 updatedAt 跳过未变行 |
数据量大时同步窗口变长 |
| 无批量查询 | 逐条查 + 强缓存 | 提交变慢,额度校验可能退化为软提示 |
| 无幂等键支持 | OA 只按状态挡重发 + 崩溃后走人工确认 | 极端情况下仍可能重复,需要财务对账兜底 |
| 无作废接口 | 出站一律延后到办结之后写 | 拿不到"中间节点写回"的能力 |
| 无对账查询 | OA 只自证"已成功发送 + 响应摘要" | 无法证明上游真的有这张单 |
| 只有测试环境没有生产 | 影子模式:正常渲染落库但不真发 | 上线首周灰度用,无功能损失 |
4. 上游还需要知道 OA 会发什么
写接口的请求体由 OA 侧 L2 写回模板渲染(映射规则见 outbound-integration-design.md §4), 渲染能力边界是:字段取值(表单字段 / 单据系统值 / 常量 / 明细逐行)、少量转换函数(元分换算、日期格式、拼接)、 枚举值翻译(走 OA 数据字典)、条件发送。上游接口形状越接近"字段一一对应 + 少量必要翻译", 配置就越简单;如果上游要求复杂报文拼装(嵌套很深的结构、需要跨行汇总后再拆包、要求签名串自拼), 每多一类都要在 OA 侧加一次开发。所以:接口设计时请把扁平结构作为目标。
5. 联调与推进
- 契约冻结:本文 §0 与 §2 的四个写接口先冻结(尤其
usedIncludesFrozen、幂等、作废、对账查询四问); - OA 先做桩:假上游现在长在
backend/tests/oa_fetch.py里(Upstream类:余额、HTTP 状态、 连错次数都能从用例里摆布),102 条入站验收全打在它上面。上游开工时把它抽成独立的tests/extdata_stub.py,直接交给上游团队当参考实现与联调靶子; - 上游按契约开发,OA 侧不阻塞:所有功能在桩上跑通并上线(预算总额与备用金由财务导入维护);
- 真实系统就绪时只换两处:数据源的地址与密钥,以及额度总额来源从"手工导入"改成"接口同步" ——占用与核销流水一行都不用改,因为 OA 从一开始就是按"本地有完整台账"设计的。
6. 请上游回答的四个问题(决定 OA 侧怎么配)
- 预算的"已用"含不含已提交未办结的在途?给不给
frozen与冻结/释放接口? - 写接口能否支持
X-Idempotency-Key幂等?重复请求的行为是返回首次结果还是报错? - 有没有作废 / 改单接口?
- 有没有按时间段或按单号查询已生成单据的接口(对账与结果确认用)?
7. 顺带一件事:如果这个系统还想把页面直接嵌进 OA
表单里有一格「外部页面」(provider=embed,见 embed-page-field-design.md),
用来把你们已有的页面摆进审批页,同一个功能不必在 OA 再开发一遍。这条路上你们要做的不多,
四条都是能不能嵌进去的前提,不是可选优化:
- 让 OA 嵌得进来:
Content-Security-Policy: frame-ancestors https://oa.example.com(别再用X-Frame-Options,它表达不了多来源); - 去掉 frame-busting(检测到
window.top !== window.self就把自己弹出去那段); - 免登走 OA 发的一次性短码:短码在地址
#之后,你们前端取到它、交给自己后端, 后端带双方约定的应用密钥调POST /api/v1/embed/tickets/verify换"现在站在屏幕前的是谁"。 短码 60 秒过期、只用一次、库里只存哈希;用第二次必然失败,但密钥不对时它不会被烧掉, 可以放心重试; - 地址上的参数(
?no={arg.contractNo}那几个)只表示"要打开哪一单",不能当身份用: 能不能看这一单,由第 3 步换到的那个人在你们系统里的权限决定。
如果那一页是你们按单据现生成的(每次给一条带签名的临时链接),OA 侧可以配成"先调接口取链接":
你们多提供一个接口,回一段 JSON,链接放在约定好的那一栏(data.url 之类),也可以只回路径
(/pages/contract/123,OA 按接口地址补全来源)。两件事要提前说定:链接挂在哪个域名上
(没在 OA 登记过的来源一律不嵌,哪怕这一页本身允许被嵌),以及别把它做成只能打开一次
——审批人点一下「刷新」就是一条新链接,iframe 装载也常常带预取。
可选的那条 postMessage(自适应框高、把值回填进表单、请 OA 发起这张单)协议在
embed-page-field-design.md §11.1,最小一段 JS 就能接;
判断口径的唯一实现在 OA 前端的 utils/embedBridge.ts,那一份与本文不重复写第二遍。
7.1 如果你们要在自己那边把事办完之后回写 OA
三种情形都走同一条通道、同一把密钥(就是第 3 条那条应用密钥),共用第 3 步验票响应里
callback.token 那把会话令牌。(OA 那一侧谁在哪一栏配什么,见
embed-configuration-guide.md §1–§2;你们这一面照本节即可。)
POST /api/v1/embed/callback Header: X-Oa-Integration-Key: {那条应用密钥}
{ "code":"erp_contract", "token":"oes_…", "kind":"prefill", "values":{ "amount":"12800" } }
{ "code":"erp_contract", "token":"oes_…", "kind":"start", "job":"JOB…", "serial":"BX-2026-0091" }
{ "code":"erp_contract", "token":"oes_…", "kind":"decide", "decision":"agree", "opinion":"已核验" }
先拿这一趟能做什么,再决定要不要调。验票响应里 callback.kind 就是那一份清单
(prefill / start / decide),它由 OA 后端按"这一格勾了哪几件事 + 这条源配没配密钥 +
此刻这个人手上有没有待办"算出来,你们申报的一律不算。清单里没有的那一档调了必挡,
但报错会说要紧的那句话:去哪儿勾、这一环有几个出口、这个人是不是已经办过了。
prekey(形如 PRE7K2M9XQ4,握手消息与验票响应都给)建议当成你们那边草稿表的外键存下来:
- 它是 OA 在"发起页还没保存"那一刻唯一能给你们的标识,也是两次打开认同一趟的依据 (同一个人同一格刷新三次,OA 只给一个号,你们不该生出三张草稿);
- 你们从自己那边发起时,把它填进
POST /api/v1/open/works的bizKey。这一趟只要已经 存在一张单了——不管是你们先建的还是那个人在 OA 里点的「发起」——OA 都不再新建, 回原单 +alreadyStarted:true。重复发起的代价(退单、终止、留痕、通知)比多问一句贵得多; - 它不是凭据:可以印在你们自己的工单标题上、可以在电话里念。授权靠令牌和密钥,不靠它。
你们那套状态词不必为 OA 改。 OA 默认只认 agree / refuse / submit,但那一格可以配一张
对照表(例如 APPROVED→agree、REJECTED→refuse),你们报文里就照自己家那套写;
大小写与首尾空格都不计较。这张表只能翻到这三种结论,翻不到出口名——出口仍由 OA 判。
要配请找 OA 侧管表单的那个人(在表单那一格的外部页面面板上,勾了「提交本环节」才看得见)。
kind=decide 那一条最要紧的三件事:
- 以打开那一页的这个人身份办,走的是 OA 引擎原来那条办理通路——环节字段权限、必填、 额度、闸门一条都不会因为"来的不是浏览器"少跑;
- 你们只说方向(
agree/refuse/submit),出口名由 OA 按这一环真实存在的出口去匹。 匹不唯一会挡下来并把候选念给你们(routeChoices),请让你们的开发把出口名一起回传, 别指望 OA 替你们猜——猜错的代价是一张走了错分支的单,而两边日志都写着成功; - 那条待办要是已经被人在 OA 里办掉了,回 200 +
already,不是失败,别重试别报警。
反过来的那一句:OA 也可能打给你们。 人在发起页没保存就返回时,如果 OA 侧开了那一档,
你们会收到一句 DELETE(或你们那条记录上配的 POST/PUT/PATCH),请求体固定一个键:
{ "oa_flow_number": "BX20261023001" }——键名是你们那条记录上写的"你们按哪个字段收 OA 的单号",
值是这一趟预留的正式单号(还没排上号时是 prekey),凭证头与你们验票用的同一把密钥。
这一条只要求幂等:同一趟可能报到两次(关页签那一刻常常也是会话过期那一刻),回 404 按
"那边没有这张单"算成功。你们没建过草稿就直接回 200,别回 4xx 让人去查一条不存在的单。
什么情况下 OA 不会打过来(这一趟已经成了单、挂着草稿、那一格没开这一档……)与完整报文在
embed-configuration-guide.md §4.7。
要以另一个人的名义办、或者要长期批量的集成,别用这条通道(它绑的是"这一趟打开", 几小时就废),走 §8.6 那条开放平台的路。整套设计与 OA 侧配法在 embed-action-design.md。
8. 票据核验接口(报销附件的外部初审)
报销单在 OA 发起,发票影像在你们系统里初审。OA 侧已经把闸门、台账、附件通道、回传接口都做完了 (设计见 invoice-review-integration-design.md),这一节是 你们要照着的四个接口与一条送审报文。四条铁律先说在前面:
- 结论只进台账,不进流转。回传接口不碰流程:OA 什么时候往下走,由提交那一刻 OA 自己的闸门判。
要"审完就让流程往下走",请另外调现成的
POST /api/v1/open/tasks/{id}/execute把那条待办办掉 (identity传审核人本人);两个入口共用同一条待办,谁先办谁生效,第二个会收到"已被谁处理", 这不算失败,别重试; - 批次号
bizKey是 OA 出的(§0 第 2 条同一分寸),回传时原样带回来。幂等、对账、人工排查全靠它; - 重复回传和迟到回传都回 200,
changed=false。把重试当错误,你们会一路重试到把限流打满; - 已出结论的那一批不许改判。要改判请让 OA 重新送审(会另起一版
revision),别拿同一批次覆盖。
8.1 OA 发给你们的送审报文
报文长什么样由 OA 这边的 L2 模板决定(字段名可以完全照你们的接口来),但要用的料 OA 一定给。 模板里引用这几个合成键就行,它们只在渲染这一刻存在、不落进表单:
| 模板里写 | 给出去的是 |
|---|---|
{form._checkBizKey} |
批次号,如 BX20261000123:1(回执要原样带回来) |
{form._checkSerial} |
OA 单号 |
{form._checkScene} |
核验场景,现在是 invoice_check |
{form._checkRevision} |
第几版(附件清单变一次涨一版) |
{form._checkFiles} |
附件清单 [{attachmentId,name,size}],只有名字和大小 |
{form._checkManifestUrl} |
那条清单入口的完整地址(7 天有效) |
投递走 OA 现成的发件箱:自带退避重试(1m/5m/30m/2h/6h)、死信、一键重推、影子模式,
同一批次同一版只会成功投递一次。报文里没有附件本体,请拿清单地址立刻拉清单、
再按清单逐条拉文件;拉失败就重新拉一次清单再拉,不必请 OA 重发整批。
8.2 拉附件清单(匿名 + 签名,不要访问令牌)
GET /api/v1/open/checks/files?bizKey=...&exp=...&sig=...
-> { "code":0, "data": { "bizKey":"BX20261000123:1", "scene":"invoice_check",
"sceneLabel":"票据初审", "serial":"BX20261000123", "title":"张三的差旅报销",
"fileCount":8, "files":[ { "attachmentId":"...", "name":"发票1.pdf", "size":482113,
"url":"https://oa.example.com/api/v1/open/attachments/.../download?job=...&exp=...&sig=...",
"path":"/api/v1/open/attachments/.../download?job=...&exp=...&sig=...", "expiresIn":600 } ] } }
url 里的域名取 OA 配的「系统访问地址」;没配时 url 只有路径那截(path 一直在),
同域反代的情况下你们自己拼上入口即可。
清单里每条 url 只有 10 分钟:放宽的是"能再问一次清单",不是"文件一直能下"。
拉失败就重新问一次清单再拉,不必请 OA 重发整批。批次已作废或已撤回时这条会 403。
GET 那个文件地址支持 Range,几十兆的扫描件套件可以断点续传。签名绑死了
附件 id + 单号 + 过期时间,换单、换附件、改 exp 任意一个都会 403(返回体是一句人话,
reason=CHECK_LINK_INVALID),不是我们没查,是签名算不出来。
8.3 回传结论
POST /api/v1/open/checks/report Header: Authorization: Bearer {访问令牌} scope: check:write
{ "provider":"invoice_check_api", "bizKey":"BX20261000123:1", "serial":"BX20261000123",
"scene":"invoice_check", "status":"partial", "reason":"8 张里 1 张抬头不符",
"items":[ { "attachmentId":"...", "invoiceNo":"04400...","amount":1200.00,
"status":"rejected", "reason":"购买方名称与报销人不符" } ],
"checker":"王财务", "checkedAt":"2026-10-22 10:12:04", "version":3, "externalRef":"TIC-2026-8812" }
-> { "code":0, "data": { "bizKey":"...", "status":"partial", "changed":true, "late":false,
"duplicate":false, "droppedItems":0, "note":"结论已记录:部分通过" } }
status 认这几个:submitting / checking / passed / partial / rejected。写别的当场拒收
(CHECK_INVALID),不会静悄悄变成一个"结果未知"来挡人。items 里的 attachmentId 必须是这次
送审给出去的那几个,不属于这张单的会被丢掉并在 droppedItems 里报个数——那是你们拼错单的最快信号。
reason 在驳回时必须说清是哪一张、为什么,只回"审核未通过"会被财务退回给你们。
两种"什么都没改"也会回 200,note 会当场告诉你们 OA 现在算的是哪个结论:
{ ..., "duplicate":true, "note":"重复回传,已按首次结果返回" }
{ ..., "late":true, "note":"这条比台账上的结论旧(或这一批已出过结论),已丢弃:台账仍是已通过" }
迟到有两种:version 比台账上那个旧(网络重放),以及这一批早就出了终态(想改判)。两种都不落库,
GET /open/checks/{bizKey} 里能翻到最后一条被丢掉的回执(responseSnapshot.late)。
要改判只有一个办法:让 OA 重新送审,拿新的 bizKey(结尾那个 :N 会 +1)。
还有一种情况必须由你们主动重送:OA 侧发现送审之后凭证清单变了(补票、换票、撤票), 旧的那一版会作废,闸门会一直挡到你们对新版回传结论为止——此时旧批次那条签名清单链接会直接 回 403(单子都不让走了,票据影像不该还能拖走)。请按新批次号处理,别拿旧批次重试。
8.4 你们对账时查这一批(可选,但有它就饿不死)
GET /api/v1/open/checks/{bizKey}?provider=invoice_check_api scope: check:read
-> { "code":0, "data": { "bizKey":"BX20261000123:1", "revision":1, "serial":"BX20261000123",
"status":"checking", "statusLabel":"初审中", "open":true, "verdict":"", "reason":"",
"summary":"8 张 / 可报 12,300.00 元", "items":[], "checker":"", "fileCount":8,
"filesHash":"...", "pollAttempts":2, "nextPollAt":"2026-10-22 09:41:02",
"externalRef":"", "createTime":"2026-10-22 09:30:11", "files":[ ... ] } }
返回的就是 OA 台账上这一批的现状,连现签好的一批文件地址也带上,省一次往返。 只有一样不给看:谁替这张单放过行——那是 OA 内部的责任信息。
"我把结论发过去了,你到底收到没有"——问这一条,别打电话。OA 侧也有兜底:你们迟迟不回传时, OA 会按这个接口反过来问你们(配了查询接口才有这条路,见下一节第 3 条)。
8.5 请票据系统回答的三件事
- 送审接口吃不吃
X-Idempotency-Key;同一批次重复送达是回首次结果还是报错; - 有没有按批次号作废的接口。没有的话 OA 侧的"撤回送审"只能标自己台账,你们那边会留下一次 没人收的任务(这份契约 §2.3 说的是同一件事);
- 有没有按批次查结论的接口。没有的话 OA 的"结果未知"这一档只能靠人工翻, 对账收敛这条路整个断掉。
8.6 要"审完就让流程往下走":办掉那条待办
回传结论只改台账,不改流转。想让单子往下走,用现成的待办接口(scope: task:write):
POST /api/v1/open/tasks/{id}/execute Header: Authorization: Bearer {访问令牌}
{ "identity":"财务本人的登录账号", "route":"通过", "opinion":"票据已核验无误", "data":{} }
-> { "code":0, "data": { "work":{...}, "done":true, "tasks":[] } }
identity 必须是这条待办的处理人本人(或其代理人),OA 不接受"以管理员身份"这种兜底。
同一条待办有两个入口(OA 审批页与这里),谁先点谁生效;后到的那一次 OA 回 200:
-> { "code":0, "data": { "alreadyHandled":true, "handledBy":"王财务",
"handledIdentity":"wangcw", "handledAt":"2026-10-22 10:20:31",
"activity":"财务复核", "route":"通过", "done":true,
"note":"这条待办已由 王财务 于 2026-10-22 10:20:31 办掉(出口「通过」),本次调用没有改动任何东西" } }
这一条不是失败,别重试、别报警:它同时覆盖"OA 页面已经办过"与"或签里被同环节另一位办掉、
你这条被系统自动结掉"两种情况(后者的 note 会写明是同环节其他处理人)。要区分"真的办成了"与
"其实早被人办了",看 alreadyHandled 这一位即可。只有身份对不上、单号确实是错的,才回非 200。
最后更新:2026-10-23(新增 §7.1:嵌页面那一格的服务端回写通道(/embed/callback 那三档)、
prekey 当草稿外键与 bizKey 幂等键的用法、decide 只报方向不报出口这三条口径。
OA 侧已实现并有验收脚本覆盖,等上游照此开发。上一轮:2026-10-22(§8 补两处口径:① 迟到回传的 note 现在带上「台账仍是哪个结论」,并说清
"附件清单变了必须由你们按新批次重送"、旧批次清单链接会回 403;② 新增 §8.6,把"代财务办那条待办"
的响应形状写全——同一条待办被 OA 页面先办掉时回 200 + alreadyHandled,不是失败。
这两条都在 scripts/invoice_demo/ 的场景 5 / 场景 6 里真跑到过。)