6.1 KiB
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:
- Upload organizations.csv
- Preview
- Run Import
- Step marked PASS
- Move to users.csv
- Repeat until all system-required CSV files are complete
- Show final verification
- Mark setup completed
- Redirect to login
Required Import Steps
Use exact dependency order:
- organizations.csv
- users.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
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:
- Upload one file
- Preview
- Store previewHash for that step
- Commit same file with previewHash
- Persist step result
- 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.