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

package/README.md

@@ -1,9 +1,8 @@
 # @perrylink/dsh-einvoice
 
-File-level Chinese e-invoice ingest, parse and pool for DeepSeek Harness (SKU-04 S1).
+File-level Chinese e-invoice (OFD/XML) ingest, parse, dedup and local archive for DeepSeek Harness.
 
-> **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.
+> **Status: alpha / public-synthetic / partial / not counted / not GA.** No customer evidence, customer data, or production-readiness claim. All acceptance rows are `counted=false`.
 
 ## Install
 
@@ -12,60 +11,61 @@ dsh plugin --profile <profile> add @perrylink/dsh-einvoice
 dsh --profile <profile> --dump-config | grep dsh-einvoice
 ```
 
-The bundle inserts one Host row. It requires the base profile's `tools` and `storageDomain` services and a configured storage backend (the shipped base profile uses `storage-json`).
+Requires DSH `>=0.2.1-rc.3 <0.3.0` and Node `>=24.9 <25`.
 
-## Tools (S1)
+<details>
+<summary>中文摘要</summary>
+
+文件级中国电子发票（OFD/XML）入库、解析、去重与本地归档。 安装：`dsh plugin --profile <profile> add @perrylink/dsh-einvoice`。公开/合成、alpha、非 GA。
+
+</details>
+
+## Tools
 
 | Tool | What it does | Risk |
 |---|---|---|
-| `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.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.ingest` | Ingest one local OFD/XML, compute SHA-256, store the original, idempotent by bytes | R1 local write |
+| `invoice.parse` | Parse old OFD `Attachs/original_invoice.xml` or 数电票 `Tags/CustomTag.xml`; return eight fields, lines, evidence and unknown fields | R0 |
+| `invoice.query` | Query the local pool by entity, period, lifecycle or text | R0 |
+| `invoice.dedup` | Group duplicates by invoice number or seller + date + total | R0 |
+| `invoice.review_queue` | Queue parsed invoices for manual local review; optional buyer-tax-id mismatch flags | R1 local write |
+| `invoice.record_receipt` | Hash a local receipt, append it and move lifecycle; `verification_source=local_receipt`, `tax_verified=false` | R1 local write |
+| `invoice.redlink` | Bind a negative red invoice to its blue invoice and 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`.
+## Input / output
 
-S3 adds red/blue matching, deterministic archive packages, check and restore. S2 verification is manual/local (no tax-bureau network call).
+**Input:** one local OFD/XML invoice per `invoice.ingest` call. **Output:** a local invoice pool, review/receipt state, red/blue links, and a deterministic archive ZIP. `invoice.check` verifies the archive; `invoice.restore` restores it locally.
 
 ## Configuration
 
 | Env | Default | Meaning |
 |---|---|---|
 | `DSH_EINVOICE_HOME` | `$DSH_HOME/storages/dsh-einvoice` | originals directory and local pool base |
-| `DSH_EINVOICE_INPUT_ROOTS` | current working directory | `path.delimiter`-separated allowlist for `invoice.ingest` |
+| `DSH_EINVOICE_INPUT_ROOTS` | `current working directory` | `path.delimiter`-separated allowlist for `invoice.ingest` |
 
-No credentials, no network, no IMAP/OCR in S1.
+## Limits / non-claims
 
-## Limitations
+- No OCR/scanning, tax-bureau verification/receipt, tax filing, 30-year archive compliance, or real-invoice accuracy claim.
+- `invoice.record_receipt` is local-only: `verification_source=local_receipt`, `tax_verified=false`.
+- No IMAP/email fetching, ERP posting, e-signature legal opinion, or Client UI.
+- S1 accepts one local file per `invoice.ingest`; directory batches are not part of this package.
+- Public samples with PII are kept outside the tarball; do not paste raw invoice output into logs or public issues.
+- No customer evidence, customer data, or production-readiness claim; all fixtures are public/synthetic.
 
-- No IMAP/email fetching, OCR engine, tax-bureau verification, ERP posting, e-signature legal opinion, or Client UI.
-- S1 accepts one local file per `invoice.ingest` call; directory batches are S2.
-- `unknown_fields`/`field_evidence` are stored locally and may contain the same sensitive fields as the invoice; keep the pool local and do not paste raw output into logs or public issues.
-- Public samples with PII are kept in `.tmp` only; they are not shipped in the tarball.
+## Public sample
 
-## Failure paths
-
-Errors are thrown as `E_INV_*` (`E_INV_FILE_UNREADABLE`, `E_INV_PATH_NOT_ALLOWED`, `E_INV_OFD_UNSUPPORTED`, `E_INV_XML_SCHEMA_DRIFT`, `E_INV_FIELD_MISSING`, `E_INV_DOC_NOT_FOUND`, `E_INV_DUP_CONFLICT`, `E_INV_STORAGE_FAILED`, `E_INV_UNKNOWN_IMPL`). DSH renders thrown errors as tool errors; they are not returned as successful `{ok:false}` values.
+Synthetic invoice XML/OFD fixtures; `ACCEPTANCE.csv` lists 7 public checks (one is `out_of_scope`). No real invoice is included.
 
 ## Development
 
 ```sh
 pnpm install --frozen-lockfile
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm gate:sku04
+pnpm build && pnpm lint && pnpm typecheck && pnpm test && pnpm gate:sku04
 ```
 
-See `docs/architecture.md`, `docs/plugin-development.md`, `docs/configuration.md`, `FIXTURES.md`, `BUILD-PLAN-04.md`.
-
 ## License
 
-Apache-2.0. Third-party notices in `NOTICE` and `THIRD-PARTY-NOTICES`.
+Apache-2.0. See `LICENSE`, `NOTICE`, `THIRD-PARTY-NOTICES`.

package/lib/plugin/storage.d.ts

@@ -17,10 +17,10 @@ export declare const lineSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const verificationSchema: z.ZodObject<{
     state: z.ZodEnum<{
-        verified: "verified";
-        pending: "pending";
         failed: "failed";
         manual: "manual";
+        pending: "pending";
+        verified: "verified";
     }>;
     queued_at: z.ZodOptional<z.ZodString>;
     updated_at: z.ZodOptional<z.ZodString>;
@@ -32,8 +32,8 @@ export declare const receiptSchema: z.ZodObject<{
     receipt_id: z.ZodString;
     result_code: z.ZodString;
     result: z.ZodEnum<{
-        pass: "pass";
         fail: "fail";
+        pass: "pass";
         unknown: "unknown";
     }>;
     verified_at: z.ZodString;
@@ -45,8 +45,8 @@ export declare const receiptSchema: z.ZodObject<{
 export declare const redlinkSchema: z.ZodObject<{
     blue_id: z.ZodString;
     mode: z.ZodEnum<{
-        manual: "manual";
         auto: "auto";
+        manual: "manual";
     }>;
     amount_delta_cents: z.ZodNumber;
     tax_delta_cents: z.ZodNumber;
@@ -86,18 +86,18 @@ export declare const invoiceSchema: z.ZodObject<{
     unknown_fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     parser_version: z.ZodString;
     lifecycle: z.ZodEnum<{
-        received: "received";
-        parsed: "parsed";
-        verified: "verified";
         archived: "archived";
+        parsed: "parsed";
         quarantined: "quarantined";
+        received: "received";
+        verified: "verified";
     }>;
     verification: z.ZodOptional<z.ZodObject<{
         state: z.ZodEnum<{
-            verified: "verified";
-            pending: "pending";
             failed: "failed";
             manual: "manual";
+            pending: "pending";
+            verified: "verified";
         }>;
         queued_at: z.ZodOptional<z.ZodString>;
         updated_at: z.ZodOptional<z.ZodString>;
@@ -109,8 +109,8 @@ export declare const invoiceSchema: z.ZodObject<{
         receipt_id: z.ZodString;
         result_code: z.ZodString;
         result: z.ZodEnum<{
-            pass: "pass";
             fail: "fail";
+            pass: "pass";
             unknown: "unknown";
         }>;
         verified_at: z.ZodString;
@@ -122,8 +122,8 @@ export declare const invoiceSchema: z.ZodObject<{
     redlink: z.ZodOptional<z.ZodObject<{
         blue_id: z.ZodString;
         mode: z.ZodEnum<{
-            manual: "manual";
             auto: "auto";
+            manual: "manual";
         }>;
         amount_delta_cents: z.ZodNumber;
         tax_delta_cents: z.ZodNumber;
@@ -159,6 +159,7 @@ export declare const finInvoiceSpec: {
             doc_id: string;
             entity_id: string;
             invoice_no: string;
+            invoice_code?: string | undefined;
             issue_date: string;
             buyer: {
                 name: string;
@@ -175,9 +176,9 @@ export declare const finInvoiceSpec: {
             lines: {
                 line_no: number;
                 description: string;
-                amount_cents: number;
                 quantity?: string | undefined;
                 unit_price_cents?: number | undefined;
+                amount_cents: number;
                 tax_rate?: string | undefined;
                 tax_cents?: number | undefined;
             }[];
@@ -185,28 +186,19 @@ export declare const finInvoiceSpec: {
             field_evidence: Record<string, string>;
             unknown_fields: Record<string, unknown>;
             parser_version: string;
-            lifecycle: "received" | "parsed" | "verified" | "archived" | "quarantined";
-            source_path: string;
-            source_sha256: string;
-            source_size: number;
-            created_at: string;
-            updated_at: string;
-            run_id: string;
-            actor: string;
-            evidence_sha256: string;
-            invoice_code?: string | undefined;
+            lifecycle: "archived" | "parsed" | "quarantined" | "received" | "verified";
             verification?: {
-                state: "verified" | "pending" | "failed" | "manual";
-                attempts: number;
+                state: "failed" | "manual" | "pending" | "verified";
                 queued_at?: string | undefined;
                 updated_at?: string | undefined;
+                attempts: number;
                 last_result?: string | undefined;
                 manual_reason?: string | undefined;
             } | undefined;
             receipts?: {
                 receipt_id: string;
                 result_code: string;
-                result: "pass" | "fail" | "unknown";
+                result: "fail" | "pass" | "unknown";
                 verified_at: string;
                 operator: string;
                 receipt_sha256: string;
@@ -215,14 +207,22 @@ export declare const finInvoiceSpec: {
             }[] | undefined;
             redlink?: {
                 blue_id: string;
-                mode: "manual" | "auto";
+                mode: "auto" | "manual";
                 amount_delta_cents: number;
                 tax_delta_cents: number;
+                allocation_cents?: number | undefined;
                 bound_at: string;
                 bound_by: string;
-                allocation_cents?: number | undefined;
             } | undefined;
+            source_path: string;
             source_name?: string | undefined;
+            source_sha256: string;
+            source_size: number;
+            created_at: string;
+            updated_at: string;
+            run_id: string;
+            actor: string;
+            evidence_sha256: string;
         }>;
     };
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@perrylink/dsh-einvoice",
-  "version": "0.2.0-alpha.0",
-  "description": "File-level Chinese e-invoice (OFD/XML) ingest, parse and pool for DeepSeek Harness (SKU-04 S1).",
+  "version": "0.2.0-alpha.2",
+  "description": "File-level Chinese e-invoice (OFD/XML) ingest, parse, dedup and local archive.",
   "type": "module",
   "main": "./lib/plugin/index.js",
   "types": "./lib/plugin/index.d.ts",
@@ -45,7 +45,8 @@
     "einvoice",
     "invoice",
     "ofd",
-    "perrylink"
+    "perrylink",
+    "finance"
   ],
   "repository": {
     "type": "git",
@@ -79,6 +80,10 @@
     "@deepseek-ai/dsh-util-values": "0.2.1-rc.3",
     "@deepseek-ai/schemastery": "3.18.5",
     "@types/node": "^24.0.0",
-    "typescript": "5.9.3"
+    "typescript": "7.0.2"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-einvoice#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-einvoice/issues"
   }
 }