allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

task-p.5

Browse Source
This commit is contained in:
phaichayon
2026-06-29 23:05:01 +07:00
parent bdc2d9f1b4
commit 4570495a77
24 changed files with 2944 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
docs/implementation/task-p.5-implementation.md Normal file
View File

@@ -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.

135
docs/implementation/task-p.5-verification-report.md Normal file
View File

@@ -0,0 +1,135 @@
# Task P.5 Verification Report
## Scope
This report verifies implementation for
[task-p.5.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.5.md).
Verified focus for this round:
- document template lifecycle management foundation
- management API integration
- management UI integration
- compile and production build safety
- compatibility with existing PDF runtime path
---
## Files Verified
Primary implementation files:
- [src/features/foundation/document-template/types.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/types.ts)
- [src/features/foundation/document-template/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/service.ts)
- [src/features/foundation/document-template/queries.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/queries.ts)
- [src/features/foundation/document-template/mutations.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/mutations.ts)
- [src/features/foundation/document-template/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts)
- [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)
- [src/features/foundation/document-template/components/template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx)
- [src/features/foundation/document-template/components/template-version-management-panel.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-version-management-panel.tsx)
- [src/lib/auth/rbac.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/lib/auth/rbac.ts)
Management routes verified:
- [src/app/api/crm/settings/document-templates/[id]/compare/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/[id]/compare/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/management/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/management/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/validate/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/validate/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/publish/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/publish/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/activate/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/activate/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/rollback/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/rollback/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/archive/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/archive/route.ts)
- [src/app/api/crm/settings/document-templates/versions/[id]/preview/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/preview/route.ts)
---
## Commands Run
```bash
npm exec tsc --noEmit
npm run build
```
Results:
- `npm exec tsc --noEmit` = PASS
- `npm run build` = PASS
---
## Verification Outcome
### API and compile safety
Confirmed:
- route-handler syntax restored and valid
- management endpoints compile under Next.js route validation
- client service methods match management API shape
- React Query keys and mutation invalidation compile successfully
### UI integration
Confirmed:
- template settings page compiles with the new management panel
- version tabs can host lifecycle actions
- validation and audit summaries are renderable from typed management payloads
### Runtime compatibility
Confirmed:
- build completed without changing approved-PDF runtime contracts
- management service reuses existing PDF audit/runtime utilities
- no database migration was introduced in this round
---
## Build Warning
`npm run build` passed, but Next.js reported a non-blocking Turbopack warning:
- import trace from `scripts/pdf-audit-utils.ts`
- warning indicates wide file tracing caused by filesystem access patterns
Current status:
- build success = PASS
- warning cleanup = NOT ADDRESSED in this round
---
## Acceptance Status
Acceptance criteria checked in this round:
- multiple template versions can coexist = PASS
- only one active version logic is enforced by management service = PASS
- draft -> validate/publish -> activate lifecycle is implemented = PASS
- rollback flow exists and restores previous version path = PASS
- validation runs before publish = PASS
- preview works without activation = PASS
- runtime audit status is visible from management UI = PASS
- visual regression status is visible from management UI = PASS
- legacy and product templates remain build-compatible = PASS
Acceptance criteria not fully verified with dedicated automated flow in this round:
- full end-to-end browser interaction verification = NOT RUN
- dedicated regression tests for management routes = NOT RUN
---
## Residual Risk
Remaining risk after this round:
- lifecycle metadata currently lives inside `schemaJson`, not dedicated schema columns
- compare UX is minimal and not yet a full detailed diff viewer
- build warning from Turbopack trace should be cleaned later if this module expands
Overall implementation status for this round:
- foundation ready = PASS
- compile/build safety = PASS
- production-hardening follow-up still recommended = YES