滞期费台账核对 PerryLink/dsh-demurrage-ledger

dsh-demurrage-ledger — 滞箱费台账完整性与算术校验

dsh-demurrage-ledger 读取一份滞箱费台账（demurrage and detention ledger）——表头加上每个集装箱一行——并校验台账自身的完整性与算术：每行至少记录集装箱号或提单号，免箱期起始日与还箱日能解析且先后顺序正确，超期天数等于这两个日期之差减去免箱天数，费用等于超期天数 × 费率，币种写成三字母代码，集装箱号不重复，备注里没有残留未替换的模板占位符。免箱天数与费率从台账本身读取，台账的列名可以是中文，也可以是英文。

它能回答什么

| 你问 | 它回答 |
| 某行的集装箱号和提单号都空着，校验会说什么吗？ | 会。只要台账给出了 containerNo 或 blNo 中至少一列，DL-001 就要求每一行都填上这两者之一，两者皆空时报告该行。它只检查是否填了其中之一，不判断费用是否本应产生。台账两列都没有时，规则会把自己列进 skipped，而不是悄悄放过。 |
| 起始日打成了 15/03/2026，还箱日却在它之前。规则怎么处理？ | DL-002 解析 startAt 并与 returnAt 比较：读不成日期的值会在该行报告，而不是跳过；起始日晚于还箱日也会报告——同一天不算晚。它只比较这两个日期；适用哪种起算口径（提单、放箱还是到港）由承运人运价表和合同决定。 |
| 超期天数列写的是 10，但两个日期和免箱期算出来是 7。这能查出来吗？ | 能。DL-003 按 returnAt − startAt − freeDays 重算天数，申报的 overdueDays 与重算结果之差超过配置的 tolerance 时报告该行，tolerance 默认为 0。它只在四个值都齐全且都能解析的行上运行；没有任何一行四个值齐全时，规则会把自己报告进 skipped。起算口径以及免箱期是否计入节假日，仍归合同管——按工作日或按小时计费时，调大 tolerance 或停用该规则。 |
| 费用不等于超期天数乘以费率——而且我的运价表第一周之后还要跳档。 | DL-004 计算 overdueDays × rate，amount 与之之差超过 tolerance 时报告该行，tolerance 默认为 0.01。它不判断费率是否合理，也不判断是否与运价表一致。阶梯运价没法用一个 rate 单元格表达，所以这类台账会报出差异：停用该规则，或者记录一个平均费率并在备注里说明。 |
| 币种单元格写的是 美元，或者 usd。这会被报告吗？ | 会。DL-005 会报告任何不符合配置档模式的 currency 值，默认模式是 ^[A-Z]{3}$——三个大写字母，例如 USD。它只做格式检查，不判断该币种是否适用于这笔结算。它的依据是配置档引用的唯一一项公开标准，其摘录记录了条款原文未取得，因此该规则停留在 warn。台账没有币种列时，该规则会在 skipped 中报告自身。 |
| 同一个箱号出现在两行。这是重复录入吗？ | DL-006 会在 containerNo 值重复时报告该行，比较时忽略空白，并指出它匹配到的较早那一行。它只检查唯一性，命中后需要人工确认：分批还箱，或者放行后再次被扣，都可能合理地占两行——请在备注里说明，而不是删掉一行。没有 containerNo 列时，该规则会报告自己无法运行，而不是静默通过。 |

遵循的标准

| 文件 | 编号 | 引用规则 |
| 承运人运价本与运输合同（无国家标准） | 无统一标准（本条依据为台账可追溯性） | DL-001 |
| 承运人运价本与运输合同（无国家标准） | 无统一标准（本条依据为日期自洽） | DL-002 |
| 承运人运价本与运输合同（无国家标准） | 无统一标准（本条依据为算术自洽） | DL-003, DL-004 |
| 《表示货币的代码》 | GB/T 12406—2022（表示货币的代码；2022-12-30 发布并实施；全部代替 GB/T 12406—2008（该版名称为「表示货币和资金的代码」）——注意旧版名称含"资金"；修改采用 ISO 4217:2015，非等同采用；条号本次未取得） | DL-005 |
| 承运人运价本与运输合同（无国家标准） | 无统一标准（本条依据为台账唯一性） | DL-006 |
| 承运人运价本与运输合同（无国家标准） | 无统一标准（本条依据为台账真实性） | DL-007 |

边界： 这个插件检查滞箱费台账的算术与完整性——箱号或提单是否记录在案，免箱期起始日与还箱日期能否解析、是否前后衔接，超期天数是否等于这两个日期之间的间隔减去免箱天数，费用是否等于天数 × 费率，币种是否符合格式，箱号是否重复。它不判定费用由谁承担、费率是否合理、能否获得减免，也不判定金额能否收回。这些取决于合同、责任划分与商务谈判。

⚠️ 这件事没有国家标准，配置档也不假装有

滞箱费与滞港费由各承运人的运价本与运输合同规定——免箱期和费率因承运人、航线与箱型而异，不存在统一的国家标准。所以这个配置档不编造标准编号：每条规则的 excerpt 都明说其依据是算术自洽或台账可追溯性，并且不存在可引用的条款。唯一的例外是币种格式，它的归属是 GB/T 12406（与 ISO 4217 一致），而那条摘录说明条款原文未取得。有测试断言每条摘录都带有上述承认之一。
插件不提供承运人的免箱期，也不提供费率。 两者都来自台账。在信任检查结果之前，有两个后果值得了解：

- 分段费率会破坏 DL-004。 费率通常分档递增（第 1–7 天一个费率，第 8 天起更高）。单个 rate 列无法表达这种情况，所以按分段计价的台账会报出差异。禁用该规则，或者记录平均费率并加一条说明。
- DL-003 不选择起算惯例。 计时从提单起算、从放箱起算还是从到港起算，以及免箱期是否包含节假日，都是合同的事。台账的 起算日期 和 免箱期 假定已经遵循合同。

兼容性

| 层面 | 状态 |
| 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 |

功能

注册 demurrage_ledger 工具。它读取一份台账——行以台账自己的列名为键，中文或英文皆可——应用版本化的规则包，返回报告。

| 规则 | 检查 | 严重级别 | 依据 |
| DL-001 | 记录了集装箱号或提单号 | warn | 台账可追溯性 |
| DL-002 | 起算日期和还箱日期可解析，且先后顺序正确 | warn | 日期一致性 |
| DL-003 | 超期天数与日期、免箱期一致 | warn | 算术 |
| DL-004 | 费用等于超期天数 × 费率 | warn | 算术 |
| DL-005 | 币种是三位字母代码 | warn | GB/T 12406 |
| DL-006 | 集装箱号在台账内唯一 | warn | 台账唯一性 |
| DL-007 | 备注列没有未替换的占位符 | warn | 台账完整性 |

安装

dsh plugin --profile <name> add dsh-demurrage-ledger
dsh --profile <name> --dump-config | grep 'dsh-demurrage-ledger'

配置

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

值得了解的规则级参数：

- DL-003 daysField / fromField / toField / subtractField / tolerance —— 天数计算。如果台账会取整，调高 tolerance；如果按工作日或小时计费，禁用该规则。
- DL-004 resultField / factorFields / tolerance —— 滞箱费计算逻辑，tolerance 默认 0.01。
- DL-005 pattern —— 币制格式，默认三个大写字母。
- DL-007 terms —— 要查找的占位符。

材料格式

工具接受 JSON 或 YAML：

carrier: 某某船务 blNo: MSCUAA123456 rows:
- { 箱号: MSCU1234567, 提单号: MSCUAA123456, 免箱期: '7', 起算日期: 2026-03-01,
还箱日期: 2026-03-15, 超期天数: '7', 费率: '120', 滞箱费金额: '840', 币制: USD, 备注: 按运价本分段计费，此为平均费率 }

列名匹配不区分大小写，并忽略空格、下划线和连字符；台账自身的列名会保留，因此每条发现都会指明它读取的是哪一列。日期可以写成 2026-03-01 或 2026-03-01 14:00，数值单元格可以带单位和千位分隔符。

规则来源

规则数据放在 rules/demurrage-ledger.yaml。由于没有国家标准规范滞箱费，规则包的 basis 条目会明确说明这一点，而不是引用某个标准；唯一的外部引用是币制代码标准，其摘录也承认未取得条款原文。加载时的校验仍然要求每条规则都带有文档、条款、摘录和来源，也仍然禁止把 derived-from-principle 或本地配置的检查设为 error。

故障排查

- DL-003 在我手工算过的台账上触发。 检查起算约定，以及免箱期是否包含节假日。发现结果会显示它使用的两个日期和免箱天数，可以据此重算。
- DL-004 在分段运价上触发。 单一费率无法表达阶梯运价。禁用该规则，或者记录一个平均费率并在备注里说明。
- DL-005 在 USD 上触发。 默认 pattern 只接受正好三个大写字母；末尾多一个空格或小写代码都会失败。请规范化导出数据。
- DL-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-demurrage-ledger@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 fixturesbash
pnpm run build # tsdown -> lib/index.mjs + lib/index.d.mts
node ../scripts/sync-shared.mjs dsh-demurrage-ledger # refresh src/shared from ../_shared

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

许可证

Apache License 2.0 © 2026 dsh-demurrage-ledger contributors。