# Task P.5 - Document Template Management Foundation

## Objective

Build the next-generation Document Template Management module for ALLA OS.

The goal is to transform `/crm/settings/templates` from a simple template repository into a complete template lifecycle management system.

This module becomes the central management console for every document template used by CRM.

Examples

* Quotation
* Purchase Order
* Invoice
* Service Report
* Inspection Report
* Delivery Note
* Future document types

This task establishes the management foundation only.

It does **not** introduce new PDF runtime functionality.

---

# Background

Task P.4 completed the PDF runtime foundation.

Completed capabilities include:

* Section-based runtime
* Product Item Engine
* Template Versioning
* Runtime Audit
* Visual Regression
* Product Template
* Legacy Compatibility

The remaining gap is operational management of templates.

---

# Scope

Included

* Document Template Management
* Template Version Lifecycle
* Version Activation
* Rollback
* Draft Management
* Publish Workflow
* Version Comparison
* Audit Integration
* Preview Integration
* Template Metadata
* Template Validation

Excluded

* PDF Runtime changes
* Product Item Engine changes
* PDF Rendering changes
* Document Assembly
* Render Policy
* SLA Merge
* Warranty Merge

---

# Current State Analysis

Before implementation, inspect the existing module.

Review at minimum

```text
/dashboard/crm/settings/templates

src/features/crm/settings/templates

API routes

Database schema

Services

Version storage

Activation flow

Preview flow
```

Document

* current architecture
* missing capabilities
* duplicated logic
* improvement opportunities

Do not redesign without reviewing existing implementation.

---

# Objectives

The new module shall manage

Template

↓

Draft

↓

Validation

↓

Preview

↓

Publish

↓

Activate

↓

Rollback

↓

Archive

↓

History

---

# Version Lifecycle

Support the following lifecycle.

```text
Draft

↓

Validated

↓

Published

↓

Active

↓

Archived
```

Only one Active version is allowed per

* Organization
* Document Type
* Template Family

---

# Template Metadata

Each version shall expose metadata.

Examples

* Version
* Template Name
* Description
* Organization
* Document Type
* Brand
* Runtime Version
* Template Variant
* Created By
* Created Date
* Published By
* Published Date
* Activated By
* Activated Date
* Previous Version
* Next Version
* Status

Metadata shall not require reading JSON.

---

# Version Operations

Support

## Create Version

Clone existing template into Draft.

---

## Duplicate Version

Create editable copy.

---

## Publish

Validate before publish.

Reject invalid templates.

---

## Activate

Activate only validated versions.

Automatically deactivate previous Active version.

---

## Rollback

Rollback to previous Active version.

No JSON modification required.

---

## Archive

Prevent activation.

Retain history.

---

# Template Validation

Validation must run before publish.

Verify

* JSON validity
* schema validity
* placeholder validity
* mapping validity
* runtime compatibility
* duplicate fields
* missing required fields
* unsupported schema

Validation should reuse existing audit components whenever possible.

---

# Preview Integration

Support Preview directly from Template Management.

Preview shall use

* current runtime
* selected template version
* fixture data

without changing Active version.

---

# Version Comparison

Support comparing two versions.

Compare

* metadata
* JSON changes
* placeholders
* mappings
* runtime compatibility
* audit results

Do not require external diff tools.

---

# Audit Integration

Display latest audit status.

Examples

```text
PASS

WARNING

FAIL
```

Show

* audit date
* runtime version
* visual regression status
* mapping coverage

---

# Visual Regression Integration

Display latest visual validation.

Examples

* baseline generated
* last comparison
* changed pages
* layout differences

No new rendering required.

Reuse existing visual regression artifacts.

---

# UI Requirements

Enhance

```text
/dashboard/crm/settings/templates
```

Suggested sections

## Template List

* Name
* Version
* Status
* Active
* Published
* Runtime Version

---

## Version History

Chronological history.

---

## Actions

* Preview
* Compare
* Duplicate
* Publish
* Activate
* Rollback
* Archive

---

## Validation

Show

* runtime audit
* visual regression
* mapping validation

---

# Security

Permissions should support

* View Templates
* Create Draft
* Publish
* Activate
* Rollback
* Archive

Activation should require elevated permission.

---

# Implementation Constraints

Do NOT

* redesign PDF runtime
* modify Product Item Engine
* change approved PDF generation
* change database schema unless strictly necessary
* break legacy template versions

---

# Testing

Verify

## Version Management

* create draft
* publish
* activate
* rollback
* archive

---

## Preview

* preview inactive version
* preview draft
* preview active

---

## Validation

* invalid JSON
* invalid mappings
* duplicate placeholders
* audit failure

---

## Regression

Confirm

* legacy template still works
* product template still works
* runtime audit remains PASS
* visual regression remains PASS

---

# Deliverables

* Enhanced Template Management module
* Version lifecycle
* Version comparison
* Preview integration
* Validation integration
* Audit integration
* Rollback support
* Updated permissions
* Regression tests

---

# Acceptance Criteria

* Multiple template versions can coexist.
* Only one Active version exists per document type.
* Draft → Publish → Activate lifecycle is enforced.
* Rollback restores previous version without data loss.
* Validation runs before publish.
* Preview works without activation.
* Runtime audit is visible from the management UI.
* Visual regression status is visible from the management UI.
* Legacy and Product templates remain fully compatible.

---

# Out of Scope

## P.5.1

* Render Configuration
* Optional Sections
* Show/Hide Product Table

## P.6

* Document Assembly
* SLA Merge
* Warranty Merge
* Appendix Merge
* Company Profile Merge
* Datasheet Merge

---

# Final Success Condition

The `/crm/settings/templates` module becomes the authoritative management console for document templates, providing complete version lifecycle management while remaining fully compatible with the PDF runtime established in Phase P.4.
