# Setup Wizard Blueprint

Target route proposal: `src/app/dashboard/administration/setup/page.tsx`

Target feature proposal: `src/features/setup/**`

UI rules:

- Use dashboard shell and `PageContainer`.
- Use shadcn/ui primitives and app icons through `@/components/icons`.
- Use server-side enforcement for all setup actions.
- Treat client-side step visibility as UX only.
- Do not reuse the existing `/setup` template onboarding component as-is; it is a historical prototype.

| Step Number | Step Name | Purpose | Inputs | Validation | Actions | APIs | Can Skip | Can Go Back | Resume Behavior | Error Handling | Output |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | System Readiness | Prove the environment can safely initialize. | none, optional setup mode | Env variables, DB connectivity, migration status, storage read/write/delete, upload directory, PDF template asset availability, optional email config. | Run read-only checks and record result. | `GET /api/setup/readiness` | no | no | Resume from latest readiness result but allow re-run. | PASS/WARNING/FAIL with suggested fix per check. | Readiness report. |
| 2 | Foundation Install | Install or verify foundation data. | seed mode, target organization context if already created | Foundation seed dependencies present; no pending migration failures. | Run extracted foundation seed services or dry-run. | `POST /api/setup/foundation` | no | yes, before commit only | If already installed, show manifest and allow verify/reapply compatible seed. | Roll back DB transaction on failure; report storage compensation if library write fails. | Foundation seed report. |
| 3 | Organization Setup | Create or update tenant organization. | `organization_name`, `organization_code`, `slug`, `tax_id`, `phone`, `email`, `address`, `default_currency`, `timezone`, `logo` | Name/code/slug required; code uppercase; slug lowercase unique; email format; timezone defaults `Asia/Bangkok`; currency resolves. | Create organization and store setup alias. | `POST /api/setup/organization` | no | yes | Existing run loads created organization and locks destructive fields unless reset. | Field errors; duplicate slug/code error; retry safe. | Organization summary. |
| 4 | Branch & Product Type Setup | Configure current scope foundations. | Branch rows, product type rows, default branch, default product type | At least one active branch and product type; codes unique; prefixes valid. | Upsert `crm_branch` and `crm_product_type` options. | `POST /api/setup/scope` | no | yes | Resume loads imported/created options. | Row-level validation table. | Scope summary and sequence suggestions. |
| 5 | Administrator Setup | Create first administrator and CRM authorization. | Admin name, email, password or existing user, membership role, CRM role, branch/product scope | Email valid; password policy for new user; user membership exists or can be created; role profile resolves. | Create/update user, membership, CRM role assignment. | `POST /api/setup/administrator` | no | yes | Resume masks password and shows resolved user/membership/assignment. | Avoid logging password; show user/role validation errors. | Administrator access summary. |
| 6 | Document Sequence Setup | Configure numbering by organization/branch/product/document type. | Document type, branch, product type, prefix, period, current number, padding, format, reset policy | Required sequence coverage for customer, lead, opportunity, quotation; format contains `{running}`; scope resolves. | Preview and upsert sequences. | `POST /api/setup/document-sequences/preview`, `POST /api/setup/document-sequences` | no | yes | Resume loads existing sequence rows and preview samples. | Per-row validation and conflict warnings. | Sequence preview and seed report. |
| 7 | Approval Workflow Setup | Configure quotation approval. | Workflow header, steps, matrix rows, SLA fields | Workflow active; steps sequential; matrix resolves to workflow; default quotation matrix exists. | Upsert workflow, steps, matrix. | `POST /api/setup/approval/preview`, `POST /api/setup/approval` | no for quotation install | yes | Resume shows active workflow and matrix status. | Matrix conflict/error report. | Approval configuration report. |
| 8 | CSV Import | Import optional master/business data. | CSV files, import mode, upsert mode, partial import toggle | Parseable CSV; required columns; references resolve; duplicates classified; unsupported templates blocked. | Preview, validate, then commit selected files in order. | `POST /api/setup/import/preview`, `POST /api/setup/import/commit` | yes | yes | Resume stores last preview hash and committed manifest. | No commit if preview has blocking errors; partial import only for selected valid files. | Import report. |
| 9 | Verification | Confirm install can operate. | check selection, optional email dry-run recipient | Required checks pass; warnings acknowledged. | Run verification matrix. | `POST /api/setup/verify` | no | yes | Resume shows last verification but requires re-run after mutations. | PASS/WARNING/FAIL with suggested fixes. | Verification report. |
| 10 | Finish & Report | Close setup and generate summary. | acknowledgement, optional export report | Required setup states completed; blocking failures absent. | Mark setup completed, write manifest/report, optionally lock setup. | `POST /api/setup/complete`, `GET /api/setup/report` | no | yes until complete | Completed run becomes read-only except explicit reset. | Completion blocked when required checks fail. | Setup summary, seed summary, import summary, verification report. |

## API Behavior

All setup write APIs should:

- require authenticated administrator or bootstrap setup token depending on system state
- validate request body with Zod or equivalent schema
- call `src/features/setup/server/**` services
- use existing auth, organization, role, seed, storage, approval, sequence, PDF, and audit foundations
- return structured step reports, not raw SQL/provider errors

## Resume Rules

- Setup run state is stored in proposed `setup_runs` and `setup_run_steps`.
- A completed step can be reviewed.
- A completed step can be re-run only when its service supports idempotent upsert and the user confirms conflict behavior.
- Later steps become stale if an earlier dependency step changes.
- Verification must be re-run after foundation, organization, scope, sequence, approval, or CSV commit changes.

## Step Outputs

Every step output should include:

- `status`: `not_started | running | passed | warning | failed | skipped`
- `startedAt`
- `completedAt`
- `summary`
- `items`
- `errors`
- `warnings`
- `nextRecommendedAction`