alla-allaos-fullstack/plans/task-d.7.1.md

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