# 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.
