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

加盟商保证金与费项结算明细表逐行复算与勾稽（保证金余额=期初+收取-退还-扣罚、费项金额=计费基数×费率、合计行逐列勾稽、重复计费、扣罚超可扣余额或超合同上限、关键格缺失与负数），每条结论引用原文行号与加盟商。本免费版只做金额逐行复算与勾稽，不做合同条款与合规性判定。触发词包括 加盟保证金核对、加盟商保证金对账、保证金余额对不上、费项结算核对、加盟费管理费复算。

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

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

什么时候用

谁会在什么时候用：连锁加盟总部（或区域代理）的财务 / 结算岗， 在每月与加盟商对账、出结算单、或者加盟商拿着结算单来说"对不上"的时候， 必须把这张加盟商保证金与费项结算明细表核一遍才能收款 / 划款 / 退保证金。

每月都要吵的就是这几处：保证金余额与「期初 + 收取 − 退还 − 扣罚」对不上、 加盟费 / 管理费金额与「计费基数 × 费率」对不上、同一笔费项计了两遍、 扣罚扣得比可扣的保证金还多、关键格留空或写成「待填」。

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

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

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

这个免费版查什么

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

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

数字会做归一化：120,000.00、千分位、带货币符号的写法、(1200)（会计负数）都被认成同一个口径； 费率写 3、3% 或 0.03 都按 3% 理解（写 1 表示 100%，本工具不会替你猜你的意思）。 表头里的空格与括号会被忽略，所以「保证金余额(元)」和「保证金余额」都认。

余额口径：保证金期初 / 收取 / 退还 / 扣罚四列都按"截至本期"填写，余额应当能被这四列复算出来； 跨期的正确填法是上期期末余额 = 本期期初。

怎么用

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": "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，因此不会有任何"未发现问题"的结论。

常见错法（本产品专属）

1. 保证金余额没把某一笔发生额算进去：最常见的是上期期末没结转成本期期初、 退还款没从余额里减、或者扣罚只在备注里写了却没落进金额列。 余额一错，后面所有"这一户该收多少 / 该退多少"的结论都跟着错，所以这一条永远排在最前面。
2. 费率用了合同里另一档：同一加盟商同一期间同一费项，合同里可能按门店数 / 营收规模分档。 费率列写 3、3%、0.03 都按 3% 理解；写成 1 意思是 100%，费项金额当场变成"整笔基数"， 差出好几个数量级。本工具不会替你猜你的意思。
3. 明细改对了、合计行忘了重算：合计行是对外金额（据此向加盟商收款 / 划款）， 明细单改过之后合计没跟着刷新，或者明细里漏了整整一行 —— 逐单都对而合计对不上时， 差异就出在合计行自身。
4. 同一笔费项计了两遍：重复导单 / 复制黏贴时，同一加盟商同一期间同一费项会出现两行、 连金额都一模一样。本工具只把「金额也相同」的判为重复计费， 按不同费率档位正当拆行的两行不会被误报。
5. 扣罚扣超了：扣罚只能扣到保证金余额为 0 为止；扣超的部分要么另行追缴、要么按合同由其他款项抵。 另外「合同扣罚上限」这一列只是你自己填的上限，本工具只做算术比较， 不判断上限填得对不对、也不判断这笔扣罚是否合规。
6. 该填 0 的格子留空：确实没有发生的收退 / 扣罚留空，会让这一行整行复算不出来。 留空就是"不知道"，本工具宁可报缺格，也不用 0 替你假设。

不包含什么

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

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

本免费版只做金额逐行复算与勾稽，不做合同条款与合规性判定： 费率该用哪一档、基数该取什么口径、扣罚是否合规、合同条款是否合法有效，都不在本版本的判断范围内。 同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）； 两档的差别就是上面这些，没有别的。

需要完整档时（可选）

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

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

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

边界（请务必知道）

本工具不做引擎 CHECKS_OUT_OF_SCOPE 里列的那些判断：加盟合同条款是否合法有效、扣罚到底该不该罚、 扣罚比例是否合规、费率档位是否与合同一致、加盟费 / 管理费该收多少、保证金是否真的收到与退还到账、 保证金的利息与税费怎么处理（那些以加盟合同、内部制度与银行流水为准）。

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