4.4 KiB
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
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
type PreviewResult = {
fileName: string;
template: string;
status:
| "PASS"
| "WARNING"
| "FAIL";
summary: {
rows:number;
valid:number;
warning:number;
error:number;
};
rows:[];
}
Overall response
{
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
{
"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.