task-p.5

2026-06-29 23:05:01 +07:00
parent bdc2d9f1b4
commit 4570495a77
24 changed files with 2944 additions and 114 deletions
--- a/plans/task-p.5.md
+++ b/plans/task-p.5.md
@@ -0,0 +1,513 @@
+# 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.