4.1 KiB
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