222 lines
7.5 KiB
Markdown
222 lines
7.5 KiB
Markdown
# 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.
|