加盟保证金与费项结算核对（免费版）

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

本免费版只做金额逐行复算与勾稽，不做合同条款与合规性判定。

什么时候用

谁会在什么时候用：连锁加盟总部（或区域代理）的财务 / 结算岗，

在每月与加盟商对账、出结算单、或者加盟商拿着结算单来说"对不上"的时候，

必须把这张加盟商保证金与费项结算明细表核一遍才能收款 / 划款 / 退保证金。

每月都要吵的就是这几处：保证金余额与「期初 + 收取 − 退还 − 扣罚」对不上、

加盟费 / 管理费金额与「计费基数 × 费率」对不上、同一笔费项计了两遍、

扣罚扣得比可扣的保证金还多、关键格留空或写成「待填」。

这张表会逐项核对什么（每一步都能被第三方用同一份输入手算复现）：

保证金余额 = 保证金期初 + 保证金收取 − 保证金退还 − 保证金扣罚
费项金额 = 计费基数 × 费率
合计行各列 = 各明细行逐列相加（合计行没填的列不核）
同一加盟商同一结算期间同一费项、且金额相同的重复计费
扣罚超过可扣保证金（余额会变负）/ 扣罚超过「合同扣罚上限」列
关键字段缺失或为占位符、金额列为负数

每条结论都带原文行号与加盟商 / 费项，可被第三方用同一口径复算；

材料不齐时不给结论，会明确列出还缺什么。

这个免费版查什么

保证金余额复算（保证金余额 = 保证金期初 + 保证金收取 − 保证金退还 − 保证金扣罚）
费项金额复算（费项金额 = 计费基数 × 费率）
合计行与明细勾稽（逐列：合计行 = 各明细行逐列相加；合计行没填的列不核）
同一加盟商同一期间同一费项、且费项金额相同的重复计费检测
扣罚超过可扣保证金（余额为负）/ 超过合同扣罚上限检测
关键字段缺失或为占位符、金额列为负数检测

（检查项由引擎的 CHECKS_GIVEN 导出，跑 --sample 会打印实际执行了哪些；

本版本不包含的 5 项列在 CHECKS_WITHHELD 里，不做也不假装做。）

数字会做归一化：120,000.00、千分位、带货币符号的写法、(1200)（会计负数）都被认成同一个口径；

费率写 3、3% 或 0.03 都按 3% 理解（写 1 表示 100%，本工具不会替你猜你的意思）。

表头里的空格与括号会被忽略，所以「保证金余额(元)」和「保证金余额」都认。

余额口径：保证金期初 / 收取 / 退还 / 扣罚四列都按"截至本期"填写，余额应当能被这四列复算出来；

跨期的正确填法是上期期末余额 = 本期期初。

怎么用

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）的形状：

{
  "status": "success",
  "service_type": "FRANCHISE_DEPOSIT_CHECK",
  "scope": {
    "checks": [...],              // 本次实际执行的检查项（6 项）
    "checks_not_run": [...],      // 本版本未执行的检查项（= CHECKS_WITHHELD，5 项）
    "rows": 5, "franchises": 3, "periods": 2,
    "totals_row": true, "totals_rows": 1,
    "fee_base_total": 840000, "fee_amount_total": 22200,
    "deposit_open_total": 80000, "deposit_in_total": 160000,
    "deposit_refund_total": 30000, "deposit_deduct_total": 2000,
    "deposit_balance_total": 208000,
    "statement_fee_amount_total": 22200,
    "rate_convention": "费率可写 3 / 3% / 0.03，均按 3% 理解…",
    "tolerance": 0.01, "executed_locally": true, "network_used": false
  },
  "findings": [
    { "level": "P0", "category": "保证金余额复算不符", "line": 2, "amount": 1000,
      "message": "甲公司（A1 / 2026-06 / 管理费）的保证金余额写的是 9000.00，按 期初 0.00 + 收取 10000.00 − 退还 0.00 − 扣罚 0.00 应为 10000.00，相差 -1000.00。",
      "advice": "…" }
  ],
  "summary": { "rows": 5, "franchises": 3, "periods": 2, "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（口径可疑）；
amount 是这条结论涉及的金额（元），0 表示这条不是金额差；
材料不齐时返回的是 {"status": "insufficient_input", "missing": [...], "advice": "…"}，

没有 result，因此不会有任何"未发现问题"的结论。

常见错法（本产品专属）

保证金余额没把某一笔发生额算进去：最常见的是上期期末没结转成本期期初、

退还款没从余额里减、或者扣罚只在备注里写了却没落进金额列。

余额一错，后面所有"这一户该收多少 / 该退多少"的结论都跟着错，所以这一条永远排在最前面。

费率用了合同里另一档：同一加盟商同一期间同一费项，合同里可能按门店数 / 营收规模分档。

费率列写 3、3%、0.03 都按 3% 理解；写成 1 意思是 100%，费项金额当场变成"整笔基数"，

差出好几个数量级。本工具不会替你猜你的意思。

明细改对了、合计行忘了重算：合计行是对外金额（据此向加盟商收款 / 划款），

明细单改过之后合计没跟着刷新，或者明细里漏了整整一行 —— 逐单都对而合计对不上时，

差异就出在合计行自身。

同一笔费项计了两遍：重复导单 / 复制黏贴时，同一加盟商同一期间同一费项会出现两行、

连金额都一模一样。本工具只把「金额也相同」的判为重复计费，

按不同费率档位正当拆行的两行不会被误报。

扣罚扣超了：扣罚只能扣到保证金余额为 0 为止；扣超的部分要么另行追缴、要么按合同由其他款项抵。

另外「合同扣罚上限」这一列只是你自己填的上限，本工具只做算术比较，

不判断上限填得对不对、也不判断这笔扣罚是否合规。

该填 0 的格子留空：确实没有发生的收退 / 扣罚留空，会让这一行整行复算不出来。

留空就是"不知道"，本工具宁可报缺格，也不用 0 替你假设。

不包含什么

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

跨加盟商 × 跨期间汇总台账（按加盟商与按结算期间归集费项金额、保证金收发扣与争议金额，

并逐户做「期初 + 收取 − 退还 − 扣罚 = 期末」的余额勾稽）

按差异金额排序的处理清单（带原文行号、加盟商、结算期间、费项与建议动作）
差异归因：费率档位不一致（同一加盟商同一期间同一费项出现多个费率 ⇒ 按其中最低费率折算多计金额）
差异归因：基数口径不一致（同一加盟商同一期间同一费项出现多个计费基数 ⇒ 按其中最低基数折算多计金额）
差异归因：扣罚缺少依据说明，以及跨期归属错位（保证金期初 ≠ 上期期末余额 / 一次性费项出现在多个结算期间）

本免费版只做金额逐行复算与勾稽，不做合同条款与合规性判定：

费率该用哪一档、基数该取什么口径、扣罚是否合规、合同条款是否合法有效，都不在本版本的判断范围内。

同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）；

两档的差别就是上面这些，没有别的。

使用次数与完整档

本免费版每次运行结束后会向服务端做一次匿名次数统计：只发送本包标识和一个不含任何材料的匿名安装标识，

不发送你的材料、不发送你的身份、不写你的表。

前 3 次：服务端不返回任何内容，输出与现在完全一样；
第 4 次起：服务端会返回一段完整档说明（完整档是另一个独立商品，条款与条件以它自己的商品页为准），届时才会打印这一行；
统计不可用（离线 / 超时 / 被拦截）时什么都不做，核对结果与退出码不受任何影响；
不想要这次统计可以加 --no-stats（核对功能完全不受影响，只是拿不到完整档说明）。

核对本身全部在本机用 Node 标准库完成，不调用任何模型、不连接加盟商结算系统或银行。

需要完整档时（可选）

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

跨加盟商 × 跨期间汇总台账（按加盟商与按结算期间归集费项金额、保证金收发扣与争议金额，并逐户做「期初 + 收取 − 退还 − 扣罚 = 期末」的余额勾稽）
按差异金额排序的处理清单（带原文行号、加盟商、结算期间、费项与建议动作）
差异归因：费率档位不一致（同一加盟商同一期间同一费项出现多个费率 ⇒ 按其中最低费率折算多计金额）
差异归因：基数口径不一致（同一加盟商同一期间同一费项出现多个计费基数 ⇒ 按其中最低基数折算多计金额）
差异归因：扣罚缺少依据说明，以及跨期归属错位（保证金期初 ≠ 上期期末余额 / 一次性费项出现在多个结算期间）

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

边界（请务必知道）

本工具不做引擎 CHECKS_OUT_OF_SCOPE 里列的那些判断：加盟合同条款是否合法有效、扣罚到底该不该罚、

扣罚比例是否合规、费率档位是否与合同一致、加盟费 / 管理费该收多少、保证金是否真的收到与退还到账、

保证金的利息与税费怎么处理（那些以加盟合同、内部制度与银行流水为准）。

只核表内勾稽：表里的计费基数、费率、金额、期初 / 收取 / 退还 / 扣罚、扣罚上限一律以你填的为准；
「没报问题」不等于「没有问题」：超出上述 6 项的检查，本版本不执行；
材料不齐时不给结论，也不会用默认值编一个「本期没问题」出来；
每条结论都带原文行号与加盟商 / 费项，可由第三方用同一份输入复算。

装到本地或在线用

· SkillHub（免费版）：https://www.skillhub.cn/skills/user_ef162806/franchise-deposit-check-free

· 全部免费工具：https://chenqg618.github.io/compliance-skills/

完整档（离线、无次数上限）：SkillPay 买断 ¥9.9，跑多少次都不再收费；免费档与完整档的检查项差别见上面的说明。

怎么装：
https://chenqg618.github.io/compliance-skills/

免费版会明确列出哪些检查没有执行，不会让你以为已经全查过。