pdf task-h

plans/task-h.5.1.md

@@ -0,0 +1,324 @@
+# Task H.5.1: PDF Integrity Audit & Payload Parity
+
+## Objective
+
+Close all remaining PDFME reliability gaps before implementing signature capture.
+
+This task freezes:
+
+* template version integrity
+* placeholder naming integrity
+* runtime payload parity
+* preview/generator consistency
+
+and becomes the final audit layer before PDF feature freeze.
+
+---
+
+## 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/implementation/task-h51-pdf-integrity-audit.md
+
+* docs/business/pdf-placeholder-registry.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
+
+---
+
+# H5.12 Template Version Integrity Audit
+
+## Purpose
+
+Validate active template version consistency.
+
+Audit:
+
+* crm_document_templates
+* crm_document_template_versions
+* crm_document_template_mappings
+
+Checks:
+
+### Active Template
+
+Only one active template per:
+
+* documentType
+* productType
+* fileType
+
+### Active Version
+
+Only one active version per template.
+
+### Approved Snapshot Version
+
+Verify:
+
+approvedTemplateVersionId
+
+exists and remains valid.
+
+### Orphan Version Detection
+
+Detect:
+
+* deleted template
+* active version without template
+* mappings without version
+
+---
+
+# H5.13 Placeholder Integrity Audit
+
+## Purpose
+
+Detect naming issues before runtime generation.
+
+Audit:
+
+PDF schema field names
+
+against
+
+mapping registry.
+
+Checks:
+
+### Duplicate Placeholder
+
+Example:
+
+quotation_date
+quotation_date_data
+
+### Typo Detection
+
+Example:
+
+quotation_date_labe
+
+quotation_code_lable
+
+### Unmapped Placeholder
+
+Exists in template but not mapping table.
+
+### Dead Mapping
+
+Exists in mapping table but not template.
+
+### Reserved Dynamic Topic Names
+
+Validate:
+
+topic
+data_topic
+
+remain reserved template placeholders.
+
+Reject:
+
+topic_1
+item_topic_1
+
+being stored in mapping tables.
+
+---
+
+# H5.14 Runtime Payload Parity Audit
+
+## Purpose
+
+Ensure Preview PDF and Generated PDF use identical data.
+
+Audit:
+
+### Preview Payload
+
+Output from:
+
+buildInputs()
+
+### Runtime Payload
+
+Output from:
+
+prepareDocument()
+
+### Approved Snapshot Payload
+
+Output from:
+
+prepareApprovedQuotationSnapshot()
+
+Checks:
+
+* field count
+* field names
+* topic input keys
+* signature keys
+* exclusion data
+* quotation totals
+* customer values
+
+---
+
+# Payload Hash Validation
+
+Generate hash:
+
+SHA256(JSON.stringify(payload))
+
+Compare:
+
+preview hash
+generation hash
+snapshot hash
+
+Result:
+
+PASS
+FAIL
+
+---
+
+# H5.15 Dynamic Topic Runtime Audit
+
+## Purpose
+
+Validate Topic Engine behavior.
+
+Audit:
+
+* topic count
+* item count
+* page count
+* generated topic keys
+
+Expected:
+
+topic_0_0
+topic_0_1
+
+item_topic_0_0
+item_topic_0_1
+
+Checks:
+
+* duplicate keys
+* missing topic items
+* empty topic sections
+* page overflow risks
+
+---
+
+# H5.16 Signature Mapping Audit
+
+## Purpose
+
+Validate H.3 integration.
+
+Audit:
+
+app1
+app1_position
+
+app2
+app2_position
+
+app3
+app3_position
+
+Checks:
+
+* resolved name
+* resolved position
+* timestamp
+* snapshot persistence
+
+---
+
+# Reporting
+
+Generate:
+
+/artifacts/pdf-audit/
+
+* template-version-report.json
+* placeholder-integrity-report.json
+* payload-parity-report.json
+* topic-runtime-report.json
+* signature-audit-report.json
+* summary.md
+
+---
+
+# Acceptance Criteria
+
+PASS:
+
+* no orphan template version
+* no orphan mappings
+* no unresolved placeholder
+* no placeholder typo
+* preview payload = generation payload
+* generation payload = approved snapshot payload
+* dynamic topic keys generated correctly
+* signature fields resolved correctly
+
+FAIL:
+
+* any hash mismatch
+* unresolved placeholder
+* duplicate active version
+* orphan mapping
+* missing signature field
+
+---
+
+# Out of Scope
+
+* signature drawing
+* signature image upload
+* handwritten signature rendering
+* PDF screenshot comparison
+* OCR validation
+
+These belong to Task H.4.
+
+---
+
+# Deliverable
+
+After completion:
+
+PDF Layer Status = Frozen
+
+Ready for:
+
+Task H.4 Signature Capture
+Task K Report Center
+Task L Approved Document Archive