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

package/TROUBLESHOOTING.md

@@ -0,0 +1,75 @@
+# 故障排查 — dsh-progress-payment
+
+每条按「症状 / 原因 / 动作」写。报错原文都是 `<一句人话>（E_XXX）｜下一步：<动作>`，
+把 `E_XXX` 和这句话一起发到 issue 即可定位。不要把真实申报或合同金额贴进 issue。
+
+## 1. CSV 缺列或某行读不懂（E_PROGRESS_CSV_ROW）
+
+- **症状**：`申报或合同 CSV 的表头/某一行读不懂（E_PROGRESS_CSV_ROW）｜下一步：按 README 的列名补齐表头；数量写纯数字（最多 3 位小数），单价写金额（最多 2 位小数），不要带单位｜细节：申报 CSV 缺少列：cumulative_qty；表头是：…`
+- **原因**：表头少了 7 列中的某一列；或某一行数量/单价为空、带单位、负数、超过小数位；或合同基准里同一清单编码出现两次。
+- **动作**：对照 `samples/quickstart/input/` 的表头；数量写 `25.92`，单价写 `480.00`，不要写 `25.92m3` 或 `￥480`。合同基准一条清单只能一行。Excel 请另存为 CSV UTF-8。
+
+## 2. 空 CSV（E_PROGRESS_CSV_EMPTY）
+
+- **症状**：`这个 CSV 是空的，既没有表头也没有数据（E_PROGRESS_CSV_EMPTY）｜下一步：确认文件不是 0 字节，并且第一行是表头、后面至少有一行数据`
+- **原因**：文件 0 字节、只有空行，或导出时选错了工作表。
+- **动作**：确认文件大小 > 0，第一行是表头；重新从 Excel 导出。
+
+## 3. 超合同量（E_PROGRESS_OVER_QTY）
+
+- **症状**：`累计完成量 101.5 超过合同量 95（E_PROGRESS_OVER_QTY）｜下一步：核对合同量和变更签证；超量部分走变更或结算，不在本期支付`
+- **原因**：申报的本期或累计完成量大于合同基准数量；常见于变更未入合同、上期累计填错、或单位换算错误（m³ / m² / t）。
+- **动作**：以合同基准为准核对；确属变更的，先办变更或签证再报量；单位不一致先统一单位。超量部分不会自动从本期金额扣减，需要人工签认。
+
+## 4. 单价与合同不符（E_PROGRESS_PRICE_MISMATCH）
+
+- **症状**：`申报合同单价 65.00 与合同基准 55.00 不符（E_PROGRESS_PRICE_MISMATCH）｜下一步：本期金额按合同单价 55.00 重算，并要求申报方改正`
+- **原因**：申报表里的合同单价被改动，或合同基准版本过期。
+- **动作**：本期金额已按合同单价重算；让申报方改正单价，或确认哪一版合同才是现行版本。`price_tolerance_bps` 只用于允许的报价浮动，不要用它掩盖错价。
+
+## 5. 重复清单项（E_PROGRESS_DUP_ITEM）
+
+- **症状**：`清单编码 010101003 在本期申报里出现 2 次（行 2、7）（E_PROGRESS_DUP_ITEM）｜下一步：确认哪一行是本期应报的；重复行不计入本期金额`
+- **原因**：申报表复制粘贴重复、多个标段合并时编码冲突，或同一清单拆成两行报量。
+- **动作**：确认哪一行是本期应报；底稿里重复行已标 `是否计入=否`，不会重复计钱。不要直接删原始申报文件。
+
+## 6. 合同基准缺清单 / 合同量不符（E_PROGRESS_CONTRACT_MISSING / E_PROGRESS_CONTRACT_MISMATCH）
+
+- **症状**：`清单编码 Z-9 不在合同基准里（E_PROGRESS_CONTRACT_MISSING）｜下一步：先补合同基准；补不了就单独确认这条清单的合同量和单价，不要直接计入本期`；或 `申报合同量 120 与合同基准 100 不符（E_PROGRESS_CONTRACT_MISMATCH）｜下一步：以合同基准为准改正申报；确需调整先办合同变更`
+- **原因**：新增清单没有进合同基准，或申报表里的合同量/单价与基准版本不一致。
+- **动作**：补齐或更新合同基准；`CONTRACT_MISSING` 时本包会回退用申报值计算并标问题，不能当作已核验。
+
+## 7. 累计小于本期（E_PROGRESS_QTY_INCONSISTENT）
+
+- **症状**：`累计完成量 10 小于本期完成量 20（E_PROGRESS_QTY_INCONSISTENT）｜下一步：核对上期累计数；累计完成量应当大于或等于本期完成量`
+- **原因**：上期累计结转错误，或本期完成量填成了合同量。
+- **动作**：核对上期已批累计；累计应 ≥ 本期。改完重新导入，不要手改已导出的底稿。
+
+## 8. 找不到这批申报（E_PROGRESS_BATCH_NOT_FOUND）
+
+- **症状**：`找不到这批申报（E_PROGRESS_BATCH_NOT_FOUND）｜下一步：先运行 progress.ingest 导入 CSV 拿到 batch_id，再运行 progress.audit 或 progress.export`
+- **原因**：`batch_id` 拼错，或换了会话/进程（批次只存在当前会话内存里）。
+- **动作**：重新运行 `progress.ingest` 拿到新的 `batch_id`，再做 `audit` / `export`。
+
+## 9. 审核参数不合法（E_PROGRESS_OPTION_INVALID）
+
+- **症状**：`审核参数不合法（E_PROGRESS_OPTION_INVALID）｜下一步：price_tolerance_bps 传 0 或正整数（单位：万分之一），不传表示 0`
+- **原因**：`price_tolerance_bps` 传了负数、NaN 或小数。
+- **动作**：不传（默认 0，精确比对）或传 `100`、`2000` 这样的非负整数。
+
+## 10. 导出文件名不安全 / 写不出去（E_PROGRESS_PATH_INVALID / E_PROGRESS_PATH_NOT_ALLOWED / E_PROGRESS_EXPORT_FAILED）
+
+- **症状**：`导出文件名不安全（E_PROGRESS_PATH_INVALID）｜下一步：只传一个由字母、数字、点、下划线或短横线组成的文件名`；或 `审核底稿没有写出去（E_PROGRESS_EXPORT_FAILED）`
+- **原因**：`filename` 带 `../`、`/`、反斜杠、空格、中文或超长；或 `$DSH_HOME/dsh-progress-payment` 只读 / 磁盘满。
+- **动作**：只传 `progress-audit-2026-10.csv` 这样的单文件名；确认 `$DSH_HOME` 可写（测试时设 `DSH_PROGRESS_PAYMENT_HOME` 到临时目录），不要删除用户数据来“修复”。
+
+## 还不行
+
+```sh
+node samples/quickstart/run.mjs --check   # 自带样例必须通过
+node --test test/*.test.mjs               # 32 项测试
+node scripts/gate.mjs                     # 元数据 + 验收门
+```
+
+仍失败时请在 <https://github.com/PerryLink/dsh-progress-payment/issues> 附上：包版本、最小合成申报
+（或生成脚本）、`progress.audit` 的完整报错行、Node 与 DSH 版本。**不要附真实合同或客户申报。**

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-progress-payment
+      name: 'dsh-progress-payment'

package/docs/assets/dsh-progress-payment-flow.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="220" viewBox="0 0 960 220" role="img" aria-label="dsh-progress-payment workflow">
+  <rect width="960" height="220" fill="#0d1117"/>
+  <g font-family="'Microsoft YaHei', 'PingFang SC', sans-serif" font-size="15" fill="#e6edf3">
+    <rect x="30" y="62" width="210" height="96" rx="12" fill="#161b22" stroke="#30363d"/>
+    <text x="48" y="94" font-size="16" font-weight="600">本期申报 CSV</text>
+    <text x="48" y="120" fill="#8b949e" font-size="13">7 列 · 6 个清单项</text>
+    <text x="48" y="140" fill="#8b949e" font-size="13">合成数据</text>
+
+    <rect x="300" y="62" width="210" height="96" rx="12" fill="#161b22" stroke="#58a6ff"/>
+    <text x="318" y="94" font-size="16" font-weight="600">progress.ingest</text>
+    <text x="318" y="120" fill="#8b949e" font-size="13">解析 · 校验表头</text>
+    <text x="318" y="140" fill="#8b949e" font-size="13">batch_id（会话内存）</text>
+
+    <rect x="570" y="62" width="210" height="96" rx="12" fill="#161b22" stroke="#f0b429"/>
+    <text x="588" y="94" font-size="16" font-weight="600">progress.audit</text>
+    <text x="588" y="120" fill="#8b949e" font-size="13">整数分金额 · 累计比例</text>
+    <text x="588" y="140" fill="#8b949e" font-size="13">超量 / 单价 / 重复项</text>
+
+    <rect x="840" y="62" width="90" height="96" rx="12" fill="#161b22" stroke="#3fb950"/>
+    <text x="856" y="94" font-size="16" font-weight="600">底稿</text>
+    <text x="856" y="120" fill="#8b949e" font-size="13">CSV</text>
+    <text x="856" y="140" fill="#8b949e" font-size="13">exports/</text>
+
+    <g stroke="#8b949e" stroke-width="2" fill="none">
+      <path d="M240 110h52" marker-end="url(#a)"/>
+      <path d="M510 110h52" marker-end="url(#a)"/>
+      <path d="M780 110h52" marker-end="url(#a)"/>
+    </g>
+    <text x="300" y="42" fill="#8b949e" font-size="13">合同基准 CSV（可选）→ 以基准为准</text>
+    <text x="570" y="42" fill="#8b949e" font-size="13">金额整数分 · 本地运行 · 不联网</text>
+  </g>
+  <defs>
+    <marker id="a" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+      <path d="M0 0l8 4-8 4z" fill="#8b949e"/>
+    </marker>
+  </defs>
+</svg>

package/docs/assets/quickstart.log

@@ -0,0 +1,14 @@
+$ node samples/quickstart/run.mjs --check
+dsh-progress-payment quickstart - synthetic progress declaration (not customer data)
+declaration: samples/quickstart/input/declaration-2026-10.csv (7 rows / 6 items)
+contract baseline: 6 items; batch pg_ea0edb1548cb530b
+period amount: 50763.60 CNY (declared 51627.60)
+cumulative: 614145.00 CNY / contract 725750.00 = 84.62%
+issues: 3 (over qty 1, price mismatch 1, duplicate 1)
+  row 4 010402001 E_PROGRESS_OVER_QTY 累计完成量 101.5 超过合同量 95
+  row 6 011702001 E_PROGRESS_PRICE_MISMATCH 申报合同单价 65.00 与合同基准 55.00 不符
+  row 7 010101003 E_PROGRESS_DUP_ITEM 清单编码 010101003 在本期申报里出现 2 次
+worksheet: exports/progress-audit-2026-10.csv 8 rows, 1291 bytes, sha256 24cca857d661...
+worksheet columns: 行号,清单编码,名称,单位,合同量,合同单价(元),本期完成量,累计完成量,本期金额(元),累计金额(元),累计比例(%),是否计入,问题代码,问题说明
+golden samples/quickstart/expected/result.json matches
+quickstart ok

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128" role="img" aria-label="Progress payment audit">
+  <rect width="128" height="128" rx="28" fill="#0b1020"/>
+  <rect x="10" y="10" width="108" height="108" rx="22" fill="#141b30" stroke="#f0b429" stroke-width="3"/>
+  <rect x="26" y="24" width="76" height="82" rx="8" fill="#f4f7ff" opacity="0.96"/>
+  <rect x="42" y="18" width="44" height="14" rx="5" fill="#f0b429"/>
+  <path d="M40 52h48M40 66h32M40 80h22" stroke="#6ea8fe" stroke-width="4" stroke-linecap="round"/>
+  <path d="M86 72l8 8 14-16" stroke="#1a7f37" stroke-width="5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/lib/core/csv.d.ts

@@ -0,0 +1,16 @@
+export declare function csvField(value: string): string;
+/** Build a UTF-8 CSV body with a trailing newline; empty input yields an empty string. */
+export declare function toCsv(rows: readonly (readonly string[])[]): string;
+/**
+ * Parse RFC 4180-style CSV: quoted fields, doubled quotes, embedded CR/LF and a
+ * UTF-8 BOM. Blank lines and rows whose every cell is empty are dropped. A
+ * quote that never closes is a row-level error (`E_PROGRESS_CSV_ROW`), not a
+ * silently truncated table.
+ */
+export declare function parseCsv(text: string): string[][];
+/** Normalise a header cell: trim, lower-case, drop spaces and a UTF-8 BOM. */
+export declare function normalizeHeader(value: string): string;
+/** Find the first alias present in the header row; -1 when the column is absent. */
+export declare function headerIndex(header: readonly string[], aliases: readonly string[]): number;
+/** Pad short rows to the header width; extra cells beyond the header are ignored. */
+export declare function cell(row: readonly string[], index: number): string;

package/lib/core/csv.js

@@ -0,0 +1,95 @@
+import { ProgressError } from './errors.js';
+/** RFC 4180 field escaping: quote on comma, quote, CR or LF and double embedded quotes. */
+const CSV_NEEDS_QUOTES = /[",\r\n]/;
+export function csvField(value) {
+    return CSV_NEEDS_QUOTES.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+/** Build a UTF-8 CSV body with a trailing newline; empty input yields an empty string. */
+export function toCsv(rows) {
+    if (rows.length === 0)
+        return '';
+    return `${rows.map((row) => row.map(csvField).join(',')).join('\n')}\n`;
+}
+/**
+ * Parse RFC 4180-style CSV: quoted fields, doubled quotes, embedded CR/LF and a
+ * UTF-8 BOM. Blank lines and rows whose every cell is empty are dropped. A
+ * quote that never closes is a row-level error (`E_PROGRESS_CSV_ROW`), not a
+ * silently truncated table.
+ */
+export function parseCsv(text) {
+    if (typeof text !== 'string')
+        throw new ProgressError('E_PROGRESS_CSV_ROW', 'CSV 内容不是文本');
+    const source = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    let index = 0;
+    while (index < source.length) {
+        const char = source[index];
+        if (inQuotes) {
+            if (char === '"') {
+                if (source[index + 1] === '"') {
+                    field += '"';
+                    index += 2;
+                    continue;
+                }
+                inQuotes = false;
+                index += 1;
+                continue;
+            }
+            field += char;
+            index += 1;
+            continue;
+        }
+        if (char === '"' && field === '') {
+            inQuotes = true;
+            index += 1;
+            continue;
+        }
+        if (char === ',') {
+            row.push(field);
+            field = '';
+            index += 1;
+            continue;
+        }
+        if (char === '\r') {
+            index += 1;
+            continue;
+        }
+        if (char === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            index += 1;
+            continue;
+        }
+        field += char;
+        index += 1;
+    }
+    if (inQuotes)
+        throw new ProgressError('E_PROGRESS_CSV_ROW', 'CSV 里有引号没有闭合');
+    if (field !== '' || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows.filter((cells) => cells.some((cell) => cell.trim() !== ''));
+}
+/** Normalise a header cell: trim, lower-case, drop spaces and a UTF-8 BOM. */
+export function normalizeHeader(value) {
+    return value.replace(/^\uFEFF/, '').trim().toLowerCase().replace(/\s+/g, '');
+}
+/** Find the first alias present in the header row; -1 when the column is absent. */
+export function headerIndex(header, aliases) {
+    for (const alias of aliases) {
+        const index = header.indexOf(normalizeHeader(alias));
+        if (index >= 0)
+            return index;
+    }
+    return -1;
+}
+/** Pad short rows to the header width; extra cells beyond the header are ignored. */
+export function cell(row, index) {
+    return index >= 0 ? (row[index] ?? '').trim() : '';
+}

package/lib/core/errors.d.ts

@@ -0,0 +1,8 @@
+/** Every user-facing failure is a stable code plus one human sentence and one next action. */
+export type ProgressErrorCode = 'E_PROGRESS_CSV_EMPTY' | 'E_PROGRESS_CSV_ROW' | 'E_PROGRESS_BATCH_NOT_FOUND' | 'E_PROGRESS_OPTION_INVALID' | 'E_PROGRESS_PATH_INVALID' | 'E_PROGRESS_PATH_NOT_ALLOWED' | 'E_PROGRESS_EXPORT_FAILED';
+/** `human sentence（E_CODE）｜Next: one action｜detail` — the only text shown to end users. */
+export declare function progressErrorMessage(code: ProgressErrorCode, detail?: string): string;
+export declare class ProgressError extends Error {
+    readonly code: ProgressErrorCode;
+    constructor(code: ProgressErrorCode, detail?: string);
+}

package/lib/core/errors.js

@@ -0,0 +1,43 @@
+const PROGRESS_HUMAN = {
+    E_PROGRESS_CSV_EMPTY: {
+        text: '这个 CSV 是空的，既没有表头也没有数据',
+        next: '确认文件不是 0 字节，并且第一行是表头、后面至少有一行数据',
+    },
+    E_PROGRESS_CSV_ROW: {
+        text: '申报或合同 CSV 的表头/某一行读不懂',
+        next: '按 README 的列名补齐表头；数量写纯数字（最多 3 位小数），单价写金额（最多 2 位小数），不要带单位',
+    },
+    E_PROGRESS_BATCH_NOT_FOUND: {
+        text: '找不到这批申报',
+        next: '先运行 progress.ingest 导入 CSV 拿到 batch_id，再运行 progress.audit 或 progress.export',
+    },
+    E_PROGRESS_OPTION_INVALID: {
+        text: '审核参数不合法',
+        next: 'price_tolerance_bps 传 0 或正整数（单位：万分之一），不传表示 0',
+    },
+    E_PROGRESS_PATH_INVALID: {
+        text: '导出文件名不安全',
+        next: '只传一个由字母、数字、点、下划线或短横线组成的文件名，例如 progress-2026-10.csv',
+    },
+    E_PROGRESS_PATH_NOT_ALLOWED: {
+        text: '导出路径越过了导出目录',
+        next: '只传一个文件名，不要带 ../、目录分隔符或符号链接',
+    },
+    E_PROGRESS_EXPORT_FAILED: {
+        text: '审核底稿没有写出去',
+        next: '确认 $DSH_HOME/dsh-progress-payment 指向可写目录后重试',
+    },
+};
+/** `human sentence（E_CODE）｜Next: one action｜detail` — the only text shown to end users. */
+export function progressErrorMessage(code, detail) {
+    const human = PROGRESS_HUMAN[code];
+    return `${human.text}（${code}）｜下一步：${human.next}${detail ? `｜细节：${detail}` : ''}`;
+}
+export class ProgressError extends Error {
+    code;
+    constructor(code, detail) {
+        super(progressErrorMessage(code, detail));
+        this.name = 'ProgressError';
+        this.code = code;
+    }
+}

package/lib/core/money.d.ts

@@ -0,0 +1,16 @@
+/** 1 unit of quantity is stored as 1000 milli-units; money is stored as integer cents. */
+export declare const QTY_SCALE = 1000;
+/** Parse a decimal amount into integer cents. Negative amounts and >2 decimals are rejected. */
+export declare function parseCents(raw: string, field: string, row: number): number;
+/** Parse a decimal quantity into integer milli-units (3 decimals). Negative quantities are rejected. */
+export declare function parseQtyMilli(raw: string, field: string, row: number): number;
+/** Quantity x contract unit price, rounded half-up to whole cents. */
+export declare function amountCents(qtyMilli: number, unitPriceCents: number): number;
+/** Format integer cents as `1234.56` (always two decimals). */
+export declare function formatCents(cents: number): string;
+/** Format integer milli-units as a compact decimal: `25.92`, `4.2`, `300`. */
+export declare function formatQty(milli: number): string;
+/** Percentage with two decimals; a non-positive total yields 0 instead of Infinity. */
+export declare function ratioPct(part: number, total: number): number;
+/** Absolute price tolerance in cents for a basis-point setting (0 bps = exact). */
+export declare function priceToleranceCents(contractPriceCents: number, bps: number): number;

package/lib/core/money.js

@@ -0,0 +1,69 @@
+import { ProgressError } from './errors.js';
+/** 1 unit of quantity is stored as 1000 milli-units; money is stored as integer cents. */
+export const QTY_SCALE = 1000;
+const MONEY = /^(\d+)(?:\.(\d{1,2}))?$/;
+const QTY = /^(\d+)(?:\.(\d{1,3}))?$/;
+function cleanNumber(raw) {
+    return String(raw).trim().replace(/[¥￥,\s]/g, '');
+}
+/** Parse a decimal amount into integer cents. Negative amounts and >2 decimals are rejected. */
+export function parseCents(raw, field, row) {
+    const value = cleanNumber(raw);
+    if (value === '')
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field} 为空`);
+    const match = MONEY.exec(value);
+    if (!match)
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field}=${JSON.stringify(raw)} 不是金额`);
+    const cents = Number(match[1]) * 100 + Number((match[2] ?? '').padEnd(2, '0'));
+    if (!Number.isSafeInteger(cents))
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field}=${JSON.stringify(raw)} 太大`);
+    return cents;
+}
+/** Parse a decimal quantity into integer milli-units (3 decimals). Negative quantities are rejected. */
+export function parseQtyMilli(raw, field, row) {
+    const value = cleanNumber(raw);
+    if (value === '')
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field} 为空`);
+    const match = QTY.exec(value);
+    if (!match)
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field}=${JSON.stringify(raw)} 不是数量`);
+    const milli = Number(match[1]) * QTY_SCALE + Number((match[2] ?? '').padEnd(3, '0'));
+    if (!Number.isSafeInteger(milli))
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field}=${JSON.stringify(raw)} 太大`);
+    return milli;
+}
+/** Quantity x contract unit price, rounded half-up to whole cents. */
+export function amountCents(qtyMilli, unitPriceCents) {
+    const raw = qtyMilli * unitPriceCents;
+    if (!Number.isSafeInteger(raw))
+        throw new ProgressError('E_PROGRESS_CSV_ROW', '金额超出可安全计算的范围');
+    return Math.round(raw / QTY_SCALE);
+}
+/** Format integer cents as `1234.56` (always two decimals). */
+export function formatCents(cents) {
+    const sign = cents < 0 ? '-' : '';
+    const abs = Math.abs(cents);
+    return `${sign}${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;
+}
+/** Format integer milli-units as a compact decimal: `25.92`, `4.2`, `300`. */
+export function formatQty(milli) {
+    const sign = milli < 0 ? '-' : '';
+    const abs = Math.abs(milli);
+    const whole = Math.floor(abs / QTY_SCALE);
+    const fraction = abs % QTY_SCALE;
+    if (fraction === 0)
+        return `${sign}${whole}`;
+    return `${sign}${whole}.${String(fraction).padStart(3, '0').replace(/0+$/, '')}`;
+}
+/** Percentage with two decimals; a non-positive total yields 0 instead of Infinity. */
+export function ratioPct(part, total) {
+    if (!Number.isFinite(part) || !Number.isFinite(total) || total <= 0)
+        return 0;
+    return Math.round((part * 10000) / total) / 100;
+}
+/** Absolute price tolerance in cents for a basis-point setting (0 bps = exact). */
+export function priceToleranceCents(contractPriceCents, bps) {
+    if (!Number.isFinite(bps) || bps <= 0)
+        return 0;
+    return Math.round((contractPriceCents * bps) / 10000);
+}

package/lib/core/progress.d.ts

@@ -0,0 +1,127 @@
+/** One declaration line exactly as parsed from the CSV (row = 1-based data row). */
+export interface DeclarationRow {
+    row: number;
+    item_code: string;
+    item_name: string;
+    unit: string;
+    contract_qty_milli: number;
+    contract_unit_price_cents: number;
+    period_qty_milli: number;
+    cumulative_qty_milli: number;
+}
+/** One contract-baseline line. Quantities and prices are authoritative for the audit. */
+export interface ContractRow {
+    item_code: string;
+    item_name: string;
+    unit: string;
+    contract_qty_milli: number;
+    contract_unit_price_cents: number;
+}
+export interface ProgressBatch {
+    batch_id: string;
+    source_name: string;
+    declaration_sha256: string;
+    contract_sha256: string | null;
+    rows: DeclarationRow[];
+    contract: ContractRow[] | null;
+}
+export type ProgressIssueCode = 'E_PROGRESS_OVER_QTY' | 'E_PROGRESS_PRICE_MISMATCH' | 'E_PROGRESS_DUP_ITEM' | 'E_PROGRESS_CONTRACT_MISSING' | 'E_PROGRESS_CONTRACT_MISMATCH' | 'E_PROGRESS_QTY_INCONSISTENT';
+export type ProgressIssue = {
+    row: number;
+    item_code: string;
+    item_name: string;
+    code: ProgressIssueCode;
+    kind: string;
+    field: string;
+    message: string;
+    blocking: boolean;
+};
+export type AuditItem = {
+    row: number;
+    item_code: string;
+    item_name: string;
+    unit: string;
+    declared_contract_qty: number;
+    declared_contract_unit_price_cents: number;
+    contract_qty: number;
+    contract_unit_price_cents: number;
+    period_qty: number;
+    cumulative_qty: number;
+    period_amount_cents: number;
+    declared_period_amount_cents: number;
+    cumulative_amount_cents: number;
+    contract_amount_cents: number;
+    cumulative_ratio_pct: number;
+    issue_codes: ProgressIssueCode[];
+};
+export type AuditSummary = {
+    items: number;
+    rows: number;
+    duplicate_rows: number;
+    contract_items: number;
+    period_amount_cents: number;
+    declared_period_amount_cents: number;
+    price_adjustment_cents: number;
+    cumulative_amount_cents: number;
+    contract_amount_cents: number;
+    cumulative_ratio_pct: number;
+    issues: number;
+    blocking_issues: number;
+    over_qty: number;
+    price_mismatch: number;
+    duplicate_items: number;
+    contract_missing: number;
+    contract_mismatch: number;
+    qty_inconsistent: number;
+    status: 'ok' | 'needs_review';
+};
+export type AuditResult = {
+    batch_id: string;
+    currency: string;
+    items: AuditItem[];
+    issues: ProgressIssue[];
+    summary: AuditSummary;
+};
+export type IngestSummary = {
+    batch_id: string;
+    rows: number;
+    items: number;
+    contract_items: number;
+    declaration_sha256: string;
+    contract_sha256?: string;
+};
+/** Parse the current-period declaration CSV. Column order is free; Chinese and English headers both work. */
+export declare function parseDeclarationCsv(text: string): DeclarationRow[];
+/** Parse the contract baseline CSV: item code, contract quantity, contract unit price. */
+export declare function parseContractCsv(text: string): ContractRow[];
+/** Parse and store one declaration batch. The batch id is deterministic for the same CSV pair. */
+export declare function ingestDeclaration(declarationCsv: string, contractCsv?: string, sourceName?: string): {
+    batch: ProgressBatch;
+    summary: IngestSummary;
+};
+/** Audit one stored batch: amounts in integer cents, cumulative ratio, over-quantity, price and duplicate checks. */
+export declare function auditBatch(batch: ProgressBatch, options?: {
+    price_tolerance_bps?: number;
+}): AuditResult;
+export interface WorksheetRow {
+    row: number;
+    item_code: string;
+    item_name: string;
+    unit: string;
+    contract_qty: number;
+    contract_unit_price_cents: number;
+    period_qty: number;
+    cumulative_qty: number;
+    period_amount_cents: number;
+    cumulative_amount_cents: number;
+    cumulative_ratio_pct: number;
+    counted: boolean;
+    issue_codes: ProgressIssueCode[];
+    issue_text: string;
+}
+/** Build one worksheet row per declaration line; repeated item codes are marked counted=false. */
+export declare function buildWorksheet(batch: ProgressBatch, audit: AuditResult, options?: {
+    price_tolerance_bps?: number;
+}): WorksheetRow[];
+/** Human sentence for one audit result; used by tool renderers and the quickstart. */
+export declare function auditSentence(audit: AuditResult): string;