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

## Objective

Improve First-run Bootstrap Setup so required system CSV files are imported step-by-step instead of uploading all files at once.

The goal is to guide the user through each required setup dependency in the correct order:

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

After all required steps pass, optional business CSV import can be shown separately.

---

## Desired UX

Route:

/administration/setup

Show First-run Bootstrap Wizard.

Each step has:

- CSV file name
- purpose
- required columns
- upload area
- preview button
- run/import button
- result summary
- PASS / WARNING / FAIL status
- next button

User flow:

1. Upload organizations.csv
2. Preview
3. Run Import
4. Step marked PASS
5. Move to users.csv
6. Repeat until all system-required CSV files are complete
7. Show final verification
8. Mark setup completed
9. Redirect to login

---

## Required Import Steps

Use exact dependency order:

1. organizations.csv
2. users.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

Important:

If current import engine requires users before organizations because organizations.created_by_email resolves to users, support one of these approaches:

Option A:
Use temporary bootstrap actor for organizations.csv.

Option B:
Change order to users.csv first.

Decision must be documented before implementation.

Recommended decision:

Step 1 users.csv
Step 2 organizations.csv
Step 3 memberships.csv

because organizations.csv currently requires created_by_email.

---

## System Required Group

Define a bootstrap required group:

system_required

Files:

- 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

Business optional group:

business_optional

Files:

- 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

---

## Implementation Scope

Update First-run Bootstrap UI:

src/app/administration/setup/page.tsx

or bootstrap setup component under:

src/features/setup/components/bootstrap-setup-wizard.tsx

Add step configuration:

src/features/setup/bootstrap/bootstrap-required-steps.ts

Each step defines:

- stepKey
- fileName
- title
- description
- required
- dependsOn
- template metadata
- status
- previewHash
- import report

---

## API Reuse

Reuse existing APIs:

POST /api/setup/bootstrap/preview
POST /api/setup/bootstrap/commit

Each step submits one CSV file at a time.

Do not create new import logic.

Commit flow per step:

1. Upload one file
2. Preview
3. Store previewHash for that step
4. Commit same file with previewHash
5. Persist step result
6. Move to next step

---

## Persistence

Persist step status in setup_run_steps.

Step keys:

bootstrap_users
bootstrap_organizations
bootstrap_memberships
bootstrap_crm_role_assignments
bootstrap_master_options
bootstrap_branches
bootstrap_product_types
bootstrap_document_sequences
bootstrap_approval_workflows
bootstrap_approval_steps
bootstrap_approval_matrix

Each step stores safe output only.

No raw CSV contents.

---

## Dependency Rules

A step is locked until all dependsOn steps pass.

Example:

memberships.csv depends on:

- users.csv
- organizations.csv

crm-role-assignments.csv depends on:

- users.csv
- organizations.csv
- memberships.csv
- master-options.csv
- branches.csv
- product-types.csv

document-sequences.csv depends on:

- organizations.csv
- branches.csv
- product-types.csv

approval-steps.csv depends on:

- approval-workflows.csv

approval-matrix.csv depends on:

- approval-workflows.csv
- branches.csv
- product-types.csv

---

## UI Requirements

Show left stepper:

System Required

- Users
- Organizations
- Memberships
- CRM Roles
- Master Options
- Branches
- Product Types
- Document Sequences
- Approval Workflows
- Approval Steps
- Approval Matrix

Optional Business Data

- Customers
- Contacts
- Leads
- Opportunities
- Quotations

Each step panel shows:

- What this file does
- Required filename
- Required headers
- Sample template reference
- Upload control
- Preview result
- Import result
- Errors and suggested fixes

---

## Completion Rule

Setup can complete only when all system_required steps are PASS or WARNING acknowledged.

Then run:

POST /api/setup/bootstrap/complete

Completion must verify:

- super_admin exists
- organization exists
- membership exists
- CRM role assignment exists
- branch exists
- product type exists
- document sequence exists
- approval workflow/matrix exists

After success:

redirect to /auth/sign-in

---

## Optional Business Import

After system_required completion, show optional step:

Import Business Data

Allow either:

- step-by-step business import
or
- batch upload all business CSV

This can be deferred if needed.

---

## Out Of Scope

- Changing CSV template format
- Rewriting import engine
- Dashboard setup wizard redesign
- Reset/reseed
- Plugin runtime changes
- Business import advanced UI
- Production public setup after completion

---

## Acceptance Criteria

- First-run setup imports required CSV files step-by-step.
- Each step accepts only the expected CSV filename.
- Each step has Preview and Run buttons.
- Import cannot run without successful previewHash.
- Next step is locked until dependencies pass.
- Step status persists across refresh.
- System cannot complete until all required steps pass.
- Existing batch import engine remains unchanged.
- No raw CSV contents are persisted.
- Setup completion redirects to login.
- After completion, public bootstrap setup is blocked.
- Typecheck passes.
