# 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.