@perrylink/dsh-einvoice 0.1.0-alpha.2 → 0.2.0-alpha.0

package/README.md

@@ -2,7 +2,8 @@
 
 File-level Chinese e-invoice ingest, parse and pool for DeepSeek Harness (SKU-04 S1).
 
-> **Status: S1+S2+S3 / public demo (0.1.0-alpha.2).** The customer evidence gate (2 enterprises + 1 bookkeeping firm + 100 real invoices) is still PARKED. S1 uses public/open-source and synthetic fixtures; its acceptance rows are `not counted` toward GA. Do not describe this package as GA-ready.
+> **Status: file-level public demo (0.2.0-alpha.0) — PARTIAL, NOT COUNTED, NOT GA.**
+> This package does **not** implement OCR/scanning, tax-bureau verification/receipt, tax filing, 30-year archive compliance, or real-invoice accuracy claims. `invoice.review_queue` / `invoice.record_receipt` are local-only; the legacy names are deprecated aliases. The customer evidence gate (2 enterprises + 1 bookkeeping firm + 100 real invoices) is still PARKED. S1 uses public/open-source and synthetic fixtures; its acceptance rows are `not counted` toward GA. Do not describe this package as GA-ready.
 
 ## Install
 
@@ -21,13 +22,15 @@ The bundle inserts one Host row. It requires the base profile's `tools` and `sto
 | `invoice.parse` | Parse old OFD `Attachs/original_invoice.xml` or 数电票 `Tags/CustomTag.xml` + ObjectRef; return eight fields, lines, evidence and unknown fields | R0 |
 | `invoice.query` | Query the invoice pool by entity, period, lifecycle or text | R0 |
 | `invoice.dedup` | Group duplicates by invoice number or seller+date+total | R0 |
-| `invoice.verify` | Queue parsed invoices for manual verification; optional buyer-tax-id mismatch flags | R1 local write |
-| `invoice.receipt` | Hash a local receipt, append it, move lifecycle to verified/quarantined; idempotent by receipt bytes | R1 local write |
+| `invoice.review_queue` | Queue parsed invoices for manual local review; optional buyer-tax-id mismatch flags. Old `invoice.verify` is a deprecated alias. | R1 local write |
+| `invoice.record_receipt` | Hash a local receipt, append it, move lifecycle to receipt-recorded/quarantined; `verification_source=local_receipt`, `tax_verified=false`; old `invoice.receipt` is a deprecated alias. | R1 local write |
 | `invoice.redlink` | Bind a negative red invoice to its blue invoice; store deltas | R1 local write |
 | `invoice.archive` | Build a manifest + originals + receipts ZIP under the local archive directory | R1 local write |
 | `invoice.check` | Verify manifest/member hashes, missing files and traversal | R0 |
 | `invoice.restore` | Restore a verified archive into the local restore root | R1 local write |
 
+Client: deferred; see `CLIENT-DECISION.md`. GA: blocked by the customer evidence gate; see `GA-CHECKLIST.md`.
+
 S3 adds red/blue matching, deterministic archive packages, check and restore. S2 verification is manual/local (no tax-bureau network call).
 
 ## Configuration

package/lib/adapters/ofd-zip-xml.js

@@ -1,7 +1,7 @@
 /** OFD (ZIP + XML) and standalone XML reader for SKU-04 S1. */
 import { unzipSync } from 'fflate';
 import { XMLParser } from 'fast-xml-parser';
-import { InvoiceError, amountToCents, normalizeDate, normalizeTaxId, } from '../core/invoice.js';
+import { InvoiceError, amountToCents, priceToCents, normalizeDate, normalizeTaxId, } from '../core/invoice.js';
 export const PARSER_ID = 'ofd-zip-xml';
 export const PARSER_VERSION = 'ofd-zip-xml@1';
 const xmlParser = new XMLParser({
@@ -96,7 +96,7 @@ function parseOldInvoice(root) {
             line_no: index + 1,
             description: textAt(line, 'Item'),
             quantity: textAt(line, 'Quantity') || undefined,
-            unit_price_cents: textAt(line, 'Price') ? amountToCents(textAt(line, 'Price')) : undefined,
+            unit_price_cents: textAt(line, 'Price') ? priceToCents(textAt(line, 'Price')) : undefined,
             amount_cents: amount ? amountToCents(amount) : 0,
             tax_rate: textAt(line, 'TaxScheme') || undefined,
             tax_cents: tax ? amountToCents(tax) : undefined,
@@ -240,7 +240,7 @@ function parseDigitalInvoice(root, textMap) {
             line_no: index + 1,
             description,
             quantity: textMap.get(quantityRefs[index] ?? '') || undefined,
-            unit_price_cents: textMap.get(priceRefs[index] ?? '') ? amountToCents(textMap.get(priceRefs[index] ?? '') ?? '') : undefined,
+            unit_price_cents: textMap.get(priceRefs[index] ?? '') ? priceToCents(textMap.get(priceRefs[index] ?? '') ?? '') : undefined,
             amount_cents: amountText ? amountToCents(amountText) : 0,
             tax_rate: textMap.get(taxSchemeRefs[index] ?? '') || undefined,
             tax_cents: taxText ? amountToCents(taxText) : undefined,
@@ -299,7 +299,7 @@ function parseGenericInvoice(root) {
             line_no: index + 1,
             description: textAt(line, 'Description') || textAt(line, 'Item'),
             quantity: textAt(line, 'Quantity') || undefined,
-            unit_price_cents: textAt(line, 'UnitPrice') ? amountToCents(textAt(line, 'UnitPrice')) : undefined,
+            unit_price_cents: textAt(line, 'UnitPrice') ? priceToCents(textAt(line, 'UnitPrice')) : undefined,
             amount_cents: textAt(line, 'Amount') ? amountToCents(textAt(line, 'Amount')) : 0,
             tax_rate: textAt(line, 'TaxRate') || undefined,
             tax_cents: textAt(line, 'TaxAmount') ? amountToCents(textAt(line, 'TaxAmount')) : undefined,

package/lib/core/invoice.d.ts

@@ -48,6 +48,8 @@ export declare class InvoiceError extends Error {
 /** Parse a decimal amount (yuan) into integer cents without floating point. */
 export declare function amountToCents(raw: unknown): number;
 /** Normalize the common Chinese date spellings to YYYY-MM-DD. */
+/** Unit prices may carry tax-calculation precision; round half-up to integer cents. */
+export declare function priceToCents(raw: unknown): number;
 export declare function normalizeDate(raw: unknown): string;
 /** Validate the shape of a PRC taxpayer id without claiming checksum validity. */
 export declare function normalizeTaxId(raw: unknown): string;

package/lib/core/invoice.js

@@ -37,6 +37,20 @@ export function amountToCents(raw) {
     return Number(cents);
 }
 /** Normalize the common Chinese date spellings to YYYY-MM-DD. */
+/** Unit prices may carry tax-calculation precision; round half-up to integer cents. */
+export function priceToCents(raw) {
+    if (typeof raw !== 'string' && typeof raw !== 'number')
+        throw new InvoiceError('E_INV_FIELD_MISSING', 'price is not a value');
+    const normalized = String(raw).trim().replace(/[¥￥,，\s]/g, '');
+    const match = /^(-?)(\d+)(?:\.(\d{1,12}))?$/.exec(normalized);
+    if (!match)
+        throw new InvoiceError('E_INV_FIELD_MISSING', `price is not a decimal: ${String(raw).slice(0, 80)}`);
+    const sign = match[1] === '-' ? -1n : 1n;
+    const whole = BigInt(match[2]);
+    const fraction = BigInt((match[3] ?? '').padEnd(12, '0'));
+    const cents = (whole * 100n + (fraction + 5000000000n) / 10000000000n);
+    return Number(sign * cents);
+}
 export function normalizeDate(raw) {
     if (typeof raw !== 'string' || raw.trim() === '') {
         throw new InvoiceError('E_INV_FIELD_MISSING', 'issue date is empty');

package/lib/plugin/tools.js

@@ -449,7 +449,7 @@ export function createTools(deps) {
         },
     });
     const verify = defineTool({
-        name: 'invoice.verify',
+        name: 'invoice.review_queue',
         description: 'Queue parsed invoices for manual/semi-automatic verification. S2 has no tax-bureau network call: it records a pending local queue and optional entity-tax-id mismatch flags.',
         parameters: {
             invoice_ids: { type: 'array', items: { type: 'string' }, description: 'Optional subset; defaults to parsed invoices' },
@@ -533,7 +533,7 @@ export function createTools(deps) {
         },
     });
     const receipt = defineTool({
-        name: 'invoice.receipt',
+        name: 'invoice.record_receipt',
         description: 'Record a local verification receipt for one parsed invoice: hash the receipt file, append an immutable receipt record, and move the invoice to verified/quarantined. Local R1 write; no tax-bureau write.',
         parameters: {
             invoice_id: { type: 'string', required: true },
@@ -552,6 +552,8 @@ export function createTools(deps) {
                     receipt_sha256: { type: 'string', required: true },
                     duplicate: { type: 'boolean', required: true },
                     lifecycle: { type: 'string', required: true },
+                    verification_source: { type: 'string', required: true },
+                    tax_verified: { type: 'boolean', required: true },
                 },
             },
             render: (_args, value) => text(`receipt ${value.receipt_id} (${value.duplicate ? 'duplicate' : 'recorded'}), invoice=${value.lifecycle}`),
@@ -571,7 +573,7 @@ export function createTools(deps) {
             const receiptSha = sha256Buffer(buffer);
             const existing = (record.receipts ?? []).find((item) => item.receipt_sha256 === receiptSha);
             if (existing) {
-                return { receipt_id: existing.receipt_id, receipt_sha256: receiptSha, duplicate: true, lifecycle: record.lifecycle };
+                return { receipt_id: existing.receipt_id, receipt_sha256: receiptSha, duplicate: true, lifecycle: record.lifecycle, verification_source: 'local_receipt', tax_verified: false };
             }
             const now = new Date().toISOString();
             const receiptRecord = {
@@ -600,7 +602,7 @@ export function createTools(deps) {
                 updated_at: now,
             };
             await deps.table.put(record.doc_id, updated);
-            return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle };
+            return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle, verification_source: 'local_receipt', tax_verified: false };
         },
     });
     const archiveDir = path.join(deps.baseDir, 'archives');
@@ -891,5 +893,7 @@ export function createTools(deps) {
             };
         },
     });
-    return [ingest, parse, query, dedup, verify, receipt, redlink, archive, check, restore];
+    const legacyVerify = { ...verify, name: 'invoice.verify', description: 'Deprecated alias for invoice.review_queue; local review queue only, no tax-bureau verification.' };
+    const legacyReceipt = { ...receipt, name: 'invoice.receipt', description: 'Deprecated alias for invoice.record_receipt; local receipt only, no tax-bureau verification.' };
+    return [ingest, parse, query, dedup, verify, legacyVerify, receipt, legacyReceipt, redlink, archive, check, restore];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perrylink/dsh-einvoice",
-  "version": "0.1.0-alpha.2",
+  "version": "0.2.0-alpha.0",
   "description": "File-level Chinese e-invoice (OFD/XML) ingest, parse and pool for DeepSeek Harness (SKU-04 S1).",
   "type": "module",
   "main": "./lib/plugin/index.js",