513 lines
5.1 KiB
Markdown
513 lines
5.1 KiB
Markdown
# 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
|