# 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