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

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.