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

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.