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

package/lib/core/progress.js

@@ -0,0 +1,372 @@
+import { createHash } from 'node:crypto';
+import { cell, headerIndex, normalizeHeader, parseCsv } from './csv.js';
+import { ProgressError } from './errors.js';
+import { amountCents, formatCents, formatQty, parseCents, parseQtyMilli, priceToleranceCents, ratioPct, } from './money.js';
+const DECLARATION_COLUMNS = {
+    item_code: ['item_code', 'code', '清单编码', '项目编码'],
+    item_name: ['item_name', 'name', '名称', '项目名称'],
+    unit: ['unit', '单位', '计量单位'],
+    contract_qty: ['contract_qty', '合同量', '合同数量'],
+    contract_unit_price: ['contract_unit_price', 'contract_price', '合同单价'],
+    period_qty: ['period_qty', '本期完成量', '本期工程量'],
+    cumulative_qty: ['cumulative_qty', '累计完成量', '累计工程量'],
+};
+const CONTRACT_COLUMNS = {
+    item_code: ['item_code', 'code', '清单编码', '项目编码'],
+    contract_qty: ['contract_qty', '合同量', '合同数量'],
+    contract_unit_price: ['contract_unit_price', 'contract_price', '合同单价'],
+};
+const CONTRACT_OPTIONAL_COLUMNS = {
+    item_name: ['item_name', 'name', '名称', '项目名称'],
+    unit: ['unit', '单位', '计量单位'],
+};
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function readTable(text, label) {
+    if (typeof text !== 'string' || text.trim() === '')
+        throw new ProgressError('E_PROGRESS_CSV_EMPTY', label);
+    const parsed = parseCsv(text);
+    if (parsed.length === 0)
+        throw new ProgressError('E_PROGRESS_CSV_EMPTY', label);
+    const header = parsed[0].map(normalizeHeader);
+    const rows = parsed.slice(1);
+    if (rows.length === 0)
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `${label} 只有表头，没有数据行`);
+    return { header, rows };
+}
+function requireColumns(header, columns, label) {
+    const index = {};
+    const missing = [];
+    for (const [key, aliases] of Object.entries(columns)) {
+        const found = headerIndex(header, aliases);
+        index[key] = found;
+        if (found < 0)
+            missing.push(aliases[0]);
+    }
+    if (missing.length > 0) {
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `${label} 缺少列：${missing.join('、')}；表头是：${header.join('、') || '空'}`);
+    }
+    return index;
+}
+function requireText(value, field, row) {
+    if (value === '')
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field} 为空`);
+    return value;
+}
+function requirePositiveQty(value, field, row) {
+    if (value <= 0)
+        throw new ProgressError('E_PROGRESS_CSV_ROW', `第 ${row} 行 ${field} 必须大于 0`);
+    return value;
+}
+/** Parse the current-period declaration CSV. Column order is free; Chinese and English headers both work. */
+export function parseDeclarationCsv(text) {
+    const { header, rows } = readTable(text, '申报 CSV');
+    const index = requireColumns(header, DECLARATION_COLUMNS, '申报 CSV');
+    return rows.map((cells, offset) => {
+        const row = offset + 1;
+        const itemCode = requireText(cell(cells, index.item_code), '清单编码', row);
+        const itemName = requireText(cell(cells, index.item_name), '名称', row);
+        const unit = requireText(cell(cells, index.unit), '单位', row);
+        const contractQty = requirePositiveQty(parseQtyMilli(cell(cells, index.contract_qty), '合同量', row), '合同量', row);
+        const contractPrice = parseCents(cell(cells, index.contract_unit_price), '合同单价', row);
+        const periodQty = parseQtyMilli(cell(cells, index.period_qty), '本期完成量', row);
+        const cumulativeQty = parseQtyMilli(cell(cells, index.cumulative_qty), '累计完成量', row);
+        return {
+            row,
+            item_code: itemCode,
+            item_name: itemName,
+            unit,
+            contract_qty_milli: contractQty,
+            contract_unit_price_cents: contractPrice,
+            period_qty_milli: periodQty,
+            cumulative_qty_milli: cumulativeQty,
+        };
+    });
+}
+/** Parse the contract baseline CSV: item code, contract quantity, contract unit price. */
+export function parseContractCsv(text) {
+    const { header, rows } = readTable(text, '合同基准 CSV');
+    const index = requireColumns(header, CONTRACT_COLUMNS, '合同基准 CSV');
+    const optional = Object.fromEntries(Object.entries(CONTRACT_OPTIONAL_COLUMNS).map(([key, aliases]) => [key, headerIndex(header, aliases)]));
+    const seen = new Set();
+    return rows.map((cells, offset) => {
+        const row = offset + 1;
+        const itemCode = requireText(cell(cells, index.item_code), '清单编码', row);
+        if (seen.has(itemCode)) {
+            throw new ProgressError('E_PROGRESS_CSV_ROW', `合同基准第 ${row} 行清单编码 ${itemCode} 重复；合同基准必须一条清单一行`);
+        }
+        seen.add(itemCode);
+        const contractQty = requirePositiveQty(parseQtyMilli(cell(cells, index.contract_qty), '合同量', row), '合同量', row);
+        return {
+            item_code: itemCode,
+            item_name: cell(cells, optional.item_name ?? -1),
+            unit: cell(cells, optional.unit ?? -1),
+            contract_qty_milli: contractQty,
+            contract_unit_price_cents: parseCents(cell(cells, index.contract_unit_price), '合同单价', row),
+        };
+    });
+}
+/** Parse and store one declaration batch. The batch id is deterministic for the same CSV pair. */
+export function ingestDeclaration(declarationCsv, contractCsv, sourceName = 'declaration.csv') {
+    const rows = parseDeclarationCsv(declarationCsv);
+    const contract = contractCsv === undefined ? null : parseContractCsv(contractCsv);
+    const declarationSha = sha256(declarationCsv);
+    const contractSha = contractCsv === undefined ? null : sha256(contractCsv);
+    const batchId = `pg_${sha256(`${declarationSha}\u0000${contractSha ?? ''}`).slice(0, 16)}`;
+    const items = new Set(rows.map((row) => row.item_code)).size;
+    const batch = {
+        batch_id: batchId,
+        source_name: sourceName,
+        declaration_sha256: declarationSha,
+        contract_sha256: contractSha,
+        rows,
+        contract,
+    };
+    return {
+        batch,
+        summary: {
+            batch_id: batchId,
+            rows: rows.length,
+            items,
+            contract_items: contract?.length ?? 0,
+            declaration_sha256: declarationSha,
+            contract_sha256: contractSha ?? undefined,
+        },
+    };
+}
+const units = (milli) => milli / 1000;
+function issueMessage(code, text, next) {
+    return `${text}（${code}）｜下一步：${next}`;
+}
+function resolveRow(row, contractMap, toleranceBps) {
+    const drafts = [];
+    let contractQty = row.contract_qty_milli;
+    let contractPrice = row.contract_unit_price_cents;
+    const baseline = contractMap?.get(row.item_code);
+    if (contractMap) {
+        if (!baseline) {
+            drafts.push({
+                code: 'E_PROGRESS_CONTRACT_MISSING',
+                kind: 'contract_missing',
+                field: 'item_code',
+                message: issueMessage('E_PROGRESS_CONTRACT_MISSING', `清单编码 ${row.item_code} 不在合同基准里`, '先补合同基准；补不了就单独确认这条清单的合同量和单价，不要直接计入本期'),
+                blocking: true,
+            });
+        }
+        else {
+            contractQty = baseline.contract_qty_milli;
+            contractPrice = baseline.contract_unit_price_cents;
+            if (row.contract_qty_milli !== baseline.contract_qty_milli) {
+                drafts.push({
+                    code: 'E_PROGRESS_CONTRACT_MISMATCH',
+                    kind: 'contract_qty_mismatch',
+                    field: 'contract_qty',
+                    message: issueMessage('E_PROGRESS_CONTRACT_MISMATCH', `申报合同量 ${formatQty(row.contract_qty_milli)} 与合同基准 ${formatQty(baseline.contract_qty_milli)} 不符`, '以合同基准为准改正申报；确需调整先办合同变更'),
+                    blocking: true,
+                });
+            }
+            const tolerance = priceToleranceCents(baseline.contract_unit_price_cents, toleranceBps);
+            if (Math.abs(row.contract_unit_price_cents - baseline.contract_unit_price_cents) > tolerance) {
+                drafts.push({
+                    code: 'E_PROGRESS_PRICE_MISMATCH',
+                    kind: 'price_mismatch',
+                    field: 'contract_unit_price',
+                    message: issueMessage('E_PROGRESS_PRICE_MISMATCH', `申报合同单价 ${formatCents(row.contract_unit_price_cents)} 与合同基准 ${formatCents(baseline.contract_unit_price_cents)} 不符`, `本期金额按合同单价 ${formatCents(baseline.contract_unit_price_cents)} 重算，并要求申报方改正`),
+                    blocking: true,
+                });
+            }
+        }
+    }
+    if (row.cumulative_qty_milli < row.period_qty_milli) {
+        drafts.push({
+            code: 'E_PROGRESS_QTY_INCONSISTENT',
+            kind: 'cumulative_below_period',
+            field: 'cumulative_qty',
+            message: issueMessage('E_PROGRESS_QTY_INCONSISTENT', `累计完成量 ${formatQty(row.cumulative_qty_milli)} 小于本期完成量 ${formatQty(row.period_qty_milli)}`, '核对上期累计数；累计完成量应当大于或等于本期完成量'),
+            blocking: true,
+        });
+    }
+    if (row.period_qty_milli > contractQty) {
+        drafts.push({
+            code: 'E_PROGRESS_OVER_QTY',
+            kind: 'period_over_contract',
+            field: 'period_qty',
+            message: issueMessage('E_PROGRESS_OVER_QTY', `本期完成量 ${formatQty(row.period_qty_milli)} 超过合同量 ${formatQty(contractQty)}`, '核对合同量和变更签证；超过合同量的部分不得计入本期'),
+            blocking: true,
+        });
+    }
+    if (row.cumulative_qty_milli > contractQty) {
+        drafts.push({
+            code: 'E_PROGRESS_OVER_QTY',
+            kind: 'cumulative_over_contract',
+            field: 'cumulative_qty',
+            message: issueMessage('E_PROGRESS_OVER_QTY', `累计完成量 ${formatQty(row.cumulative_qty_milli)} 超过合同量 ${formatQty(contractQty)}`, '核对合同量和变更签证；超量部分走变更或结算，不在本期支付'),
+            blocking: true,
+        });
+    }
+    const periodAmount = amountCents(row.period_qty_milli, contractPrice);
+    const cumulativeAmount = amountCents(row.cumulative_qty_milli, contractPrice);
+    const contractAmount = amountCents(contractQty, contractPrice);
+    return {
+        item_code: row.item_code,
+        item_name: row.item_name,
+        unit: row.unit,
+        declared_contract_qty_milli: row.contract_qty_milli,
+        declared_contract_unit_price_cents: row.contract_unit_price_cents,
+        contract_qty_milli: contractQty,
+        contract_unit_price_cents: contractPrice,
+        period_qty_milli: row.period_qty_milli,
+        cumulative_qty_milli: row.cumulative_qty_milli,
+        period_amount_cents: periodAmount,
+        declared_period_amount_cents: amountCents(row.period_qty_milli, row.contract_unit_price_cents),
+        cumulative_amount_cents: cumulativeAmount,
+        contract_amount_cents: contractAmount,
+        cumulative_ratio_pct: ratioPct(cumulativeAmount, contractAmount),
+        issues: drafts,
+    };
+}
+/** Audit one stored batch: amounts in integer cents, cumulative ratio, over-quantity, price and duplicate checks. */
+export function auditBatch(batch, options = {}) {
+    const toleranceBps = options.price_tolerance_bps ?? 0;
+    if (!Number.isFinite(toleranceBps) || toleranceBps < 0) {
+        throw new ProgressError('E_PROGRESS_OPTION_INVALID', `price_tolerance_bps=${toleranceBps}`);
+    }
+    const contractMap = batch.contract ? new Map(batch.contract.map((row) => [row.item_code, row])) : null;
+    const firstRows = new Map();
+    const counts = new Map();
+    for (const row of batch.rows) {
+        if (!firstRows.has(row.item_code))
+            firstRows.set(row.item_code, row);
+        const bucket = counts.get(row.item_code) ?? [];
+        bucket.push(row);
+        counts.set(row.item_code, bucket);
+    }
+    const items = [];
+    const issues = [];
+    for (const row of firstRows.values()) {
+        const resolved = resolveRow(row, contractMap, toleranceBps);
+        for (const draft of resolved.issues) {
+            issues.push({
+                row: row.row,
+                item_code: resolved.item_code,
+                item_name: resolved.item_name,
+                code: draft.code,
+                kind: draft.kind,
+                field: draft.field,
+                message: draft.message,
+                blocking: draft.blocking,
+            });
+        }
+        items.push({
+            row: row.row,
+            item_code: resolved.item_code,
+            item_name: resolved.item_name,
+            unit: resolved.unit,
+            declared_contract_qty: units(resolved.declared_contract_qty_milli),
+            declared_contract_unit_price_cents: resolved.declared_contract_unit_price_cents,
+            contract_qty: units(resolved.contract_qty_milli),
+            contract_unit_price_cents: resolved.contract_unit_price_cents,
+            period_qty: units(resolved.period_qty_milli),
+            cumulative_qty: units(resolved.cumulative_qty_milli),
+            period_amount_cents: resolved.period_amount_cents,
+            declared_period_amount_cents: resolved.declared_period_amount_cents,
+            cumulative_amount_cents: resolved.cumulative_amount_cents,
+            contract_amount_cents: resolved.contract_amount_cents,
+            cumulative_ratio_pct: resolved.cumulative_ratio_pct,
+            issue_codes: resolved.issues.map((draft) => draft.code),
+        });
+    }
+    let duplicateRows = 0;
+    for (const [code, rows] of counts) {
+        if (rows.length < 2)
+            continue;
+        duplicateRows += rows.length - 1;
+        const message = issueMessage('E_PROGRESS_DUP_ITEM', `清单编码 ${code} 在本期申报里出现 ${rows.length} 次（行 ${rows.map((row) => row.row).join('、')}）`, '确认哪一行是本期应报的；重复行不计入本期金额');
+        issues.push({
+            row: rows[1].row,
+            item_code: code,
+            item_name: rows[1].item_name,
+            code: 'E_PROGRESS_DUP_ITEM',
+            kind: 'duplicate_item',
+            field: 'item_code',
+            message,
+            blocking: true,
+        });
+    }
+    issues.sort((left, right) => left.row - right.row || left.code.localeCompare(right.code) || left.kind.localeCompare(right.kind));
+    for (const item of items)
+        item.issue_codes = [...new Set(item.issue_codes)].sort();
+    const periodAmount = items.reduce((total, item) => total + item.period_amount_cents, 0);
+    const declaredPeriodAmount = items.reduce((total, item) => total + item.declared_period_amount_cents, 0);
+    const cumulativeAmount = items.reduce((total, item) => total + item.cumulative_amount_cents, 0);
+    const contractAmount = items.reduce((total, item) => total + item.contract_amount_cents, 0);
+    const countCode = (code) => issues.filter((issue) => issue.code === code).length;
+    return {
+        batch_id: batch.batch_id,
+        currency: 'CNY',
+        items,
+        issues,
+        summary: {
+            items: items.length,
+            rows: batch.rows.length,
+            duplicate_rows: duplicateRows,
+            contract_items: batch.contract?.length ?? 0,
+            period_amount_cents: periodAmount,
+            declared_period_amount_cents: declaredPeriodAmount,
+            price_adjustment_cents: periodAmount - declaredPeriodAmount,
+            cumulative_amount_cents: cumulativeAmount,
+            contract_amount_cents: contractAmount,
+            cumulative_ratio_pct: ratioPct(cumulativeAmount, contractAmount),
+            issues: issues.length,
+            blocking_issues: issues.filter((issue) => issue.blocking).length,
+            over_qty: countCode('E_PROGRESS_OVER_QTY'),
+            price_mismatch: countCode('E_PROGRESS_PRICE_MISMATCH'),
+            duplicate_items: countCode('E_PROGRESS_DUP_ITEM'),
+            contract_missing: countCode('E_PROGRESS_CONTRACT_MISSING'),
+            contract_mismatch: countCode('E_PROGRESS_CONTRACT_MISMATCH'),
+            qty_inconsistent: countCode('E_PROGRESS_QTY_INCONSISTENT'),
+            status: issues.length === 0 ? 'ok' : 'needs_review',
+        },
+    };
+}
+/** Build one worksheet row per declaration line; repeated item codes are marked counted=false. */
+export function buildWorksheet(batch, audit, options = {}) {
+    const contractMap = batch.contract ? new Map(batch.contract.map((row) => [row.item_code, row])) : null;
+    const seen = new Set();
+    const toleranceBps = options.price_tolerance_bps ?? 0;
+    return batch.rows.map((row) => {
+        const duplicate = seen.has(row.item_code);
+        seen.add(row.item_code);
+        const resolved = resolveRow(row, contractMap, toleranceBps);
+        const codes = resolved.issues.map((draft) => draft.code);
+        if (duplicate)
+            codes.push('E_PROGRESS_DUP_ITEM');
+        const uniqueCodes = [...new Set(codes)].sort();
+        const messages = resolved.issues.map((draft) => draft.message);
+        if (duplicate) {
+            messages.push(issueMessage('E_PROGRESS_DUP_ITEM', `清单编码 ${row.item_code} 在本期申报里重复出现`, '确认哪一行是本期应报的；重复行不计入本期金额'));
+        }
+        return {
+            row: row.row,
+            item_code: row.item_code,
+            item_name: row.item_name,
+            unit: row.unit,
+            contract_qty: units(resolved.contract_qty_milli),
+            contract_unit_price_cents: resolved.contract_unit_price_cents,
+            period_qty: units(resolved.period_qty_milli),
+            cumulative_qty: units(resolved.cumulative_qty_milli),
+            period_amount_cents: resolved.period_amount_cents,
+            cumulative_amount_cents: resolved.cumulative_amount_cents,
+            cumulative_ratio_pct: resolved.cumulative_ratio_pct,
+            counted: !duplicate,
+            issue_codes: uniqueCodes,
+            issue_text: messages.join('；'),
+        };
+    });
+}
+/** Human sentence for one audit result; used by tool renderers and the quickstart. */
+export function auditSentence(audit) {
+    const { summary } = audit;
+    return `进度款审核：${summary.items} 个清单项，本期 ${formatCents(summary.period_amount_cents)} CNY，累计 ${formatCents(summary.cumulative_amount_cents)} CNY（${summary.cumulative_ratio_pct}%），${summary.issues} 个问题`;
+}

package/lib/core/safe-path.d.ts

@@ -0,0 +1,12 @@
+/** A single export filename component: no separators, no whitespace, max 120 chars. */
+export declare const SAFE_EXPORT_FILENAME: RegExp;
+/**
+ * Resolve a caller-supplied export filename inside a base directory.
+ *
+ * 1. the filename must be one safe component (`[A-Za-z0-9._-]{1,120}`);
+ * 2. the resolved path must stay below `resolve(baseDir) + sep`;
+ * 3. the directory is created with `mkdir -p` and the path is re-anchored on
+ *    `realpath(baseDir)` so a symlinked directory cannot redirect the write
+ *    outside the canonical base.
+ */
+export declare function safeExportPath(baseDir: string, filename: string): Promise<string>;

package/lib/core/safe-path.js

@@ -0,0 +1,31 @@
+import { mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { ProgressError } from './errors.js';
+/** A single export filename component: no separators, no whitespace, max 120 chars. */
+export const SAFE_EXPORT_FILENAME = /^[A-Za-z0-9._-]{1,120}$/;
+/**
+ * Resolve a caller-supplied export filename inside a base directory.
+ *
+ * 1. the filename must be one safe component (`[A-Za-z0-9._-]{1,120}`);
+ * 2. the resolved path must stay below `resolve(baseDir) + sep`;
+ * 3. the directory is created with `mkdir -p` and the path is re-anchored on
+ *    `realpath(baseDir)` so a symlinked directory cannot redirect the write
+ *    outside the canonical base.
+ */
+export async function safeExportPath(baseDir, filename) {
+    if (typeof filename !== 'string' || !SAFE_EXPORT_FILENAME.test(filename)) {
+        throw new ProgressError('E_PROGRESS_PATH_INVALID', `unsafe export filename: ${JSON.stringify(filename)}`);
+    }
+    const base = path.resolve(baseDir);
+    const candidate = path.resolve(base, filename);
+    if (!candidate.startsWith(base + path.sep)) {
+        throw new ProgressError('E_PROGRESS_PATH_NOT_ALLOWED', `export path escapes base directory: ${JSON.stringify(filename)}`);
+    }
+    await mkdir(base, { recursive: true });
+    const realBase = await realpath(base);
+    const realCandidate = path.resolve(realBase, filename);
+    if (!realCandidate.startsWith(realBase + path.sep)) {
+        throw new ProgressError('E_PROGRESS_PATH_NOT_ALLOWED', `export path escapes base directory after realpath: ${JSON.stringify(filename)}`);
+    }
+    return realCandidate;
+}

package/lib/plugin/index.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProgressBatch } from '../core/progress.js';
+export declare const name = "dsh-progress-payment";
+export declare const inject: string[];
+/** Local write root: `$DSH_PROGRESS_PAYMENT_HOME`, else `$DSH_HOME/dsh-progress-payment`. */
+export declare function resolveBaseDir(env?: NodeJS.ProcessEnv): string;
+/** Session-scoped batch table; tests may inject their own Map-backed implementation. */
+export declare function createBatchTable(): {
+    get(key: string): ProgressBatch | undefined;
+    put(key: string, value: ProgressBatch): void;
+};
+export declare function apply(ctx: Context): Promise<void>;

package/lib/plugin/index.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { createTools } from './tools.js';
+export const name = 'dsh-progress-payment';
+export const inject = ['tools'];
+/** Local write root: `$DSH_PROGRESS_PAYMENT_HOME`, else `$DSH_HOME/dsh-progress-payment`. */
+export function resolveBaseDir(env = process.env) {
+    const override = env.DSH_PROGRESS_PAYMENT_HOME?.trim();
+    if (override)
+        return override;
+    const dshHome = env.DSH_HOME?.trim();
+    return path.join(dshHome || process.cwd(), 'dsh-progress-payment');
+}
+/** Session-scoped batch table; tests may inject their own Map-backed implementation. */
+export function createBatchTable() {
+    const map = new Map();
+    return {
+        get: (key) => map.get(key),
+        put: (key, value) => {
+            map.set(key, value);
+        },
+    };
+}
+export async function apply(ctx) {
+    for (const tool of createTools({ batches: createBatchTable(), baseDir: resolveBaseDir() }))
+        ctx.tools.register(tool);
+}

package/lib/plugin/tools.d.ts

@@ -0,0 +1,12 @@
+import { type ProgressBatch } from '../core/progress.js';
+export interface BatchTable {
+    get(key: string): ProgressBatch | undefined;
+    put(key: string, value: ProgressBatch): void | Promise<void>;
+}
+export interface ToolDeps {
+    /** Session-scoped batch table; the plugin creates one per apply(). */
+    batches: BatchTable;
+    /** Local write root; the plugin uses `$DSH_HOME/dsh-progress-payment`. */
+    baseDir: string;
+}
+export declare function createTools(deps: ToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition[];

package/lib/plugin/tools.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { toCsv } from '../core/csv.js';
+import { ProgressError } from '../core/errors.js';
+import { formatCents } from '../core/money.js';
+import { auditBatch, auditSentence, buildWorksheet, ingestDeclaration, } from '../core/progress.js';
+import { safeExportPath } from '../core/safe-path.js';
+const text = (value) => [{ type: 'text', text: value }];
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const WORKSHEET_HEADER = [
+    '行号',
+    '清单编码',
+    '名称',
+    '单位',
+    '合同量',
+    '合同单价(元)',
+    '本期完成量',
+    '累计完成量',
+    '本期金额(元)',
+    '累计金额(元)',
+    '累计比例(%)',
+    '是否计入',
+    '问题代码',
+    '问题说明',
+];
+/** UTF-8 BOM so Excel on Windows opens the Chinese headers correctly. */
+function worksheetCsv(batch, audit, toleranceBps) {
+    const rows = buildWorksheet(batch, audit, { price_tolerance_bps: toleranceBps }).map((row) => [
+        String(row.row),
+        row.item_code,
+        row.item_name,
+        row.unit,
+        String(row.contract_qty),
+        formatCents(row.contract_unit_price_cents),
+        String(row.period_qty),
+        String(row.cumulative_qty),
+        formatCents(row.period_amount_cents),
+        formatCents(row.cumulative_amount_cents),
+        row.cumulative_ratio_pct.toFixed(2),
+        row.counted ? '是' : '否',
+        row.issue_codes.join(';'),
+        row.issue_text,
+    ]);
+    return `\uFEFF${toCsv([WORKSHEET_HEADER, ...rows])}`;
+}
+function requireBatch(deps, batchId) {
+    const batch = batchId ? deps.batches.get(batchId) : undefined;
+    if (!batch)
+        throw new ProgressError('E_PROGRESS_BATCH_NOT_FOUND', `batch_id=${JSON.stringify(batchId ?? '')}`);
+    return batch;
+}
+export function createTools(deps) {
+    const ingest = defineTool({
+        name: 'progress.ingest',
+        description: 'Import one current-period progress declaration CSV (item code, name, unit, contract qty, contract unit price, period qty, cumulative qty) and an optional contract baseline; stores the batch in session memory; no file is written.',
+        parameters: {
+            declaration_csv: { type: 'string', required: true },
+            contract_csv: { type: 'string' },
+            source_name: { type: 'string' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    batch_id: { type: 'string', required: true },
+                    rows: { type: 'number', required: true },
+                    items: { type: 'number', required: true },
+                    contract_items: { type: 'number', required: true },
+                    declaration_sha256: { type: 'string', required: true },
+                    contract_sha256: { type: 'string' },
+                },
+            },
+            render: (_args, value) => text(`进度款申报：${value.items} 个清单项 / ${value.rows} 行，合同基准 ${value.contract_items} 项（${value.batch_id}）`),
+        },
+        async execute(args) {
+            const { batch, summary } = ingestDeclaration(args.declaration_csv, args.contract_csv, args.source_name ?? 'declaration.csv');
+            await deps.batches.put(batch.batch_id, batch);
+            return summary;
+        },
+    });
+    const audit = defineTool({
+        name: 'progress.audit',
+        description: 'Audit a stored declaration: period amount in integer cents, cumulative ratio, over-contract quantity, contract/declared unit-price mismatch, cumulative-over-contract and duplicate item codes. Returns the problem list; amounts stay in integer cents. Read-only.',
+        parameters: {
+            batch_id: { type: 'string', required: true },
+            price_tolerance_bps: { type: 'number' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    batch_id: { type: 'string', required: true },
+                    currency: { type: 'string', required: true },
+                    items: { type: 'json', required: true },
+                    issues: { type: 'json', required: true },
+                    summary: { type: 'json', required: true },
+                },
+            },
+            render: (_args, value) => text(auditSentence(value)),
+        },
+        async execute(args) {
+            const batch = requireBatch(deps, args.batch_id);
+            return auditBatch(batch, { price_tolerance_bps: args.price_tolerance_bps ?? 0 });
+        },
+    });
+    const exportCsv = defineTool({
+        name: 'progress.export',
+        description: 'Run the audit again and write the review worksheet CSV (one row per declaration line, duplicate rows marked counted=no) under $DSH_HOME/dsh-progress-payment/exports; returns path, rows and sha256. Local R1 write.',
+        parameters: {
+            batch_id: { type: 'string', required: true },
+            filename: { type: 'string' },
+            price_tolerance_bps: { type: 'number' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', required: true },
+                    sha256: { type: 'string', required: true },
+                    rows: { type: 'number', required: true },
+                    bytes: { type: 'number', required: true },
+                    items: { type: 'number', required: true },
+                    issues: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`审核底稿 ${value.rows} 行 -> ${value.path}`),
+        },
+        async execute(args) {
+            const batch = requireBatch(deps, args.batch_id);
+            const toleranceBps = args.price_tolerance_bps ?? 0;
+            const auditResult = auditBatch(batch, { price_tolerance_bps: toleranceBps });
+            const csv = worksheetCsv(batch, auditResult, toleranceBps);
+            const suffix = batch.batch_id.replace(/^pg_/, '').slice(0, 8);
+            const filename = args.filename ?? `progress-audit-${suffix}.csv`;
+            let filePath;
+            try {
+                filePath = await safeExportPath(path.join(deps.baseDir, 'exports'), filename);
+            }
+            catch (error) {
+                if (error instanceof ProgressError)
+                    throw error;
+                throw new ProgressError('E_PROGRESS_EXPORT_FAILED', String(error));
+            }
+            try {
+                await writeFile(filePath, csv, 'utf8');
+            }
+            catch (error) {
+                throw new ProgressError('E_PROGRESS_EXPORT_FAILED', String(error));
+            }
+            return {
+                path: filePath,
+                sha256: sha256(csv),
+                rows: batch.rows.length + 1,
+                bytes: Buffer.byteLength(csv, 'utf8'),
+                items: auditResult.summary.items,
+                issues: auditResult.summary.issues,
+            };
+        },
+    });
+    return [ingest, audit, exportCsv];
+}