unis-oa/docs/integration-contract.md

26 KiB
Raw Permalink Blame History

业务系统对接契约 v0.1(由 OA 侧先定,供对方照着开发)

前提:其它业务系统尚未开发,没有取数接口。这份文档趁现在把接口形状定下来, 让上游按 OA 舒适的口径实现——晚一天定,就多一天按别人的形状写适配层。

配套:integration-master-plan.md 总方案;实现细节见 form-data-integration-design.md(入站)与 outbound-integration-design.md(出站)。

0. 三条最要紧的约定(现在定,以后改要换数据)

  1. 金额一律整数「分」(long),不要用浮点、不要用字符串的元。OA 的额度台账就是分, 两边同口径可以省掉一整层换算与四舍五入争议。
  2. 业务主键由 OA 出:OA 把单据号 serial 和幂等键 X-Idempotency-Key 发过来, 上游必须按这个键挡重复。上游内部主键可以自定,但要用 refNo 回传给 OA 存着。
  3. 时间一律 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. 联调与推进

  1. 契约冻结:本文 §0 与 §2 的四个写接口先冻结(尤其 usedIncludesFrozen、幂等、作废、对账查询四问);
  2. OA 先做桩:假上游现在长在 backend/tests/oa_fetch.py 里(Upstream 类:余额、HTTP 状态、 连错次数都能从用例里摆布),102 条入站验收全打在它上面。上游开工时把它抽成独立的 tests/extdata_stub.py,直接交给上游团队当参考实现与联调靶子;
  3. 上游按契约开发,OA 侧不阻塞:所有功能在桩上跑通并上线(预算总额与备用金由财务导入维护);
  4. 真实系统就绪时只换两处:数据源的地址与密钥,以及额度总额来源从"手工导入"改成"接口同步" ——占用与核销流水一行都不用改,因为 OA 从一开始就是按"本地有完整台账"设计的。

6. 请上游回答的四个问题(决定 OA 侧怎么配)

  1. 预算的"已用"含不含已提交未办结的在途?给不给 frozen 与冻结/释放接口?
  2. 写接口能否支持 X-Idempotency-Key 幂等?重复请求的行为是返回首次结果还是报错?
  3. 有没有作废 / 改单接口?
  4. 有没有按时间段或按单号查询已生成单据的接口(对账与结果确认用)?

7. 顺带一件事:如果这个系统还想把页面直接嵌进 OA

表单里有一格「外部页面」(provider=embed,见 embed-page-field-design.md), 用来把你们已有的页面摆进审批页,同一个功能不必在 OA 再开发一遍。这条路上你们要做的不多, 四条都是能不能嵌进去的前提,不是可选优化:

  1. 让 OA 嵌得进来:Content-Security-Policy: frame-ancestors https://oa.example.com (别再用 X-Frame-Options,它表达不了多来源);
  2. 去掉 frame-busting(检测到 window.top !== window.self 就把自己弹出去那段);
  3. 免登走 OA 发的一次性短码:短码在地址 # 之后,你们前端取到它、交给自己后端, 后端带双方约定的应用密钥调 POST /api/v1/embed/tickets/verify 换"现在站在屏幕前的是谁"。 短码 60 秒过期、只用一次、库里只存哈希;用第二次必然失败,但密钥不对时它不会被烧掉, 可以放心重试;
  4. 地址上的参数(?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 那一条最要紧的三件事:

  1. 以打开那一页的这个人身份办,走的是 OA 引擎原来那条办理通路——环节字段权限、必填、 额度、闸门一条都不会因为"来的不是浏览器"少跑;
  2. 你们只说方向(agree / refuse / submit),出口名由 OA 按这一环真实存在的出口去匹。 匹不唯一会挡下来并把候选念给你们(routeChoices),请让你们的开发把出口名一起回传, 别指望 OA 替你们猜——猜错的代价是一张走了错分支的单,而两边日志都写着成功;
  3. 那条待办要是已经被人在 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),这一节是 你们要照着的四个接口与一条送审报文。四条铁律先说在前面:

  1. 结论只进台账,不进流转。回传接口不碰流程:OA 什么时候往下走,由提交那一刻 OA 自己的闸门判。 要"审完就让流程往下走",请另外调现成的 POST /api/v1/open/tasks/{id}/execute 把那条待办办掉 (identity 传审核人本人);两个入口共用同一条待办,谁先办谁生效,第二个会收到"已被谁处理", 这不算失败,别重试;
  2. 批次号 bizKey 是 OA 出的(§0 第 2 条同一分寸),回传时原样带回来。幂等、对账、人工排查全靠它;
  3. 重复回传和迟到回传都回 200,changed=false。把重试当错误,你们会一路重试到把限流打满;
  4. 已出结论的那一批不许改判。要改判请让 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 请票据系统回答的三件事

  1. 送审接口吃不吃 X-Idempotency-Key;同一批次重复送达是回首次结果还是报错;
  2. 有没有按批次号作废的接口。没有的话 OA 侧的"撤回送审"只能标自己台账,你们那边会留下一次 没人收的任务(这份契约 §2.3 说的是同一件事);
  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 里真跑到过。)