SaaS订阅用量与超额计费核对（免费版）

订阅用量与超额计费明细表逐项核对（超额用量复算、超额费用复算、账单金额勾稽、套餐额度适配、同一账期同一订阅号重复行、关键字段空缺），每条结论引用原文行号与订阅号。本免费版执行引擎声明的 6 项免费检查。触发词包括 SaaS订阅用量与超额计费核对、订阅用量与超额计费明细表对不上、超额费用算错、账单金额对不上、套餐额度与实际用量。

完全本地运行：引擎已经打包在本技能里（engine/ 目录）。 核对过程不需要联网、不需要 API Key、没有调用次数上限。

什么时候用

谁会在什么时候用：SaaS 公司的出账岗 / 商务 / 财务，以及企业客户（甲方）的财务， 在每月出账、客户对账、续费谈判这几个固定节点上，都得把这张订阅用量与超额计费明细表核一遍才能往下走。 超额费多算、账单对不上、重复开通，正是双方每月都要吵的几件事。

这张表会逐项核对什么：

• 超额用量 = max(0, 实际用量 − 套餐额度)
• 超额费用 = 超额用量 × 超额单价
• 账单金额 = 套餐费 + 超额费 + 坐席费 − 折扣
• 套餐额度是否远高于实际用量（套餐买大了、白付套餐费）
• 同一账期不得出现同一订阅号两行；关键格不得留空或写占位符

每条结论都带原文行号与订阅号，可被第三方用同一口径复算； 材料不齐时不给结论，会明确列出还缺什么。

这个免费版查什么

1. 超额用量复算（超额用量 = max(0, 实际用量 − 套餐额度)）
2. 超额费用复算（超额费用 = 超额用量 × 超额单价，逐行复算）
3. 账单金额勾稽（账单金额 = 套餐费 + 超额费 + 坐席费 − 折扣）
4. 用量与套餐额度适配检测（实际用量远低于额度 ⇒ 套餐买大了、白付套餐费）
5. 同一账期同一订阅号重复行检测
6. 关键字段缺失或为占位符检测

（检查项由引擎的 CHECKS_GIVEN 导出，跑 --sample 会打印实际执行了哪些； 本版本不包含的 5 项列在 CHECKS_WITHHELD 里，不做也不假装做。）

数字会做归一化：12,000（千分位）、1240元、(120)（会计负数）、0.5%（折成 0.005） 都会被认成同一个口径；超额单价列写 0.5 表示每个用量 0.5 元，本工具不会替你猜你的意思。 表头里的空格、全角括号与单位后缀会被忽略，所以「实际用量(次)」和「实际用量」都认； 表头是完全相等匹配的，所以「套餐额度」不会把「套餐费」抢走、「超额用量」不会把「超额单价」抢走。

怎么用

bash

node scripts/run.mjs --sample                 # 先看样例
node scripts/run.mjs --input 你的材料.json     # 跑自己的材料
node scripts/run.mjs --input 你的材料.json --json

入参就是含表头的一张表（{"text": "账期\t客户编码\t订阅号\t…"}）： 从 Excel 或计费系统导出里直接复制成文本（Tab 分隔最稳）贴进去即可。 表头缺列会明确告诉你缺了哪一列；缺一列就不给结论，不会拿 0 替你假设"这个月没超额"。

没有超额请把「超额用量 / 超额单价 / 超额费用」都填 0： 填 0 表示"确实没有"，留空表示"不知道"，这两者不能混。

退出码

码	含义
0	已执行检查
1	没给入参
3	材料不齐 —— 此时不给结论（既不说"对"，也不说"错"）
4	入参文件读不到或无法解析
9	未预期错误

出参

run.mjs --json（以及引擎 run() 返回值里的 result）的形状：

text

{
  "status": "success",
  "service_type": "SAAS_USAGE_BILLING_CHECK",
  "scope": {
    "checks": [...],              // 本次实际执行的检查项
    "checks_not_run": [...],      // 本版本未执行的检查项（= CHECKS_WITHHELD）
    "rows": 7, "periods": 2, "customers": 3,
    "totals_row": true, "totals_rows": 1,
    "plan_quota_total": 135000, "actual_usage_total": 140000,
    "overage_usage_total": 15200, "overage_fee_total": 8500,
    "plan_fee_total": 8900, "seat_fee_total": 700, "discount_total": 150,
    "bill_total": 17950, "tolerance": 0.01,
    "executed_locally": true, "network_used": false
  },
  "findings": [
    { "level": "P0", "category": "超额费用复算不符", "line": 2, "amount": 120,
      "message": "客户「C001 杭州甲贸易有限公司」订阅 SUB-0001 的超额费用是 600.00，按 超额用量 1200 × 超额单价 0.6 = 720.00，相差 -120.00。",
      "advice": "…" }
  ],
  "summary": { "rows": 7, "periods": 2, "customers": 3, "total": 0, "p0": 0, "p1": 0, "p2": 0,
               "verdict": "NO_ISSUE_FOUND", "omitted": 0 },
  "checks_executed": [...], "checks_withheld": [...],
  "checks_given": [...], "checks_out_of_scope": [...],
  "note": "…", "disclaimer": "…"
}

• findings[].line 是原文行号（含表头，从 1 起），level 是 P0（金额算错 / 缺关键格）、 P1（口径可疑）、P2（不是错，但值得谈）；
• amount 是这条结论涉及的金额（元），0 表示这条不是金额差；
• 材料不齐时返回的是 {"status": "insufficient_input", "missing": [...], "advice": "…"}， 没有 result，因此不会有任何"未发现问题"的结论。

常见错法（本产品专属）

1. 把年付套餐的整年额度砸在一个月里：套餐额度要按账期摊（年付 ÷ 12）。 额度填成整年的数，超额用量会被算成 0（漏收）；一行填年度额度、另一行填月度额度， 同一客户同一账期的超额就直接矛盾。本工具只核 max(0, 实际用量 − 套餐额度) 这个算术， 额度怎么摊是你的合同口径，所以它把不符的行连同行号列出来让你核口径，而不是替你改。
2. 超额单价取错档 / 调价前后混用：调价生效日前后混在一张表里，同一客户相邻两行出现两个单价。 超额费用 = 超额用量 × 超额单价，单价错一档，金额直接差一个比例。 按「千次」计价却按实际用量乘，也会差出数量级 —— 请按合同的计价条款逐行复算。
3. 折扣减了两次、或者账单金额没跟着明细刷新：账单金额 = 套餐费 + 超额费 + 坐席费 − 折扣， 这一格是要付出去的钱（公司据此确认收入）。明细改过之后账单没重算，是出账期最常见的错。
4. 实际用量没超额度，超额用量却填了数：多半是把上月的超额量带过来了， 或者把两个订阅的用量加总后拿去比一个订阅的额度。本工具会把这一行单独点出来并说明"本应是 0"。
5. 该填 0 的格子留空：没有超额的订阅，超额用量 / 超额单价 / 超额费用留空， 会让这一行整行复算不出来。留空就是"不知道"，本工具宁可报缺格，也不用 0 替你假设。 待确认、待核 这类占位符和留空一样对待。

这个免费版不包含

以下检查项不在本版本范围内，调用时也不会执行（列在引擎的 CHECKS_WITHHELD 里）：

• 合计行勾稽（合计行各列 = 各明细行逐列相加，不符时报出差异金额并定位差异订阅号）
• 折扣列异常检测（折扣超过套餐费 + 坐席费 ⇒ 把超额费也一起打折了；折扣为负 ⇒ 实收大于应收）
• 同一客户同一账期出现多个订阅号（同一主体被重复开通套餐 ⇒ 套餐费可能被收了两遍）
• 用量口径核对（同一客户同一账期出现多个套餐额度 ⇒ 额度口径不一致，超额用量被算高或算低）
• 跨客户 / 跨账期汇总台账与按多收金额排序的处理清单（按客户 × 账期汇总用量 / 超额用量 / 超额费 / 账单与多收金额，按金额排序，逐条带原文行号）

同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）； 两档的差别就是上面这些，没有别的。

需要完整档时（可选）

本免费版是完整可用的核心产出，本版本不包含下面这些项：

• 合计行勾稽（合计行各列 = 各明细行逐列相加，不符时报出差异金额并定位差异订阅号）
• 折扣列异常检测（折扣超过套餐费 + 坐席费 ⇒ 把超额费也一起打折了；折扣为负 ⇒ 实收大于应收）
• 同一客户同一账期出现多个订阅号（同一主体被重复开通套餐 ⇒ 套餐费可能被收了两遍）
• 用量口径核对（同一客户同一账期出现多个套餐额度 ⇒ 额度口径不一致，超额用量被算高或算低）
• 跨客户 / 跨账期汇总台账与按多收金额排序的处理清单（按客户 × 账期汇总用量 / 超额用量 / 超额费 / 账单与多收金额，按金额排序，逐条带原文行号）

同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）；两档的差别就是上面这些，没有别的。

边界（请务必知道）

本工具不做引擎 CHECKS_OUT_OF_SCOPE 里列的那些判断：额度该按哪一档报价、超额单价是否符合合同、 用量统计口径（去重规则 / 失败请求算不算 / 测试 Key 算不算 / 跨月切分点）对不对、折扣是否已审批、 账单是否已开票或已回款（那些以销售合同、计费系统、用量报表与银行流水为准）。

• 只核表内勾稽：表里的套餐额度、实际用量、超额单价、套餐费、坐席费、折扣一律以你填的为准；
• 「没报问题」不等于「没有问题」：超出上述 6 项的检查，本版本不执行；
• 材料不齐时不给结论，也不会用默认值编一个「本期没问题」出来；
• 每条结论都带原文行号与订阅号，可由第三方用同一份输入复算。