alla-allaos-fullstack/docs/implementation/task-p.6-implementation.md

Task P.6 Implementation Report

Scope

This report documents implementation completed for task-p.6.md.

Focus of this round:

• build the reusable Document Library foundation
• add storage-backed PDF version management for static append documents
• add CRM settings management UI and route handlers
• wire permissions and audit logging
• strengthen adoption with realistic seed coverage

---

Review Inputs

Reviewed before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/task-catalog.md
• docs/security/crm-authorization-boundaries.md
• docs/adr/0008-attachment-storage-strategy.md
• docs/adr/0009-approved-document-storage-lifecycle.md
• docs/adr/0013-pdf-visual-parity-strategy.md
• docs/implementation/task-i-storage-artifact-lifecycle.md
• docs/implementation/task-p.5-implementation.md
• docs/implementation/task-p.5.1-implementation.md

---

Implementation Summary

1. Document Library schema foundation

Added dedicated schema and migration support for reusable static document families and their uploaded PDF versions:

• src/db/schema.ts
• drizzle/0007_document_library_foundation.sql

Core model split:

• crm_document_libraries for logical document families
• crm_document_library_versions for uploaded PDF versions and lifecycle state

Database constraints added:

• unique library code per organization
• unique version per library
• single active version per library through partial unique index

2. Server foundation and lifecycle rules

Added reusable server-side foundation under src/features/foundation/document-library:

• types.ts
• server/validation.ts
• server/service.ts
• service.ts
• queries.ts
• mutations.ts

Behavior implemented:

• library create and metadata update
• PDF upload with MIME, size, checksum, readability, and page-count validation
• draft -> published -> active -> archived lifecycle enforcement
• draft deletion guard
• preview and download for explicit version or active version
• audit logging for create, update, upload, publish, activate, archive, preview, and download actions

3. CRM settings routes and UI

Added management route handlers under src/app/api/crm/settings/document-library and a management page at src/app/dashboard/crm/settings/document-library/page.tsx.

The settings UI now supports:

• filtering by type, brand, language, and product type
• version history inspection
• PDF upload
• publish, activate, archive, preview, and download actions

4. RBAC integration

Extended CRM permissions in:

• src/lib/auth/rbac.ts
• src/config/nav-config.ts

Permissions added:

• documentLibraryRead
• documentLibraryCreate
• documentLibraryUpdate
• documentLibraryUpload
• documentLibraryPublish
• documentLibraryActivate
• documentLibraryArchive
• documentLibraryDownload

5. Foundation seed hardening

Extended src/db/seeds/foundation.seed.ts to seed realistic Document Library starter data per organization.

Seed behavior now:

• creates logical document families
• generates valid one-page PDF fixtures with @pdfme/pdf-lib
• stores files through the configured storage provider
• writes version metadata with checksum, size, page count, and lifecycle timestamps
• keeps the seed idempotent through organization/code and library/version upserts

Seeded starter coverage:

• SLA + ALLA + Crane + TH
• Warranty + ONVALLA + Dock Door + EN
• Company Profile + ALLA + All Product Types + TH
• Installation Manual + Generic + Service + EN

Lifecycle coverage inside seed data:

• draft
• published
• active
• archived

---

Design Decisions

Reuse storage foundation instead of bespoke file writes

Document Library versions store metadata in the database, but seeded PDFs are written through the same storage provider contract used by runtime upload paths. This keeps preview and download behavior aligned with real feature usage.

Separate static library from approved document artifacts

This task does not reuse quotation approved-artifact persistence as the primary record model. Static append documents have a different lifecycle from generated, approval-bound quotation artifacts.

Seed with real PDFs, not fake metadata

Because preview and download routes depend on actual storage objects, seed data must create valid PDF binaries. Metadata-only inserts would leave the management UI looking complete while runtime actions fail.

---

Deliverables Completed

• Document Library schema and migration
• server validation and lifecycle services
• settings route handlers
• management page and client query/mutation integration
• RBAC and navigation integration
• validation tests for PDF upload and lifecycle helpers
• realistic multi-status foundation seed coverage

---

Known Gaps

• P.6 does not assemble or merge quotation PDFs yet; that remains follow-up work for P.7.
• Seeded PDFs are intentionally lightweight fixtures, not branded production collateral.
• No browser E2E coverage was added in this round.
• Signed URL or CDN/offload delivery is still not part of this foundation.

---

Outcome

P.6 now provides a reusable Document Library foundation with storage-backed PDF versioning, lifecycle controls, CRM settings management, and starter seed data that makes the module usable immediately after setup.