Status:
accepted

Context:
Task H introduced server-side PDF generation for quotation preview, download, and approved-document persistence.
Task H.1 validated the full path with a real quotation fixture and confirmed that approved artifacts originally persisted to local disk under `public/generated/...`.
Task I introduces a storage-provider abstraction and a database-backed document artifact model so approved PDFs are no longer tied to raw public paths as the source of truth.

Decision:

- Use a storage provider abstraction for approved quotation PDFs.
- Support a local provider for development and an S3 / MinIO-compatible provider for production-oriented deployments.
- Persist approved-document metadata in `crm_document_artifacts`.
- Persist `approved_artifact_id` on the quotation row as the primary approved-artifact reference.
- Keep `approved_pdf_url` as a compatibility field and allow `artifact:<artifactId>` references during the migration period.
- Lock approved PDF artifacts after generation and treat them as immutable-first records.

Consequences:

- Approved PDF persistence no longer depends on raw `public/generated/...` paths as the system of record.
- Secure download routes can resolve artifacts from database metadata and storage-provider reads.
- Local storage remains acceptable for development, but production-oriented deployments can move to S3/MinIO-compatible object storage without changing the quotation flow contract.
- Legacy approved PDFs stored under `public/generated/...` still require explicit migration and remain a temporary compatibility burden.

Future:

- migrate legacy approved PDFs into `crm_document_artifacts`
- extend the storage abstraction to manual attachments as well as generated artifacts
- support signed URLs or another private delivery strategy where required
- define operator-facing void/replacement workflow for immutable approved artifacts
- add retention/cleanup policy for superseded or voided artifacts
- move approved-PDF generation to an async job when post-approval auto-generation is introduced