task-p4.5.1

plans/task-p.4.5.1.md

@@ -0,0 +1,426 @@
+# 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.