427 lines
6.1 KiB
Markdown
427 lines
6.1 KiB
Markdown
# Task P.4.5.1 - PDF Visual Regression & Layout Validation
|
|
|
|
## Objective
|
|
|
|
Validate the visual quality of the new Product Item PDF template and establish a reusable visual regression framework for all future PDF document templates.
|
|
|
|
This task focuses on **rendered output**, not runtime logic.
|
|
|
|
The goal is to ensure that generated PDFs are visually correct, readable, stable, and production-ready across different data volumes.
|
|
|
|
No runtime architecture changes are expected.
|
|
|
|
---
|
|
|
|
# Prerequisites
|
|
|
|
Completed:
|
|
|
|
* Task P.4 Discovery
|
|
* Task P.4.1 Runtime Verification
|
|
* Task P.4.2 Runtime Architecture Design
|
|
* Task P.4.3 Runtime Refactoring
|
|
* Task P.4.3.1 Runtime Regression Stabilization
|
|
* Task P.4.4 Product Item Engine
|
|
* Task P.4.5 Product Item Template Version
|
|
|
|
Runtime audit must already pass.
|
|
|
|
---
|
|
|
|
# Scope
|
|
|
|
Included
|
|
|
|
* PDF visual validation
|
|
* Layout verification
|
|
* Table pagination verification
|
|
* Typography verification
|
|
* Overflow detection
|
|
* Alignment verification
|
|
* Visual regression baseline generation
|
|
* Golden PDF fixtures
|
|
* Screenshot comparison strategy
|
|
* Visual QA checklist
|
|
|
|
Excluded
|
|
|
|
* Runtime refactoring
|
|
* New template versions
|
|
* CRM UI
|
|
* Database changes
|
|
* API changes
|
|
* Render Policy UI
|
|
|
|
---
|
|
|
|
# Validation Matrix
|
|
|
|
Generate PDFs using at least the following datasets.
|
|
|
|
## Dataset A
|
|
|
|
```text
|
|
0 Product Items
|
|
```
|
|
|
|
Expected
|
|
|
|
* No rendering errors
|
|
* Empty-state behavior follows template design
|
|
* No broken layout
|
|
|
|
---
|
|
|
|
## Dataset B
|
|
|
|
```text
|
|
1 Product Item
|
|
```
|
|
|
|
Expected
|
|
|
|
* Single-row table
|
|
* Proper spacing
|
|
* Totals correctly aligned
|
|
|
|
---
|
|
|
|
## Dataset C
|
|
|
|
```text
|
|
4 Product Items
|
|
```
|
|
|
|
Expected
|
|
|
|
* Matches current UAT fixture
|
|
* No unnecessary page break
|
|
|
|
---
|
|
|
|
## Dataset D
|
|
|
|
```text
|
|
20 Product Items
|
|
```
|
|
|
|
Expected
|
|
|
|
* Product table spans multiple pages
|
|
* Table header repeats
|
|
* No overlapping rows
|
|
|
|
---
|
|
|
|
## Dataset E
|
|
|
|
```text
|
|
100 Product Items
|
|
```
|
|
|
|
Expected
|
|
|
|
* Stable pagination
|
|
* Header repeated correctly
|
|
* Footer not corrupted
|
|
* Signature page remains intact
|
|
|
|
---
|
|
|
|
## Dataset F
|
|
|
|
```text
|
|
Long Description
|
|
```
|
|
|
|
Use extremely long product descriptions.
|
|
|
|
Expected
|
|
|
|
* Dynamic row height
|
|
* No text clipping
|
|
* No column overlap
|
|
|
|
---
|
|
|
|
# Layout Verification
|
|
|
|
Validate
|
|
|
|
## Page Structure
|
|
|
|
Page 1
|
|
|
|
* Customer section
|
|
* Company header
|
|
* Quotation information
|
|
|
|
Page 2+
|
|
|
|
* Product Item table
|
|
|
|
Final Page
|
|
|
|
* Topics
|
|
* Conditions
|
|
* Signature
|
|
|
|
Verify page ordering.
|
|
|
|
---
|
|
|
|
## Table Validation
|
|
|
|
Verify
|
|
|
|
* Header repeats
|
|
* Borders remain continuous
|
|
* Cell padding
|
|
* Vertical spacing
|
|
* Horizontal alignment
|
|
* Numeric alignment
|
|
* Currency alignment
|
|
* Discount formatting
|
|
* Total formatting
|
|
|
|
---
|
|
|
|
## Typography
|
|
|
|
Verify
|
|
|
|
* Font consistency
|
|
* Font size
|
|
* Line spacing
|
|
* Thai text rendering
|
|
* English text rendering
|
|
* Mixed-language rendering
|
|
* Unicode support
|
|
|
|
---
|
|
|
|
## Overflow Detection
|
|
|
|
Verify no
|
|
|
|
* clipped text
|
|
* overlapping text
|
|
* hidden rows
|
|
* hidden borders
|
|
* truncated values
|
|
* broken page footer
|
|
* broken page header
|
|
|
|
---
|
|
|
|
## Signature Validation
|
|
|
|
Verify
|
|
|
|
* Signature block always remains together
|
|
* Signature names align with positions
|
|
* No signature split across pages
|
|
|
|
---
|
|
|
|
## Topic Validation
|
|
|
|
Verify
|
|
|
|
* Topic numbering
|
|
* Topic indentation
|
|
* Topic spacing
|
|
* Multi-page topics
|
|
* Topic continuation
|
|
|
|
---
|
|
|
|
## Product Item Validation
|
|
|
|
Verify
|
|
|
|
* Item numbering
|
|
* Quantity formatting
|
|
* Unit formatting
|
|
* Currency formatting
|
|
* Discount formatting
|
|
* Grand total
|
|
* Decimal precision
|
|
|
|
---
|
|
|
|
# Visual Regression Framework
|
|
|
|
Create reusable visual fixtures.
|
|
|
|
Examples
|
|
|
|
```text
|
|
fixtures/pdf-visual/
|
|
|
|
quotation-empty
|
|
|
|
quotation-single-item
|
|
|
|
quotation-standard
|
|
|
|
quotation-long-description
|
|
|
|
quotation-100-items
|
|
|
|
quotation-multi-topic
|
|
```
|
|
|
|
These fixtures become the baseline for future visual comparison.
|
|
|
|
---
|
|
|
|
# Golden PDF Baseline
|
|
|
|
Generate canonical PDFs for each fixture.
|
|
|
|
Store as reference outputs.
|
|
|
|
Future template changes must compare against these baselines.
|
|
|
|
---
|
|
|
|
# Screenshot Strategy
|
|
|
|
Generate page screenshots.
|
|
|
|
Compare
|
|
|
|
* page count
|
|
* page order
|
|
* layout
|
|
* table placement
|
|
* signature placement
|
|
|
|
Minor rendering differences should be configurable with tolerance.
|
|
|
|
---
|
|
|
|
# Visual QA Checklist
|
|
|
|
Each generated PDF must be checked for:
|
|
|
|
* Header alignment
|
|
* Logo position
|
|
* Company block alignment
|
|
* Customer block alignment
|
|
* Table borders
|
|
* Table header repetition
|
|
* Column widths
|
|
* Currency alignment
|
|
* Total alignment
|
|
* Topic spacing
|
|
* Signature spacing
|
|
* Footer alignment
|
|
* Page numbers (if applicable)
|
|
* Margins
|
|
* White space consistency
|
|
|
|
---
|
|
|
|
# Automated Validation
|
|
|
|
Extend audit tooling where practical.
|
|
|
|
Validate
|
|
|
|
* page count
|
|
* section order
|
|
* table presence
|
|
* repeated header
|
|
* signature section
|
|
* overflow detection
|
|
* clipping detection
|
|
* unexpected blank pages
|
|
|
|
---
|
|
|
|
# Manual Review Checklist
|
|
|
|
Review both
|
|
|
|
* ALLA
|
|
* ONVALLA
|
|
|
|
for
|
|
|
|
* Light data
|
|
* Heavy data
|
|
* Long text
|
|
* Thai language
|
|
* English language
|
|
* Mixed language
|
|
|
|
---
|
|
|
|
# Performance Validation
|
|
|
|
Generate
|
|
|
|
```text
|
|
500 Product Items
|
|
```
|
|
|
|
Verify
|
|
|
|
* generation time
|
|
* memory usage
|
|
* pagination stability
|
|
|
|
No runtime crashes.
|
|
|
|
---
|
|
|
|
# Deliverables
|
|
|
|
* Visual regression fixtures
|
|
* Golden PDF baselines
|
|
* Screenshot comparison assets
|
|
* Visual QA checklist
|
|
* Automated validation updates
|
|
* Manual review report
|
|
* Performance report
|
|
|
|
---
|
|
|
|
# Acceptance Criteria
|
|
|
|
* Every visual fixture renders successfully.
|
|
* Product table pagination is visually correct.
|
|
* Table headers repeat correctly.
|
|
* No clipping or overlapping text.
|
|
* Signature block remains intact.
|
|
* Topic layout remains correct.
|
|
* Thai and English render correctly.
|
|
* ALLA and ONVALLA templates pass visual review.
|
|
* Golden baseline PDFs are generated.
|
|
* Future visual regression testing is possible using the stored baselines.
|
|
|
|
---
|
|
|
|
# Out of Scope
|
|
|
|
## Task P.4.6
|
|
|
|
* CRM Template Version Management
|
|
* Version activation workflow
|
|
* Template rollback
|
|
* Template comparison UI
|
|
|
|
## Task P.4.7
|
|
|
|
* Optional section configuration
|
|
* User-selectable Product Table visibility
|
|
* Organization/customer render preferences
|
|
|
|
---
|
|
|
|
# Final Success Condition
|
|
|
|
Task P.4.5.1 is complete when the Product Item template is validated visually across all supported scenarios, a reusable visual regression baseline has been established, and future PDF template changes can be verified automatically against those baselines before release.
|