532 lines
6.9 KiB
Markdown
532 lines
6.9 KiB
Markdown
# Task D.7 – Initial System Setup Wizard & Seed Framework
|
||
|
||
## Objective
|
||
|
||
Design and implement a production-ready initialization framework for ALLA OS that allows a brand-new installation to be configured without writing code.
|
||
|
||
The implementation must audit the current project, discover all required seed dependencies, generate reusable CSV templates, provide a generic CSV import engine, and build a Setup Wizard for initializing the system from an empty database.
|
||
|
||
The solution must preserve existing architecture, Organization isolation, Branch scope, Product Type scope, RBAC, Approval Workflow, Document Sequence, Storage, and PDF configuration.
|
||
|
||
---
|
||
|
||
# Phase 1 — Existing System Audit (Mandatory)
|
||
|
||
Before implementing, perform a complete audit of the current project.
|
||
|
||
Review at minimum:
|
||
|
||
- AGENTS.md
|
||
- docs/standards/*
|
||
- docs/adr/*
|
||
- drizzle/*
|
||
- src/db/schema.ts
|
||
- src/db/seeds/**/*
|
||
- src/features/foundation/**/*
|
||
- src/features/auth/**/*
|
||
- src/features/crm/**/*
|
||
- src/features/approval/**/*
|
||
- src/features/storage/**/*
|
||
- src/features/document-sequence/**/*
|
||
- src/features/master-options/**/*
|
||
- src/features/pdf/**/*
|
||
- src/features/organizations/**/*
|
||
|
||
Do not create duplicate seed logic.
|
||
|
||
Reuse existing services whenever possible.
|
||
|
||
---
|
||
|
||
# Phase 2 — Seed Dependency Analysis
|
||
|
||
Audit every table and identify:
|
||
|
||
- Required
|
||
- Optional
|
||
- Generated
|
||
- Runtime only
|
||
|
||
Generate a dependency graph.
|
||
|
||
Example
|
||
|
||
Organization
|
||
→ Branch
|
||
→ Membership
|
||
→ User
|
||
→ Customer
|
||
→ Contact
|
||
→ Lead
|
||
→ Opportunity
|
||
→ Quotation
|
||
→ Approval
|
||
|
||
Produce a report containing:
|
||
|
||
- Seed order
|
||
- Dependency tree
|
||
- Circular dependency detection
|
||
- Missing seed data
|
||
- Existing seed coverage
|
||
- Recommended improvements
|
||
|
||
No implementation should begin until this report is complete.
|
||
|
||
---
|
||
|
||
# Phase 3 — Seed Classification
|
||
|
||
Separate all seed data into four groups.
|
||
|
||
## Foundation Seed
|
||
|
||
Required for every installation.
|
||
|
||
Examples
|
||
|
||
- System Configuration
|
||
- Roles
|
||
- Permissions
|
||
- Master Option Categories
|
||
- Master Options
|
||
- Status Definitions
|
||
- Document Types
|
||
- Product Types
|
||
- Currency
|
||
- Tax Rates
|
||
- Storage Providers
|
||
- Notification Types
|
||
- Approval Types
|
||
- Default PDF Templates
|
||
|
||
---
|
||
|
||
## Organization Seed
|
||
|
||
Organization-specific data.
|
||
|
||
Examples
|
||
|
||
- Organization
|
||
- Company Profile
|
||
- Branch
|
||
- Department
|
||
- Team
|
||
- Warehouse
|
||
- Position
|
||
- Company Logo
|
||
- Signature
|
||
- Email Settings
|
||
- Approval Matrix
|
||
- Document Sequence
|
||
|
||
---
|
||
|
||
## Business Seed
|
||
|
||
Operational data.
|
||
|
||
Examples
|
||
|
||
- Customer
|
||
- Contact
|
||
- Site
|
||
- Product
|
||
- Service
|
||
- Price Book
|
||
- Lead
|
||
- Opportunity
|
||
- Quotation
|
||
- Quotation Items
|
||
|
||
---
|
||
|
||
## Demo / UAT Seed
|
||
|
||
Sample business data.
|
||
|
||
Create realistic demo data for:
|
||
|
||
Organization
|
||
|
||
- ALLA
|
||
- ONVALLA
|
||
|
||
Users
|
||
|
||
- IT
|
||
- Marketing
|
||
- Sales
|
||
- Sales Manager
|
||
- CEO
|
||
|
||
Customers
|
||
|
||
Leads
|
||
|
||
Opportunities
|
||
|
||
Approved Quotations
|
||
|
||
Rejected Quotations
|
||
|
||
Follow-up Activities
|
||
|
||
Attachments
|
||
|
||
---
|
||
|
||
# Phase 4 — CSV Template Generator
|
||
|
||
Generate reusable CSV templates for every importable entity.
|
||
|
||
Directory
|
||
|
||
/setup/templates/
|
||
|
||
Example
|
||
|
||
organizations.csv
|
||
|
||
branches.csv
|
||
|
||
users.csv
|
||
|
||
memberships.csv
|
||
|
||
roles.csv
|
||
|
||
permissions.csv
|
||
|
||
customers.csv
|
||
|
||
contacts.csv
|
||
|
||
sites.csv
|
||
|
||
products.csv
|
||
|
||
leads.csv
|
||
|
||
opportunities.csv
|
||
|
||
quotations.csv
|
||
|
||
quotation-items.csv
|
||
|
||
approval-matrix.csv
|
||
|
||
document-sequences.csv
|
||
|
||
master-options.csv
|
||
|
||
currencies.csv
|
||
|
||
tax-rates.csv
|
||
|
||
Each template must contain
|
||
|
||
- Header
|
||
- Sample row
|
||
- Required fields
|
||
- Optional fields
|
||
- Enum examples
|
||
- Validation rules
|
||
- Relationship examples
|
||
|
||
---
|
||
|
||
# Phase 5 — Generic CSV Import Engine
|
||
|
||
Create a reusable import engine.
|
||
|
||
Requirements
|
||
|
||
- CSV Parser
|
||
- Validation
|
||
- Required field checking
|
||
- Enum validation
|
||
- Foreign key resolution
|
||
- Duplicate detection
|
||
- Upsert support
|
||
- Transaction support
|
||
- Rollback on failure
|
||
- Import report
|
||
|
||
Return
|
||
|
||
- Imported
|
||
- Updated
|
||
- Skipped
|
||
- Errors
|
||
- Warnings
|
||
|
||
The engine must be reusable by every future module.
|
||
|
||
---
|
||
|
||
# Phase 6 — Setup Wizard
|
||
|
||
Create a new Administration page.
|
||
|
||
Administration
|
||
|
||
└── Setup Wizard
|
||
|
||
Wizard flow
|
||
|
||
## Step 1
|
||
|
||
System Readiness
|
||
|
||
Check
|
||
|
||
- Environment Variables
|
||
- Database
|
||
- Storage
|
||
- Migration Status
|
||
- Upload Directory
|
||
- PDF Template
|
||
- Email Configuration
|
||
|
||
---
|
||
|
||
## Step 2
|
||
|
||
Initialize Foundation
|
||
|
||
Install
|
||
|
||
- Foundation Seed
|
||
- Roles
|
||
- Permissions
|
||
- Master Data
|
||
|
||
---
|
||
|
||
## Step 3
|
||
|
||
Organization Setup
|
||
|
||
Configure
|
||
|
||
- Company Name
|
||
- Organization Code
|
||
- Tax ID
|
||
- Address
|
||
- Logo
|
||
- Default Currency
|
||
- Fiscal Year
|
||
|
||
---
|
||
|
||
## Step 4
|
||
|
||
Branch Setup
|
||
|
||
Configure
|
||
|
||
- Branch
|
||
- Department
|
||
- Team
|
||
- Warehouse
|
||
|
||
---
|
||
|
||
## Step 5
|
||
|
||
CSV Import
|
||
|
||
Upload CSV files.
|
||
|
||
Preview
|
||
|
||
- Data
|
||
- Validation
|
||
- Error Summary
|
||
|
||
Support partial import.
|
||
|
||
---
|
||
|
||
## Step 6
|
||
|
||
Document Sequence
|
||
|
||
Configure
|
||
|
||
Organization
|
||
|
||
↓
|
||
|
||
Branch
|
||
|
||
↓
|
||
|
||
Product Type
|
||
|
||
↓
|
||
|
||
Prefix
|
||
|
||
↓
|
||
|
||
Running Number
|
||
|
||
Preview
|
||
|
||
CRA2607-001
|
||
|
||
DKA2607-001
|
||
|
||
SCO2607-001
|
||
|
||
---
|
||
|
||
## Step 7
|
||
|
||
Approval Workflow
|
||
|
||
Configure
|
||
|
||
- Sequential
|
||
- Any One
|
||
- Amount-based Approval
|
||
|
||
Preview approval flow.
|
||
|
||
---
|
||
|
||
## Step 8
|
||
|
||
Administrator
|
||
|
||
Create first administrator account.
|
||
|
||
Assign
|
||
|
||
- System Admin
|
||
- Organization Admin
|
||
|
||
---
|
||
|
||
## Step 9
|
||
|
||
Verification
|
||
|
||
Automatically verify
|
||
|
||
- Login
|
||
- Permission
|
||
- Organization
|
||
- Branch
|
||
- Document Sequence
|
||
- Approval
|
||
- Storage
|
||
- PDF
|
||
- Email
|
||
|
||
Display
|
||
|
||
PASS
|
||
|
||
WARNING
|
||
|
||
FAIL
|
||
|
||
---
|
||
|
||
## Step 10
|
||
|
||
Finish
|
||
|
||
Generate
|
||
|
||
- Setup Summary
|
||
- Seed Summary
|
||
- Import Summary
|
||
- Verification Report
|
||
|
||
---
|
||
|
||
# Phase 7 — Reset & Reseed
|
||
|
||
Create reusable reset commands.
|
||
|
||
Support
|
||
|
||
- Reset Foundation
|
||
- Reset Organization
|
||
- Reset Demo Data
|
||
- Reset Business Data
|
||
- Full Reset
|
||
|
||
All operations must be transactional.
|
||
|
||
---
|
||
|
||
# UI Requirements
|
||
|
||
Use shadcn/ui.
|
||
|
||
Implement
|
||
|
||
- Stepper Wizard
|
||
- Progress Bar
|
||
- Import Preview Table
|
||
- Validation Badge
|
||
- Summary Cards
|
||
- Success Screen
|
||
- Error Screen
|
||
- Resume Setup
|
||
- Dark Mode
|
||
- Responsive Layout
|
||
|
||
---
|
||
|
||
# Technical Requirements
|
||
|
||
- Reuse existing services.
|
||
- Do not duplicate business logic.
|
||
- Idempotent seed operations.
|
||
- Organization-aware.
|
||
- Branch-aware.
|
||
- Product Type-aware.
|
||
- Transaction-safe.
|
||
- Extensible for future modules.
|
||
- Follow ALLA OS coding standards.
|
||
|
||
---
|
||
|
||
# Deliverables
|
||
|
||
- Seed dependency audit report
|
||
- Seed inventory matrix
|
||
- CSV templates
|
||
- Generic CSV import engine
|
||
- Setup Wizard
|
||
- Validation engine
|
||
- Verification engine
|
||
- Reset engine
|
||
- Seed execution report
|
||
- Technical documentation
|
||
|
||
---
|
||
|
||
# Acceptance Criteria
|
||
|
||
> Implementation log 2026-07-02: Phase 1/2 audit completed and saved to
|
||
> `docs/implementation/task-d7-initial-system-setup-audit.md`. Implementation
|
||
> is intentionally gated until this seed dependency audit report is reviewed.
|
||
|
||
- Empty database can be initialized entirely through the Setup Wizard.
|
||
- All Foundation data can be installed without manual SQL.
|
||
- Organizations can be created from the wizard.
|
||
- CSV templates cover every importable master and business entity.
|
||
- CSV imports support validation, preview, rollback, and upsert.
|
||
- Demo/UAT data can be generated independently from Foundation data.
|
||
- System verification reports all required services before first login.
|
||
- Reset and reseed operations are repeatable and deterministic.
|
||
- Existing functionality remains backward compatible.
|