task-p.5.1
This commit is contained in:
phaichayon
181
docs/implementation/task-p.5.1-implementation.md
Normal file
181
docs/implementation/task-p.5.1-implementation.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user