alla-allaos-fullstack/docs/adr/0013-pdf-visual-parity-strategy.md

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