alla-allaos-fullstack/plans/task-p.5.1.md

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:

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:

2.0 -> 2.0-copy-1

or

2.0 -> 2.1-draft

UI

Add button:

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:

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:

/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:

scripts/pdf-audit-utils.ts

Goal

Remove server build dependency on script-only utilities.

Recommended Fix

Move shared audit logic into:

src/features/foundation/pdf-audit/server/

Keep script wrappers in:

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:

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.