dsh-progress-payment 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README-es.md

@@ -0,0 +1,13 @@
+<div align="center">
+
+# dsh-progress-payment
+
+> **Repositorio oficial. El único repositorio oficial de este paquete, mantenido por PerryLink. Apache-2.0.**
+
+</div>
+
+Audita una declaración de pago por avance de obra contra la línea base del contrato: importes en céntimos enteros, ratio acumulado y lista de problemas (exceso de cantidad, precio distinto, partidas duplicadas), con exportación a CSV. Todo se ejecuta localmente.
+
+## Documentación completa
+
+La documentación completa (instalación, permisos, ejemplos y solución de problemas) está en [README.md](README.md) y [README-zh.md](README-zh.md).

package/README-hi.md

@@ -0,0 +1,13 @@
+<div align="center">
+
+# dsh-progress-payment
+
+> **आधिकारिक रिपॉज़िटरी। इस पैकेज की एकमात्र आधिकारिक रिपॉज़िटरी, PerryLink द्वारा अनुरक्षित। Apache-2.0.**
+
+</div>
+
+निर्माण प्रगति-भुगतान घोषणा की अनुबंध आधार-रेखा से जाँच: पूर्णांक पैसे में राशि, संचयी अनुपात, तथा अधिक मात्रा / भिन्न दर / दोहराई गई मदों की सूची, CSV निर्यात के साथ। सब कुछ लोकल चलता है।
+
+## पूरा दस्तावेज़
+
+पूरा दस्तावेज़ (इंस्टॉल, अनुमतियाँ, उदाहरण और समस्या-निवारण) [README.md](README.md) और [README-zh.md](README-zh.md) में है।

package/README-pt.md

@@ -0,0 +1,13 @@
+<div align="center">
+
+# dsh-progress-payment
+
+> **Repositório oficial. O único repositório oficial deste pacote, mantido por PerryLink. Apache-2.0.**
+
+</div>
+
+Audita uma declaração de pagamento por medição de obra contra a linha de base do contrato: valores em centavos inteiros, razão acumulada e lista de problemas (quantidade excedida, preço divergente, itens duplicados), com exportação para CSV. Tudo roda localmente.
+
+## Documentação completa
+
+A documentação completa (instalação, permissões, exemplos e solução de problemas) está em [README.md](README.md) e [README-zh.md](README-zh.md).

package/README-zh.md

@@ -0,0 +1,205 @@
+<div align="center">
+
+# dsh-progress-payment
+
+> **官方仓库。** 本包唯一官方仓库，由 PerryLink 维护；其他账号下的同名仓库与本项目无关。Apache-2.0。
+
+[![npm](https://img.shields.io/npm/v/dsh-progress-payment)](https://www.npmjs.com/package/dsh-progress-payment)
+[![CI](https://github.com/PerryLink/dsh-progress-payment/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-progress-payment/actions)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+**按合同基准确认本期进度款：金额整数分、累计比例、超量/单价/重复项问题清单 → 审核底稿 CSV。**
+
+> **状态：alpha / 公开合成 / partial / not counted / 非 GA。** 不含客户数据、客户证据，也不作生产可用声明。
+
+[English](README.md) · [简体中文](README-zh.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
+
+```sh
+dsh plugin --profile <profile> add dsh-progress-payment
+```
+
+</div>
+
+## 一句话
+
+把本期进度款申报按合同基准逐项核对，算出本期金额和累计比例，列出超量、单价不符和重复清单项，再导出审核底稿 CSV。
+
+## 适合 / 不适合
+
+- **适合**：总包、分包、业主方的造价和监理人员，每期几十到几千条清单项的进度款申报；先核对量和单价，再决定本期签认多少；把申报、合同基准和问题清单留成一份可复核的 CSV 底稿。
+- **不适合**：替代计价软件、结算审核或法律意见；没有合同基准的手工报量；判断变更签证是否成立（本包只按合同基准提示超量，不替你做变更审批）；扫描件/PDF/图片的 OCR（只收 CSV）。
+
+## 输入
+
+- **申报 CSV**：UTF-8，表头含 `清单编码,名称,单位,合同量,合同单价,本期完成量,累计完成量`；也接受英文表头 `item_code,item_name,unit,contract_qty,contract_unit_price,period_qty,cumulative_qty`，列顺序随意。
+- **合同基准 CSV**（可选）：`清单编码,合同量,合同单价`（英文 `item_code,contract_qty,contract_unit_price`）。给了基准就以基准为权威；不给就用申报里的合同量/单价。
+- **格式约定**：数量最多 3 位小数，单价/金额最多 2 位小数；金额内部按**整数分**计算，不用浮点累加。
+- **样例**：`samples/quickstart/input/declaration-2026-10.csv`（7 行 / 6 个清单项）和 `contract-baseline.csv`（6 项），全部为合成数据（虚构清单编码和金额）。
+
+## 输出
+
+- `progress.ingest`：`batch_id`、行数、清单项数、合同基准项数；只存在当前会话内存里，不落盘。
+- `progress.audit`：每个清单项的合同量/单价、本期完成量、累计完成量、本期金额、累计金额、累计比例，加一份按行号排序的问题清单（`E_PROGRESS_*`）；金额都是整数分。
+- `progress.export`：审核底稿 CSV（UTF-8 BOM，Excel 直接打开不乱码），一行一条申报记录，重复行标 `是否计入=否`；写到 `$DSH_HOME/dsh-progress-payment/exports/`，返回路径、行数、字节数和 sha256。
+- **不改原 CSV**，不上传、不联网、不调用模型。
+
+## 示例
+
+直接复制下面这句：
+
+> 帮我审一下这期进度款申报，按合同基准核对超量和单价，把问题清单导成底稿。
+
+用自带样例复跑并核对金标：
+
+```sh
+node samples/quickstart/run.mjs --check
+```
+
+![dsh-progress-payment quickstart 真实运行输出](docs/assets/quickstart.png)
+
+样例是一次真实运行：7 行申报 / 6 个清单项，本期金额 **50,763.60 CNY**，累计 **614,145.00 CNY（84.62%）**，3 个阻塞问题——矩形柱累计 101.5 m³ 超合同量 95 m³、基础模板申报单价 65.00 与合同基准 55.00 不符、挖沟槽土方重复出现 2 次。金标 `samples/quickstart/expected/result.json` 由 `node samples/quickstart/run.mjs --json` 真实产生，不是手写。
+
+## 权限
+
+读：用户指定的申报 CSV 和合同基准 CSV（样例 `samples/quickstart/input/`）；不读其他目录。
+写：`$DSH_HOME/dsh-progress-payment/exports/`（审核底稿 CSV）；不改原文件。
+联网：否。
+外部系统：无。
+
+`progress.ingest`、`progress.audit` 标 **R0**（只读；`ingest` 只写入当前会话内存，不落盘）；`progress.export` 标 **R1**（本地写，只写 `$DSH_HOME/dsh-progress-payment` 下的 `exports/`）。可用 `DSH_PROGRESS_PAYMENT_HOME` 覆盖本地写根目录（测试用），默认严格等于 `$DSH_HOME/dsh-progress-payment`。
+
+## FAQ
+
+### 1. 为什么本期金额和我自己算的不一样？
+
+本包按**合同基准单价**计算本期金额，不用申报里填的单价。申报单价和基准不一致时会报 `E_PROGRESS_PRICE_MISMATCH`，并把“按申报单价算的金额”和“按合同单价算的金额”都列出来，差额在 `summary.price_adjustment_cents` 里。数量×单价按分四舍五入到整数分，不累加浮点误差。
+
+### 2. “超合同量”到底按哪一版合同量？
+
+给了合同基准就以基准为准；没给才用申报里的合同量。本期完成量超过合同量、累计完成量超过合同量都会报 `E_PROGRESS_OVER_QTY`，两者用 `kind` 区分（`period_over_contract` / `cumulative_over_contract`）。超量部分不会自动扣减合同额，需要走变更或结算。
+
+### 3. 重复清单项会重复算钱吗？
+
+不会。同一清单编码出现多次时，只按第一次出现的行计入本期金额，其余行在底稿里标 `是否计入=否`，并报 `E_PROGRESS_DUP_ITEM`。但哪一行才是“本期应报的”需要你确认，本包不自动挑。
+
+### 4. 会改我的 CSV 或上传数据吗？
+
+不会。只读用户指定的 CSV；只在本地 `exports/` 写底稿；不联网、不调用模型、不上传。
+
+### 5. 能直接读 Excel 吗？
+
+不能。请先在 Excel“另存为 → CSV UTF-8”。如果表头是中文且用 Excel 保存，文件可能带 BOM，本包能正确识别。
+
+## 版本
+
+`0.1.0-alpha.1` · 32 项测试通过（`node --test test/*.test.mjs`）。
+
+> ⭐ 如果它帮到了你，点个 star 会让下一个人更容易找到它；没有任何功能被 star 解锁。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-progress-payment
+dsh --profile <profile> --dump-config | grep dsh-progress-payment
+```
+
+卸载：
+
+```sh
+dsh plugin --profile <profile> remove dsh-progress-payment
+```
+
+### 安装通道
+
+- **npm（推荐）:** `dsh plugin --profile <profile> add dsh-progress-payment`
+- **git 通道:** `dsh plugin --profile <profile> add github:PerryLink/dsh-progress-payment`
+- **tarball:** `pnpm pack`，然后 `dsh plugin --profile <profile> add ./dsh-progress-payment-<version>.tgz`
+
+## 工具
+
+工具名是稳定 API；说明保留英文以匹配运行时输出。
+
+| 工具 | 用途 | 风险 |
+|---|---|---|
+| `progress.ingest` | 导入本期申报 CSV 与可选合同基准 CSV，返回 `batch_id`；只写会话内存 | R0 |
+| `progress.audit` | 审核：本期金额、累计比例、超合同量、单价不符、累计>合同量、重复清单项；返回问题清单，金额整数分 | R0 |
+| `progress.export` | 重跑审核并写审核底稿 CSV（UTF-8 BOM），返回路径、行数、sha256 | R1 local write |
+
+## 审核规则
+
+1. **金额**：`本期金额 = 本期完成量 × 合同单价`，按整数分四舍五入；累计金额同理。
+2. **累计比例**：`累计金额 ÷ 合同金额 × 100`，保留 2 位小数；合同金额为 0 时返回 0。
+3. **超合同量**：`本期完成量 > 合同量` 或 `累计完成量 > 合同量` → `E_PROGRESS_OVER_QTY`。
+4. **单价不符**：申报合同单价 ≠ 合同基准单价 → `E_PROGRESS_PRICE_MISMATCH`；可用 `price_tolerance_bps` 放宽容差（默认 0，精确比对）。
+5. **累计 > 合同量**：同 3 的 `cumulative_over_contract`，累计比例会超过 100%。
+6. **重复清单项**：同一 `清单编码` 出现多次 → `E_PROGRESS_DUP_ITEM`；仅第一次出现计入金额。
+7. **合同基准缺失 / 合同量不符**：`E_PROGRESS_CONTRACT_MISSING` / `E_PROGRESS_CONTRACT_MISMATCH`。
+8. **累计小于本期**：`E_PROGRESS_QTY_INCONSISTENT`，通常是上期累计填错。
+
+## 快速开始
+
+```sh
+# 1) 导入申报（工具面）
+#    progress.ingest({ declaration_csv, contract_csv })
+
+# 2) 审核（工具面）
+#    progress.audit({ batch_id })
+
+# 3) 导出底稿（工具面）
+#    progress.export({ batch_id, filename: "progress-audit-2026-10.csv" })
+```
+
+用样例直接跑：
+
+```sh
+node samples/quickstart/run.mjs --check
+```
+
+## 验收证据
+
+公开/合成 fixture 在 `samples/quickstart/`；`ACCEPTANCE.csv` 记录检查，除 quickstart 行外均为 `counted=false`。
+
+| req_id | metric | threshold | actual | pass | source | counted |
+|---|---|---|---|---|---|---|
+| PG-A02 | 本期金额（分） | 5076360 | 5076360 | true | public/synthetic | false |
+| PG-A06 | 单价不符 | E_PROGRESS_PRICE_MISMATCH x1 | 1 | true | public/synthetic | false |
+| PS1-QS01 | quickstart 金标 | 1/1 | 1 | true | synthetic/quickstart | true |
+
+*这是 fixture 支撑的验收行，不是客户运行；没有编造输出。*
+
+## 边界与已知限制
+
+- **只做量价核对**：不判断变更签证、索赔、质量扣款、税率和支付比例是否合理；这些仍需合同条款和人工判断。
+- **单价只有一个口径**：申报里的 `合同单价` 是本期计价依据；没有“本期单价/信息价”列。
+- **不自动挑选重复行**：重复清单项会全部列出并只计第一行，哪行应报需要人工确认。
+- **金额上限**：单行金额需落在 JavaScript 安全整数范围内；超出会报 `E_PROGRESS_CSV_ROW`。
+- **只收 CSV**：不支持 xlsx、PDF、扫描件；Excel 请先另存为 CSV。
+- 仅公开/合成样例；alpha/partial、not counted，不作 GA 或生产可用声明。
+
+## 开发
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build && pnpm lint && pnpm typecheck
+node --test test/*.test.mjs
+node scripts/gate.mjs
+```
+
+## 兼容性
+
+| 维度 | 状态 |
+|---|---|
+| Harness | `dsh >=0.2.1-rc.3 <0.4.0` |
+| Node | `>=24.9.0 <25` |
+| Platforms | All; local files only |
+| 数据 | No network, no model call, no upload |
+
+## 相关项目
+
+- [dsh-ifc-qto](https://github.com/PerryLink/dsh-ifc-qto)（模型工程量，可作为申报量的对照）
+- [dsh-ap-three-way](https://github.com/PerryLink/dsh-ap-three-way)（付款单三单匹配）
+- [领域索引](https://perrylink.github.io/dsh-plugins/)
+
+## 许可证
+
+Apache-2.0. See `LICENSE`, `NOTICE`, `THIRD-PARTY-NOTICES`.

package/README.md

@@ -1,3 +1,205 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-progress-payment
+
+> **Official repository.** The only official repository of this package, maintained by PerryLink. Same-name repositories under other accounts are not affiliated. Apache-2.0.
+
+[![npm](https://img.shields.io/npm/v/dsh-progress-payment)](https://www.npmjs.com/package/dsh-progress-payment)
+[![CI](https://github.com/PerryLink/dsh-progress-payment/actions/workflows/ci.yml/badge.svg)](https://github.com/PerryLink/dsh-progress-payment/actions)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+**Audit a construction progress-payment declaration against the contract baseline: integer-cent amounts, cumulative ratio, over-quantity / price / duplicate issues → review worksheet CSV.**
+
+> **Status: alpha / public-synthetic / partial / not counted / not GA.** No customer data, customer evidence, or production-readiness claim.
+
+[English](README.md) · [简体中文](README-zh.md) · [Español](README-es.md) · [Português](README-pt.md) · [हिन्दी](README-hi.md)
+
+```sh
+dsh plugin --profile <profile> add dsh-progress-payment
+```
+
+</div>
+
+## One-liner
+
+Check this period's declared quantities and prices against the contract, compute the period and cumulative amounts plus the cumulative ratio, list over-quantity, price-mismatch and duplicate bill items, and export a review worksheet CSV.
+
+## Fit / not a fit
+
+- **Fits:** quantity surveyors, cost engineers and site supervisors who audit a monthly progress payment with tens to thousands of bill items; checking quantity and unit price before signing the certificate; keeping the declaration, contract baseline and issue list in one reviewable CSV.
+- **Does not fit:** replacing estimating/settlement software or legal advice; declarations with no contract baseline; deciding whether a change order is valid (this package flags over-quantity but does not approve variations); OCR of scanned PDFs (CSV only).
+
+## Input
+
+- **Declaration CSV:** UTF-8, header `清单编码,名称,单位,合同量,合同单价,本期完成量,累计完成量` (Chinese) or `item_code,item_name,unit,contract_qty,contract_unit_price,period_qty,cumulative_qty` (English). Column order is free.
+- **Contract baseline CSV (optional):** `清单编码,合同量,合同单价` (or `item_code,contract_qty,contract_unit_price`). When supplied it is authoritative; otherwise the declared contract quantity/price is used.
+- **Precision:** quantities up to 3 decimals, prices/amounts up to 2 decimals. Money is computed in **integer cents**, never float accumulation.
+- **Sample:** `samples/quickstart/input/declaration-2026-10.csv` (7 rows / 6 bill items) and `contract-baseline.csv` (6 items). Synthetic only.
+
+## Output
+
+- `progress.ingest`: `batch_id`, rows, item count, contract-item count. Session memory only; no file is written.
+- `progress.audit`: per item the contract quantity/price, period quantity, cumulative quantity, period amount, cumulative amount, cumulative ratio, plus a row-ordered issue list (`E_PROGRESS_*`). Amounts are integer cents.
+- `progress.export`: review worksheet CSV (UTF-8 BOM, opens cleanly in Excel), one row per declaration line with duplicate rows marked `是否计入=否`; written to `$DSH_HOME/dsh-progress-payment/exports/`; returns path, rows, bytes and sha256.
+- The source CSVs are never modified; no upload, no network, no model call.
+
+## Example
+
+Paste this one line into the agent:
+
+> 帮我审一下这期进度款申报，按合同基准核对超量和单价，把问题清单导成底稿。
+
+Reproduce the bundled sample and compare with the golden file:
+
+```sh
+node samples/quickstart/run.mjs --check
+```
+
+![dsh-progress-payment quickstart terminal output](docs/assets/quickstart.png)
+
+This is a real run: 7 declaration rows / 6 bill items, period amount **50,763.60 CNY**, cumulative **614,145.00 CNY (84.62%)**, and 3 blocking issues — the rectangular column exceeded its contract quantity (101.5 vs 95 m³), the formwork price was 65.00 against a 55.00 baseline, and one item code appeared twice. `samples/quickstart/expected/result.json` is the real stdout of `node samples/quickstart/run.mjs --json`, not hand-written.
+
+## Permissions
+
+Read: the declaration CSV and contract baseline CSV the user names (sample: `samples/quickstart/input/`); nothing else.
+Write: `$DSH_HOME/dsh-progress-payment/exports/` (review worksheet CSV) only; source files are not modified.
+Network: no.
+External systems: none.
+
+`progress.ingest` and `progress.audit` are **R0** (read-only; `ingest` keeps the batch in session memory). `progress.export` is **R1** (local write under `$DSH_HOME/dsh-progress-payment`). `DSH_PROGRESS_PAYMENT_HOME` can override the local write root for tests.
+
+## FAQ
+
+### 1. Why does the period amount differ from my own calculation?
+
+The audit prices every line at the **contract baseline unit price**, not the declared price. A declared price that differs raises `E_PROGRESS_PRICE_MISMATCH` and both amounts are reported; the delta is `summary.price_adjustment_cents`. Quantity × price is rounded half-up to whole cents.
+
+### 2. Which contract quantity is the ceiling?
+
+The contract baseline wins when supplied; the declared contract quantity is used only when no baseline is given. Both `period_qty > contract_qty` and `cumulative_qty > contract_qty` raise `E_PROGRESS_OVER_QTY`, distinguished by `kind` (`period_over_contract` / `cumulative_over_contract`). Over-quantity is not silently deducted — it needs a variation or settlement.
+
+### 3. Do duplicate item codes get paid twice?
+
+No. Only the first occurrence counts toward the period amount; the other rows are marked `是否计入=否` in the worksheet and raise `E_PROGRESS_DUP_ITEM`. Which row is the right one still needs a human decision.
+
+### 4. Does it modify or upload my CSV?
+
+No. It reads the named CSVs, writes only under `$DSH_HOME/dsh-progress-payment/exports/`, and never uses the network or a model call.
+
+### 5. Can it read Excel directly?
+
+No. Save the sheet as **CSV UTF-8** first. Excel-written UTF-8 CSVs with a BOM are accepted.
+
+## Version
+
+`0.1.0-alpha.1` · 32 tests pass (`node --test test/*.test.mjs`).
+
+> ⭐ If this helps, a star makes it easier for the next person to find it. Nothing is gated behind it.
+
+## Install
+
+```sh
+dsh plugin --profile <profile> add dsh-progress-payment
+dsh --profile <profile> --dump-config | grep dsh-progress-payment
+```
+
+Uninstall:
+
+```sh
+dsh plugin --profile <profile> remove dsh-progress-payment
+```
+
+### Install channels
+
+- **npm (recommended):** `dsh plugin --profile <profile> add dsh-progress-payment`
+- **git channel:** `dsh plugin --profile <profile> add github:PerryLink/dsh-progress-payment`
+- **tarball:** `pnpm pack`, then `dsh plugin --profile <profile> add ./dsh-progress-payment-<version>.tgz`
+
+## Tools
+
+Tool names are stable API; descriptions stay in English to match runtime output.
+
+| Tool | Purpose | Risk |
+|---|---|---|
+| `progress.ingest` | Import a declaration CSV and an optional contract baseline; returns `batch_id`; session memory only | R0 |
+| `progress.audit` | Period amount, cumulative ratio, over-quantity, price mismatch, cumulative-over-contract and duplicate items; returns the issue list; integer cents | R0 |
+| `progress.export` | Re-run the audit and write the review worksheet CSV (UTF-8 BOM); returns path, rows, sha256 | R1 local write |
+
+## Audit rules
+
+1. **Amount:** `period amount = period qty × contract unit price`, rounded half-up to whole cents; cumulative is computed the same way.
+2. **Cumulative ratio:** `cumulative amount ÷ contract amount × 100`, two decimals; a zero contract amount yields 0.
+3. **Over quantity:** `period_qty > contract_qty` or `cumulative_qty > contract_qty` → `E_PROGRESS_OVER_QTY`.
+4. **Price mismatch:** declared contract unit price ≠ baseline unit price → `E_PROGRESS_PRICE_MISMATCH`; `price_tolerance_bps` relaxes it (default 0 = exact).
+5. **Cumulative > contract quantity:** the `cumulative_over_contract` kind; the ratio can exceed 100%.
+6. **Duplicate item:** the same `item_code` appears more than once → `E_PROGRESS_DUP_ITEM`; only the first occurrence is counted.
+7. **Missing / mismatched baseline:** `E_PROGRESS_CONTRACT_MISSING` / `E_PROGRESS_CONTRACT_MISMATCH`.
+8. **Cumulative below period:** `E_PROGRESS_QTY_INCONSISTENT`, usually a wrong opening cumulative.
+
+## Quick start
+
+```sh
+# 1) import the declaration (tool surface)
+#    progress.ingest({ declaration_csv, contract_csv })
+
+# 2) audit (tool surface)
+#    progress.audit({ batch_id })
+
+# 3) export the worksheet (tool surface)
+#    progress.export({ batch_id, filename: "progress-audit-2026-10.csv" })
+```
+
+Or run the sample:
+
+```sh
+node samples/quickstart/run.mjs --check
+```
+
+## Acceptance evidence
+
+Public/synthetic fixtures live in `samples/quickstart/`; `ACCEPTANCE.csv` records the checks. Every row is `counted=false` except the quickstart row.
+
+| req_id | metric | threshold | actual | pass | source | counted |
+|---|---|---|---|---|---|---|
+| PG-A02 | period amount (cents) | 5076360 | 5076360 | true | public/synthetic | false |
+| PG-A06 | price mismatch | E_PROGRESS_PRICE_MISMATCH x1 | 1 | true | public/synthetic | false |
+| PS1-QS01 | quickstart golden | 1/1 | 1 | true | synthetic/quickstart | true |
+
+*Fixture-backed rows, not a customer run; no output is invented.*
+
+## Limits and known limitations
+
+- **Quantity/price only:** no judgement on variations, claims, retention, tax or pay ratios; those still need the contract and a human.
+- **One price basis:** the declaration's `contract_unit_price` is the pricing basis; there is no current-price or index-price column.
+- **No automatic duplicate choice:** duplicates are listed and only the first row is counted; a human must pick the right one.
+- **Amount ceiling:** a single line must stay inside the JavaScript safe-integer range; otherwise `E_PROGRESS_CSV_ROW`.
+- **CSV only:** no xlsx, PDF or scanned documents.
+- Public/synthetic samples only; alpha/partial, not counted, no GA or production-readiness claim.
+
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build && pnpm lint && pnpm typecheck
+node --test test/*.test.mjs
+node scripts/gate.mjs
+```
+
+## Compatibility
+
+| Surface | Status |
+|---|---|
+| Harness | `dsh >=0.2.1-rc.3 <0.4.0` |
+| Node | `>=24.9.0 <25` |
+| Platforms | All; local files only |
+| Data | No network, no model call, no upload |
+
+## Related work
+
+- [dsh-ifc-qto](https://github.com/PerryLink/dsh-ifc-qto) (model quantities, a cross-check for declared quantities)
+- [dsh-ap-three-way](https://github.com/PerryLink/dsh-ap-three-way) (payment invoice / PO / GRN three-way match)
+- [Domain index](https://perrylink.github.io/dsh-plugins/)
+
+## License
+
+Apache-2.0. See `LICENSE`, `NOTICE`, `THIRD-PARTY-NOTICES`.