@perrylink/dsh-einvoice 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -2,7 +2,7 @@
 
 File-level Chinese e-invoice ingest, parse and pool for DeepSeek Harness (SKU-04 S1).
 
-> **Status: S1 / public demo.** 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: S1+S2 / public demo (0.1.0-alpha.1).** 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
 
@@ -20,8 +20,11 @@ The bundle inserts one Host row. It requires the base profile's `tools` and `sto
 | `invoice.ingest` | Ingest one local OFD/XML file, compute SHA-256, store the original locally, idempotent by bytes | R1 local write |
 | `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 |
 
-S2/S3 add dedup, verification/receipt, red/blue matching, archive packages and archive checks; S1 does not register them.
+S3 adds red/blue matching, archive packages and archive checks; S2 verification is manual/local (no tax-bureau network call).
 
 ## Configuration
 

package/lib/plugin/storage.d.ts

@@ -15,6 +15,33 @@ export declare const lineSchema: z.ZodObject<{
     tax_rate: z.ZodOptional<z.ZodString>;
     tax_cents: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+export declare const verificationSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        verified: "verified";
+        pending: "pending";
+        failed: "failed";
+        manual: "manual";
+    }>;
+    queued_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    attempts: z.ZodDefault<z.ZodNumber>;
+    last_result: z.ZodOptional<z.ZodString>;
+    manual_reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const receiptSchema: z.ZodObject<{
+    receipt_id: z.ZodString;
+    result_code: z.ZodString;
+    result: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        unknown: "unknown";
+    }>;
+    verified_at: z.ZodString;
+    operator: z.ZodString;
+    receipt_sha256: z.ZodString;
+    receipt_path: z.ZodString;
+    recorded_at: z.ZodString;
+}, z.core.$strip>;
 export declare const invoiceSchema: z.ZodObject<{
     doc_id: z.ZodString;
     entity_id: z.ZodString;
@@ -53,6 +80,33 @@ export declare const invoiceSchema: z.ZodObject<{
         archived: "archived";
         quarantined: "quarantined";
     }>;
+    verification: z.ZodOptional<z.ZodObject<{
+        state: z.ZodEnum<{
+            verified: "verified";
+            pending: "pending";
+            failed: "failed";
+            manual: "manual";
+        }>;
+        queued_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<z.ZodString>;
+        attempts: z.ZodDefault<z.ZodNumber>;
+        last_result: z.ZodOptional<z.ZodString>;
+        manual_reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    receipts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        receipt_id: z.ZodString;
+        result_code: z.ZodString;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            unknown: "unknown";
+        }>;
+        verified_at: z.ZodString;
+        operator: z.ZodString;
+        receipt_sha256: z.ZodString;
+        receipt_path: z.ZodString;
+        recorded_at: z.ZodString;
+    }, z.core.$strip>>>;
     source_path: z.ZodString;
     source_sha256: z.ZodString;
     source_size: z.ZodNumber;
@@ -116,6 +170,24 @@ export declare const finInvoiceSpec: {
             actor: string;
             evidence_sha256: string;
             invoice_code?: string | undefined;
+            verification?: {
+                state: "verified" | "pending" | "failed" | "manual";
+                attempts: number;
+                queued_at?: string | undefined;
+                updated_at?: string | undefined;
+                last_result?: string | undefined;
+                manual_reason?: string | undefined;
+            } | undefined;
+            receipts?: {
+                receipt_id: string;
+                result_code: string;
+                result: "pass" | "fail" | "unknown";
+                verified_at: string;
+                operator: string;
+                receipt_sha256: string;
+                receipt_path: string;
+                recorded_at: string;
+            }[] | undefined;
         }>;
     };
 };

package/lib/plugin/storage.js

@@ -19,6 +19,24 @@ export const lineSchema = z.object({
     tax_rate: z.string().optional(),
     tax_cents: z.number().int().optional(),
 });
+export const verificationSchema = z.object({
+    state: z.enum(['pending', 'verified', 'failed', 'manual']),
+    queued_at: z.string().optional(),
+    updated_at: z.string().optional(),
+    attempts: z.number().int().nonnegative().default(0),
+    last_result: z.string().optional(),
+    manual_reason: z.string().optional(),
+});
+export const receiptSchema = z.object({
+    receipt_id: z.string(),
+    result_code: z.string(),
+    result: z.enum(['pass', 'fail', 'unknown']),
+    verified_at: z.string(),
+    operator: z.string(),
+    receipt_sha256: z.string(),
+    receipt_path: z.string(),
+    recorded_at: z.string(),
+});
 export const invoiceSchema = z.object({
     doc_id: z.string().min(1),
     entity_id: z.string(),
@@ -37,6 +55,8 @@ export const invoiceSchema = z.object({
     unknown_fields: z.record(z.string(), z.unknown()),
     parser_version: z.string(),
     lifecycle: z.enum(['received', 'parsed', 'verified', 'archived', 'quarantined']),
+    verification: verificationSchema.optional(),
+    receipts: z.array(receiptSchema).optional(),
     source_path: z.string(),
     source_sha256: z.string(),
     source_size: z.number().int().nonnegative(),

package/lib/plugin/tools.js

@@ -300,5 +300,244 @@ export function createTools(deps) {
             };
         },
     });
-    return [ingest, parse, query];
+    const dedup = defineTool({
+        name: 'invoice.dedup',
+        description: 'Group parsed invoices by invoice number, or by seller+date+total when the number is absent; returns duplicate groups and their basis. Read-only.',
+        parameters: {
+            filter: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    entity_id: { type: 'string' },
+                    period: { type: 'string', description: 'YYYY-MM from issue_date' },
+                },
+            },
+            doc_ids: { type: 'array', items: { type: 'string' }, description: 'Optional subset; defaults to the whole pool' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    groups: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                fingerprint: { type: 'string', required: true },
+                                kind: { type: 'string', required: true },
+                                basis: { type: 'string', required: true },
+                                members: {
+                                    type: 'array',
+                                    required: true,
+                                    items: {
+                                        type: 'object',
+                                        additionalProperties: false,
+                                        properties: {
+                                            doc_id: { type: 'string', required: true },
+                                            invoice_no: { type: 'string', required: true },
+                                            seller_name: { type: 'string', required: true },
+                                            total_cents: { type: 'number', required: true },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    total: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`dedup: ${value.total} duplicate groups`),
+        },
+        async execute(args) {
+            const filter = args.filter ?? {};
+            const selected = args.doc_ids?.length
+                ? args.doc_ids.map((id) => deps.table.get(id)).filter((record) => record !== undefined)
+                : [...deps.table.entries()].map(([, record]) => record);
+            const groups = new Map();
+            for (const record of selected) {
+                if (filter.entity_id && record.entity_id !== filter.entity_id)
+                    continue;
+                if (filter.period && invoicePeriod(record.issue_date) !== filter.period)
+                    continue;
+                const byNumber = record.invoice_no !== '';
+                const fingerprint = byNumber
+                    ? `invoice_no:${record.invoice_no}`
+                    : `seller_date_total:${record.seller.tax_id}:${record.issue_date}:${record.total_cents}`;
+                const kind = byNumber ? 'invoice_no' : 'seller_date_total';
+                const basis = byNumber ? 'same invoice number' : 'same seller tax id + issue date + total';
+                let group = groups.get(fingerprint);
+                if (!group) {
+                    group = { fingerprint, kind, basis, members: [] };
+                    groups.set(fingerprint, group);
+                }
+                group.members.push({
+                    doc_id: record.doc_id,
+                    invoice_no: record.invoice_no,
+                    seller_name: record.seller.name,
+                    total_cents: record.total_cents,
+                });
+            }
+            const duplicateGroups = [...groups.values()].filter((group) => group.members.length > 1);
+            return { groups: duplicateGroups, total: duplicateGroups.length };
+        },
+    });
+    const verify = defineTool({
+        name: 'invoice.verify',
+        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' },
+            entity_id: { type: 'string' },
+            period: { type: 'string', description: 'YYYY-MM from issue_date' },
+            entity_tax_id: { type: 'string', description: 'Expected buyer tax id for header validation' },
+            limit: { type: 'number', description: '1..200, default 100' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    queue: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                doc_id: { type: 'string', required: true },
+                                invoice_no: { type: 'string', required: true },
+                                seller_name: { type: 'string', required: true },
+                                total_cents: { type: 'number', required: true },
+                                state: { type: 'string', required: true },
+                                entity_match: { type: 'boolean', required: true },
+                                needs_review: { type: 'array', items: { type: 'string' }, required: true },
+                            },
+                        },
+                    },
+                    total: { type: 'number', required: true },
+                },
+            },
+            render: (_args, value) => text(`verify queue: ${value.total} pending`),
+        },
+        async execute(args) {
+            const limit = Math.max(1, Math.min(200, Math.floor(args.limit ?? 100)));
+            const expected = args.entity_tax_id?.trim().toUpperCase();
+            const selected = args.invoice_ids?.length
+                ? args.invoice_ids.map((id) => deps.table.get(id)).filter((record) => record !== undefined)
+                : [...deps.table.entries()].map(([, record]) => record);
+            const queue = [];
+            for (const record of selected) {
+                if (queue.length >= limit)
+                    break;
+                if (record.lifecycle !== 'parsed' && record.lifecycle !== 'verified')
+                    continue;
+                if (args.entity_id && record.entity_id !== args.entity_id)
+                    continue;
+                if (args.period && invoicePeriod(record.issue_date) !== args.period)
+                    continue;
+                const entityMatch = !expected || record.buyer.tax_id.toUpperCase() === expected;
+                const needsReview = [];
+                if (!entityMatch)
+                    needsReview.push('entity_mismatch');
+                if (!record.buyer.tax_id)
+                    needsReview.push('missing_buyer_tax_id');
+                const now = new Date().toISOString();
+                const updated = {
+                    ...record,
+                    verification: {
+                        state: 'pending',
+                        queued_at: record.verification?.queued_at ?? now,
+                        updated_at: now,
+                        attempts: record.verification?.attempts ?? 0,
+                        manual_reason: needsReview.join(',') || record.verification?.manual_reason,
+                    },
+                };
+                await deps.table.put(record.doc_id, updated);
+                queue.push({
+                    doc_id: record.doc_id,
+                    invoice_no: record.invoice_no,
+                    seller_name: record.seller.name,
+                    total_cents: record.total_cents,
+                    state: 'pending',
+                    entity_match: entityMatch,
+                    needs_review: needsReview,
+                });
+            }
+            return { queue, total: queue.length };
+        },
+    });
+    const receipt = defineTool({
+        name: 'invoice.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 },
+            receipt_file: { type: 'string', required: true, description: 'Local receipt file under an allowed input root' },
+            result_code: { type: 'string', required: true },
+            result: { type: 'string', enum: ['pass', 'fail', 'unknown'], required: true },
+            verified_at: { type: 'string', required: true },
+            operator: { type: 'string', required: true },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    receipt_id: { type: 'string', required: true },
+                    receipt_sha256: { type: 'string', required: true },
+                    duplicate: { type: 'boolean', required: true },
+                    lifecycle: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => text(`receipt ${value.receipt_id} (${value.duplicate ? 'duplicate' : 'recorded'}), invoice=${value.lifecycle}`),
+        },
+        async execute(args) {
+            const record = deps.table.get(args.invoice_id);
+            if (!record)
+                throw new InvoiceError('E_INV_DOC_NOT_FOUND', `unknown invoice: ${args.invoice_id}`);
+            if (!args.result_code.trim() || !args.verified_at.trim() || !args.operator.trim()) {
+                throw new InvoiceError('E_INV_RECEIPT_INCOMPLETE', 'result_code, verified_at and operator are required', { needs_review: true });
+            }
+            const resolved = await resolveAllowedPath(args.receipt_file, deps.inputRoots);
+            const info = await stat(resolved);
+            if (!info.isFile() || info.size === 0)
+                throw new InvoiceError('E_INV_RECEIPT_INCOMPLETE', 'receipt file is empty or not a file');
+            const buffer = await readFile(resolved);
+            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 };
+            }
+            const now = new Date().toISOString();
+            const receiptRecord = {
+                receipt_id: newDocId(),
+                result_code: args.result_code.trim(),
+                result: args.result,
+                verified_at: args.verified_at.trim(),
+                operator: args.operator.trim(),
+                receipt_sha256: receiptSha,
+                receipt_path: resolved,
+                recorded_at: now,
+            };
+            const lifecycle = args.result === 'pass' ? 'verified' : args.result === 'fail' ? 'quarantined' : 'parsed';
+            const updated = {
+                ...record,
+                lifecycle,
+                receipts: [...(record.receipts ?? []), receiptRecord],
+                verification: {
+                    state: args.result === 'pass' ? 'verified' : args.result === 'fail' ? 'failed' : 'manual',
+                    queued_at: record.verification?.queued_at,
+                    updated_at: now,
+                    attempts: record.verification?.attempts ?? 0,
+                    last_result: args.result_code.trim(),
+                    manual_reason: args.result === 'unknown' ? 'unknown_result' : undefined,
+                },
+                updated_at: now,
+            };
+            await deps.table.put(record.doc_id, updated);
+            return { receipt_id: receiptRecord.receipt_id, receipt_sha256: receiptSha, duplicate: false, lifecycle };
+        },
+    });
+    return [ingest, parse, query, dedup, verify, receipt];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perrylink/dsh-einvoice",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "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",