# Task D.7.5 CSV Commit Import Engine

Date: 2026-07-03
Status: implemented

## Scope Delivered

- Added protected commit API:
  - `POST /api/setup/import/commit`
- Added setup CSV commit service:
  - `src/features/setup/server/csv-commit.service.ts`
  - `src/features/setup/server/csv/commit-builder.ts`
  - `src/features/setup/server/csv/upsert-executor.ts`
  - `src/features/setup/server/csv/import-report.ts`

## Behavior

- Commit requires `previewHash`.
- Commit re-runs D.7.4 preview on the submitted files.
- Commit rejects mismatched `previewHash`.
- Commit rejects preview results with blocking errors.
- Commit follows dependency order from `setup/templates/templates.json` through the D.7.4 preview ordering.
- `dryRun=true` returns planned actions and does not start transaction writes.
- Non-dry-run commits execute in a single database transaction.
- Supported rows use idempotent business-key upsert behavior.
- Password updates only run for existing users when `password` is supplied and `reset_password=true`; otherwise password input is ignored with a report warning.
- Import reports never return password hashes.

## Supported Templates

The commit executor supports the templates registered by D.7.3/D.7.4:

- `users.csv`
- `organizations.csv`
- `memberships.csv`
- `crm-role-assignments.csv`
- `master-options.csv`
- `branches.csv`
- `product-types.csv`
- `document-sequences.csv`
- `approval-workflows.csv`
- `approval-steps.csv`
- `approval-matrix.csv`
- `customers.csv`
- `contacts.csv`
- `contact-shares.csv`
- `leads.csv`
- `opportunities.csv`
- `opportunity-parties.csv`
- `quotations.csv`
- `quotation-items.csv`
- `quotation-parties.csv`
- `quotation-topics.csv`
- `quotation-topic-items.csv`

## Safety Notes

- D.7.5 reuses D.7.4 parsing, template detection, validation, dependency resolution, preview actions, and `previewHash`.
- Setup import writes directly with Drizzle for this slice because no safe setup import service contract exists for every supported template.
- The import report includes `AUDIT_GAP` warnings for direct Drizzle writes; a future service wrapper can add per-row audit semantics without changing the preview contract.
- Storage, attachments, approval execution, PDFs, setup state persistence, seed manifest persistence, and destructive reset remain out of scope.

## Verification

- `npm run typecheck` passed.
- `npx oxlint src/features/setup/server/csv src/features/setup/server/csv-commit.service.ts src/app/api/setup/import/commit/route.ts` passed.