# Task I: Storage Abstraction and Approved Artifact Lifecycle

## 1. Files Added

- `src/features/foundation/storage/types.ts`
- `src/features/foundation/storage/service.ts`
- `src/features/foundation/storage/server/local-provider.ts`
- `src/features/foundation/storage/server/s3-provider.ts`
- `src/features/foundation/storage/server/provider.ts`
- `src/features/foundation/storage/server/checksum.ts`
- `src/features/foundation/document-artifact/server/service.ts`
- `src/app/api/crm/document-artifacts/[id]/download/route.ts`
- `drizzle/0009_lazy_shard.sql`
- `drizzle/meta/0009_snapshot.json`

## 2. Files Modified

- `package.json`
- `package-lock.json`
- `src/db/schema.ts`
- `src/lib/auth/rbac.ts`
- `src/features/foundation/pdf-generator/server/service.ts`
- `src/features/foundation/approval/server/service.ts`
- `src/features/crm/quotations/api/types.ts`
- `src/features/crm/quotations/server/service.ts`
- `src/features/crm/quotations/components/quotation-detail.tsx`
- `src/app/api/crm/quotations/[id]/approved-pdf/route.ts`
- `scripts/seed-task-h1-fixture.js`
- `docs/implementation/technical-debt.md`
- `docs/adr/0009-approved-document-storage-lifecycle.md`

## 3. Storage Provider Added

Added a storage foundation under `src/features/foundation/storage/**`.

Providers:

- local provider for development
- S3 / MinIO-compatible provider for production-oriented storage

Configuration supported:

- `STORAGE_PROVIDER`
- `LOCAL_STORAGE_ROOT`
- `S3_ENDPOINT`
- `S3_REGION`
- `S3_BUCKET`
- `S3_ACCESS_KEY_ID`
- `S3_SECRET_ACCESS_KEY`
- `S3_FORCE_PATH_STYLE`

## 4. Artifact Schema Added

Added `crm_document_artifacts` with:

- organization/entity identity
- document and artifact types
- template version reference
- storage provider and storage key
- file metadata
- checksum
- lifecycle status
- generated / locked / voided metadata
- JSON metadata payload

Added `approved_artifact_id` to `crm_quotations`.

## 5. Approved PDF Refactor

Approved quotation PDFs now:

- write through `StorageProvider.putObject()`
- persist checksum via SHA-256
- create a `crm_document_artifacts` row
- lock the artifact after generation
- update quotation `approvedArtifactId`
- keep `approvedPdfUrl` as compatibility reference in `artifact:<artifactId>` form

Rules enforced:

- only approved quotations can generate approved PDF
- locked approved artifacts cannot be overwritten
- existing active approved artifact blocks silent regeneration

## 6. Secure Download Added

Added secure artifact route:

- `GET /api/crm/document-artifacts/[id]/download`

Updated quotation approved-PDF flow so secure reads resolve artifact metadata from the database and fetch bytes through the storage provider instead of treating public file paths as source of truth.

## 7. UI Updated

Quotation detail now shows approved artifact metadata when available:

- file name
- generated by
- generated at
- checksum short form
- locked status badge

It also shows a legacy warning when a quotation still references old `/generated/...` storage without an artifact record.

## 8. Permissions Added

- `crm.document_artifact.read`
- `crm.document_artifact.download`
- `crm.document_artifact.void`

Defaults were added alongside the existing quotation PDF permissions in RBAC role derivation.

## 9. Audit Integration

Artifact service now audits:

- `create`
- `lock`
- `void`
- `download`

Entity type:

- `crm_document_artifact`

## 10. Compatibility Notes

Compatibility behavior now supports:

- `approvedArtifactId` when present
- `approvedPdfUrl = artifact:<artifactId>` during migration
- legacy `/generated/...` approved PDF paths with warning fallback

Task I intentionally does not bulk-migrate legacy files yet.

## 11. Remaining Risks

- artifact void/regeneration still has no admin UI workflow
- legacy approved PDFs still need one-time migration into artifact storage
- signed-URL delivery is not enabled yet; downloads are still server-streamed
- storage-provider health and bucket policy checks are still operational concerns outside the app

## 12. Task J Readiness

Task I leaves the app ready for:

- richer artifact lifecycle tooling
- legacy-file migration command
- object-storage rollout beyond local development
- future secure delivery strategies such as signed URLs

## 13. Verification

- `npx tsc --noEmit`
- `npm run gen`