加盟保证金与费项结算核对（免费版）
完全本地运行：引擎已经打包在本技能里（
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 里）：
- 跨加盟商 × 跨期间汇总台账（按加盟商与按结算期间归集费项金额、保证金收发扣与争议金额， 并逐户做「期初 + 收取 − 退还 − 扣罚 = 期末」的余额勾稽）
- 按差异金额排序的处理清单（带原文行号、加盟商、结算期间、费项与建议动作）
- 差异归因：费率档位不一致（同一加盟商同一期间同一费项出现多个费率 ⇒ 按其中最低费率折算多计金额）
- 差异归因：基数口径不一致（同一加盟商同一期间同一费项出现多个计费基数 ⇒ 按其中最低基数折算多计金额）
- 差异归因：扣罚缺少依据说明，以及跨期归属错位（保证金期初 ≠ 上期期末余额 / 一次性费项出现在多个结算期间）
本免费版只做金额逐行复算与勾稽，不做合同条款与合规性判定： 费率该用哪一档、基数该取什么口径、扣罚是否合规、合同条款是否合法有效，都不在本版本的判断范围内。 同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）； 两档的差别就是上面这些，没有别的。
需要完整档时（可选）
本免费版是完整可用的核心产出，本版本不包含下面这些项：
- 跨加盟商 × 跨期间汇总台账（按加盟商与按结算期间归集费项金额、保证金收发扣与争议金额，并逐户做「期初 + 收取 − 退还 − 扣罚 = 期末」的余额勾稽）
- 按差异金额排序的处理清单（带原文行号、加盟商、结算期间、费项与建议动作）
- 差异归因：费率档位不一致（同一加盟商同一期间同一费项出现多个费率 ⇒ 按其中最低费率折算多计金额）
- 差异归因：基数口径不一致（同一加盟商同一期间同一费项出现多个计费基数 ⇒ 按其中最低基数折算多计金额）
- 差异归因：扣罚缺少依据说明，以及跨期归属错位（保证金期初 ≠ 上期期末余额 / 一次性费项出现在多个结算期间）
同名工具的完整档是另一个独立商品（条款与条件以它自己的商品页为准）；两档的差别就是上面这些，没有别的。
边界（请务必知道）
本工具不做引擎 CHECKS_OUT_OF_SCOPE 里列的那些判断：加盟合同条款是否合法有效、扣罚到底该不该罚、
扣罚比例是否合规、费率档位是否与合同一致、加盟费 / 管理费该收多少、保证金是否真的收到与退还到账、
保证金的利息与税费怎么处理（那些以加盟合同、内部制度与银行流水为准）。
- 只核表内勾稽：表里的计费基数、费率、金额、期初 / 收取 / 退还 / 扣罚、扣罚上限一律以你填的为准；
- 「没报问题」不等于「没有问题」：超出上述 6 项的检查，本版本不执行；
- 材料不齐时不给结论，也不会用默认值编一个「本期没问题」出来；
- 每条结论都带原文行号与加盟商 / 费项，可由第三方用同一份输入复算。