356 lines
6.1 KiB
Markdown
356 lines
6.1 KiB
Markdown
# 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.
|