# Task P.6 - Document Library Foundation

## Objective

Build the Document Library foundation for managing reusable PDF documents that can later be assembled with CRM-generated documents.

This phase prepares the system for future PDF merge workflows such as:

* Quotation + SLA
* Quotation + Warranty
* Quotation + Datasheet
* Quotation + Drawing
* Quotation + Company Profile

This task does **not** perform PDF merge yet.

---

# Background

Completed phases:

* P.4 PDF Runtime
* P.5 Document Template Management
* P.5.1 Production Hardening

The next required foundation is a centralized library for external/static documents before implementing Document Assembly.

---

# Scope

Included:

* Document Library data model
* Document category/type model
* Version management
* Organization and brand scope
* Language support
* Product type applicability
* File upload/storage metadata
* Active/default version handling
* Preview/download APIs
* Basic management UI
* RBAC permissions
* Audit log integration

Excluded:

* PDF merge
* SLA assembly into quotation
* Render configuration
* User-selectable append documents
* Approval package generation

---

# Document Types

Support document types such as:

* SLA
* Warranty
* Terms and Conditions
* Company Profile
* Datasheet
* Drawing
* Certificate
* Appendix
* Safety Document
* Installation Manual

---

# Data Model Requirements

Design tables for:

## Document Library

Represents a logical document family.

Example:

```text
SLA - Crane - TH
Warranty - Dock Door - EN
Company Profile - ALLA - TH
```

Fields should include:

* id
* organizationId
* code
* name
* documentType
* description
* brand
* language
* productType
* status
* isActive
* createdBy
* createdAt
* updatedAt

## Document Library Versions

Represents uploaded PDF versions.

Fields should include:

* id
* libraryId
* version
* fileName
* filePath / storageKey
* mimeType
* fileSize
* checksum
* pageCount
* status
* isActive
* publishedAt
* publishedBy
* archivedAt
* archivedBy
* createdAt
* updatedAt

---

# Version Lifecycle

Support:

```text
Draft
↓
Published
↓
Active
↓
Archived
```

Only one active version is allowed per library item.

---

# Storage Requirements

Reuse the existing storage abstraction from prior PDF artifact work.

Do not store PDF binary directly in database.

Store only:

* storage key
* filename
* MIME type
* checksum
* size
* metadata

---

# Upload Requirements

Allow uploading PDF files only in this phase.

Validate:

* MIME type = application/pdf
* file size limit
* checksum
* readable PDF
* page count extraction if available

Reject invalid uploads.

---

# Preview and Download

Provide:

* preview document version
* download document version
* download active version

Preview should not mutate lifecycle state.

---

# Applicability Rules

Each document may apply to:

* organization
* brand
* document type
* product type
* language

Examples:

```text
SLA + ALLA + Crane + TH
Warranty + ONVALLA + Dock Door + EN
Company Profile + ALLA + All Product Types + TH
```

---

# API Requirements

Create APIs for:

* list document library items
* create library item
* update library item
* create/upload version
* publish version
* activate version
* archive version
* preview version
* download version
* delete draft version if safe

---

# UI Requirements

Add management UI under CRM settings or document settings.

Suggested route:

```text
/dashboard/crm/settings/document-library
```

UI should include:

* library list
* filters by type, brand, language, product type
* version history
* upload new version
* publish
* activate
* archive
* preview
* download

---

# Permissions

Add permissions:

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

Activation should require elevated permission.

---

# Audit Log

Record audit logs for:

* create library item
* update metadata
* upload version
* publish version
* activate version
* archive version
* download version

---

# Validation

Validate:

* duplicate code per organization
* duplicate active version
* invalid PDF
* missing file
* unsupported document type
* unsupported language
* invalid lifecycle transition

---

# Testing Requirements

Run:

```bash
npm run typecheck
npm run build
```

Add tests for:

* version lifecycle
* active version uniqueness
* PDF upload validation
* checksum generation
* archive protection
* permission guards where practical

---

# Acceptance Criteria

* Document Library module exists.
* PDF files can be registered as document versions.
* Only valid PDFs are accepted.
* Versions support Draft, Published, Active, Archived lifecycle.
* Only one active version exists per library item.
* Active document can be previewed and downloaded.
* Library items can be filtered by type, brand, language, and product type.
* Storage abstraction is reused.
* No PDF merge is implemented in this phase.
* System is ready for P.7 Document Assembly.

---

# Out of Scope

## P.7

* Merge quotation PDF with SLA/Warranty/Datasheet
* Document package generation
* Page ordering rules
* Final merged PDF artifact

## P.8

* Render configuration
* User-selectable append documents
* Default append policy per product type

---

# Final Success Condition

Task P.6 is complete when ALLA OS has a reusable Document Library that can store, version, activate, preview, and download static PDF documents such as SLA, Warranty, Datasheet, Drawing, and Company Profile, without yet merging them into generated CRM PDFs.