alla-allaos-fullstack/docs/implementation/task-p.5-implementation.md

Task P.5 Implementation Report

Scope

This report documents the implementation completed for task-p.5.md.

Goal of this round:

• extend the existing CRM document template foundation
• add template version lifecycle management
• surface validation, preview, audit, and visual status in the management UI
• keep the existing PDF runtime compatible
• avoid database schema changes unless strictly necessary

---

Review Inputs

Reviewed before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/task-catalog.md
• docs/adr/0012-approval-signature-strategy.md
• docs/adr/0013-pdf-visual-parity-strategy.md
• docs/implementation/task-g-document-preview-foundation.md
• docs/implementation/task-h-pdf-generation-persistence.md

---

Current-State Findings

Existing /dashboard/crm/settings/templates already provided:

• template CRUD
• version CRUD
• mapping CRUD
• raw schema JSON editing

Missing management capabilities before this task:

• lifecycle statuses beyond isActive
• publish workflow
• rollback workflow
• archive workflow
• reusable version validation endpoint
• preview selected inactive version from management flow
• comparison endpoint between two versions
• management-oriented metadata in UI without reading raw JSON

---

Implementation Summary

1. Template lifecycle metadata foundation

Extended document-template contracts in src/features/foundation/document-template/types.ts to support:

• draft | validated | published | active | archived
• runtime version
• template variant
• brand
• published and activated metadata
• previous and next version links
• validation summary
• audit summary

Implementation stores management metadata inside template version schemaJson under internal management metadata instead of introducing a database migration in this round.

2. Management service layer

Added src/features/foundation/document-template/server/management-service.ts to centralize:

• version lifecycle inference
• validation
• publish
• activate
• rollback
• archive
• compare
• preview
• audit and visual summary loading

Validation reuses existing PDF audit/runtime foundations:

• buildQuotationPdfRuntime
• generatePdfFromTemplate
• helpers from scripts/pdf-audit-utils.ts

3. API endpoints for management operations

Added management API routes under src/app/api/crm/settings/document-templates:

• [id]/compare/route.ts
• versions/[id]/management/route.ts
• versions/[id]/validate/route.ts
• versions/[id]/publish/route.ts
• versions/[id]/activate/route.ts
• versions/[id]/rollback/route.ts
• versions/[id]/archive/route.ts
• versions/[id]/preview/route.ts

Also normalized legacy template CRUD routes under src/app/api/crm/document-templates and the settings version update route to restore valid route-handler structure.

4. Permissions

Extended CRM permissions in src/lib/auth/rbac.ts:

• crmDocumentTemplatePublish
• crmDocumentTemplateActivate
• crmDocumentTemplateRollback
• crmDocumentTemplateArchive

These permissions were also added into the CRM Settings permission group.

5. Client service and React Query integration

Extended client-side document-template service in src/features/foundation/document-template/service.ts with methods for:

• management fetch
• validate
• publish
• activate
• rollback
• archive
• preview
• compare

Extended React Query support in:

• queries.ts
• mutations.ts

Added cache invalidation for template lists, detail views, version views, and version management detail after lifecycle operations.

6. Management UI

Added new lifecycle panel component:

• template-version-management-panel.tsx

Integrated it into:

• template-settings.tsx

UI capabilities added:

• lifecycle badge display
• validation summary display
• audit summary display
• visual regression summary display
• preview action
• compare action
• publish action
• activate action
• rollback action
• archive action
• version edit action on existing versions

---

Design Decisions

Reuse existing foundation instead of rewrite

This task extends the existing document-template foundation instead of replacing it. Existing CRUD, mappings, and JSON editing remain available.

No schema migration in this round

Lifecycle metadata is stored in managed version metadata inside schemaJson. This keeps existing template versions and runtime compatibility intact while allowing the management module to evolve first.

Runtime remains unchanged

No approved-PDF generation rules, product item engine behavior, or section assembly logic were redesigned in this task.

---

Deliverables Completed

• enhanced template management API
• version lifecycle operations
• validation integration
• preview integration
• compare integration
• audit summary integration
• visual regression summary integration
• updated permissions
• management UI panel on /dashboard/crm/settings/templates

---

Known Gaps

The following items are not fully completed in this round:

• no database-backed dedicated lifecycle columns yet
• compare flow currently returns backend comparison and confirms result through UI feedback, but does not yet render a full side-by-side diff viewer
• explicit duplicate-version shortcut is not yet separated from create/edit UX
• no new automated regression test suite was added for management routes in this round

These gaps do not block the current management foundation, but they should be considered for follow-up work if P.5 is expected to be fully production-polished.