维修工单核对 PerryLink/dsh-repair-order-qc

dsh-repair-order-qc — 机动车维修工单登记簿与结算算术检查

dsh-repair-order-qc 读取一份机动车维修工单登记簿——车辆表头加上每个明细行一行——检查这份登记簿自身的完整性与算术：客户的报修内容与已完成的作业是否记录在案，项目名称列是否填写，数量、单价、金额是否可解析，金额是否等于数量 × 单价，各行金额合计是否等于结算金额，结算金额是否等于配件费加人工费减折扣，收款日期是否不晚于交车日期，工单号在登记簿内是否唯一，以及项目名称列里是否还残留模板占位符。

它能回答什么

| 你问 | 它怎么答 |
| 某行写着数量 2、单价 180，金额却是 400——检查能发现吗？ | 能。RO-002 会报出这一行，因为 2 × 180 = 360，而金额单元格写的是 400。只有数量、单价、金额三者都能解析为数字时规则才运行，容差为 0.01，用于吸收四舍五入。它不判断单价是否合理，也不判断这个项目到底该不该收费。 |
| 各行金额加起来对不上材料表头写的结算金额。 | RO-003 把 amount 列相加，与材料表头声明的结算金额 total 比较，并报告它加了多少行、差额有多大。容差为 0.01。它只做这道加法，不判断各项收费是否合理。 |
| 我们的工单没有配件费合计，也没有人工费合计——插件还能告诉我结算金额错了吗？ | 不能，而且它会明说。RO-004 检查配件费加人工费减折扣是否等于结算金额；材料里没有 partsTotal 和 laborTotal 两项合计时，它把自己记进 skipped，而不是擅自假定一种构成。它的折扣列表示减免金额；如果登记簿记录的是折扣率，应停用这条规则或改用其他检查。 |
| 交车日期早于收款日期。 | RO-005 会报出这一行：它比较收款日期与交车日期，收款晚于交车时报告该行。同一天算作不晚；无法解析的日期会在自己那一行上报出，而不是默默放过；它不判断维修耗时是否合理。 |
| 同一个工单号出现在两行上。 | RO-006 会报出重复的工单号，因为这会重复计费，也会切断工单与其归档之间的对应关系；比较时忽略空白字符。一张工单拆成多个明细行是正常形态——请在项目名称列里区分这些行，不要重复工单号。这条规则只检查唯一性。 |
| 项目名称单元格仍写着【】或待填。 | RO-007 会报告残留的占位符，因为没有真实项目的工单无法结算。它查找的 terms 列表来自它自己的规则包，可以按你的模板调整。它只检查这些字面字符串是否出现，不检查措辞是否恰当。 |

遵循的标准

| 文件 | 编号 | 引用它的规则 |
| 《机动车维修管理规定》 | 交通运输部令2021年第18号（2005 年公布，经 2015、2016、2019、2021 年四次修正，自 2005 年 8 月 1 日起施行） | RO-001, RO-002, RO-003, RO-004, RO-005, RO-006, RO-007 |

边界： 本插件检查机动车维修工单的算术与完整性——客户报修内容与所做维修是否记录在案、某一行金额是否等于数量 × 单价、各行金额合计是否等于结算金额、结算金额是否等于配件费加工时费再减折扣、交车日期是否不早于接车日期、工单编号是否前后一致、是否还有占位符残留。它不判断维修是否必要、收费是否合理、是否存在过度维修，也不判断维修做得是否到位。

⚠️ 它查的是算术，不是维修

一份工单，数字完全自洽，但做的维修本就不该卖——照样能通过本插件。判断必要性与价格，需要车辆实际状况、技术标准和维修合同，这些本插件一概没有。

工时单价来自登记表或你的配置。 没有内置任何单价标准。插件也不检查配件是否正品；登记表写什么，它就报什么。

有两条算术规则要读登记表的构成，跑不起来时都会说明：

- RO-002 校验 金额 = 数量 × 单价，三个单元格只要有一个解析不了，就在 skipped 里报告自己。容差为 0.01，用于处理舍入。
- RO-004 校验 配件费合计 + 工时费合计 − 折扣 = 结算总额。减法在规则包里写成逐项符号（signs: [1, 1, -1]），而不是负的比例系数，这样结论读起来就像人自己写的算式。登记表若没有配件费/工时费的拆分，规则就不运行，而不是去假设一种构成。

规则包里每个 excerpt 都明说了：条款原文没有取到。 制度依据在《机动车维修管理规定》和 GB/T 16739 里。核查环节没能取到逐字条款原文，所以规则包在 excerpt 字段里直接写明这一缺口，并把所有规则都保持在 warn 或 info。拿到原文后，把每个 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 |

功能说明

注册 repair_order_qc 工具。它读取一份维修工单登记表——车辆表头，加上每个项目行一行——套用带版本的规则包，返回报告。

| 规则 | 检查内容 | 严重级别 | 依据类型 |
| RO-001 | 记录了报告与已完成的作业 | warn | direct |
| RO-002 | 行金额等于数量 × 单价 | warn | direct |
| RO-003 | 各行金额合计等于结算金额 | warn | direct |
| RO-004 | 总额等于配件费 + 工时费 − 折扣 | warn | direct |
| RO-005 | 交车日期不早于接车日期 | warn | principle |
| RO-006 | 工单号使用一致 | warn | principle |
| RO-007 | 项目列中没有未替换的占位符 | warn | principle |

安装

dsh plugin --profile <name> add dsh-repair-order-qc
dsh --profile <name> --dump-config | grep 'dsh-repair-order-qc'

配置

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

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

- RO-002 的 resultField / factorFields / tolerance —— 行内算术。
- RO-003 的 field / headerField / tolerance —— 求和的列，以及它必须匹配的表头数字。
- RO-004 的 expression —— 组成方式，写作 { "op": "sum", "fields": [...], "signs": [1, 1, -1] }。如果你的结算组成方式不同，改符号；如果你收的是折扣费率而不是金额，停用该规则。
- RO-007 的 terms —— 要查找的占位符。

材料格式

工具接受 JSON 或 YAML：

customer: 某某客户 vehicle: 某某车型 mileage: '48600' partsTotal: '360' laborTotal: '200' discount: '0' total: '560' rows:
- { 工单号: WX-2026-0018, 进厂日期: 2026-03-02, 出厂日期: 2026-03-04,
项目名称: 前制动片, 数量: '2', 单价: '180', 金额: '360', 客户反映: 刹车时有异响, 施工内容: 更换前制动片一副并试车 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；登记表自身的列名会保留，因此问题项会指出它读取的是哪一列。整单只写一次的数字（配件费与工时费合计、结算金额）可以放在表头，算术检查会找到它们。

规则来源

规则数据位于 rules/repair-order-qc.yaml。规则包的表头完整说明了引用缺口，每条规则的 note 重复了与该规则相关的部分。加载时的守卫通常强制「一个「摘录必须是一段真实引用，至少八个字符」——这句话分不清引用和描述，所以这个包靠表头、每条规则的说明，还有一个测试来兜底：测试断言每条 excerpt 都留出了这段间隔。

故障排查

- RO-004 报告自己跳过了。 登记表里没有零件或工时合计，也就没有组成可查。插件不会自己假设一个。
- RO-004 在我明知没问题的结算单上触发了。 零件、工时、折扣的数字和合计对不上。查一下你的折扣是费率还是金额——如果是费率，就禁用这条规则。
- RO-002 在我认为已经取整的行上触发了。 默认容差是 0.01；如果你的定价取整更粗，就调大它。
- RO-006 在同一张工单上触发了两次。 一张工单带多个明细行很正常——让工单号保持共用即可。只有当同一个号码出现在你本意是不同工单的行上时，规则才会触发；如果你的登记表本来就按设计让多行共用同一个号码，就禁用这条规则。
- 插件装上了，但工具一直不出现。 检查 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-repair-order-qc@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-repair-order-qc # refresh src/shared from ../_shared

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

许可证

Apache License 2.0 © 2026 dsh-repair-order-qc contributors.