task-d.7.5

docs/implementation/task-d75-csv-commit-import-engine.md

@@ -0,0 +1,66 @@
+# 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.