task-p.5.1
This commit is contained in:
phaichayon
422
plans/task-p.5.1.md
Normal file
422
plans/task-p.5.1.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# Task P.5.1 - Document Template Management Production Hardening
|
||||
|
||||
## Objective
|
||||
|
||||
Harden the Document Template Management foundation from Task P.5 so it is ready for production use and future extension.
|
||||
|
||||
This task focuses on technical debt, maintainability, validation, test coverage, and production-readiness.
|
||||
|
||||
Do NOT change PDF runtime behavior.
|
||||
Do NOT change Product Item Engine behavior.
|
||||
Do NOT introduce Document Assembly or PDF Merge.
|
||||
Do NOT introduce Render Configuration UI.
|
||||
|
||||
---
|
||||
|
||||
# Background
|
||||
|
||||
Task P.5 introduced the Document Template Management foundation.
|
||||
|
||||
Implemented capabilities include:
|
||||
|
||||
* lifecycle operations
|
||||
* validate
|
||||
* publish
|
||||
* activate
|
||||
* rollback
|
||||
* archive
|
||||
* preview
|
||||
* compare
|
||||
* audit summary
|
||||
* visual regression summary
|
||||
* management UI panel
|
||||
|
||||
Known remaining risks:
|
||||
|
||||
* lifecycle metadata currently lives inside `schemaJson`
|
||||
* compare UI is minimal
|
||||
* duplicate version shortcut is not explicit
|
||||
* management route regression tests are missing
|
||||
* browser/E2E verification is missing
|
||||
* Turbopack build warning exists due to filesystem tracing from audit utilities
|
||||
|
||||
---
|
||||
|
||||
# Scope
|
||||
|
||||
Included:
|
||||
|
||||
* metadata separation design and implementation
|
||||
* migration-safe lifecycle metadata handling
|
||||
* duplicate version workflow
|
||||
* version comparison UX improvement
|
||||
* template health validation
|
||||
* management route tests
|
||||
* minimal browser/E2E checks
|
||||
* build warning cleanup
|
||||
* management audit hardening
|
||||
|
||||
Excluded:
|
||||
|
||||
* PDF runtime refactor
|
||||
* Product Item template changes
|
||||
* Document Assembly
|
||||
* SLA merge
|
||||
* Render Policy UI
|
||||
* Optional section configuration
|
||||
* Document Library
|
||||
|
||||
---
|
||||
|
||||
# Phase 1 - Metadata Separation
|
||||
|
||||
## Problem
|
||||
|
||||
Task P.5 stores lifecycle metadata inside `schemaJson`.
|
||||
|
||||
This is acceptable for foundation delivery but not ideal long term.
|
||||
|
||||
`schemaJson` should remain PDFMe template JSON only.
|
||||
|
||||
## Goal
|
||||
|
||||
Separate management metadata from PDFMe schema JSON.
|
||||
|
||||
Preferred approach:
|
||||
|
||||
```text
|
||||
crm_document_template_versions
|
||||
schema_json = pure PDFMe JSON
|
||||
metadata_json = lifecycle/management metadata
|
||||
```
|
||||
|
||||
If a database migration is approved, add `metadata_json`.
|
||||
|
||||
If schema migration is not allowed in this task, implement a compatibility adapter that:
|
||||
|
||||
* reads legacy metadata from `schemaJson`
|
||||
* writes new metadata into a dedicated safe location only after schema support exists
|
||||
* prevents metadata from leaking into exported PDFMe JSON
|
||||
|
||||
## Required Metadata
|
||||
|
||||
Support:
|
||||
|
||||
* lifecycleStatus
|
||||
* runtimeVersion
|
||||
* templateVariant
|
||||
* brand
|
||||
* publishedBy
|
||||
* publishedAt
|
||||
* activatedBy
|
||||
* activatedAt
|
||||
* archivedBy
|
||||
* archivedAt
|
||||
* previousVersionId
|
||||
* validationSummary
|
||||
* auditSummary
|
||||
* visualSummary
|
||||
|
||||
## Acceptance
|
||||
|
||||
* Exported template JSON contains only valid PDFMe JSON.
|
||||
* Runtime continues reading valid `schemaJson`.
|
||||
* Existing versions remain readable.
|
||||
* No template version data loss.
|
||||
|
||||
---
|
||||
|
||||
# Phase 2 - Duplicate Version Workflow
|
||||
|
||||
Add an explicit duplicate action.
|
||||
|
||||
## Behavior
|
||||
|
||||
Duplicate should:
|
||||
|
||||
* clone an existing version
|
||||
* create a new Draft version
|
||||
* copy schema JSON
|
||||
* copy mappings
|
||||
* reset lifecycle metadata
|
||||
* clear active/published state
|
||||
* assign a new version label
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
2.0 -> 2.0-copy-1
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```text
|
||||
2.0 -> 2.1-draft
|
||||
```
|
||||
|
||||
## UI
|
||||
|
||||
Add button:
|
||||
|
||||
```text
|
||||
Duplicate as Draft
|
||||
```
|
||||
|
||||
## Acceptance
|
||||
|
||||
* User can duplicate any non-archived version.
|
||||
* New version is Draft.
|
||||
* Existing active version remains unchanged.
|
||||
* Mappings are copied correctly.
|
||||
|
||||
---
|
||||
|
||||
# Phase 3 - Version Compare UX
|
||||
|
||||
Improve compare from backend-only result to user-readable UI.
|
||||
|
||||
## Compare Tabs
|
||||
|
||||
Show:
|
||||
|
||||
1. Metadata diff
|
||||
2. Placeholder diff
|
||||
3. Mapping diff
|
||||
4. Field/schema diff
|
||||
5. JSON diff
|
||||
|
||||
## Minimum UX
|
||||
|
||||
* side-by-side version selector
|
||||
* highlight added fields
|
||||
* highlight removed fields
|
||||
* highlight changed mappings
|
||||
* show validation status of both versions
|
||||
|
||||
## Acceptance
|
||||
|
||||
* User can compare any two versions of the same template.
|
||||
* UI explains differences without opening raw JSON manually.
|
||||
* Compare does not mutate data.
|
||||
|
||||
---
|
||||
|
||||
# Phase 4 - Template Health Validation
|
||||
|
||||
Add a stronger validation layer before publish.
|
||||
|
||||
## Validate
|
||||
|
||||
* JSON parse validity
|
||||
* PDFMe schema validity
|
||||
* duplicate field names
|
||||
* unknown plugins
|
||||
* unsupported schema types
|
||||
* missing required placeholders
|
||||
* orphan mappings
|
||||
* unmapped placeholders
|
||||
* section marker validity
|
||||
* missing active-compatible page roles
|
||||
* items_table validity for product templates
|
||||
* topic template validity
|
||||
* signature field validity
|
||||
|
||||
## Output
|
||||
|
||||
Return structured health result:
|
||||
|
||||
```ts
|
||||
type TemplateHealthStatus = 'pass' | 'warning' | 'fail';
|
||||
```
|
||||
|
||||
With:
|
||||
|
||||
* issues
|
||||
* severity
|
||||
* location
|
||||
* suggested fix
|
||||
|
||||
## Acceptance
|
||||
|
||||
* Invalid templates cannot be published.
|
||||
* Warnings are visible.
|
||||
* Health result is shown in UI.
|
||||
|
||||
---
|
||||
|
||||
# Phase 5 - Management Route Tests
|
||||
|
||||
Add automated tests for management endpoints.
|
||||
|
||||
## Test Routes
|
||||
|
||||
* validate
|
||||
* publish
|
||||
* activate
|
||||
* rollback
|
||||
* archive
|
||||
* preview
|
||||
* compare
|
||||
* duplicate
|
||||
|
||||
## Test Cases
|
||||
|
||||
* unauthorized request
|
||||
* missing version
|
||||
* invalid lifecycle transition
|
||||
* publish invalid template
|
||||
* activate unpublished version
|
||||
* rollback from active version
|
||||
* archive active version protection
|
||||
* compare incompatible versions
|
||||
|
||||
## Acceptance
|
||||
|
||||
* Tests run in CI-friendly mode.
|
||||
* Tests do not require manual DB cleanup.
|
||||
* Existing `npm exec tsc --noEmit` remains PASS.
|
||||
|
||||
---
|
||||
|
||||
# Phase 6 - Minimal E2E Verification
|
||||
|
||||
Add minimal browser-level verification for:
|
||||
|
||||
```text
|
||||
/dashboard/crm/settings/templates
|
||||
```
|
||||
|
||||
## Verify
|
||||
|
||||
* page loads
|
||||
* version list renders
|
||||
* management panel renders
|
||||
* validation action can be triggered
|
||||
* preview action can be triggered
|
||||
* compare dialog/page opens
|
||||
* duplicate action creates draft
|
||||
* archive confirmation appears
|
||||
|
||||
## Acceptance
|
||||
|
||||
* E2E covers the core management workflow.
|
||||
* Tests can run against local seeded data.
|
||||
|
||||
---
|
||||
|
||||
# Phase 7 - Build Warning Cleanup
|
||||
|
||||
## Current Warning
|
||||
|
||||
Build passes but Turbopack reports filesystem tracing warning from:
|
||||
|
||||
```text
|
||||
scripts/pdf-audit-utils.ts
|
||||
```
|
||||
|
||||
## Goal
|
||||
|
||||
Remove server build dependency on script-only utilities.
|
||||
|
||||
## Recommended Fix
|
||||
|
||||
Move shared audit logic into:
|
||||
|
||||
```text
|
||||
src/features/foundation/pdf-audit/server/
|
||||
```
|
||||
|
||||
Keep script wrappers in:
|
||||
|
||||
```text
|
||||
scripts/
|
||||
```
|
||||
|
||||
Script files should import shared logic, not the other way around.
|
||||
|
||||
## Acceptance
|
||||
|
||||
* `npm run build` passes without the filesystem tracing warning.
|
||||
* Runtime code does not import from `scripts/`.
|
||||
* Scripts may import from runtime-safe shared modules.
|
||||
|
||||
---
|
||||
|
||||
# Phase 8 - Regression Verification
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
npm exec tsc --noEmit
|
||||
npm run build
|
||||
npm run audit:pdf
|
||||
```
|
||||
|
||||
Also run any route tests and E2E tests added in this task.
|
||||
|
||||
Verify:
|
||||
|
||||
* legacy template still works
|
||||
* product template still works
|
||||
* PDF runtime remains unchanged
|
||||
* visual regression baselines remain valid
|
||||
* template management actions work
|
||||
|
||||
---
|
||||
|
||||
# Deliverables
|
||||
|
||||
* separated metadata handling
|
||||
* duplicate version workflow
|
||||
* compare UX improvement
|
||||
* template health validation
|
||||
* management route tests
|
||||
* minimal E2E coverage
|
||||
* build warning cleanup
|
||||
* updated documentation
|
||||
|
||||
---
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
* `schemaJson` remains clean PDFMe JSON.
|
||||
* Lifecycle metadata no longer pollutes exported templates.
|
||||
* Existing versions remain readable through compatibility handling.
|
||||
* Duplicate as Draft works.
|
||||
* Compare UI is usable.
|
||||
* Template Health blocks invalid publish.
|
||||
* Management route tests pass.
|
||||
* Minimal E2E workflow passes.
|
||||
* Turbopack warning is resolved or explicitly documented if unavoidable.
|
||||
* Runtime audit remains PASS.
|
||||
* Build remains PASS.
|
||||
|
||||
---
|
||||
|
||||
# Out of Scope
|
||||
|
||||
## P.5.2
|
||||
|
||||
* Document Library
|
||||
* SLA PDF records
|
||||
* Warranty PDF records
|
||||
* Appendix records
|
||||
|
||||
## P.6
|
||||
|
||||
* PDF Merge
|
||||
* SLA Assembly
|
||||
* Warranty Assembly
|
||||
* Final document package generation
|
||||
|
||||
## P.7
|
||||
|
||||
* Render Configuration
|
||||
* Optional section UI
|
||||
* User-selectable Product Table visibility
|
||||
|
||||
---
|
||||
|
||||
# Final Success Condition
|
||||
|
||||
Task P.5.1 is complete when Document Template Management is production-hardened, metadata is safely separated from PDFMe schema JSON, version operations are test-covered, comparison and validation are usable, and build/runtime regression checks remain fully green.
|
||||
Reference in New Issue
Block a user