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/docs/implementation/task-p.5-implementation.md
+++ b/docs/implementation/task-p.5-implementation.md
@@ -0,0 +1,221 @@
+# Task P.5 Implementation Report
+
+## Scope
+
+This report documents the implementation completed for
+[task-p.5.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/AGENTS.md)
+- [docs/standards/project-foundations.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/project-foundations.md)
+- [docs/standards/architecture-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/architecture-rules.md)
+- [docs/standards/task-catalog.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/task-catalog.md)
+- [docs/adr/0012-approval-signature-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0012-approval-signature-strategy.md)
+- [docs/adr/0013-pdf-visual-parity-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0013-pdf-visual-parity-strategy.md)
+- [docs/implementation/task-g-document-preview-foundation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-g-document-preview-foundation.md)
+- [docs/implementation/task-h-pdf-generation-persistence.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/queries.ts)
+- [mutations.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-version-management-panel.tsx)
+
+Integrated it into:
+
+- [template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/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.