pdf task-h

2026-06-19 15:09:58 +07:00
parent a85d24235c
commit fd01ebf7c7
35 changed files with 3905 additions and 133 deletions
--- a/plans/task-h.5.1.md
+++ b/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
--- a/plans/task-h.5.md
+++ b/plans/task-h.5.md
@@ -0,0 +1,512 @@
+# Task H.5: PDF Mapping Audit & Visual Parity
+
+## Goal
+
+ทำ Audit PDFME ทั้งระบบเพื่อให้ผลลัพธ์ PDF ของ ALLA OS มีความถูกต้องและใกล้เคียงกับระบบ CRM เดิมมากที่สุด
+
+Focus:
+
+* Mapping Accuracy
+* Runtime Data Completeness
+* Topic Rendering
+* Table Rendering
+* Signature Placement
+* Visual Parity
+
+Task นี้ยังไม่เพิ่ม Feature ใหม่
+
+Task นี้เน้น:
+
+```txt
+Correctness
+Consistency
+Regression Detection
+```
+
+---
+
+# Background
+
+Task H.2 delivered:
+
+```txt
+Dynamic Topic Engine
+Topic Runtime Expansion
+PDFME Mapping Hotfix
+```
+
+Task H.3 delivered:
+
+```txt
+Prepared By
+Approved By
+Authorized By
+```
+
+However:
+
+There is still no formal audit process proving that:
+
+```txt
+Template Schema
+Mappings
+Document Data
+PDF Input
+Rendered Output
+```
+
+remain synchronized.
+
+---
+
+# Scope H5.1 Template Inventory Audit
+
+Create:
+
+```txt
+scripts/audit-pdf-template-inventory.ts
+```
+
+Purpose:
+
+Scan every active template version.
+
+Output:
+
+```txt
+Template Name
+Version
+Schema Fields
+Table Fields
+Dynamic Topic Fields
+Unknown Fields
+Duplicate Fields
+```
+
+Detect:
+
+```txt
+missing mappings
+orphan mappings
+duplicate mappings
+```
+
+---
+
+# Scope H5.2 Mapping Coverage Audit
+
+Create:
+
+```txt
+scripts/audit-pdf-mapping-coverage.ts
+```
+
+Audit:
+
+```txt
+crm_document_template_mappings
+crm_document_template_table_columns
+```
+
+Verify:
+
+Every PDFME field belongs to:
+
+```txt
+mapped field
+dynamic topic field
+system field
+```
+
+Flag:
+
+```txt
+unmapped field
+```
+
+Examples:
+
+```txt
+customer_att
+quotation_date
+quotation_price
+topic
+data_topic
+app1
+app2
+app3
+```
+
+---
+
+# Scope H5.3 Runtime Payload Audit
+
+Create:
+
+```txt
+scripts/audit-pdf-runtime-payload.ts
+```
+
+Generate:
+
+```txt
+documentData
+templateInput
+pdfme.topic_inputs
+```
+
+Audit:
+
+```txt
+undefined
+null
+empty string
+invalid arrays
+```
+
+Output:
+
+```txt
+field
+value
+source
+status
+```
+
+---
+
+# Scope H5.4 Dynamic Topic Audit
+
+Audit:
+
+```txt
+crm_quotation_topics
+crm_quotation_topic_items
+```
+
+Verify:
+
+```txt
+topic
+data_topic
+topic_1_0
+item_topic_1_0
+topic_1_1
+item_topic_1_1
+...
+```
+
+Rules:
+
+```txt
+no orphan topic
+no orphan topic item
+no duplicate topic section
+```
+
+Verify:
+
+Multi-page expansion.
+
+---
+
+# Scope H5.5 Table Audit
+
+Audit:
+
+```txt
+quotation items
+```
+
+Verify:
+
+```txt
+description
+qty
+unit
+unit price
+discount
+amount
+```
+
+Match:
+
+```txt
+crm_quotation_items
+```
+
+Ensure:
+
+```txt
+table rows
+table columns
+totals
+```
+
+remain synchronized.
+
+---
+
+# Scope H5.6 Legacy CRM Comparison
+
+Create:
+
+```txt
+docs/implementation/pdf-parity-checklist.md
+```
+
+Compare against:
+
+Legacy CRM PDF.
+
+Checklist:
+
+```txt
+Header
+Customer Block
+Project Block
+Items
+Topics
+Price Summary
+Signatures
+Footer
+```
+
+Status:
+
+```txt
+Match
+Partial
+Missing
+```
+
+---
+
+# Scope H5.7 Visual Parity Screenshots
+
+Create:
+
+```txt
+scripts/generate-pdf-audit-report.ts
+```
+
+Generate:
+
+```txt
+PDF Audit JSON
+PDF Audit Markdown
+```
+
+Include:
+
+```txt
+template version
+quotation id
+topic count
+item count
+field count
+```
+
+Purpose:
+
+Future regression testing.
+
+---
+
+# Scope H5.8 Mapping Registry Freeze
+
+Create:
+
+```txt
+docs/business/pdf-mapping-registry.md
+```
+
+Document:
+
+```txt
+PDF Field
+Source Path
+Transform
+Example Value
+```
+
+Examples:
+
+```txt
+quotation_date
+quotation.quotationDate
+formatPdfDate()
+
+quotation_price
+quotation.totalAmount
+formatPdfCurrency()
+
+customer_att
+quotation.attention
+
+topic
+dynamic topic engine
+
+app1
+signature.preparedBy.name
+```
+
+This becomes the source of truth.
+
+---
+
+# Scope H5.9 Preview / Approved Consistency
+
+Verify:
+
+```txt
+Preview PDF
+Approved Snapshot
+Approved PDF
+```
+
+must produce identical business content.
+
+Differences allowed:
+
+```txt
+watermark
+generated timestamp
+artifact metadata
+```
+
+Everything else:
+
+```txt
+must match
+```
+
+---
+
+# Scope H5.10 Regression Fixture
+
+Expand:
+
+```txt
+seed-task-h1-fixture.js
+```
+
+Create:
+
+```txt
+QT-H5-AUDIT
+```
+
+Contains:
+
+```txt
+multiple topics
+multiple topic items
+multiple project parties
+multiple quotation items
+approval history
+```
+
+Purpose:
+
+Stable audit dataset.
+
+---
+
+# Scope H5.11 Verification
+
+Create:
+
+```txt
+npm run audit:pdf
+```
+
+Runs:
+
+```txt
+audit-pdf-template-inventory
+audit-pdf-mapping-coverage
+audit-pdf-runtime-payload
+generate-pdf-audit-report
+```
+
+Output:
+
+```txt
+PASS
+WARNING
+FAIL
+```
+
+---
+
+# ADR
+
+Create:
+
+```txt
+docs/adr/0013-pdf-visual-parity-strategy.md
+```
+
+Freeze:
+
+```txt
+PDF Mapping Registry
+Audit Process
+Visual Parity Rules
+Preview vs Approved Consistency
+```
+
+---
+
+# Explicit Non-Scope
+
+Do NOT implement:
+
+```txt
+signature image
+draw signature
+digital signature
+template designer rewrite
+new PDF engine
+```
+
+Those belong to later tasks.
+
+---
+
+# Output
+
+1. Files Added
+2. Files Modified
+3. Mapping Coverage Result
+4. Runtime Payload Result
+5. Topic Audit Result
+6. Table Audit Result
+7. Visual Parity Result
+8. ADR Added
+9. Remaining Risks
+
+---
+
+# Definition of Done
+
+✔ Every active PDF field mapped
+
+✔ No orphan mappings
+
+✔ No unresolved placeholders
+
+✔ Dynamic topics verified
+
+✔ Quotation table verified
+
+✔ Preview and approved PDF consistent
+
+✔ Mapping registry documented
+
+✔ Audit command available
+
+✔ Visual parity checklist completed
+
+✔ ADR created