task-p.5.1

2026-06-30 09:21:34 +07:00
parent 4570495a77
commit e4573ac0c9
28 changed files with 8566 additions and 1875 deletions
--- a/docs/implementation/pdf-audit-report.json
+++ b/docs/implementation/pdf-audit-report.json
@@ -1,12 +1,12 @@
 {
-  "generatedAt": "2026-06-29T08:13:58.800Z",
+  "generatedAt": "2026-06-30T01:35:48.376Z",
  "overallStatus": "PASS",
  "quotationCode": "QT2606-1122",
  "expectedFixtureCode": "QT-H5-AUDIT",
  "template": {
    "templateName": "ALLA Quotation Standard",
-    "version": "1.0",
-    "versionId": "6c375f16-3f89-4987-88b0-c8ebe48aeb89",
+    "version": "2.1",
+    "versionId": "86f99414-4656-44a9-9937-8457794dc710",
    "fieldCount": 44,
    "previousVersion": "2.0",
    "deletedFields": [
--- a/docs/implementation/pdf-audit-report.md
+++ b/docs/implementation/pdf-audit-report.md
@@ -1,9 +1,9 @@
 # PDF Audit Report

- Generated At: 2026-06-29T08:13:58.800Z
+- Generated At: 2026-06-30T01:35:48.376Z
 - Overall Status: PASS
 - Quotation Code: QT2606-1122
- Template: ALLA Quotation Standard v1.0
+- Template: ALLA Quotation Standard v2.1
 - Previous Version: 2.0

 ## Metrics
--- a/docs/implementation/task-p.5.1-implementation.md
+++ b/docs/implementation/task-p.5.1-implementation.md
@@ -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.
--- a/docs/implementation/task-p.5.1-verification-report.md
+++ b/docs/implementation/task-p.5.1-verification-report.md
@@ -0,0 +1,124 @@
+# Task P.5.1 Verification Report
+
+## Scope
+
+This report verifies implementation work for
+[task-p.5.1.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.5.1.md).
+
+Verification focus:
+
+- metadata separation compile safety
+- duplicate workflow compile safety
+- compare UI compile safety
+- helper test execution
+- migration execution
+- build and audit regression checks
+
+---
+
+## Commands Run
+
+```bash
+npm exec tsc --noEmit
+npm exec tsx --test src/features/foundation/document-template/server/metadata.test.ts
+npm exec tsx --test src/features/foundation/document-template/server/service.test.ts
+npm run db:generate
+npm run db:migrate
+npm run build
+npm run audit:pdf
+```
+
+---
+
+## Results
+
+### TypeScript
+
+- `npm exec tsc --noEmit` = PASS
+
+### Added tests
+
+- `metadata.test.ts` = PASS
+- `service.test.ts` = PASS
+
+### Migration flow
+
+- `npm run db:generate` = PASS
+- `npm run db:migrate` = PASS
+
+### Build
+
+- `npm run build` = PASS
+
+Residual build status:
+
+- build warning still present from Turbopack trace on
+  [shared.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-audit/server/shared.ts)
+
+### PDF audit regression
+
+- `npm run audit:pdf` = command PASS
+- `audit:pdf` integrity summary = FAIL
+
+Observed blocking audit issue:
+
+- `ACTIVE_VERSION_SCHEMA_DRIFT`
+- current report points to ALLA active product template version not matching its source JSON
+
+Relevant generated artifact:
+
+- [artifacts/pdf-audit/template-version-report.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/artifacts/pdf-audit/template-version-report.json)
+
+---
+
+## What Was Verified Successfully
+
+- document template metadata can now be modeled through dedicated `metadata_json`
+- legacy embedded metadata remains readable through compatibility helpers
+- duplicate version label generation works
+- duplicate route was compiled into the app route tree
+- management panel compiles with:
+  - duplicate action
+  - richer compare dialog
+  - stronger validation display
+- migration file generated and applied successfully
+
+---
+
+## What Remains Unverified or Incomplete
+
+- dedicated route-handler tests for validate/publish/activate/rollback/archive/duplicate
+- minimal browser/E2E checks for `/dashboard/crm/settings/templates`
+- full Turbopack warning cleanup
+- clean `audit:pdf` integrity summary for current seeded DB state
+
+---
+
+## Acceptance Status
+
+Acceptance criteria status for this round:
+
+- `schemaJson` clean-path implementation added = PASS
+- compatibility handling for legacy metadata added = PASS
+- duplicate as draft workflow added = PASS
+- compare UI made substantially more usable = PASS
+- stronger template health structure added = PASS
+- helper-level automated tests added = PASS
+- build remains PASS = PASS
+- runtime code no longer imports `scripts/` directly = PASS
+- Turbopack warning resolved = FAIL
+- runtime audit remains fully green = FAIL
+- route tests complete = FAIL
+- minimal E2E workflow complete = FAIL
+
+---
+
+## Verification Conclusion
+
+P.5.1 made meaningful hardening progress and is build-safe, migration-safe, and test-improved.
+
+However, this round does not fully satisfy every acceptance target yet because:
+
+- the Turbopack warning still remains
+- route/E2E coverage is still incomplete
+- current database verification still shows active template schema drift in `audit:pdf`