# Task D.7.12 Step-by-Step First-Run Required CSV Import

Date: 2026-07-03
Status: implemented

## Review Completed

- Reviewed `AGENTS.md` task governance from the active repository instructions.
- Reviewed `docs/standards/task-contract-template.md`.
- Reviewed `docs/standards/task-catalog.md`.
- Reviewed `docs/standards/project-foundations.md`.
- Reviewed `docs/standards/architecture-rules.md`.
- Reviewed `docs/standards/ui-ux-rules.md`.
- Reviewed `docs/standards/task-review-checklist.md`.
- Reviewed setup lineage notes:
  - `docs/implementation/task-d7-initial-system-setup-audit.md`
  - `docs/implementation/task-d76-dashboard-setup-wizard-ui.md`
  - `docs/implementation/task-d78-seed-manifest-setup-state-persistence.md`
  - `docs/setup/setup-wizard-blueprint.md`

## Decision

The required CSV order is:

1. `users.csv`
2. `organizations.csv`
3. `memberships.csv`
4. `crm-role-assignments.csv`
5. `master-options.csv`
6. `branches.csv`
7. `product-types.csv`
8. `document-sequences.csv`
9. `approval-workflows.csv`
10. `approval-steps.csv`
11. `approval-matrix.csv`

This intentionally uses `users.csv` before `organizations.csv` because `organizations.csv`
resolves `created_by_email` against existing users. This follows the recommendation in
`plans/task-d.7.12.md` and avoids introducing a temporary bootstrap actor into the
organization import data path.

## Scope Delivered

- Added server-owned bootstrap required step metadata in `setup-bootstrap.service.ts`.
- Added `crm-role-assignments.csv` to the required bootstrap file list.
- Changed public bootstrap preview and commit APIs to accept one expected CSV file per step.
- Persisted each required CSV result to its own `setup_run_steps.step_key`.
- Updated bootstrap completion to require all required step keys to be `passed` or `warning`.
- Added bootstrap step dependency staleness rules in setup run persistence.
- Reworked the Administration Setup Wizard UI into a left-stepper, single-step import flow.
- Kept optional business CSV imports separate from system-required steps.

## Reuse

- Reused existing CSV preview and commit engine.
- Reused existing `/api/setup/bootstrap/preview`, `/api/setup/bootstrap/commit`, and
  `/api/setup/bootstrap/complete` route groups.
- Reused existing `setup_runs` and `setup_run_steps` persistence.
- Reused setup template metadata from `setup/templates/templates.json`.
- Reused shadcn/ui dashboard primitives and existing icon registry.

## Verification

- `npm run typecheck -- --pretty false` passed.