alla-allaos-fullstack/plans/task-h.5.md

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 นี้เน้น:

Correctness
Consistency
Regression Detection

---

Background

Task H.2 delivered:

Dynamic Topic Engine
Topic Runtime Expansion
PDFME Mapping Hotfix

Task H.3 delivered:

Prepared By
Approved By
Authorized By

However:

There is still no formal audit process proving that:

Template Schema
Mappings
Document Data
PDF Input
Rendered Output

remain synchronized.

---

Scope H5.1 Template Inventory Audit

Create:

scripts/audit-pdf-template-inventory.ts

Purpose:

Scan every active template version.

Output:

Template Name
Version
Schema Fields
Table Fields
Dynamic Topic Fields
Unknown Fields
Duplicate Fields

Detect:

missing mappings
orphan mappings
duplicate mappings

---

Scope H5.2 Mapping Coverage Audit

Create:

scripts/audit-pdf-mapping-coverage.ts

Audit:

crm_document_template_mappings
crm_document_template_table_columns

Verify:

Every PDFME field belongs to:

mapped field
dynamic topic field
system field

Flag:

unmapped field

Examples:

customer_att
quotation_date
quotation_price
topic
data_topic
app1
app2
app3

---

Scope H5.3 Runtime Payload Audit

Create:

scripts/audit-pdf-runtime-payload.ts

Generate:

documentData
templateInput
pdfme.topic_inputs

Audit:

undefined
null
empty string
invalid arrays

Output:

field
value
source
status

---

Scope H5.4 Dynamic Topic Audit

Audit:

crm_quotation_topics
crm_quotation_topic_items

Verify:

topic
data_topic
topic_1_0
item_topic_1_0
topic_1_1
item_topic_1_1
...

Rules:

no orphan topic
no orphan topic item
no duplicate topic section

Verify:

Multi-page expansion.

---

Scope H5.5 Table Audit

Audit:

quotation items

Verify:

description
qty
unit
unit price
discount
amount

Match:

crm_quotation_items

Ensure:

table rows
table columns
totals

remain synchronized.

---

Scope H5.6 Legacy CRM Comparison

Create:

docs/implementation/pdf-parity-checklist.md

Compare against:

Legacy CRM PDF.

Checklist:

Header
Customer Block
Project Block
Items
Topics
Price Summary
Signatures
Footer

Status:

Match
Partial
Missing

---

Scope H5.7 Visual Parity Screenshots

Create:

scripts/generate-pdf-audit-report.ts

Generate:

PDF Audit JSON
PDF Audit Markdown

Include:

template version
quotation id
topic count
item count
field count

Purpose:

Future regression testing.

---

Scope H5.8 Mapping Registry Freeze

Create:

docs/business/pdf-mapping-registry.md

Document:

PDF Field
Source Path
Transform
Example Value

Examples:

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:

Preview PDF
Approved Snapshot
Approved PDF

must produce identical business content.

Differences allowed:

watermark
generated timestamp
artifact metadata

Everything else:

must match

---

Scope H5.10 Regression Fixture

Expand:

seed-task-h1-fixture.js

Create:

QT-H5-AUDIT

Contains:

multiple topics
multiple topic items
multiple project parties
multiple quotation items
approval history

Purpose:

Stable audit dataset.

---

Scope H5.11 Verification

Create:

npm run audit:pdf

Runs:

audit-pdf-template-inventory
audit-pdf-mapping-coverage
audit-pdf-runtime-payload
generate-pdf-audit-report

Output:

PASS
WARNING
FAIL

---

ADR

Create:

docs/adr/0013-pdf-visual-parity-strategy.md

Freeze:

PDF Mapping Registry
Audit Process
Visual Parity Rules
Preview vs Approved Consistency

---

Explicit Non-Scope

Do NOT implement:

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