task-d.7.12
This commit is contained in:
phaichayon
355
plans/task-d.7.12.md
Normal file
355
plans/task-d.7.12.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user