325 lines
4.1 KiB
Markdown
325 lines
4.1 KiB
Markdown
# 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
|