# Task D.7.6 – Dashboard Setup Wizard UI

## Objective

Build a dashboard-native Setup Wizard UI for ALLA OS Administration.

The wizard must connect the previously implemented setup APIs into one guided workflow:

- D.7.2 Readiness and Verification APIs
- D.7.3 CSV Template Pack and Template Metadata API
- D.7.4 CSV Preview Validation Engine
- D.7.5 CSV Commit Import Engine

This task focuses on UI and orchestration only.

Do not implement seed execution, destructive reset, setup state persistence, seed manifest persistence, or new migrations in this task.

---

## Review Before Implementation

Review:

- AGENTS.md
- plans/task-d.7.md
- plans/task-d.7.1.md
- plans/task-d.7.2.md
- plans/task-d.7.3.md
- plans/task-d.7.4.md
- plans/task-d.7.5.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/csv-template-spec.md
- docs/setup/import-mapping.md
- setup/templates/README.md
- setup/templates/templates.json
- src/features/setup/api/types.ts
- src/features/setup/api/service.ts
- src/features/setup/api/queries.ts
- src/app/api/setup/readiness/route.ts
- src/app/api/setup/verify/route.ts
- src/app/api/setup/templates/route.ts
- src/app/api/setup/import/preview/route.ts
- src/app/api/setup/import/commit/route.ts
- existing dashboard pages and PageContainer usage
- src/config/nav-config.ts

---

## Implementation Scope

Create dashboard page:

src/app/dashboard/administration/setup/page.tsx

Create UI components under:

src/features/setup/components/

Recommended components:

- setup-wizard.tsx
- setup-wizard-stepper.tsx
- setup-status-badge.tsx
- setup-check-list.tsx
- setup-summary-cards.tsx
- setup-template-list.tsx
- csv-upload-dropzone.tsx
- csv-preview-table.tsx
- csv-import-report.tsx
- setup-verification-summary.tsx
- setup-finish-panel.tsx

Optional hooks:

src/features/setup/api/use-setup-readiness.ts
src/features/setup/api/use-setup-templates.ts
src/features/setup/api/use-csv-preview.ts
src/features/setup/api/use-csv-commit.ts
src/features/setup/api/use-setup-verification.ts

---

## Route and Navigation

Add menu item under Administration:

Administration

  Setup Wizard

Target route:

/dashboard/administration/setup

The route must be protected by existing dashboard/auth rules.

If setup APIs require `super_admin`, the UI should show a friendly permission message when unauthorized.

---

## Wizard Steps

Implement these UI steps.

### Step 1 – System Readiness

Call:

GET /api/setup/readiness

Show:

- Overall status
- PASS / WARNING / FAIL counts
- Check list grouped by area
- Suggested fixes
- Re-run button

Blocking behavior:

- FAIL should block moving forward unless step is marked dry-run / review-only.
- WARNING can continue with acknowledgement.

---

### Step 2 – Template Pack

Call:

GET /api/setup/templates

Show:

- available CSV templates
- import order
- seed type
- required columns
- sample file name
- unsupported/deferred templates from README or metadata if available

Optional:

- link to local setup/templates path in documentation text only
- do not implement file download unless already available

---

### Step 3 – CSV Upload

Allow upload of multiple CSV files.

Rules:

- accept only `.csv`
- show selected files
- allow remove/replace
- show detected file count
- show missing recommended templates as info only
- do not upload automatically until Preview button is clicked

---

### Step 4 – CSV Preview

Call:

POST /api/setup/import/preview

Input:

multipart/form-data files

Show:

- previewHash
- overall status
- per-file status
- row count
- create/update/error/warning counts
- row-level errors
- row-level warnings
- dependency warnings
- duplicate warnings

Blocking behavior:

- FAIL blocks commit.
- WARNING requires acknowledgement before commit.
- Store previewHash in client state only for this task.

---

### Step 5 – CSV Commit

Call:

POST /api/setup/import/commit

Input:

same files + previewHash

Support:

- dryRun toggle
- commit button
- show import report

Rules:

- Commit button disabled when preview has blocking errors.
- If files changed after preview, force re-preview.
- If commit returns previewHash mismatch, show clear message and require re-preview.

---

### Step 6 – Verification

Call:

POST /api/setup/verify

Input:

optional organizationId / active org context

Show:

- overall status
- PASS / WARNING / FAIL counts
- grouped checks
- suggested fixes
- re-run button

---

### Step 7 – Finish

Show:

- readiness summary
- template summary
- preview summary
- commit summary
- verification summary
- next recommended task

Because setup state persistence is out of scope, do not permanently lock or complete setup.

Show clear message:

This wizard session is not persisted yet. Persistent setup runs will be implemented in D.7.8.

---

## UI Requirements

Use:

- shadcn/ui
- PageContainer
- Card
- Button
- Badge
- Alert
- Table
- Tabs or Accordion where helpful
- Progress / Stepper
- ScrollArea for long reports
- responsive layout
- dark mode compatible styles

Avoid:

- hardcoded colors outside design tokens
- raw JSON dumps as main UI
- giant ungrouped error lists
- hidden errors

---

## UX Requirements

The wizard should feel like an enterprise setup console.

Must include:

- clear progress
- clear blocking vs non-blocking issues
- grouped diagnostics
- concise summary cards
- actionable suggested fixes
- retry/re-run buttons
- empty states
- loading states
- error states
- permission denied state

Recommended status language:

PASS

WARNING

FAIL

Do not translate status enum values in API handling.

---

## State Management

D.7.6 uses client-side state only.

Track:

- current step
- readiness report
- template metadata
- selected files
- preview report
- previewHash
- commit report
- verification report
- warning acknowledgement

Do not implement DB persistence.

If browser refreshes, state can reset.

Add note that persistent resume will arrive in D.7.8.

---

## API Integration Rules

- Reuse existing setup API types.
- Do not duplicate response shapes manually if types exist.
- Handle non-200 responses safely.
- Show safe error message from API contract.
- Do not display raw stack traces.
- Do not log sensitive CSV data.
- Do not upload files except to preview/commit endpoints.

---

## CSV File Change Rules

After successful preview:

- if selected files are removed, added, renamed, or content changed
- clear previewHash
- clear commit report
- require preview again

Implementation can use file name + size + lastModified fingerprint for this task.

---

## Out Of Scope

- Persistent setup state
- setup_runs / setup_run_steps migrations
- seed_manifests persistence
- seed execution
- scoped reset/reseed UI
- CSV template ZIP download
- production setup lock
- installation profile engine
- plugin runtime
- real file attachment import
- email settings persistence
- new CRM behavior

---

## Deliverables

Required:

src/app/dashboard/administration/setup/page.tsx

src/features/setup/components/setup-wizard.tsx
src/features/setup/components/setup-wizard-stepper.tsx
src/features/setup/components/setup-status-badge.tsx
src/features/setup/components/setup-check-list.tsx
src/features/setup/components/setup-summary-cards.tsx
src/features/setup/components/setup-template-list.tsx
src/features/setup/components/csv-upload-dropzone.tsx
src/features/setup/components/csv-preview-table.tsx
src/features/setup/components/csv-import-report.tsx
src/features/setup/components/setup-verification-summary.tsx
src/features/setup/components/setup-finish-panel.tsx

Navigation update:

src/config/nav-config.ts

Optional:

src/features/setup/api/use-setup-readiness.ts
src/features/setup/api/use-setup-templates.ts
src/features/setup/api/use-csv-preview.ts
src/features/setup/api/use-csv-commit.ts
src/features/setup/api/use-setup-verification.ts

---

## Acceptance Criteria

✓ Dashboard route exists at /dashboard/administration/setup.

✓ Navigation exposes Setup Wizard under Administration.

✓ Stepper wizard renders with all required steps.

✓ Readiness step calls GET /api/setup/readiness.

✓ Template step calls GET /api/setup/templates.

✓ CSV upload accepts multiple CSV files.

✓ Preview step calls POST /api/setup/import/preview.

✓ Preview report displays file and row-level validation results.

✓ Commit step calls POST /api/setup/import/commit with previewHash.

✓ Commit is disabled when preview has FAIL.

✓ File changes after preview clear previewHash and require re-preview.

✓ Verification step calls POST /api/setup/verify.

✓ Finish step summarizes all prior outputs.

✓ UI handles loading, empty, error, unauthorized, warning, and success states.

✓ Uses shadcn/ui and existing dashboard layout conventions.

✓ No setup data persistence or reset logic is introduced.

✓ Typecheck passes or unrelated failures are documented.

---

## Suggested Verification

Run:

npm run typecheck

Run scoped lint:

npx oxlint src/features/setup src/app/dashboard/administration/setup src/config/nav-config.ts

Manual test:

1. Open /dashboard/administration/setup as super_admin.
2. Run readiness.
3. View template pack.
4. Upload valid CSV batch.
5. Run preview.
6. Confirm previewHash appears.
7. Run dryRun commit.
8. Run commit.
9. Re-run verification.
10. Confirm finish summary.
11. Modify selected file after preview.
12. Confirm previewHash clears.
13. Login as non-super_admin and confirm friendly unauthorized behavior.

---

## Follow-up

After D.7.6:

D.7.8 – Seed Manifest and Setup State Persistence

D.7.7 – Scoped Reset and Reseed Engine

D.7.9 – Installation Profile and Plugin Runtime Enhancement
