pdf task-h

docs/adr/0013-pdf-visual-parity-strategy.md

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