# 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.