pdf task-h

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