alla-allaos-fullstack/docs/implementation/task-h1-pdf-generation-stabilization.md

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