task-d.7.12

docs/implementation/task-d712-step-by-step-bootstrap-csv-import.md

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