6.4 KiB
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
/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.
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
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
/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.