# ADR 0013: PDF Visual Parity Strategy

## Status

Accepted

## Context

The quotation PDF flow now includes:

- production PDFME templates per organization
- DB-backed mapping registry
- dynamic topic expansion
- approval signature resolution
- approved snapshot persistence

What was missing was a repeatable audit strategy proving that template schema, mappings, runtime payload, and approved snapshot content remain synchronized over time.

## Decision

- freeze a documented PDF mapping registry in `docs/business/pdf-mapping-registry.md`
- keep a human-readable parity checklist in `docs/implementation/pdf-parity-checklist.md`
- add an audit suite:
  - `audit-pdf-template-inventory`
  - `audit-pdf-mapping-coverage`
  - `audit-pdf-runtime-payload`
  - `generate-pdf-audit-report`
- expose the suite through `npm run audit:pdf`
- prefer the stable fixture quotation code `QT-H5-AUDIT` for repeatable audits when available
- compare preview runtime content against approved snapshot content for business-field consistency

## Visual Parity Rules

- allowed differences:
  - watermark state
  - generated timestamp
  - artifact metadata
- disallowed differences:
  - customer identity
  - quotation commercial values
  - topic content
  - signature identity
  - mapped table content

## Consequences

- regressions in template coverage become detectable without opening every PDF manually
- mapping ownership is explicit and reviewable
- future PDF changes must update both runtime logic and the registry/checklist when business content changes