支付宝对账脚本 v3.6.1：聚合结算 + 账户流水 + 余利宝明细的整合对账

电商财务团队每月对账时最头疼的不是算账，而是「同一个支付宝店、对三张账单」。聚合结算账单里看到提现和平台代收；账户流水里看到余额退款、保证金扣款、记账本转账；余利宝明细里又有申购、赎回、收益。这三张表描述的是同一店铺的同一账期，但用的字段口径不同、表的颗粒度不同、落到金蝶的单据类型也不同——稍有不慎就会出现"重复计收"或"互抵错位"。

本文聚焦支付宝对账脚本 v3.6.1（2026-09-10 用户定稿）的工程实现：它不是把三张表的行简单拼起来，而是用「平台聚合范式 + 双码匹配 + matchedSupplyOrderIds 收窄机制」把三表的 BillRow 合并成一个统一的 IncomePlanItem / ExpenseAggregation 流，再交给转换脚本出金蝶单据。

[来源：2026-09-10 真实计划 IRP-ALIPAY-20260905-0001 复盘 + docs/BUSINESS_REQUIREMENT/17-alipay-integration-transform.md + docs/insights/contents/4.3.1-alipay-full-reconciliation-manual-three-tables.md]

一、为什么是 v3.6.1：三表整合的关键修补

在 v3.6.1 之前，支付宝对账脚本虽然已经能跑通三表（聚合结算 aggregated_settlement + 账户流水 account_flow + 余利宝 yulibao），但存在两个**接口类"金额虚增"或"行级漏判"**的隐患：

1.1 「部分结算」行的虚增：把整张暂估单全部 SKU 聚进单据体行

R2 部分结算只结了一行（净额 = 供应链某单行金额），但脚本走 finalize 兜底时，把"全部未下推财务应收的供应链行"作为 matchedSupplyOrderIds 返回。执行层拿到这个全集，就会把这些行的全部 SKU 聚进财务应收单体行，剩余未结算的 SKU 下期重复出单。实证：订单只该按 522 行匹配下推，结果按整张暂估单的 1,200 行全聚，下期重复出 678。

1.2 「整单轧差」承载行的虚增：把负向退货行拦在物料外

整单轧差承载行的命中子集本身含负向退货行（出库+退货、账单轧净场景）。原方向过滤把退货行拦在物料外，财务应收单按出库全额虚增（如该结 219 按 438 出单）。

v3.6.1 用两条最小修补解决这两类虚增：

R2 单行命中档补返回显式 matchedSupplyOrderIds = [命中行 id]（不要走 finalize 兜底）。
成功兜底 matchedIds 由 salFinBaseQty 过滤后全集收窄为叠加账期过滤后的 periodOrders——物料范围与主匹配核对的供应链净额同口径。

实证（IRP-ALIPAY-20260905-0001）：判定结果与 v3.6.0 全等（零回归），但物料明细范围收紧后，财务应收单的金额从虚增状态回落到正确口径。这是同行写不出的反直觉干货——很多团队以为"对账成功了，结果就对"，但对账成功 ≠ 物料明细正确，v3.6.1 修的正是后者的同一类口径。

更深入的沙箱契约与轮次链可参见项目内 .opencode/skills/reconciliation-script-development/SKILL.md。

二、三表账户流整合：平台聚合范式的标准实现

proc-012 支付宝三表对账流程图：聚合结算+账户流水+余利宝明细

支付宝三表对账流程图（proc-012）：聚合结算 + 账户流水 + 余利宝明细的三路数据源，通过统一的「对账引擎」和「23 个 diffReason 业务标签码」汇入收入/费用计划，再分别出财务应收单/费用应收单/费用应付单/销售收款单/银行转账单。

支付宝的"三表"不是三张毫无关系的清单，而是同一账期的三视角：

表	字段口径	颗粒度	用途
聚合结算 `aggregated_settlement`	财务 6 月手工结果表对齐的 ZC.ZFB / SR.ZFB 细颗粒度	1 行 = 1 笔交易收款/退款/扣款	主营收入（`SR.ZFB.HKSR` / `SR.ZFB.TK`）+ 部分费用
账户流水 `account_flow`	平台提供的 20+ 列原始字段	1 行 = 1 笔资金动账	退款例外档 4.1 证据、退款/扣款/转账
余利宝明细 `yulibao`	申购/赎回/收益三类	1 行 = 1 笔基金动作	`SR.ZFB.YLBSY` / `SR.ZFB.YLBSH` / `SR.ZFB.YLBSG` 三类核算

把这三表接到对账引擎的不是"按表各自写一段对账脚本"，而是平台聚合范式的两个标准方法：

// apps/api/src/biz_reconciliation/alipay/aggregation.ts
export function createAlipayAggregation(prisma: PrismaClient): PlatformAggregation {
  return {
    aggregateIncome:  (input) => aggregateIncome(prisma, input),
    aggregateExpense: (input) => aggregateExpense(prisma, input),
  };
}

关键点：getBillRowDelegatesByPlatform(prisma, ALIPAY) 返回的是支付宝平台下所有已注册账单类型的 BillRow 委托——当前三个：聚合结算、账户流水、余利宝明细。这意味着聚合代码本身只写一份，新增账单类型只需要在 parse-scripts/bill-row-router.ts 的 ROUTES 数组追加一个路由，聚合层自动纳入。新增成本 = 一次注册，不是重写一套聚合。v3.6.1 沿用此架构，三表 BillRow 的查询接口完全一致。

2.1 收入聚合：同一业务订单号下正负拆行

aggregateIncome 走的是业务订单号 + 金额符号的二维聚合键：

const key = `${businessOrderNo}:${direction}`; // POSITIVE / NEGATIVE

含义是：同一订单的卖出收入（POSITIVE）和退货退款（NEGATIVE）各自走一轮对账，分别匹配供应链的出库单/退货单。orderFeeAmount 来自 BillRow.feeAmount（订单费用侧，带符号），公摊费用由费用对账沙箱后续反写，不在此聚合。

2.2 费用聚合：核算项目 × 金额类型 × 方向五元键

aggregateExpense 用的是核算项目 + amountKind(INCOME/FEE) + direction——每行 BillRow 拆两个独立贡献：

incomeAmount ≠ 0 → INCOME 贡献（费用侧的非主营收入，如扣款退回）
feeAmount ≠ 0 → FEE 贡献（费用侧的常规费用）

两个都非零就拆两条，方向按贡献符号定（POSITIVE/NEGATIVE，分向聚合不轧差）。同号累加天然不会出现零组，无需旧版"零费用组剔除"。这套设计的妙处是：支付宝那 20 项应付项目、8 项其他费用、3 项保证金类费用，分别打各自的 ZC.ZFB. 标签，转换层按核算项目出费用应付单/费用应收单/销售收款单/银行转账单时不需要再回查 BillRow。*

这套「聚合层归一化、对账层只关心平面骨架、转换层按规则出金蝶单据」的三段式架构，正是轻易云智能对账系统处理 7 大平台多账型的同一套范式——支付宝只是这套范式在「三表账户流」上的特例化落地，其它平台按相同骨架接入即可。

[来源：apps/api/src/biz_reconciliation/alipay/aggregation.ts（62–126 行 v3 平台账单开发范式 + 2026-08-06 费用聚合 v4 现行默认）]

三、轮次链：闸门链首 + 终止 AMOUNT_DIFF 无兜底

proc-017 23 标签码判定流程图：机读 + 人读双轨

23 标签码判定流程图（proc-017）：对账体行 → 差额 ≠ 0 → 进入标签码判定 → 机读判定（auto，跑全部 23 标签码规则，命中即停）→ 输出 diffReason + diffDisposalSuggestion（机读 + 人读双轨）。

v3.6.1 的判定逻辑零变化——它从 v3.5.0 整单轧差口径继承下来的轮次链是：

防误判闸门（过滤后无供应链单）
  ① 正负抵消·净额轧差并入（NET_MERGED，v3.6.7 起打标）
  ② 合并单号部分结算（PARTIAL_SETTLEMENT，含 matchedSupplyOrderIds）
  ③ 配件链（PRICE_DIFF_ORDER，资金流水「补差价专用」档）
  ④ 退款例外（资金流水余额退款 / 售后仅退款三档 / 聚合结算交易退款，均与 |账单净额| 严格相等 → REFUND_ONLY）
  ⑤ 普通退货存在档（售后存在普通退货记录 → INSTANT_REFUND，存在即命中、不核金额）
  ⑥ 缺单 MISSING_SUPPLY

第 1 轮 R1 主匹配（净额 = 净额）
第 2 轮 R2 部分结算（单行 / R2b 多行合并）
第 4 轮 R4 退款链（资金流水余额退款 → 售后仅退款三档 → 4.4b 纯退款行 → 普通退货金额核实/存在性兜底）
第 5 轮 R5 价保扣款差异（渠道 2 合并、排除平台审核拒绝、严格相等 → PRICE_PROTECT_DIFF）

兜底有单「金额不一致」、无单「缺供应链订单」

金额判定全部严格相等、无容差——这是 v3.6.1 明确拒绝放宽容差的口径，理由是：金额判等放宽容差 0.01，会让"价保扣款差异"和"退货差价"等已知形态被吃掉，最终靠人工兜底反而更乱。

3.1 23 个 diffReason 业务标签码的支付宝适配

arch-016 23 个 diffReason 业务标签码体系图

23 个 diffReason 业务标签码体系图（arch-016）：机读 + 人读双轨，5 类分组（取消/退货类、平台差异类、供应链类、其他差异类、人工兜底类）。

v3.6.1 默认用到的标签码清单（来自支付宝数据特征）：

标签码	适用场景	出现频次
`PARTIAL_SETTLEMENT`	部分结算（单行/多行合并）	高
`REFUND_ONLY`	仅退款（资金流水余额退款 / 售后三档）	高
`INSTANT_REFUND`	极速退款（普通退货两档制）	中
`PRICE_DIFF_ORDER`	补差价/配件订单	中
`PRICE_PROTECT_DIFF`	价保扣款差异（渠道 2）	低
`MISSING_SUPPLY`	缺供应链订单	低
`AMOUNT_DIFF`	金额不一致（终止兜底）	低
`NET_MERGED`	整单轧差非承载行	高

每条标签码都对应一种"机器可识别的差异原因 + 业务可读的处理建议（diffDisposalSuggestion）"，机读 + 人读双轨——转换层按 diffReason 走不同的金蝶单据规则（规则表 transform_rules 用 entryKey + diffReason 双键匹配），人工查阅时看 diffDisposalSuggestion 直接决定要不要走费用应收单还是手工处理。

3.2 配件链的两次反转（v3.6.5 翻转）

值得记录的反转细节：v3.6.5 把配件链①（售后配件 SKU 557510197695 命中）由 SUCCESS 改成 FAILURE + PRICE_DIFF_ORDER——配件销售不进供应链应收属口径差异，但用户口径保持对账失败、仅打标。**命中即返回，不再检查退款证据。**实证 IRP-ALIPAY-20260915-0001：v3.6.5 恰 48 行判定变化（全部 SUCCESS/PRICE_DIFF_ORDER → FAILURE/PRICE_DIFF_ORDER，差异 = 账单净额）。

但 v3.6.1 写就的版本里这条仍是 SUCCESS + PRICE_DIFF_ORDER，因为反转发生在 v3.6.5（2026-09-18）。版本与基准必须同时出现，只报标签不报版本 = 误导——这是同行文章常踩的坑。

四、平台聚合范式的工程价值：23 个标签码的归一化落地

proc-003 收入对账完整流程图：创建到确认

收入对账完整流程图（proc-003）：从 3 步向导创建 IncomePlan → 7 态状态机迁移 → PENDING → READY → RECONCILING → RECONCILED → CONFIRMED / FAILED / CANCELLED → 物料明细独立表 → 桥表 plan_source_relations 反向追溯。

平台聚合范式不是"把对账脚本写在一个文件里"的便利，而是让每个平台的差异收敛在聚合层、对账层只写 23 个标签码 + 轮次链的解耦设计。具体到 v3.6.1：

聚合层：跨三表（聚合结算 + 账户流水 + 余利宝明细）按 businessOrderNo + direction 拆 IncomeAggregationRow，按 accountingItemId + amountKind + direction 拆 ExpenseAggregationRow。新增账单类型 = 一次 ROUTES 注册，聚合代码零改动。
对账层：v3.6.1 脚本体只关心"净额 vs 净额 + 退款证据链 + 配件链 + 价保链"四件事。三表的字段差异（聚合结算有"业务描述"前缀编码、账户流水有"商品名称"列、余利宝有"交易类型"列）被聚合层消化掉了，对账脚本只看到 IncomePlanItem.businessOrderNo 和净额。
转换层：消费对账成功体行（reconcileResult=SUCCESS），按 diffReason 出金蝶单据——主单合并下推 + 差额单（差额 = 账单净额 − 下推金额，带符号配平）。对账失败（FAILURE）体行不出单、不进 unmatched，"用户确认对账失败的不用管"。

这个三层分栈让 23 个标签码真正可机读——聚合层负责"哪行属于哪类收入/费用"，对账层负责"哪行匹配供应链哪类证据"，转换层负责"哪行出金蝶哪张单据"。每层只关心自己这一段的机读码，互不串台。

[来源：apps/api/src/biz_reconciliation/transform/alipay-transform-scripts.ts（v1.6.1 收入转换 + v1.7.0 费用转换配套；对账脚本 v3.6.1 落 IncomePlanItem.matched_supply_order_ids）+ docs/BUSINESS_REQUIREMENT/06-reconciliation.md（2026-09-10 合并单号部分结算全流程贯通）]

4.1 v3.6.1 修复链：matchedSupplyOrderIds 落库特性

v3.6.1 的"金额虚增修复"不是写在脚本注释里的口号，而是有完整的修复链：

对账脚本 v3.6.1（单行命中档显式返回 matchedSupplyOrderIds=[命中行 id]）
  ↓
执行层 income-reconcile（落库 IncomePlanItem.matched_supply_order_ids 字段）
  ↓
转换脚本 v1.6.0（消费 matchedSupplyOrderIds，物料 supplyOrderId 直查兜底出分录）
  ↓
推送 handler（同一暂估单命中分录属多个线上订单时，强制分录级下推，产物分录线上订单号按钩稽映射修正）

每一层都依赖上一层的"明确返回命中子集"承诺——v3.6.1 之前的脚本走 finalize 兜底时返回的是"未下推财务应收的全部行"，下游拿到全集就把整张暂估单的剩余 SKU 也聚进物料明细，下期重复出单。v3.6.1 用"显式返回 + 兜底收窄"两个最小修补，把这个层层放大的虚增堵住了。

配平不变式：实证 IRP-ALIPAY-20260910-0001，两笔合并单订单 5124733418155000237（¥44.80）/ 5124555363581228648（¥200.85，合并单 AR26071901086 行 8118696/8118695）由 unmatched 转为直推，批次总额与体行合计差额 0.00。更下游出账系统的金蝶单据按 FID 整单下推后，正负财务单同步轧平，不再残留抵消单。

工程落地层面，轻易云智能对账系统已经在生产环境跑通支付宝 v3.6.x 系列（v3.6.1 / v3.6.3 / v3.6.5 / v3.6.7 / v3.6.8 共 5 个版本共存，详见 docs/BUSINESS_REQUIREMENT/06-reconciliation.md 历史段），每条脚本变更都经过 harness 全量回放验证、合成用例 24/24 通过的交付纪律——这是把 v3.6.1 的接口契约严格化落到生产环境的工程证据。

五、写作视角与读者收益

如果你正在为多平台对账设计做技术选型，v3.6.1 的核心可借鉴点是：

聚合层归一化：把"哪行属于哪类收入/费用"在聚合层就消化掉，对账脚本只看到业务订单号 + 净额。
matchedSupplyOrderIds 显式返回：单行命中档不要走 finalize 兜底返回全集，避免物料明细把整张暂估单的全部 SKU 聚进来。
23 个 diffReason 业务标签码：机读码 + 人读 diffDisposalSuggestion 双轨，让转换层按规则出单、人工查阅时直接拿到处理建议。
金额判定严格相等、无容差：不要放宽容差 0.01，已知形态被打掉反而要靠人工兜底——这是同行文章不写的反直觉干货。

如果你用的是其它对账框架（比如开源 ETL 工具 + 内部规则引擎），把这三张表的字段映射脚本迁移到本框架时，最容易踩的坑是"按表各写一段对账脚本"而不是用平台聚合范式——后者才能让新增账单类型 = 一次注册，而不是重写一套聚合。7 大平台落地（支付宝 / 天猫 / 京东POP / 抖店 / 拼多多 / 亚马逊 / 速卖通，5 大账型、24 张独立表）已经验证了这套范式的可扩展性。

如果你是在做平台的商户接入或商户自助工具，v3.6.1 的轮次链和标签码清单是直接可复用的——把聚合结算、账户流水、余利宝明细三张表映射到 IncomePlanItem / ExpenseAggregation 这两个标准结构，剩下的交给框架处理。这是同行业 90% 的中小电商团队都在跳过的产品机会。

更深入的脚本演进链与跨平台踩坑清单可参见项目内 .opencode/skills/platform-script-onboarding/SKILL.md 与 .opencode/skills/raw-bill-development/SKILL.md。

六、给读者的 Takeaway

支付宝对账脚本 v3.6.1 是个看起来很小的版本号，但它修补的不是脚本体本身，而是三层修复链（聚合层 → 对账层 → 转换层 → 推送 handler）的接口契约。matchedSupplyOrderIds 这个字段从"兜底返回全集"变成"显式返回命中子集"，意味着执行层、转换层、推送层都不再需要猜测——每层只拿到自己该用的数据，互不串台。

把 v3.6.1 的设计哲学抽象到任何一个多平台对账场景：接口契约的严格化比脚本逻辑的复杂化更重要。当聚合层、对账层、转换层的入参/出参被显式定义后，新增平台或新形态就只是"按表填充几个字段"，而不是"重写一套对账引擎"。

最后记一个易踩的坑：版本号与基准数字必须同时出现——本文提到的"v3.6.1 物料明细收紧"、"v3.6.5 配件链反转"、"v3.6.7 NET_MERGED 打标"是三个不同版本的不同行为，把它们揉在一篇文章里而没有标注日期，会让读者误以为是同一时期的同一规范。这套业务规则以 v3 重构定稿文档为权威，脚本变更历史沉淀在每个平台的对账脚本注释里、可追溯、可回滚。

配套脚本：apps/api/src/biz_reconciliation/transform/alipay-transform-scripts.ts（INCOME v1.6.1 + EXPENSE v1.7.0，platform=ALIPAY 平台级默认）+ apps/api/src/biz_reconciliation/alipay/aggregation.ts（v3 平台账单开发范式）+ parse-scripts/bill-row-router.ts（ALIPAY 三个 ROUTES：aggregated_settlement / account_flow / yulibao）。种子脚本：docs/BUSINESS_REQUIREMENT/scripts/对账/支付宝收入对账默认脚本 v3.6.1.json（isDefault=false，降级保留历史；当前默认 v3.6.8 含 R3b 配件链零额暂估扩展）。