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

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "dsh-progress-payment",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "description": "Audit construction progress-payment declarations against the contract baseline and export a review worksheet; amounts in integer cents.",
+  "type": "module",
+  "main": "./lib/plugin/index.js",
+  "types": "./lib/plugin/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/plugin/index.d.ts",
+      "default": "./lib/plugin/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README-zh.md",
+    "README-es.md",
+    "README-pt.md",
+    "README-hi.md",
+    "TROUBLESHOOTING.md",
+    "screenshots.json",
+    "samples",
+    "docs/assets",
+    "icon.svg"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "demo": {
+      "sample": "samples/quickstart/input/declaration-2026-10.csv",
+      "prompt": "帮我审一下这期进度款申报，按合同基准核对超量和单价，把问题清单导成底稿。",
+      "expect": "samples/quickstart/expected/result.json",
+      "screenshot": "docs/assets/quickstart.png",
+      "reads": [
+        "用户指定的进度款申报 CSV 与合同基准 CSV（样例：samples/quickstart/input/）"
+      ],
+      "writes": [
+        "$DSH_HOME/dsh-progress-payment/exports/"
+      ],
+      "network": false,
+      "external": []
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.3 <0.4.0",
+    "node": ">=24.9.0 <25"
+  },
+  "packageManager": "pnpm@11.28.5",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "node scripts/lint.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "gate": "node scripts/gate.mjs",
+    "acceptance": "node scripts/acceptance.mjs",
+    "quickstart": "node samples/quickstart/run.mjs --check",
+    "prepublishOnly": "npm run build && node scripts/lint.mjs && node scripts/gate.mjs"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "progress-payment",
+    "construction",
+    "quantity-surveying",
+    "csv",
+    "perrylink"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-progress-payment.git"
+  },
+  "homepage": "https://perrylink.github.io/dsh-plugins/packages/dsh-progress-payment.html",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-progress-payment/issues"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.5 <5.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.3 <0.4.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}

package/samples/quickstart/expected/result.json

@@ -0,0 +1,206 @@
+{
+  "_note": "Real tool output. The export path is normalised to exports/<file>.csv (the run directory is a temp dir); everything else is verbatim. Amounts are integer cents.",
+  "sample": {
+    "declaration": {
+      "path": "samples/quickstart/input/declaration-2026-10.csv",
+      "bytes": 412,
+      "sha256": "b74c68756bbd882b7b627194d772df672155d84fa7d1028182598dfa10afa2c0"
+    },
+    "contract": {
+      "path": "samples/quickstart/input/contract-baseline.csv",
+      "bytes": 159,
+      "sha256": "dc42b8123b3a68aa63a2be29226f73d22c614974538513bd896af53a12c1e4d3"
+    }
+  },
+  "ingest": {
+    "batch_id": "pg_ea0edb1548cb530b",
+    "rows": 7,
+    "items": 6,
+    "contract_items": 6,
+    "declaration_sha256": "b74c68756bbd882b7b627194d772df672155d84fa7d1028182598dfa10afa2c0",
+    "contract_sha256": "dc42b8123b3a68aa63a2be29226f73d22c614974538513bd896af53a12c1e4d3"
+  },
+  "audit": {
+    "batch_id": "pg_ea0edb1548cb530b",
+    "currency": "CNY",
+    "items": [
+      {
+        "row": 1,
+        "item_code": "010101001",
+        "item_name": "平整场地",
+        "unit": "m2",
+        "declared_contract_qty": 1200,
+        "declared_contract_unit_price_cents": 350,
+        "contract_qty": 1200,
+        "contract_unit_price_cents": 350,
+        "period_qty": 300,
+        "cumulative_qty": 900,
+        "period_amount_cents": 105000,
+        "declared_period_amount_cents": 105000,
+        "cumulative_amount_cents": 315000,
+        "contract_amount_cents": 420000,
+        "cumulative_ratio_pct": 75,
+        "issue_codes": []
+      },
+      {
+        "row": 2,
+        "item_code": "010101003",
+        "item_name": "挖沟槽土方",
+        "unit": "m3",
+        "declared_contract_qty": 850,
+        "declared_contract_unit_price_cents": 2800,
+        "contract_qty": 850,
+        "contract_unit_price_cents": 2800,
+        "period_qty": 120,
+        "cumulative_qty": 520,
+        "period_amount_cents": 336000,
+        "declared_period_amount_cents": 336000,
+        "cumulative_amount_cents": 1456000,
+        "contract_amount_cents": 2380000,
+        "cumulative_ratio_pct": 61.18,
+        "issue_codes": []
+      },
+      {
+        "row": 3,
+        "item_code": "010401001",
+        "item_name": "混凝土基础",
+        "unit": "m3",
+        "declared_contract_qty": 260,
+        "declared_contract_unit_price_cents": 48000,
+        "contract_qty": 260,
+        "contract_unit_price_cents": 48000,
+        "period_qty": 25.92,
+        "cumulative_qty": 240.5,
+        "period_amount_cents": 1244160,
+        "declared_period_amount_cents": 1244160,
+        "cumulative_amount_cents": 11544000,
+        "contract_amount_cents": 12480000,
+        "cumulative_ratio_pct": 92.5,
+        "issue_codes": []
+      },
+      {
+        "row": 4,
+        "item_code": "010402001",
+        "item_name": "矩形柱",
+        "unit": "m3",
+        "declared_contract_qty": 95,
+        "declared_contract_unit_price_cents": 61000,
+        "contract_qty": 95,
+        "contract_unit_price_cents": 61000,
+        "period_qty": 12,
+        "cumulative_qty": 101.5,
+        "period_amount_cents": 732000,
+        "declared_period_amount_cents": 732000,
+        "cumulative_amount_cents": 6191500,
+        "contract_amount_cents": 5795000,
+        "cumulative_ratio_pct": 106.84,
+        "issue_codes": [
+          "E_PROGRESS_OVER_QTY"
+        ]
+      },
+      {
+        "row": 5,
+        "item_code": "010515001",
+        "item_name": "现浇构件钢筋",
+        "unit": "t",
+        "declared_contract_qty": 80,
+        "declared_contract_unit_price_cents": 520000,
+        "contract_qty": 80,
+        "contract_unit_price_cents": 520000,
+        "period_qty": 4.2,
+        "cumulative_qty": 62.4,
+        "period_amount_cents": 2184000,
+        "declared_period_amount_cents": 2184000,
+        "cumulative_amount_cents": 32448000,
+        "contract_amount_cents": 41600000,
+        "cumulative_ratio_pct": 78,
+        "issue_codes": []
+      },
+      {
+        "row": 6,
+        "item_code": "011702001",
+        "item_name": "基础模板",
+        "unit": "m2",
+        "declared_contract_qty": 1800,
+        "declared_contract_unit_price_cents": 6500,
+        "contract_qty": 1800,
+        "contract_unit_price_cents": 5500,
+        "period_qty": 86.4,
+        "cumulative_qty": 1720,
+        "period_amount_cents": 475200,
+        "declared_period_amount_cents": 561600,
+        "cumulative_amount_cents": 9460000,
+        "contract_amount_cents": 9900000,
+        "cumulative_ratio_pct": 95.56,
+        "issue_codes": [
+          "E_PROGRESS_PRICE_MISMATCH"
+        ]
+      }
+    ],
+    "issues": [
+      {
+        "row": 4,
+        "item_code": "010402001",
+        "item_name": "矩形柱",
+        "code": "E_PROGRESS_OVER_QTY",
+        "kind": "cumulative_over_contract",
+        "field": "cumulative_qty",
+        "message": "累计完成量 101.5 超过合同量 95（E_PROGRESS_OVER_QTY）｜下一步：核对合同量和变更签证；超量部分走变更或结算，不在本期支付",
+        "blocking": true
+      },
+      {
+        "row": 6,
+        "item_code": "011702001",
+        "item_name": "基础模板",
+        "code": "E_PROGRESS_PRICE_MISMATCH",
+        "kind": "price_mismatch",
+        "field": "contract_unit_price",
+        "message": "申报合同单价 65.00 与合同基准 55.00 不符（E_PROGRESS_PRICE_MISMATCH）｜下一步：本期金额按合同单价 55.00 重算，并要求申报方改正",
+        "blocking": true
+      },
+      {
+        "row": 7,
+        "item_code": "010101003",
+        "item_name": "挖沟槽土方",
+        "code": "E_PROGRESS_DUP_ITEM",
+        "kind": "duplicate_item",
+        "field": "item_code",
+        "message": "清单编码 010101003 在本期申报里出现 2 次（行 2、7）（E_PROGRESS_DUP_ITEM）｜下一步：确认哪一行是本期应报的；重复行不计入本期金额",
+        "blocking": true
+      }
+    ],
+    "summary": {
+      "items": 6,
+      "rows": 7,
+      "duplicate_rows": 1,
+      "contract_items": 6,
+      "period_amount_cents": 5076360,
+      "declared_period_amount_cents": 5162760,
+      "price_adjustment_cents": -86400,
+      "cumulative_amount_cents": 61414500,
+      "contract_amount_cents": 72575000,
+      "cumulative_ratio_pct": 84.62,
+      "issues": 3,
+      "blocking_issues": 3,
+      "over_qty": 1,
+      "price_mismatch": 1,
+      "duplicate_items": 1,
+      "contract_missing": 0,
+      "contract_mismatch": 0,
+      "qty_inconsistent": 0,
+      "status": "needs_review"
+    }
+  },
+  "export": {
+    "path": "exports/progress-audit-2026-10.csv",
+    "sha256": "24cca857d661d882968ffe16e05773636c6b669bbdd48c577fe416cc84b45e18",
+    "rows": 8,
+    "bytes": 1291,
+    "items": 6,
+    "issues": 3
+  },
+  "worksheet": {
+    "bom": true,
+    "text": "行号,清单编码,名称,单位,合同量,合同单价(元),本期完成量,累计完成量,本期金额(元),累计金额(元),累计比例(%),是否计入,问题代码,问题说明\n1,010101001,平整场地,m2,1200,3.50,300,900,1050.00,3150.00,75.00,是,,\n2,010101003,挖沟槽土方,m3,850,28.00,120,520,3360.00,14560.00,61.18,是,,\n3,010401001,混凝土基础,m3,260,480.00,25.92,240.5,12441.60,115440.00,92.50,是,,\n4,010402001,矩形柱,m3,95,610.00,12,101.5,7320.00,61915.00,106.84,是,E_PROGRESS_OVER_QTY,累计完成量 101.5 超过合同量 95（E_PROGRESS_OVER_QTY）｜下一步：核对合同量和变更签证；超量部分走变更或结算，不在本期支付\n5,010515001,现浇构件钢筋,t,80,5200.00,4.2,62.4,21840.00,324480.00,78.00,是,,\n6,011702001,基础模板,m2,1800,55.00,86.4,1720,4752.00,94600.00,95.56,是,E_PROGRESS_PRICE_MISMATCH,申报合同单价 65.00 与合同基准 55.00 不符（E_PROGRESS_PRICE_MISMATCH）｜下一步：本期金额按合同单价 55.00 重算，并要求申报方改正\n7,010101003,挖沟槽土方,m3,850,28.00,120,520,3360.00,14560.00,61.18,否,E_PROGRESS_DUP_ITEM,清单编码 010101003 在本期申报里重复出现（E_PROGRESS_DUP_ITEM）｜下一步：确认哪一行是本期应报的；重复行不计入本期金额\n"
+  }
+}

package/samples/quickstart/input/contract-baseline.csv

@@ -0,0 +1,7 @@
+清单编码,合同量,合同单价
+010101001,1200,3.50
+010101003,850,28.00
+010401001,260,480.00
+010402001,95,610.00
+010515001,80,5200.00
+011702001,1800,55.00

package/samples/quickstart/input/declaration-2026-10.csv

@@ -0,0 +1,8 @@
+清单编码,名称,单位,合同量,合同单价,本期完成量,累计完成量
+010101001,平整场地,m2,1200,3.50,300,900
+010101003,挖沟槽土方,m3,850,28.00,120,520
+010401001,混凝土基础,m3,260,480.00,25.92,240.5
+010402001,矩形柱,m3,95,610.00,12,101.5
+010515001,现浇构件钢筋,t,80,5200.00,4.2,62.4
+011702001,基础模板,m2,1800,65.00,86.4,1720
+010101003,挖沟槽土方,m3,850,28.00,120,520

package/samples/quickstart/run.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * dsh-progress-payment quickstart — audits the bundled synthetic declaration
+ * against the bundled contract baseline and exports the review worksheet.
+ *
+ *   node samples/quickstart/run.mjs            # human-readable summary
+ *   node samples/quickstart/run.mjs --json     # the golden result on stdout
+ *   node samples/quickstart/run.mjs --check    # recompute and diff against the golden file
+ *
+ * The golden file `expected/result.json` is the stdout of `--json`; it is a real
+ * run over the committed CSVs, not hand-written output. No network, no model,
+ * no customer data: every code and amount is synthetic.
+ */
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+import { mkdtemp, readFile, realpath, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createTools } from '../../lib/plugin/tools.js'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const root = path.resolve(here, '..', '..')
+const DECLARATION = 'samples/quickstart/input/declaration-2026-10.csv'
+const CONTRACT = 'samples/quickstart/input/contract-baseline.csv'
+const expectedPath = path.join(here, 'expected', 'result.json')
+const mode = process.argv.includes('--check') ? 'check' : process.argv.includes('--json') ? 'json' : 'summary'
+const sha256 = (value) => createHash('sha256').update(value).digest('hex')
+
+class MemoryTable {
+  constructor() {
+    this.map = new Map()
+  }
+  get(key) {
+    return this.map.get(key)
+  }
+  put(key, value) {
+    this.map.set(key, value)
+  }
+}
+
+async function run() {
+  const declarationText = await readFile(path.join(root, DECLARATION), 'utf8')
+  const contractText = await readFile(path.join(root, CONTRACT), 'utf8')
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), 'dsh-progress-payment-quickstart-'))
+  const realTemp = await realpath(tempDir)
+  try {
+    const tools = Object.fromEntries(createTools({ batches: new MemoryTable(), baseDir: tempDir }).map((tool) => [tool.name, tool]))
+    const exec = { callId: 'quickstart', agent: { id: 'quickstart' } }
+
+    const ingest = await tools['progress.ingest'].execute(
+      { declaration_csv: declarationText, contract_csv: contractText, source_name: 'declaration-2026-10.csv' },
+      exec,
+    )
+    const audit = await tools['progress.audit'].execute({ batch_id: ingest.batch_id }, exec)
+    const exported = await tools['progress.export'].execute(
+      { batch_id: ingest.batch_id, filename: 'progress-audit-2026-10.csv' },
+      exec,
+    )
+    const csvText = await readFile(exported.path, 'utf8')
+
+    return {
+      _note:
+        'Real tool output. The export path is normalised to exports/<file>.csv (the run directory is a temp dir); everything else is verbatim. Amounts are integer cents.',
+      sample: {
+        declaration: { path: DECLARATION, bytes: Buffer.byteLength(declarationText), sha256: sha256(declarationText) },
+        contract: { path: CONTRACT, bytes: Buffer.byteLength(contractText), sha256: sha256(contractText) },
+      },
+      ingest,
+      audit,
+      export: {
+        path: `exports/${path.basename(exported.path)}`,
+        sha256: exported.sha256,
+        rows: exported.rows,
+        bytes: exported.bytes,
+        items: exported.items,
+        issues: exported.issues,
+      },
+      worksheet: {
+        bom: csvText.charCodeAt(0) === 0xfeff,
+        text: csvText.replace(/^\uFEFF/, ''),
+      },
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true })
+  }
+}
+
+function printSummary(result) {
+  const { audit, export: exported, worksheet } = result
+  const summary = audit.summary
+  console.log('dsh-progress-payment quickstart - synthetic progress declaration (not customer data)')
+  console.log(`declaration: ${result.sample.declaration.path} (${summary.rows} rows / ${summary.items} items)`)
+  console.log(`contract baseline: ${summary.contract_items} items; batch ${audit.batch_id}`)
+  console.log(`period amount: ${(summary.period_amount_cents / 100).toFixed(2)} CNY (declared ${(summary.declared_period_amount_cents / 100).toFixed(2)})`)
+  console.log(`cumulative: ${(summary.cumulative_amount_cents / 100).toFixed(2)} CNY / contract ${(summary.contract_amount_cents / 100).toFixed(2)} = ${summary.cumulative_ratio_pct}%`)
+  console.log(`issues: ${summary.issues} (over qty ${summary.over_qty}, price mismatch ${summary.price_mismatch}, duplicate ${summary.duplicate_items})`)
+  for (const issue of audit.issues) console.log(`  row ${issue.row} ${issue.item_code} ${issue.code} ${issue.message.split('（')[0]}`)
+  console.log(`worksheet: ${exported.path} ${exported.rows} rows, ${exported.bytes} bytes, sha256 ${exported.sha256.slice(0, 12)}...`)
+  console.log(`worksheet columns: ${worksheet.text.split('\n')[0]}`)
+}
+
+const result = await run()
+
+if (mode === 'json') {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+} else if (mode === 'check') {
+  const expected = JSON.parse(await readFile(expectedPath, 'utf8'))
+  assert.deepEqual(result, expected)
+  printSummary(result)
+  console.log('golden samples/quickstart/expected/result.json matches')
+  console.log('quickstart ok')
+} else {
+  printSummary(result)
+  console.log('run with --check to compare against expected/result.json')
+}

package/screenshots.json

@@ -0,0 +1,21 @@
+[
+  {
+    "path": "docs/assets/quickstart.png",
+    "kind": "quickstart",
+    "alt": "dsh-progress-payment quickstart terminal output",
+    "caption": "Real command: node samples/quickstart/run.mjs --check — a synthetic 7-row / 6-item declaration against a 6-item contract baseline yields 50,763.60 CNY for the period, 84.62% cumulative, 3 blocking issues (over quantity, price mismatch, duplicate item) and an 8-row review worksheet. Rendered from the captured terminal output.",
+    "command": "node samples/quickstart/run.mjs --check",
+    "run_at": "2026-11-02T15:05:00Z",
+    "output_sha256": "bdaa9e845c43bab3e29b0e48dddfb801af505e6e552ffc3b12351f59c12feff5",
+    "output_path": "samples/quickstart/expected/result.json",
+    "log": "docs/assets/quickstart.log",
+    "log_sha256": "582cc7f92d0a8ca7d7ee6030e5d1607b6c3609d0f55dd745f5296b9fd99f6710",
+    "image_sha256": "beeda8ec806af9221faf8f253cff5191232f0580fa6a6012112ee48f09ba8854"
+  },
+  {
+    "path": "docs/assets/dsh-progress-payment-flow.svg",
+    "kind": "flow",
+    "alt": "dsh-progress-payment workflow diagram",
+    "caption": "Pipeline diagram: local declaration CSV + contract baseline to integer-cent audit to local worksheet. Schematic, not test evidence."
+  }
+]