task-i

docs/implementation/task-h1-pdf-generation-stabilization.md

@@ -0,0 +1,122 @@
+# Task H.1: PDF Generation Stabilization
+
+## 1. Files Added
+
+- `scripts/seed-task-h1-fixture.js`
+- `scripts/verify-task-h1.js`
+- `docs/adr/0009-approved-document-storage-lifecycle.md`
+
+## 2. Files Modified
+
+- `package.json`
+- `docs/implementation/technical-debt.md`
+
+Task H.1 builds on the Task H PDF pipeline and focuses on validation, fixture support, documentation, and storage-lifecycle clarification.
+
+## 3. Smoke Test Record Used
+
+Added a dev-only fixture script for a real quotation scenario:
+
+- approved fixture code: `QT-TASK-H1-APPROVED`
+- draft fixture code: `QT-TASK-H1-DRAFT`
+- customer fixture code: `CUS-TASK-H1`
+
+Fixture script provisions:
+
+- organization-scoped customer and contact
+- approved quotation with item, customer role, scope/exclusion/payment topics, and completed approval history
+- draft quotation for negative approved-PDF validation
+- test users for permission checks
+
+## 4. PDF APIs Verified
+
+Task H.1 verification script covers:
+
+- `GET /api/crm/quotations/[id]/pdf-preview`
+- `GET /api/crm/quotations/[id]/pdf-download`
+- `POST /api/crm/quotations/[id]/approved-pdf`
+- `GET /api/crm/quotations/[id]/approved-pdf`
+
+Expected checks included:
+
+- preview responds as inline PDF
+- download responds as attachment PDF
+- approved-PDF POST succeeds for approved quotation
+- approved-PDF GET returns persisted artifact
+- non-approved quotation cannot generate approved PDF
+
+## 5. Persistence Verified
+
+Task H.1 verification targets:
+
+- `approvedPdfUrl`
+- `approvedSnapshot`
+- `approvedTemplateVersionId`
+- quotation attachment metadata row
+- audit log row
+- generated file under `public/generated/quotations/<organizationId>/`
+
+## 6. Permission Verified
+
+Fixture and verification support explicit checks for:
+
+- `super_admin`
+- admin workspace member
+- regular user with PDF permissions
+- regular user without PDF permissions
+
+Permissions covered:
+
+- `crm.quotation.pdf.preview`
+- `crm.quotation.pdf.download`
+- `crm.quotation.pdf.generate_approved`
+
+## 7. Error Handling / Hardening
+
+Task H.1 centered hardening around safe operational verification rather than a large refactor.
+
+The main stabilization additions were:
+
+- reusable dev fixture creation
+- repeatable HTTP verification script
+- clearer storage lifecycle documentation
+- explicit debt tracking for fonts, local storage, and approved-artifact policy
+
+## 8. ADR / Technical Debt Updated
+
+Added ADR:
+
+- `docs/adr/0009-approved-document-storage-lifecycle.md`
+
+Updated debt notes in:
+
+- `docs/implementation/technical-debt.md`
+
+Tracked concerns include:
+
+- font compatibility fallback
+- local filesystem storage limitation
+- approved artifact immutability policy
+- post-approval automation gap
+- missing CI-backed PDF E2E coverage
+
+## 9. Remaining Risks
+
+- approved PDF storage still uses local public filesystem semantics and is not production-grade object storage
+- approved artifact lifecycle is still not immutable by policy
+- PDF verification is script-based and not yet part of CI
+- task fixture scripts currently depend on a prepared local environment and seeded master-option / approval data
+
+## 10. Task I Readiness
+
+Task H.1 leaves the PDF flow better prepared for Task I by providing:
+
+- a repeatable quotation fixture path
+- a repeatable verification script
+- explicit storage-lifecycle decision documentation
+- visible technical-debt boundaries for future production hardening
+
+## 11. Verification Commands
+
+- `npm run seed:task-h1-fixture`
+- `npm run verify:task-h1`