182 lines
6.8 KiB
Markdown
182 lines
6.8 KiB
Markdown
# Task P.5.1 Implementation Report
|
|
|
|
## Scope
|
|
|
|
This report documents implementation work completed for
|
|
[task-p.5.1.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.5.1.md).
|
|
|
|
Focus of this round:
|
|
|
|
- production hardening for document template management
|
|
- metadata separation path from `schemaJson`
|
|
- duplicate version workflow
|
|
- stronger template health validation
|
|
- improved compare UX
|
|
- regression-safe migration support
|
|
- test coverage for new hardening helpers
|
|
|
|
---
|
|
|
|
## 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/implementation/task-p.5-implementation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.5-implementation.md)
|
|
- [docs/implementation/task-p.5-verification-report.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.5-verification-report.md)
|
|
|
|
---
|
|
|
|
## Implementation Summary
|
|
|
|
### 1. Metadata separation foundation
|
|
|
|
Added dedicated `metadata_json` support for document template versions:
|
|
|
|
- [src/db/schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts)
|
|
- [drizzle/0006_lazy_shiver_man.sql](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/drizzle/0006_lazy_shiver_man.sql)
|
|
|
|
Migration behavior:
|
|
|
|
- add `metadata_json`
|
|
- backfill legacy `__templateManagement` from `schema_json` into `metadata_json`
|
|
- scrub embedded metadata from `schema_json`
|
|
|
|
Compatibility helper added in:
|
|
|
|
- [metadata.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/metadata.ts)
|
|
|
|
This helper now:
|
|
|
|
- reads dedicated metadata first
|
|
- falls back to legacy metadata inside `schemaJson`
|
|
- sanitizes exported schema so PDFMe JSON stays clean
|
|
|
|
### 2. Document template server hardening
|
|
|
|
Updated template server foundation in:
|
|
|
|
- [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts)
|
|
- [management-service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/management-service.ts)
|
|
|
|
Key changes:
|
|
|
|
- sanitize `schemaJson` on create and update
|
|
- store lifecycle metadata in `metadataJson`
|
|
- preserve legacy metadata compatibility on read
|
|
- duplicate version support with cloned mappings and table columns
|
|
- stronger validation output with structured health issues
|
|
- compare output expanded with:
|
|
- field/schema changes
|
|
- mapping difference payload
|
|
- validation state for both versions
|
|
- basic JSON diff summary
|
|
|
|
### 3. Duplicate-as-draft workflow
|
|
|
|
Added explicit duplicate action:
|
|
|
|
- [src/app/api/crm/settings/document-templates/versions/[id]/duplicate/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/duplicate/route.ts)
|
|
|
|
Client and mutation support updated in:
|
|
|
|
- [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/service.ts)
|
|
- [mutations.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/mutations.ts)
|
|
|
|
Behavior implemented:
|
|
|
|
- duplicate any source version into a new draft
|
|
- copy schema JSON
|
|
- copy mappings
|
|
- copy mapping columns
|
|
- clear active lifecycle state
|
|
- generate a unique draft/copy version label
|
|
|
|
### 4. Compare UX improvement
|
|
|
|
Rebuilt comparison dialog in:
|
|
|
|
- [template-version-management-panel.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-version-management-panel.tsx)
|
|
|
|
Compare UI now shows tabs for:
|
|
|
|
- metadata
|
|
- placeholders
|
|
- mappings
|
|
- schema
|
|
- health
|
|
|
|
This replaces the earlier toast-only compare result.
|
|
|
|
### 5. Validation and health output
|
|
|
|
Extended validation contract in:
|
|
|
|
- [types.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/types.ts)
|
|
|
|
New validation output includes:
|
|
|
|
- `healthStatus`
|
|
- structured `issues`
|
|
- `orphanMappings`
|
|
- `unsupportedSchemaTypes`
|
|
- `sectionMarkerIssues`
|
|
- suggested next step
|
|
|
|
### 6. Audit utility relocation
|
|
|
|
Moved reusable audit helpers into runtime code space:
|
|
|
|
- [src/features/foundation/pdf-audit/server/shared.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-audit/server/shared.ts)
|
|
|
|
Script shim now re-exports from:
|
|
|
|
- [scripts/pdf-audit-utils.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/pdf-audit-utils.ts)
|
|
|
|
This removes direct runtime imports from `scripts/`.
|
|
|
|
### 7. Automated tests added
|
|
|
|
Added focused tests for hardening helpers:
|
|
|
|
- [metadata.test.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/metadata.test.ts)
|
|
- [service.test.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.test.ts)
|
|
|
|
Covered:
|
|
|
|
- legacy metadata extraction
|
|
- schema sanitization
|
|
- metadata merge precedence
|
|
- duplicate version label generation
|
|
|
|
---
|
|
|
|
## Generated Verification Artifacts
|
|
|
|
Verification commands updated existing generated outputs:
|
|
|
|
- [docs/implementation/pdf-audit-report.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/pdf-audit-report.json)
|
|
- [docs/implementation/pdf-audit-report.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/pdf-audit-report.md)
|
|
- [artifacts/pdf-audit/summary.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/artifacts/pdf-audit/summary.json)
|
|
- [artifacts/pdf-audit/summary.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/artifacts/pdf-audit/summary.md)
|
|
|
|
These were not hand-edited as part of feature logic. They are generated by verification runs.
|
|
|
|
---
|
|
|
|
## Known Gaps After This Round
|
|
|
|
- Turbopack warning still persists during `npm run build`, even though runtime no longer imports from `scripts/` directly.
|
|
- Full route-level management tests were not added yet.
|
|
- Minimal browser/E2E verification was not added yet.
|
|
- `audit:pdf` still reports an existing active template schema drift for ALLA product template data in the current database state.
|
|
|
|
---
|
|
|
|
## Outcome
|
|
|
|
P.5.1 significantly improved the production-readiness of the document template management foundation, especially around metadata handling, draft duplication, health reporting, and compare usability, while keeping the PDF runtime path unchanged.
|