# 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`