alla-allaos-fullstack/docs/setup/setup-wizard-blueprint.md

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