pdf task-h

docs/implementation/pdf-audit-report.json

@@ -0,0 +1,69 @@
+{
+  "generatedAt": "2026-06-19T07:44:58.283Z",
+  "overallStatus": "WARNING",
+  "quotationCode": "QT-H5-AUDIT",
+  "expectedFixtureCode": "QT-H5-AUDIT",
+  "template": {
+    "templateName": "ALLA Quotation Standard",
+    "version": "1.0",
+    "versionId": "4ac3e91c-8320-4f41-81cd-5068cc9b5768",
+    "fieldCount": 46,
+    "duplicateFields": [],
+    "unknownFields": [
+      "line"
+    ]
+  },
+  "metrics": {
+    "topicCount": 5,
+    "itemCount": 3,
+    "partyCount": 3,
+    "dynamicTopicFieldCount": 5,
+    "dynamicTopicItemFieldCount": 5,
+    "mappingCount": 19
+  },
+  "mappingCoverage": {
+    "placeholderTokenCount": 13,
+    "unmappedTokens": [],
+    "orphanMappings": [],
+    "itemTableColumns": [
+      {
+        "columnName": "Item",
+        "sourceField": "itemNumber"
+      },
+      {
+        "columnName": "Description",
+        "sourceField": "description"
+      },
+      {
+        "columnName": "Qty",
+        "sourceField": "quantity"
+      },
+      {
+        "columnName": "Unit",
+        "sourceField": "unitLabel"
+      },
+      {
+        "columnName": "Unit Price",
+        "sourceField": "unitPrice"
+      },
+      {
+        "columnName": "Total",
+        "sourceField": "totalPrice"
+      }
+    ]
+  },
+  "runtimePayload": {
+    "templateInputKeys": 31,
+    "topicInputKeys": 10
+  },
+  "consistency": {
+    "status": "WARNING",
+    "approvedSnapshotAvailable": false,
+    "approvedArtifactReference": null,
+    "inconsistentKeys": []
+  },
+  "integritySummary": {
+    "available": true,
+    "artifactDir": "C:\\Users\\mtpphtaps\\Documents\\gitea\\alla-allaos-fullstack\\artifacts\\pdf-audit"
+  }
+}

docs/implementation/pdf-audit-report.md

@@ -0,0 +1,30 @@
+# PDF Audit Report
+
+- Generated At: 2026-06-19T07:44:58.283Z
+- Overall Status: WARNING
+- Quotation Code: QT-H5-AUDIT
+- Template: ALLA Quotation Standard v1.0
+
+## Metrics
+
+- Topic Count: 5
+- Item Count: 3
+- Project Party Count: 3
+- Mapping Count: 19
+
+## Mapping Coverage
+
+- Placeholder Tokens: 13
+- Unmapped Tokens: None
+- Orphan Mappings: None
+
+## Visual / Consistency
+
+- Approved Snapshot Available: No
+- Consistency Status: WARNING
+- Inconsistent Keys: None
+
+## Integrity Layer
+
+- Integrity Summary Available: Yes
+- Artifact Directory: C:\Users\mtpphtaps\Documents\gitea\alla-allaos-fullstack\artifacts\pdf-audit

docs/implementation/pdf-parity-checklist.md

@@ -0,0 +1,37 @@
+# PDF Parity Checklist
+
+## Header
+
+| Area | Expectation | Status |
+| --- | --- | --- |
+| Company block | Static company branding and contact text render from template | Partial |
+| Customer block | `customer_name`, `customer_addr`, `customer_tel`, `customer_email`, `customer_att` render from mapping registry | Match |
+| Document references | `quotation_code`, `quotation_date`, `project_name`, `site_location` render from live quotation data | Match |
+
+## Commercial Body
+
+| Area | Expectation | Status |
+| --- | --- | --- |
+| Items | `items_table` columns stay aligned with quotation item rows and totals | Match |
+| Topics | Dynamic topic engine expands `topic_*` / `item_topic_*` in order | Match |
+| Exclusion block | `exclusion_data` renders as `string[][]` table payload | Match |
+| Price summary | `quotation_price` and `currency` use formatted runtime values | Match |
+
+## Approval / Footer
+
+| Area | Expectation | Status |
+| --- | --- | --- |
+| Signatures | `app1/app2/app3` map to prepared/approved/authorized blocks | Match |
+| Signature placement | Closing block stays together after dynamic topic pagination | Partial |
+| Footer copy | Static footer text and closing statement remain template-owned | Match |
+
+## Visual Parity Rules
+
+- `Match` means the current PDF runtime has a verified mapping path and auditable payload.
+- `Partial` means the business data path is correct but final pixel-perfect comparison still needs manual screenshot review against the legacy CRM PDF.
+- `Missing` should only be used when a field or section has no runtime path.
+
+## Integrity Freeze
+
+- `npm run audit:pdf` is the integrity gate for template, placeholder, payload, topic runtime, and snapshot parity.
+- `QT-H5-AUDIT` is the preferred fixture for repeatable PDF audits.

docs/implementation/task-h5-pdf-mapping-audit-visual-parity.md

@@ -0,0 +1,36 @@
+# Task H.5: PDF Mapping Audit & Visual Parity
+
+## Files Added
+
+- `scripts/pdf-audit-utils.ts`
+- `scripts/audit-pdf-template-inventory.ts`
+- `scripts/audit-pdf-mapping-coverage.ts`
+- `scripts/audit-pdf-runtime-payload.ts`
+- `scripts/generate-pdf-audit-report.ts`
+- `docs/implementation/pdf-parity-checklist.md`
+- `docs/business/pdf-mapping-registry.md`
+- `docs/adr/0013-pdf-visual-parity-strategy.md`
+- `docs/implementation/task-h5-pdf-mapping-audit-visual-parity.md`
+
+## Files Modified
+
+- `package.json`
+- `scripts/seed-task-h1-fixture.js`
+
+## Audit Coverage
+
+- template inventory audit scans active template versions, schema field names, table fields, dynamic topic fields, duplicates, missing mappings, and orphan mappings
+- mapping coverage audit compares placeholder tokens with DB mappings and table-column metadata
+- runtime payload audit inspects resolved `documentData`, `templateInput`, and `pdfme.topic_inputs`
+- report generator writes JSON and Markdown summary artifacts for regression review
+
+## Fixture Strategy
+
+- `seed-task-h1-fixture.js` now also provisions `QT-H5-AUDIT`
+- the audit fixture is intended to carry richer topic/item/party coverage than the original H.1 smoke dataset
+
+## Remaining Risks
+
+- approved snapshot parity remains a warning when the target quotation has never generated an approved PDF artifact
+- the audit suite validates business payload parity, not pixel-perfect PDF screenshots
+- manual review is still needed when template designers move static labels or brand blocks

docs/implementation/task-h51-pdf-integrity-audit.md

@@ -0,0 +1,40 @@
+# Task H.5.1: PDF Integrity Audit & Payload Parity
+
+## Files Added
+
+- `scripts/audit-template-version-integrity.ts`
+- `scripts/audit-placeholder-integrity.ts`
+- `scripts/audit-payload-parity.ts`
+- `scripts/audit-approved-snapshot-parity.ts`
+- `scripts/generate-pdf-integrity-report.ts`
+- `docs/business/pdf-placeholder-registry.md`
+- `docs/implementation/task-h51-pdf-integrity-audit.md`
+
+## Files Modified
+
+- `package.json`
+- `scripts/generate-pdf-audit-report.ts`
+- `docs/implementation/pdf-parity-checklist.md`
+- `docs/business/pdf-mapping-registry.md`
+- `docs/implementation/technical-debt.md`
+- `scripts/pdf-audit-utils.ts`
+
+## Integrity Coverage
+
+- template-version integrity checks active template uniqueness, active version uniqueness, orphan mappings, and approved template-version references
+- placeholder integrity checks duplicate names, typo-like names, unmapped placeholders, dead mappings, and reserved dynamic topic names
+- payload parity computes SHA256 hashes for preview, generation, and computed snapshot payloads
+- approved snapshot parity compares stored snapshot payloads against computed snapshot payloads when they exist
+- integrity summary writes machine-readable artifacts into `artifacts/pdf-audit/`
+
+## Verification Result
+
+- `npx tsc --noEmit` passed
+- `npm run audit:pdf` runs the full H.5 + H.5.1 stack
+- current integrity result is expected to be `WARNING` when the audit fixture has not yet generated a persisted approved snapshot/artifact
+
+## Remaining Risks
+
+- stored approved snapshot parity still depends on generating a real approved PDF artifact for `QT-H5-AUDIT`
+- template field `line` is still treated as a tolerated designer-owned oddity rather than a normalized mapping field
+- the audit stack validates payload integrity and runtime parity, not screenshot-level pixel parity

docs/implementation/technical-debt.md

@@ -212,6 +212,7 @@ Future:
 
 - keep validating pagination and closing-block placement against production designer expectations for large topic sets
 - add fixture-backed end-to-end PDF generation verification in CI once a stable runtime path is available
+- decide whether static template field `line` should remain a tolerated designer-only artifact or be normalized in future audits
 
 ## After Task I