514 lines
6.4 KiB
Markdown
514 lines
6.4 KiB
Markdown
# 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.
|