423 lines
7.8 KiB
Markdown
423 lines
7.8 KiB
Markdown
# 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.
|