alla-allaos-fullstack/plans/task-d.7.4.md

# 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.