task-d.7.4

plans/task-d.7.4.md

@@ -0,0 +1,437 @@
+# Task D.7.4 – CSV Preview Validation Engine
+
+## Objective
+
+Implement a reusable, non-destructive CSV Preview Validation Engine for ALLA OS.
+
+This engine must validate uploaded CSV files against the official template pack and return a complete preview report without modifying any database records.
+
+The preview engine becomes the shared foundation for D.7.5 (CSV Commit Import Engine), Setup Wizard, and future bulk import features.
+
+No database writes, seed execution, or reset operations are allowed in this task.
+
+---
+
+## Review Before Implementation
+
+Review:
+
+- AGENTS.md
+- plans/task-d.7.md
+- plans/task-d.7.1.md
+- plans/task-d.7.2.md
+- plans/task-d.7.3.md
+- docs/setup/seed-matrix.md
+- docs/setup/csv-template-spec.md
+- docs/setup/import-mapping.md
+- docs/setup/setup-wizard-blueprint.md
+- docs/setup/verification-matrix.md
+- setup/templates/*
+- setup/templates/templates.json
+
+Treat templates.json as the runtime source of truth.
+
+---
+
+## Implementation Scope
+
+Create:
+
+src/features/setup/server/csv-preview.service.ts
+
+Supporting modules
+
+src/features/setup/server/csv/
+    parser.ts
+    validator.ts
+    dependency-resolver.ts
+    header-validator.ts
+    value-validator.ts
+    preview-builder.ts
+    template-registry.ts
+
+Create API
+
+POST /api/setup/import/preview
+
+---
+
+## Input
+
+Accept one or more CSV files.
+
+Each file must match one registered template.
+
+Files may be uploaded in any order.
+
+Engine must automatically resolve dependency order.
+
+---
+
+## Validation Stages
+
+Stage 1
+
+Template Detection
+
+- Match filename
+- Match template registry
+- Match supported template
+
+Reject unknown templates.
+
+---
+
+Stage 2
+
+Schema Validation
+
+Validate
+
+- header names
+- header order
+- duplicated columns
+- missing columns
+- extra columns
+- template version (if available)
+
+---
+
+Stage 3
+
+CSV Validation
+
+Validate
+
+- encoding
+- delimiter
+- empty rows
+- duplicated rows
+- inconsistent column counts
+
+---
+
+Stage 4
+
+Value Validation
+
+Validate
+
+Required fields
+
+Email
+
+Boolean
+
+Integer
+
+Decimal
+
+Date (YYYY-MM-DD)
+
+Enum
+
+Length
+
+Regex
+
+Custom validators
+
+---
+
+Stage 5
+
+Relationship Resolution
+
+Resolve
+
+organization
+
+branch
+
+product type
+
+users
+
+memberships
+
+CRM role
+
+customer
+
+contact
+
+lead
+
+opportunity
+
+quotation
+
+master options
+
+Return
+
+Resolved
+
+Missing
+
+Ambiguous
+
+---
+
+Stage 6
+
+Dependency Validation
+
+Read
+
+templates.json
+
+Validate
+
+dependsOn
+
+Detect
+
+Missing parent files
+
+Circular dependency
+
+Invalid import order
+
+---
+
+Stage 7
+
+Duplicate Detection
+
+Classify
+
+New
+
+Existing
+
+Update
+
+Conflict
+
+Duplicate inside CSV
+
+---
+
+Stage 8
+
+Preview Report
+
+Return
+
+Imported
+
+Updated
+
+Skipped
+
+Warnings
+
+Errors
+
+Grouped by file.
+
+---
+
+## Report Contract
+
+```ts
+type PreviewResult = {
+  fileName: string;
+
+  template: string;
+
+  status:
+    | "PASS"
+    | "WARNING"
+    | "FAIL";
+
+  summary: {
+
+    rows:number;
+
+    valid:number;
+
+    warning:number;
+
+    error:number;
+
+  };
+
+  rows:[];
+}
+```
+
+Overall response
+
+```ts
+{
+    summary,
+
+    files:[],
+
+    generatedAt,
+
+    previewHash
+}
+```
+
+previewHash will be required by D.7.5.
+
+---
+
+## Rules
+
+Do not
+
+Insert
+
+Update
+
+Delete
+
+Commit
+
+Seed
+
+Generate IDs
+
+Generate document numbers
+
+Trigger approval
+
+Generate PDFs
+
+Only preview.
+
+---
+
+## Error Contract
+
+Every error
+
+Must contain
+
+File
+
+Row
+
+Column
+
+Code
+
+Message
+
+Suggested Fix
+
+Example
+
+```json
+{
+  "file":"customers.csv",
+
+  "row":12,
+
+  "column":"customer_type",
+
+  "code":"UNKNOWN_OPTION",
+
+  "message":"Customer type not found.",
+
+  "suggestedFix":"Import master-options.csv first."
+}
+```
+
+---
+
+## Reuse Rules
+
+Reuse existing
+
+Master Option services
+
+Organization services
+
+CRM services
+
+Validation helpers
+
+Document sequence helpers
+
+Do not duplicate logic.
+
+---
+
+## Deliverables
+
+src/features/setup/server/csv-preview.service.ts
+
+src/features/setup/server/csv/
+
+POST /api/setup/import/preview
+
+Shared validation utilities
+
+Structured preview response
+
+previewHash generator
+
+---
+
+## Acceptance Criteria
+
+✓ Preview never writes database.
+
+✓ Multiple CSVs supported.
+
+✓ Dependency order resolved automatically.
+
+✓ Unknown templates rejected.
+
+✓ Header validation implemented.
+
+✓ Data validation implemented.
+
+✓ Relationship resolution implemented.
+
+✓ Duplicate detection implemented.
+
+✓ Structured report returned.
+
+✓ previewHash generated.
+
+✓ Uses templates.json as runtime registry.
+
+✓ Typecheck passes.
+
+---
+
+## Future
+
+D.7.5
+
+Commit Import Engine
+
+Uses
+
+previewHash
+
+↓
+
+Transaction
+
+↓
+
+Upsert
+
+↓
+
+Import Report
+
+No validation logic should be duplicated between D.7.4 and D.7.5.