task-d.7.4

docs/implementation/task-d74-csv-preview-validation-engine.md

@@ -0,0 +1,47 @@
+# Task D.7.4 CSV Preview Validation Engine
+
+Date: 2026-07-02
+Status: implemented
+
+## Scope Delivered
+
+- Added reusable preview-only CSV engine:
+  - `src/features/setup/server/csv-preview.service.ts`
+  - `src/features/setup/server/csv/parser.ts`
+  - `src/features/setup/server/csv/template-registry.ts`
+  - `src/features/setup/server/csv/header-validator.ts`
+  - `src/features/setup/server/csv/value-validator.ts`
+  - `src/features/setup/server/csv/dependency-resolver.ts`
+  - `src/features/setup/server/csv/validator.ts`
+  - `src/features/setup/server/csv/preview-builder.ts`
+  - `src/features/setup/server/csv/types.ts`
+- Added protected preview route:
+  - `POST /api/setup/import/preview`
+
+## Behavior
+
+- Accepts one or more CSV files through `multipart/form-data`.
+- Detects templates by filename from `setup/templates/templates.json`.
+- Treats `templates.json` plus checked-in CSV headers as runtime template truth.
+- Rejects unknown and unsupported templates with structured row/file errors.
+- Validates exact header names, order, duplicate columns, missing columns, and extra columns.
+- Parses UTF-8 comma-delimited CSV with quoted cell support.
+- Reports invalid encoding, empty rows, duplicate rows, inconsistent column counts, required fields, emails, booleans, integers, decimals, dates, enums, JSON metadata, format rules, and amount/line-total warnings.
+- Resolves dependencies from both uploaded batch files and existing database rows without writing.
+- Detects duplicate business keys inside each uploaded file.
+- Classifies rows as `create`, `update`, or `error`.
+- Returns structured file/row report with `PASS`, `WARNING`, `FAIL` status and `previewHash` for D.7.5.
+
+## Safety Notes
+
+- No database insert/update/delete logic added.
+- No seed execution added.
+- No reset/reseed behavior added.
+- No document number generation, approval triggering, PDF generation, or storage writes added.
+- Relationship checks use read-only Drizzle selects.
+- `quotation-topic-items.csv` resolves `topic_key` from the uploaded batch because `topic_key` is an import-only alias and is not persisted in `crm_quotation_topics`.
+
+## Verification
+
+- `npm run typecheck`: passed.
+- `npx oxlint src/features/setup/server/csv src/features/setup/server/csv-preview.service.ts src/app/api/setup/import/preview`: passed.