task-d.7.2

plans/task-d.7.1.md

@@ -0,0 +1,775 @@
+# Task D.7.1 – Setup Blueprint & Seed Specification
+
+## Objective
+
+Create a complete implementation blueprint for the ALLA OS Initial Setup, Seed Framework, CSV Import, Reset/Reseed, and Verification workflow before starting code implementation.
+
+This task must convert the Phase 1/2 audit from Task D.7 into a precise technical specification that can be implemented safely without guessing, duplicating seed logic, or breaking existing CRM, RBAC, approval, document sequence, storage, or PDF behavior.
+
+No production code implementation should begin in this task except documentation/specification files and optional CSV template drafts.
+
+---
+
+# Scope
+
+## In Scope
+
+- Complete Seed Matrix
+- CSV Template Specification
+- CSV Import Mapping
+- Setup Wizard Flow Specification
+- Setup State Machine
+- Verification Matrix
+- Reset/Reseed Matrix
+- Seed Version Strategy
+- Seed Manifest Strategy
+- Setup Plugin Architecture
+- Implementation Slice Plan for D.7.2+
+
+## Out of Scope
+
+- Building the final Setup Wizard UI
+- Building the CSV import engine
+- Running destructive reset logic
+- Changing existing seed behavior
+- Changing production CRM business logic
+- Adding unsupported first-class domains without schema decision
+
+---
+
+# Phase 1 — Review Existing Audit
+
+Start from the existing Task D.7 Phase 1/2 audit report.
+
+Review:
+
+- `plans/task-d.7.md`
+- Task D.7 audit output
+- `AGENTS.md`
+- `docs/standards/*`
+- `docs/adr/*`
+- `src/db/schema.ts`
+- `src/db/seeds/**/*`
+- `scripts/seed-system.ts`
+- `scripts/seed-uat.ts`
+- `scripts/seed-reset.ts`
+- `scripts/db/reset-database.ts`
+- `src/features/foundation/**/*`
+- `src/features/crm/**/*`
+- `src/features/setup/**/*`
+
+Do not repeat the same audit. Extend it into a blueprint.
+
+---
+
+# Phase 2 — Complete Seed Matrix
+
+Create a complete seed matrix covering all known setup-related tables and concepts.
+
+Output file:
+
+```text
+docs/setup/seed-matrix.md
+```
+
+Required columns:
+
+```text
+Module
+Entity
+Table / Storage
+Seed Type
+Required For First Login
+Required For CRM
+Required For Quotation
+CSV Importable
+Wizard Editable
+Auto Generated
+Source of Truth
+Dependencies
+Import Order
+Reset Scope
+Notes
+```
+
+Seed Type values:
+
+```text
+foundation
+organization
+business
+demo_uat
+runtime_generated
+runtime_only
+unsupported_pending_schema
+```
+
+Example row:
+
+```text
+Foundation | Branch | ms_options(category=crm_branch) | organization | yes | yes | yes | yes | yes | no | CSV/Wizard | organization, created_by_user | 08 | organization_reset | Branch is currently modeled as master option, not a branch table.
+```
+
+The matrix must explicitly include:
+
+- users
+- organizations
+- memberships
+- CRM role profiles
+- CRM user role assignments
+- ms_options
+- crm_branch options
+- crm_product_type options
+- document sequences
+- approval workflows
+- approval steps
+- approval matrices
+- document templates
+- document template versions
+- document template mappings
+- document libraries
+- notification templates
+- report definitions
+- customers
+- contacts
+- contact shares
+- leads
+- opportunities
+- quotations
+- quotation items
+- quotation topics
+- quotation topic items
+- quotation project parties
+- followups
+- audit logs
+- notification events
+- generated PDFs / document artifacts
+- uploaded files / attachments
+- setup state
+- seed manifests
+
+Also include unsupported or ambiguous items:
+
+- departments
+- teams
+- warehouses
+- sites
+- price books
+- services
+- tax rate table if not first-class
+- email provider config if not first-class
+
+---
+
+# Phase 3 — CSV Template Specification
+
+Create CSV template specification.
+
+Output file:
+
+```text
+docs/setup/csv-template-spec.md
+```
+
+For each supported CSV, define:
+
+```text
+File Name
+Purpose
+Target Table / Service
+Seed Type
+Required Columns
+Optional Columns
+Generated Columns
+Validation Rules
+Relationship Resolution
+Duplicate Detection
+Upsert Key
+Import Order
+Example Rows
+Error Examples
+```
+
+Required CSV specs:
+
+```text
+organizations.csv
+users.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
+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
+```
+
+Unsupported/deferred specs must be marked clearly:
+
+```text
+departments.csv
+teams.csv
+warehouses.csv
+sites.csv
+services.csv
+price-books.csv
+tax-rates.csv
+attachments.csv
+email-settings.csv
+```
+
+Each CSV section must include at least one example row.
+
+Example:
+
+```csv
+organization_code,organization_name,slug,tax_id,default_currency,status
+ALLA,ALLA Public Company Limited,alla,0107558000393,THB,active
+```
+
+---
+
+# Phase 4 — Import Mapping Specification
+
+Create import mapping specification.
+
+Output file:
+
+```text
+docs/setup/import-mapping.md
+```
+
+For every supported CSV, define:
+
+```text
+CSV Column
+Target Field
+Transform
+Validation
+Required
+Reference Resolver
+Fallback
+Notes
+```
+
+Important mappings:
+
+## branches.csv
+
+Must map to:
+
+```text
+ms_options
+category = crm_branch
+organization_id = selected organization
+value/code = branch_code
+label = branch_name
+metadata = prefix, address, tax info if applicable
+```
+
+## product-types.csv
+
+Must map to:
+
+```text
+ms_options
+category = crm_product_type
+value/code = product_type_code
+label = product_type_name
+metadata = document_prefix
+```
+
+## document-sequences.csv
+
+Must resolve:
+
+```text
+organization_code
+branch_code
+product_type_code
+document_type
+period_format
+prefix
+current_number
+```
+
+## users.csv + memberships.csv
+
+Must clarify whether user creation and organization membership are separate or combined.
+
+## crm-role-assignments.csv
+
+Must resolve:
+
+```text
+user_email
+organization_code
+crm_role_code
+branch_code
+product_type_code
+```
+
+## customers.csv
+
+Must resolve:
+
+```text
+organization_code
+owner_user_email
+customer_type
+customer_group
+```
+
+## leads/opportunities/quotations
+
+Must resolve:
+
+```text
+organization_code
+customer_code
+contact_email
+branch_code
+product_type_code
+owner_user_email
+created_by_email
+```
+
+---
+
+# Phase 5 — Setup Wizard Blueprint
+
+Create wizard blueprint.
+
+Output file:
+
+```text
+docs/setup/setup-wizard-blueprint.md
+```
+
+Define:
+
+```text
+Step Number
+Step Name
+Purpose
+Inputs
+Validation
+Actions
+APIs
+Can Skip
+Can Go Back
+Resume Behavior
+Error Handling
+Output
+```
+
+Required wizard steps:
+
+1. System Readiness
+2. Foundation Install
+3. Organization Setup
+4. Branch & Product Type Setup
+5. Administrator Setup
+6. Document Sequence Setup
+7. Approval Workflow Setup
+8. CSV Import
+9. Verification
+10. Finish & Report
+
+Each step must define required fields.
+
+Example:
+
+```text
+Organization Setup Inputs
+
+organization_name: required
+organization_code: required, uppercase, unique
+slug: required, lowercase, unique
+tax_id: optional
+phone: optional
+email: optional email format
+address: optional
+default_currency: required, default THB
+timezone: required, default Asia/Bangkok
+logo: optional
+```
+
+---
+
+# Phase 6 — Setup State Machine
+
+Create setup state specification.
+
+Output file:
+
+```text
+docs/setup/setup-state-machine.md
+```
+
+Define state model:
+
+```text
+not_started
+readiness_checked
+foundation_installed
+organization_created
+administrator_created
+scope_configured
+sequences_configured
+approval_configured
+csv_validated
+csv_imported
+verified
+completed
+failed
+cancelled
+```
+
+Define events:
+
+```text
+CHECK_READINESS
+INSTALL_FOUNDATION
+CREATE_ORGANIZATION
+CREATE_ADMIN
+CONFIGURE_SCOPE
+CONFIGURE_SEQUENCES
+CONFIGURE_APPROVAL
+VALIDATE_CSV
+IMPORT_CSV
+RUN_VERIFICATION
+COMPLETE_SETUP
+FAIL_STEP
+CANCEL_SETUP
+RESUME_SETUP
+RESET_STEP
+```
+
+Define persistence strategy.
+
+If no setup table exists, propose new table:
+
+```text
+setup_runs
+setup_run_steps
+seed_manifests
+seed_manifest_items
+```
+
+Do not implement migrations in this task unless explicitly approved.
+
+---
+
+# Phase 7 — Verification Matrix
+
+Create verification matrix.
+
+Output file:
+
+```text
+docs/setup/verification-matrix.md
+```
+
+Required columns:
+
+```text
+Check ID
+Area
+Check Name
+Purpose
+Required For
+Method
+Pass Condition
+Warning Condition
+Fail Condition
+Suggested Fix
+API / Service
+```
+
+Checks must include:
+
+- environment variable presence
+- database connectivity
+- migration status
+- storage read/write/delete smoke test
+- upload directory readiness
+- first administrator exists
+- administrator membership exists
+- administrator CRM role assignment resolves
+- organization active
+- branch option exists
+- product type option exists
+- document sequence preview works
+- quotation approval workflow resolves
+- approval matrix resolves
+- PDF template exists
+- PDF template version active
+- PDF mapping exists
+- notification templates exist
+- report definitions exist
+- email configuration optional dry-run
+
+---
+
+# Phase 8 — Reset / Reseed Matrix
+
+Create reset/reseed specification.
+
+Output file:
+
+```text
+docs/setup/reset-reseed-matrix.md
+```
+
+Define reset scopes:
+
+```text
+foundation_reset
+organization_reset
+business_reset
+demo_uat_reset
+full_reset
+csv_import_rollback
+setup_run_reset
+```
+
+For each scope define:
+
+```text
+Tables affected
+Data retained
+Data deleted
+Safety guard
+Requires confirmation
+Allowed environment
+Transaction behavior
+Storage cleanup behavior
+Audit behavior
+Recommended command/API
+```
+
+Rules:
+
+- Production destructive reset must be blocked.
+- Reset must require explicit confirmation.
+- Storage cleanup must be compensated and reported.
+- Runtime generated approved artifacts must not be casually deleted outside explicit full reset/demo reset.
+
+---
+
+# Phase 9 — Seed Version and Manifest Strategy
+
+Create seed lifecycle specification.
+
+Output file:
+
+```text
+docs/setup/seed-version-manifest.md
+```
+
+Define:
+
+```text
+Seed Package
+Version
+Dependencies
+Checksum
+Applied At
+Applied By
+Target Organization
+Source
+Status
+Report
+```
+
+Propose manifest format:
+
+```json
+{
+  "name": "crm-foundation",
+  "version": "1.0.0",
+  "type": "foundation",
+  "dependencies": ["system-core@1.0.0"],
+  "items": [
+    {
+      "file": "master-options.csv",
+      "checksum": "...",
+      "required": true
+    }
+  ]
+}
+```
+
+Define upgrade behavior:
+
+```text
+same version + same checksum = skip
+same version + changed checksum = warn/block unless force
+newer version = apply if compatible
+older version = block unless rollback mode
+```
+
+---
+
+# Phase 10 — Setup Plugin Architecture
+
+Create plugin architecture proposal.
+
+Output file:
+
+```text
+docs/setup/setup-plugin-architecture.md
+```
+
+Goal:
+
+Future modules can register setup behavior without editing the core wizard.
+
+Plugin contract should cover:
+
+```text
+module_id
+display_name
+setup_steps
+csv_templates
+seed_tasks
+verification_checks
+reset_scopes
+dependencies
+enabled_condition
+```
+
+Example modules:
+
+```text
+core
+foundation
+crm
+quotation
+approval
+document
+notification
+reporting
+future_asset
+future_hr
+```
+
+No implementation required, but the design must be concrete enough for future implementation.
+
+---
+
+# Phase 11 — Implementation Plan for D.7.2+
+
+Create implementation slice plan.
+
+Output file:
+
+```text
+plans/task-d.7.2.md
+```
+
+Recommended slices:
+
+## D.7.2
+
+Setup Readiness and Verification APIs
+
+## D.7.3
+
+CSV Template Generator and Static Template Pack
+
+## D.7.4
+
+CSV Preview Validation Engine
+
+## D.7.5
+
+CSV Commit Import Engine
+
+## D.7.6
+
+Dashboard Setup Wizard UI
+
+## D.7.7
+
+Scoped Reset and Reseed Engine
+
+## D.7.8
+
+Seed Manifest and Setup State Persistence
+
+Each slice must include:
+
+```text
+Objective
+Files to review
+Implementation scope
+Out of scope
+Acceptance criteria
+Risk notes
+```
+
+---
+
+# Deliverables
+
+The task is complete only when the following files exist:
+
+```text
+docs/setup/seed-matrix.md
+docs/setup/csv-template-spec.md
+docs/setup/import-mapping.md
+docs/setup/setup-wizard-blueprint.md
+docs/setup/setup-state-machine.md
+docs/setup/verification-matrix.md
+docs/setup/reset-reseed-matrix.md
+docs/setup/seed-version-manifest.md
+docs/setup/setup-plugin-architecture.md
+plans/task-d.7.2.md
+```
+
+Optional drafts:
+
+```text
+setup/templates/*.csv
+```
+
+---
+
+# Acceptance Criteria
+
+- The setup implementation can be started without guessing.
+- Every setup-related entity is classified.
+- Every supported CSV has required fields, validation, mapping, upsert key, and examples.
+- Unsupported CSVs are clearly marked with the reason.
+- Wizard steps have inputs, validation, actions, APIs, outputs, and resume behavior.
+- Setup state machine is defined.
+- Verification checks are actionable.
+- Reset/reseed scopes are safe and explicit.
+- Seed version and manifest behavior is defined.
+- Future module setup plugin strategy is documented.
+- No existing production behavior is changed.
+ 
+---
+
+# Implementation Log
+
+## 2026-07-02 - Blueprint documentation completed
+
+- Created complete setup blueprint/specification deliverables under `docs/setup/`.
+- Created next implementation slice plan at `plans/task-d.7.2.md`.
+- No production code behavior was changed.

plans/task-d.7.2.md

@@ -0,0 +1,222 @@
+# Task D.7.2 - Setup Readiness and Verification APIs
+
+## Objective
+
+Implement the first non-destructive setup API slice for ALLA OS Initial Setup: readiness checks, verification checks, and report contracts. This slice must not run destructive reset logic or commit seed/import data.
+
+## Files To Review
+
+- `AGENTS.md`
+- `plans/task-d.7.md`
+- `plans/task-d.7.1.md`
+- `docs/implementation/task-d7-initial-system-setup-audit.md`
+- `docs/setup/seed-matrix.md`
+- `docs/setup/setup-wizard-blueprint.md`
+- `docs/setup/setup-state-machine.md`
+- `docs/setup/verification-matrix.md`
+- `docs/setup/reset-reseed-matrix.md`
+- `src/db/schema.ts`
+- `src/features/foundation/storage/**`
+- `src/features/foundation/document-sequence/**`
+- `src/features/foundation/document-template/**`
+- `src/features/foundation/pdf-generator/**`
+- `src/features/foundation/approval/**`
+- `src/features/foundation/master-options/**`
+- `src/features/crm/reports/**`
+- `src/lib/auth/session.ts`
+- `src/lib/auth/crm-access.ts`
+
+## Implementation Scope
+
+- Create setup feature API contracts:
+  - `src/features/setup/api/types.ts`
+  - `src/features/setup/api/service.ts`
+  - `src/features/setup/api/queries.ts`
+- Create read-only setup server services:
+  - `src/features/setup/server/readiness.service.ts`
+  - `src/features/setup/server/verification.service.ts`
+- Create thin route handlers:
+  - `src/app/api/setup/readiness/route.ts`
+  - `src/app/api/setup/verify/route.ts`
+- Implement structured check result types:
+  - `PASS`
+  - `WARNING`
+  - `FAIL`
+- Implement checks from `docs/setup/verification-matrix.md` that can safely run without mutating production data.
+- For storage smoke test, either use an explicitly temporary setup key and cleanup immediately or mark as warning when provider does not support safe smoke test yet.
+- Return actionable `suggestedFix` values without leaking secrets or raw SQL errors.
+
+## Out Of Scope
+
+- Final Setup Wizard UI.
+- CSV template generator.
+- CSV preview/import commit engine.
+- Seed execution.
+- Destructive reset/reseed APIs.
+- Setup state persistence tables.
+- Migrations for `setup_runs` or `seed_manifests`.
+- Changing existing production CRM behavior.
+
+## Acceptance Criteria
+
+- `GET /api/setup/readiness` returns readiness report with environment, database, migration, storage, PDF, and optional email checks.
+- `POST /api/setup/verify` returns verification report for a selected organization or current active organization.
+- Route handlers are thin and call setup server services.
+- All checks return consistent structured result objects.
+- Checks use existing foundation services where available.
+- No production data is created, updated, or deleted except safe temporary storage smoke-test object if explicitly implemented.
+- Unauthorized users cannot access setup reports.
+- Relevant lint/typecheck passes or failures are documented.
+
+## Risk Notes
+
+- Migration status detection may need a conservative fallback if Drizzle metadata table differs by environment.
+- Storage smoke testing is partly non-transactional; if cleanup fails, the API must report a warning with the storage key.
+- PDF/template checks should inspect existing template rows and mappings, not render or persist PDFs in this slice.
+- Email checks should remain optional unless a first-class provider configuration is added.
+
+---
+
+# Future Slices
+
+---
+
+# Implementation Log
+
+## 2026-07-02 - Readiness and verification APIs implemented
+
+- Added setup API contracts under `src/features/setup/api/`.
+- Added read-only setup services under `src/features/setup/server/`.
+- Added protected route handlers:
+  - `GET /api/setup/readiness`
+  - `POST /api/setup/verify`
+- Verification:
+  - `npm run typecheck` passed.
+  - `npx oxlint src/features/setup src/app/api/setup` passed.
+  - `npm run lint` still fails on pre-existing unrelated repo lint issues outside this task.
+- Implementation note: `docs/implementation/task-d72-setup-readiness-verification-apis.md`
+
+## Task D.7.3 - CSV Template Generator Static Template Pack
+
+Objective: create checked-in `setup/templates/*.csv` files and optional route to download them.
+
+Scope:
+
+- Generate templates from `docs/setup/csv-template-spec.md`.
+- Include headers and sample rows.
+- Mark unsupported templates in docs only, not importable packs.
+
+Out scope:
+
+- CSV parser.
+- CSV commit import.
+
+Acceptance criteria:
+
+- Supported templates exist under `setup/templates/`.
+- Each template has required headers and one safe sample row.
+- Template docs match checked-in files.
+
+## Task D.7.4 - CSV Preview Validation Engine
+
+Objective: implement reusable CSV parser, validation, relationship resolution, duplicate detection, and preview report.
+
+Scope:
+
+- `src/features/setup/server/csv-import.service.ts`
+- preview-only API route
+- validation from `docs/setup/import-mapping.md`
+
+Out scope:
+
+- DB commit writes.
+- rollback.
+
+Acceptance criteria:
+
+- Preview classifies imported/updated/skipped/error candidates.
+- Unsupported templates are blocked with clear reason.
+
+## Task D.7.5 - CSV Commit Import Engine
+
+Objective: commit validated CSV imports transactionally where safe.
+
+Scope:
+
+- commit API
+- transaction support
+- upsert support
+- import report
+
+Out scope:
+
+- UI.
+- arbitrary rollback beyond failed transaction.
+
+Acceptance criteria:
+
+- Commit requires matching preview hash.
+- DB-only imports rollback on error.
+- Related feature/foundation services are reused where practical.
+
+## Task D.7.6 - Dashboard Setup Wizard UI
+
+Objective: build dashboard-native setup wizard using existing app shell.
+
+Scope:
+
+- `src/app/dashboard/administration/setup/page.tsx`
+- setup wizard components under `src/features/setup/components/`
+- readiness, verification, CSV preview integration
+
+Out scope:
+
+- destructive reset UI.
+- migrations for setup state persistence unless D.7.8 completed first.
+
+Acceptance criteria:
+
+- Uses `PageContainer`.
+- Responsive, accessible, dark-mode compatible.
+- Shows progress, preview tables, validation badges, and summary report.
+
+## Task D.7.7 - Scoped Reset and Reseed Engine
+
+Objective: implement non-production scoped reset/reseed service.
+
+Scope:
+
+- reset scopes from `docs/setup/reset-reseed-matrix.md`
+- safety guards
+- confirmation tokens
+- reports
+
+Out scope:
+
+- production reset workflow.
+
+Acceptance criteria:
+
+- Production destructive reset blocked.
+- Scope reset is organization-aware.
+- Storage cleanup is reported.
+
+## Task D.7.8 - Seed Manifest and Setup State Persistence
+
+Objective: add persistent setup run and seed manifest tracking.
+
+Scope:
+
+- schema/migrations for `setup_runs`, `setup_run_steps`, `seed_manifests`, `seed_manifest_items`
+- state transitions from `docs/setup/setup-state-machine.md`
+- manifest behavior from `docs/setup/seed-version-manifest.md`
+
+Out scope:
+
+- new business seed behavior.
+
+Acceptance criteria:
+
+- Setup can resume.
+- Seed packages are versioned and checksummed.
+- Completion report is persisted.

plans/task-d.7.md

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

plans/task-seed-uat.md

@@ -0,0 +1,28 @@
+Create UAT seed pipeline for ALLA OS.
+
+Requirements:
+1. Add CSV import seed support from /src/db/seeds/uat-csv/*.csv
+2. Import order:
+   organizations
+   branches
+   product_types
+   users
+   memberships
+   document_sequences
+   customers
+   contacts
+   leads_opportunities
+   quotations
+   quotation_items
+   approval_steps
+3. Add npm scripts:
+   - seed:system
+   - seed:org
+   - seed:uat
+   - db:reset:uat
+4. Seed must be idempotent using upsert.
+5. Reset must clear transactional CRM data first, then seed foundation/master/UAT data again.
+6. Preserve organization boundary: ALLA and ONVALLA data must not mix.
+7. Verify login personas:
+   IT → MK → Sale → Manager → CEO
+8. Verify document sequence by organization + branch + product type.