三包台账核对 PerryLink/dsh-warranty-calc

dsh-warranty-calc — 保修期与索赔金额一致性检查

dsh-warranty-calc 读取一份保修索赔登记表——经销商表头，加上每行一条索赔记录——检查这份登记表自身的算术和期间是否自洽：每条索赔是否记录了索赔编号或零件名称，索赔日期是否落在登记表写明的保修结束日期之内，索赔时的里程能否解析为数字、是否超过登记表写明的里程上限，索赔金额是否等于数量 × 单价，销售日期是否不晚于索赔日期，以及索赔编号是否重复。

它能回答什么

| 你的疑问 | 它给出的答案 |
| 登记表没记录保修结束日期。索赔日期检查是不是就直接通过了？ | 不是。保修结束列留空时，WC-002 会把自己记进 skipped：它假定没有保修期，绝不从销售日期推算出一个。列填了值，它只检查索赔日期是否落在销售日期和你写的结束日期之间；报出问题意味着日期与你登记表里的期间对不上，而不是这条索赔已超出保修期。 |
| 索赔金额不等于数量 × 单价。这能查出来吗？ | 能。claimAmount 与 quantity × unitPrice 的差值超过 0.01 容差时，WC-005 会报出该行。它只管零件金额：如果你的登记表按零件 + 工时 − 免赔额结算（laborHours、laborRate、deductible 是单独的列），这条规则会报出差额——把 resultField 指向只含零件的列，或者关掉它。它不判断单价是否合理，也不判断零件是否本该更换。 |
| 里程列写的是 48,600 公里。还能读出来吗？超过上限会怎样？ | 能。WC-003 取其中的数字部分，所以 48600 和 48,600 公里 都能解析；只有解析不出的里程才会报出，它不判断里程是否超限。超限比较由 WC-004 做，对照的是你登记表写明的 warrantyMiles 上限——没有内置任何数值——它报出问题意味着「超过你记录的上限」，绝不是「超出保修期」——时间和里程是两道独立的限制，以先到者为准。 |
| 同一个索赔编号出现在两行上。 | WC-007 会报出重复的 claimNo，忽略空白字符，因为重复会让索赔总额被重复计算，也让厂商无法对账。同一条索赔因不同零件登记在多行是正常的：在零件名称列里把它们区分开。 |
| 某行既没有索赔编号，也没有零件名称。 | 只有 claimNo 和 partName 都没填时，WC-001 才报出该行：两者有其一就够了。它检查的是最基本的追溯信息是否存在，不判断这条索赔是否在保修期内、是否应该受理。 |
| 销售日期晚于索赔日期。 | WC-006 比较台账中的这两个日期，当 saleDate 晚于 claimDate 时报告该行。起始日期取自你的销售日期列：规则条款把开票日期和交付日期列为起点，本规则不替你选定其中一个，实际起点以厂商承诺为准。无法解析的日期单独报告，不会悄悄跳过。 |

遵循的标准

| 文件 | 编号 | 引用规则 |
| 《家用汽车产品修理更换退货责任规定》 | 市场监管总局令第43号（2021 年 7 月 22 日公布，自 2022 年 1 月 1 日起施行） | WC-001, WC-003, WC-005, WC-006, WC-007 |
| 各厂商质保政策与三包规定（本机构配置） | 无统一标准（本条依据为台账写明的质保期） | WC-002 |
| 各厂商质保政策（本机构配置） | 无统一标准（本条依据为台账写明的里程上限） | WC-004 |

边界： 本插件检查质保索赔台账的算术与期间自洽性——索赔是否记录了编号或零件名称，索赔日期是否落在台账写明的质保期截止日之内，里程能否解析且不超过台账写明的里程上限，索赔金额是否等于数量 × 单价，销售日期是否不晚于索赔日期，以及索赔编号是否重复。它不判定索赔是否应当受理、故障是否在保修范围内，也不判定故障是否由误用或正常磨损造成。

⚠️ 质保政策由厂商制定，本规则包不假装引用某一家的政策

质保期长度、里程上限、工时费率和免赔额由各厂商的质保政策以及相关产品类别的三包规定确定。不存在统一标准，所以每条规则的 basis 都如实说明这一点，并停留在 warn 或 info。

在信任某条发现之前，有三点后果值得了解：

- 插件从不推导质保期截止日。 它不会计算「销售日期 + 36 个月」，因为各月天数不同，而且质保期可能从交付或登记起算，而非从销售起算——算出来的日期看着精确，却可能是错的。你按适用政策推算出日期，填进质保期截止日列，WC-002 拿它来比对。
- WC-004 的里程上限同样来自台账。 没有内置任何数值，命中只意味着「超过你记录的里程上限」，绝不等于「已出保」——时间和里程是两个独立的上限，以先到者为准，而超过任一上限后的处理方式各家政策不同。
- WC-005 只覆盖零件。 实际索赔金额常常要加工时费和材料费，再减去免赔额，而本台账为这些项目设有单独的列。按「零件 + 工时 − 免赔额」结算的台账会报出差异；把 resultField 指向零件金额列，或停用该规则。

规则包里的每一条 excerpt 都明说了条款原文未能取得。 当条款已经拿到手，把每个 excerpt 换成真正的条款，并把 kind 升到 direct。

兼容性

| 层面 | 状态 |
| Harness | 对等范围 >=0.1.2-rc.1 <0.2.0 \|\| >=0.2.0-0 <0.3.0 —— 已验证同时接受 0.2.0-rc.2 和 0.2.1-alpha.1。故意不声明 engines.dsh：它没有读取方，也无法拒绝宿主 |
| Node | ^22.19.0 || >=24.0.0 |
| 平台 | 全部（纯 ESM；无原生代码，无网络，不调用模型） |
| 工具模式 | 在 native、ptc 和 both 下都能用；处理一批索赔时用 ptc |

它做什么

注册 warranty_calc 工具。它读取一份索赔登记表 —— 经销商表头，加上每行一条索赔 —— 套用带版本的规则包，返回报告。

| 规则 | 检查项 | 严重级别 | 依据类型 |
| WC-001 | 索赔记录了自己的单号或配件名称 | warn | direct |
| WC-002 | 索赔日期落在记录的质保期截止日之内 | info | local |
| WC-003 | 索赔时里程能解析成数字 | warn | principle |
| WC-004 | 索赔时里程不超过记录的里程上限 | info | local |
| WC-005 | 索赔金额等于数量 × 单价 | warn | direct |
| WC-006 | 销售日期不晚于索赔日期 | warn | principle |
| WC-007 | 索赔单号不重复 | warn | principle |

安装

dsh plugin --profile <name> add dsh-warranty-calc
dsh --profile <name> --dump-config | grep 'dsh-warranty-calc'

配置

| 键 | 类型 | 默认值 | 说明 |
| rulesFile | string | rules/warranty-calc.yaml | 规则包路径，相对于包根目录 |
| disabledRules | string[] | [] | 要停止运行的规则 id；每个都会出现在 skipped 里 |
| onlyRules | string[] | [] | 只运行这些规则 id；留空则运行全部规则 |
| skipNotes | string | "" | 追加到每条 skipped 原因后面的备注 |
| timeoutMs | number | 120000 | 协作式工具超时预算 |

几个值得了解的规则级参数：

- WC-002 需要登记表里的 质保期截止日 / warrantyEndAt 列；没有这一列，规则会在 skipped 里报告自己。插件从不按月数推算日期。
- WC-004 需要登记表里的 warrantyMiles。没有内置的里程数值。
- WC-005 的 resultField / factorFields / tolerance —— 配件部分的算术；如果你的结算包含工时费和免赔额，重新指向即可。

材料格式

工具接受 JSON 或 YAML：

dealer: 某某服务站 manufacturer: 某某厂商 policyVersion: 2026 版质保政策 rows:
- { 索赔单号: SP-2026-0018, 配件名称: 前制动片, 销售日期: 2024-03-10,
索赔时里程: '48600', 质保期月数: '36', 质保里程: '100000', 质保期截止日: 2027-03-09, 索赔日期: 2026-03-05, 数量: '2', 单价: '180', 索赔金额: '360', 处理结论: 同意索赔 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；登记表自己的列名会保留，所以一条发现会指明它读取的是哪一列。

规则来源

规则数据放在 rules/warranty-calc.yaml。保修政策是厂商自己的文书，不是标准，所以规则包里的 basis 条目直接写明这一点，不引用任何标准。加载时的校验仍然要求每条规则都带 document、clause、excerpt 和 source，也仍然禁止把本地配置的检查设为 error。

故障排查

- WC-002 报告自己被跳过。 登记表里没有保修结束日期。插件不会替你推算：每个月的天数不一样，保修期也可能从交付日或登记日起算。
- WC-002 触发了，但我认为这次索赔在保修范围内。 登记的结束日期和索赔日期对不上。按适用的政策重新核对结束日期是怎么算出来的。
- WC-004 在我认为在保的索赔上触发。 里程超过了你登记的里程上限——但时间和里程是两个独立的限制，只有这一条并不代表索赔已出保。
- WC-005 在正确的结算单上触发。 金额里很可能包含工时费和免赔额。把 resultField 指向只含零件的列，或者关掉这条规则。
- WC-006 在我能看懂的日期上触发。 读取器接受 2026-03-05 或 2026-03-05 09:30；2026年3月5日 会被故意报为无法解析。
- 插件装上了，但工具一直不出现。 检查 main 是否指向 lib/index.mjs，以及 pnpm run build 是否生成了它；main 写错会让加载器静默跳过这个入口。
- dsh plugin add 以不兼容为由拒绝这个包。 peer 范围覆盖 0.1.x 和 0.2.x；如果你的运行时不在这个范围内，显式授予豁免： dsh plugin --profile <name> allow-version dsh-warranty-calc@0.1.0 --dsh-version <runtime> --accept-risk
- check 报告 manifest-peers 失败。 静态检查器比对的是一个硬编码的 peer 范围，早于 0.2 系列。运行时会在安装时强制校验 peer 兼容性，所以声明的范围才是正确的；这是 dsh-plugin-dev 里已知的上游问题。

开发

pnpm install
pnpm run typecheck # tsc --noEmit
pnpm test # vitest, the shared table-plugin suite plus paired fixtures
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-warranty-calc # refresh src/shared from ../_shared

这个插件是纯数据的：src/model.ts 声明表结构，共享工具包提供读取器和检查引擎，规则包声明每一条检查。

许可证

Apache License 2.0 © 2026 dsh-warranty-calc contributors.