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