公摊费用反写 实时 覆盖式 双模式

摘要：业务人员反复在同一个地方犯嘀咕——"我只改了分摊脚本，run-allocate 一下怎么就把订单明细清掉一列又重写？"这不是 bug，是双模式的代价。「公摊」用 实时（E1：先撤旧再累写），「订单费用下沉」用 覆盖式（E11：先清零再 set 写）。本文不抽象，给业务人员和财务经理一份 4 维度对比 + 3 步选择法，把"我什么时候该期望哪种行为"讲明白。

关键词：公摊费用反写、实时、覆盖式、双模式、撤旧、orderFee

数字先出来，3 张单子的傍晚

10 月 30 日傍晚 17:50，财务经理李颖的飞书弹出两条告警。

第一条：「费用计划 EP-AMAZON-EU-20261025-0003 已进入 READY 状态，公摊总额 = 92,408.16 元。」这是欧洲站 10 月的直通车、仓储费、FBA 物流三个核算项目的合并，事件已经进入 run-allocate 队列。

第二条更像 bug 反馈：「抖店侧业务同事问，为什么我改了分摊脚本，物料明细那列从 0 重新累起来，而不是把上一轮的数清掉？另外最右边那列『订单费用』是直接变了——这又是为什么？」

李颖当天就要回答两件事：（1）哪种反写模式写在哪个字段？（2）业务人员重跑脚本时，到底是被加了一次还是被覆盖了一次？

这两个问题指向 v3 重构后最容易被忽视、却最有展示业务深度的一对决策 —— 实时（E1）与 覆盖式（E11）。它不是产品功能，是设计结果。明白这层，run-allocate 按钮按下的瞬间你能预演一切。

**双模式登场不是为「秀技术」，而是因为业务上两类数字本来就不该用同一种写入方式。**一个要的是「能撤回」——9 万元的推广费摊给 800 个订单后，老板改主意要按订单成本而不是收入分摊；另一个要的是「要幂等」——一行平台挂账的订单费用，跑了 5 次脚本都得是同一个数[来源：2026-08-05 费用对账深化方案 § E1/E11]。

---

一、为什么有两种模式：业务里本就有两类反写

把「公摊费用反写」拆开看，其实是两条不同的写链：

第一类数字的本质是「累加」——同笔公摊分给同一订单的多个来源（直通车、站外引流、店铺红包）都要加上。第二类的本质是「归属」——这笔订单的平台扣点有一个权威值，脚本只负责按口径拆到 SKU，多跑一次脚本结果不变。

「累加」的写就不能直接覆盖，否则会把上一次的成果擦掉；「归属」的写就不能只做累加，否则多跑一次脚本数字就大了一倍。两种模式因此分化成「实时」与「覆盖式」。

上图是费用对账深化文档里最关键的一张图。它把双模式画在一张流程图上：左边「订单级 / SKU 级」走实时——先撤旧再累写；右边「orderFee」走覆盖——先清零再 set 写。两者在同一次 run-allocate 触发、同一个事务里完成。

---

二、实时模式（E1）：撤旧 + 累写，「可重跑」靠逐行回退

「实时」= 「撤旧 + 累写」的 4 步骤循环。每一次 run-allocate 触发时，service 层都按以下顺序执行：

1. 撤旧：把本聚合上一次反写过的那批字表按订单 id / SKU id 逐行 decrement 把对应字段拉回原值。不做 blanket 清零——多个聚合可能写过同一个 SKU 明细，撤旧只回退自己这一聚合的贡献。
2. 删除旧字表：把上一轮的 ExpenseAllocationItem 物理删除。
3. 写新值：脚本返回的新分配结果按行 += 到 IncomePlanItem.allocatedFeeAmount（订单级）或 IncomePlanMaterialItem.allocatedFeeAmount（SKU 级）。
4. 记字表：写新分配的明细用作下次撤旧的依据。

四个动作在同一个 Postgres 事务里、串行执行。事务的边界就是「聚合」——一个聚合成功才推进到下一个聚合；任一聚合失败就回滚整聚合已做的改动，账单行停留在「待对账」、聚合 isAllocated=false 可重跑。

2.1 三个被业务人员反复问的细节

• 为什么 confirm 之前就能看到数字？ 这是 E1 的关键决策——反写时机定在「run-allocate」而非「confirm 时机」。业务人员按下分摊按钮的瞬间，9 万元就拆给 800 个订单了，但订单级那张表只是「分摊就绪」，收入计划并没有被锁定。这是 v3 之前（旧项目 v4.0）反写要在 confirm 才发生的反直觉改动——为了让用户"run 完就能看见"，业务确认节奏提前到了 run-allocate 时机。这一改动也是轻易云对账系统 v3 重构里把"脚本结果可见性"列为第一原则的具体落点。
• 为什么重跑不会越摊越多？ 因为撤旧按「字表里上次本聚合的写值」逐行 decrement。同样的脚本跑两遍，最终结果是同一个数字——这叫可重入，不是幂等的另一种说法。撤旧按「行级 decrement」而不是「清零」，换来的代价是任何一笔写都需要先读字表、按行计算回退值。
• 为什么 SKU 行和订单级行不能混？ E8 防双计：同一订单不能既出现订单级行又出现 SKU 级行。混了直接判该聚合 FAILED。这个判断在沙箱出口 + 后端校验两道关口都会做，防其中一道因脚本版本漂移而漏掉。

2.2 实时模式的代价：行级 decrement 的强度上限

对一个 10,000 条聚合、每条 100 个订单的店铺，撤旧最坏情况要做 100 万次更新。这是 v3 文档里特意标的 allocations ≤ 10000 条/聚合 上限的由来（2026-07-28 由 2000 上调，覆盖大店账期）。同时也有上限 orderFeeAllocations ≤ 25000 条/聚合，这两个上限是「实时模式的性能边界」，跑批前要心里有数。

---

三、覆盖式模式（E11）：清零 + set 写，「天然幂等」由写入语义保证

「覆盖式」= 「清零 + set 写」。orderFeeAllocations 这段专属字段走的就是这条路：

1. 不撤旧——覆盖式写入天然幂等，不需要单独撤旧逻辑。
2. 清零：把本聚合涉及到的每个订单在 IncomePlanMaterialItem.orderFeeAmount 字段清 0。
3. set 写：按脚本返回的 (businessOrderNo, skuCode, feeAmount) 三元组 set 写入。

业务人员每天面对的反直觉场景就是它：平台佣金从聚合拆到 SKU 是「归属」——一笔订单的平台佣金只有一个权威值，脚本只决定如何拆到 SKU。即使重跑 5 次脚本，结果都是同一个三元组。同比「公摊」就不一样了，9 万元的推广费可能因为分摊基数变化（成本 vs 收入）或脚本算法调整，每次都不一样。

写链因此分化：归属用 set、写覆盖；累加用 +=、必须撤旧[来源：2026-08-23 四平台验证复盘]。

3.1 覆盖式为什么不需要撤旧？

幂等的两个条件：顺序无关（执行两次都得到同一个值）、重复无关（同上）。set 写天然满足这两个条件。但 += 不满足——重跑两遍同样的脚本，每行就累了两遍同等的金额。所以才需要「先撤旧」这一步撤销上一轮的写。

3.2 orderFee 字段为什么不受撤旧重跑影响

跑老脚本（v1，未返回 orderFeeAllocations）—— orderFeeAmount 字段保持旧值不动（覆盖式写入天然幂等）。 跑新脚本（v2，返回 orderFeeAllocations）—— orderFeeAmount 字段被新算法的输出 set 写。 再跑一次新脚本——字段值依然是这次 set 写之后的结果，不会多次累加。

但反过来，如果脚本本轮不返回 orderFeeAllocations、上一轮又返回过——上一轮的值不会被自动清零，因为 v1 → v2 跨越时不能假设上轮的输出就是本轮想要的。所以 v2 起的逻辑始终把 orderFeeAmount 视作「脚本上次明确写过的值」，跑新脚本立刻覆盖，跑老脚本保留。

对于业务人员这意味着：升级脚本版本时，特别是从 v1 到 v2 的升级，第一件事是验证清楚当前字段值是不是脚本预期的输出；如果不是，先手动同步。

---

四、4 维对比：实时 vs 覆盖式，一眼记住

---

五、案例：亚马逊欧洲站，6 个核算项目如何选择

亚马逊欧洲站 10 月的费用计划 EP-AMAZON-EU-20261025-0003 包含 6 个核算项目，金额分布是这样的（实际跑批 TFB-20261030-0003）：

费用汇总那一栏，6 个核算项目全部显示为「待分摊」。点击进入计划详情、绑定的收入计划 IRP-AMAZON-EU-20260929-0001 是 9 月底已 CONFIRMED 状态——这是 E4 闸（绑定收入计划必须 CONFIRMED 才能跑分摊；不然 400）。

按下分摊按钮后，沙箱一次跑出两类结果：

• 4 个累加型项目都给 allocations[] 数组，每行触发 实时反写：IncomePlanItem.allocatedFeeAmount +=
• 2 个归属型项目（平台佣金 / 推荐服务费）还顺带返回 orderFeeAllocations[]（可选段，v2 起），IncomePlanMaterialItem.orderFeeAmount 字段被 覆盖式写入

「顺带返回」四个字是最容易被误解的设计选择——同一个脚本一次跑批，业务只调一次，跑完两个字段都到位。如果业务想偷懒只返回 orderFee 不返回公摊、或反过来，则只能跑半套——预期就要调整[来源：2026-09-21 五平台脚本工程师对齐会议纪要]。

5.1 反写后视图：物料明细三列

跑完以后打开收入计划 IRP-AMAZON-EU-20260929-0001 的详情，看物料明细。原先只有收入 + 成本两列，现在并排多出三列：

「费用合计」是前端虚拟列，不进数据库。这样设计的目的是避免「费用合计」与「订单费用 + 公摊费用」哪天对不上时出现数据一致性争议。一切差额都以原字段之和为准，可视化只服务人眼。

5.2 案例中的反直觉点

• 4 个累加型项目里有 1 个（FBA 物流）金额小但订单数多——分摊脚本返回了 SKU 级行（v2 契约下可填 skuCode），按 allocatedFeeAmount SKU 行重写，行级 decrement 比 blanket 更省心。
• 2 个覆盖式项目（佣金 / 推荐服务费）的 orderFeeAmount 字段默认都是 0，跑过一次脚本之后才被 set 写。这对应了「脚本首次上线的迁移场景」——业务人员心里要有这个预期：升级脚本后第一次跑批，orderFee 字段呈现的不再是 0，也不是「上轮 ×N」，而是「本轮完整 set 写之后的值」。

在意某跨境电商集团的同款 6 项核算场景里，这套双模式上线首月就把"运营 / 财务两边数不一致"的对账工单压到了每月 5 件以内（其中 4 件是脚本本身 bug，1 件是供应链侧数据延迟）[来源：2026-09-30 跨境电商 S&P 集团 9 月复盘]。

---

六、3 步选择法：业务场景如何决定反写模式

很多团队在第一次跑公摊脚本时被这种问题困住——"我看到订单级数字已经分了，还要不要动 SKU 级数字？orderFee 那一栏能不动？" 这一节给业务人员和财务经理一份 3 步检查表。

第 1 步 · 是"累加"还是"归属"

业务里这笔费用是「累加」还是「归属」：

• 累加（多笔同源费用落到同一订单）→ 走实时（E1）
• 归属（一笔权威值，拆 SKU）→ 走覆盖（E11）

不靠感觉判断，靠业务场景。同行佣金、平台扣点都是「归属」——因为订单只会有一个权威交易流水对账结果。

第 2 步 · 同订单是否出现多条同源

如果同一订单的同一核算项目按月有多条流水（比如直通车费按日累计、月度汇总），那是「累加」无疑——跑多次脚本都要往同一数字上加，跑前必须撤旧。

第 3 步 · 字段语义

看字段名：

• allocatedFeeAmount（不管是订单级还是 SKU 级）→ 实时（E1）
• orderFeeAmount → 覆盖（E11）

判断不出来的时候，回到业务里看「这一笔到底是不是账单的归属值」。

6.1 选错模式的两类典型代价

实际跑批中第二类比第一类更容易踩，因为归属性数字（佣金 / 推荐服务费）业务上更常被误以为"也是分摊来的"。一上来不要被字段名带跑，先看业务场景。

6.2 双模式同事务：边界在哪里

两个模式在同一个 run-allocate、同一事务里跑完，但写入路径独立。整套撤旧 + 分摊 + 反写处理被框定在一个 Postgres 事务里、单聚合串行。某个聚合失败 = 整聚合回滚，账单行不前进——状态保留 PENDING，可重跑[来源：2026-09-12 抖店分摊脚本 v1.1.0 验证]。

E9 尾差容差（≤ 0.01 元）也在同事务中校验——Σallocations 与 totalAmount 不匹配时该聚合 FAILED、isAllocated 保持 false。订单级 / SKU 级行走的累加校验、orderFee 走的归属校验、合计校验三件事在一次事务里跑完。

把这两条写链放在一个事务里跑，是轻易云对账系统对"双模式可在不破坏原子性的前提下各自走不同反写路径"的工程实现。一个聚合失败整组回滚，业务侧不需要补擦任何已分摊过的数字——这是选 v3 双模式设计优于"分两次事务/两次提交"的根本原因。

---

七、重跑幂等与脚本版本迁移

业务人员升级脚本版本时，两个最常被踩的坑：

7.1 同版本重跑：完全幂等

设计层面：撤旧的「逐行 decrement」保证同脚本重跑不会越摊越多；覆盖式天然幂等。两者在同一事务内串行执行、不受其他聚合影响。

业务层面：可放心在试跑端点看到效果后再 run-allocate 落库（试跑端点 POST /expense-allocate-scripts/test 同步只读、不落库、含 balanced 合计校验容差）。

7.2 跨版本重跑：脚本算法变化时

撤回机制只能撤销「本聚合上一次的写值」，不能撤销「旧版本脚本历史上的所有写值」。脚本算法变了，撤回逻辑的不变量仍然在，但要意识到：

• 数值会变（口径变了，必然新口径生效）
• 撤销的事务追溯只追溯本聚合上一轮

升级脚本时，业务上要做三件事：

1. 在沙箱端点试跑（同步 / 只读 / 不落库），返回 balanced 校验容差
2. 比对试跑结果与上次字段值的差异（差异大就先把字段清掉再跑）
3. 真正 run-allocate 落库

7.3 orderFee 字段迁移注意

v1（未返回 orderFeeAllocations）→ v2（返回）跨越：

• 上一轮的 orderFeeAmount 不动（覆盖式写入天然幂等）。
• 本轮 v2 第一次跑——本轮脚本逻辑决定的全量 set 写覆盖到目标字段上。
• 业务应该预期：第一次跑新脚本，orderFeeAmount 字段值不是「上轮的 1/2」或「上轮的 1.3 倍」，而是按新算法完整覆盖后的值。

---

八、收尾：双模式不是产品特性，是业务数字本来的样子

公摊费用反写的高级使用不复杂——理解两类数字的不同语义，按对应模式调用即可。

双模式设计不是为了让技术看起来「高级」，也不是为了让产品宣传「双引擎」。它对应的是两条业务规律：

• 公摊是「累加」→ 实时
• 订单费用是「归属」→ 覆盖

业务人员面对脚本版本升级、月度关账、批量重跑时的正确动作不是「记住哪条 SQL 改哪个字段」，而是从业务问题出发，问清楚「这一笔到底是累加还是归属」。

明白这层，run-allocate 按钮按下的瞬间你能预演一切：公摊那一列数字会是什么样、orderFee 那一列数字会是什么样、为什么一个是先撤旧再累写、另一个是先清零再 set 写——背后只有一个判断基准：这是不是订单的唯一权威值。

答案决定模式。