alla-allaos-fullstack/docs/implementation/task-d76-dashboard-setup-wizard-ui.md

Task D.7.6 Dashboard Setup Wizard UI

Date: 2026-07-03 Status: implemented

Scope Delivered

Added dashboard-native setup wizard route:

• GET /dashboard/administration/setup
• Server-side page access restricted to super_admin
• Admin navigation item for Setup Wizard

Added setup UI orchestration:

• src/features/setup/components/setup-wizard.tsx
• src/app/dashboard/administration/setup/page.tsx

Extended setup API client surface:

• src/features/setup/api/types.ts
• src/features/setup/api/service.ts
• src/features/setup/api/queries.ts
• src/features/setup/api/use-csv-commit.ts
• src/features/setup/api/use-setup-verification.ts

Behavior

• Step 1 calls setup readiness and displays overall status, PASS / WARNING / FAIL counts, grouped checks, suggested fixes, loading, error, and permission states.
• Step 2 calls template metadata and displays registered setup templates from the existing setup template API.
• Step 3 accepts one or more CSV files and does not upload them until the user clicks preview.
• Step 4 calls CSV preview, stores previewHash in client state only, displays per-file summaries, row/error/warning counts, and grouped safe error messages.
• Step 5 calls CSV commit with the latest previewHash.
• Commit is disabled when preview has FAIL.
• Commit requires warning acknowledgement when preview has WARNING.
• File changes after preview clear commit eligibility and require re-preview, using file name + size + lastModified fingerprint.
• Step 6 calls setup verification and displays grouped checks plus summary counts.
• Step 7 summarizes readiness, preview, commit, and verification results for the current browser session.

Security And API Notes

• Setup page uses auth() and PageContainer access fallback for non-super-admin users.
• Existing setup APIs remain the enforcement boundary and still require super_admin.
• Upload requests use FormData directly so browser-managed multipart boundaries are preserved.
• UI reads safe API error messages and does not render raw stack traces.
• CSV files are uploaded only to the preview and commit endpoints.
• The wizard does not log CSV data.

Out Of Scope Preserved

• No setup state persistence.
• No seed manifest persistence.
• No destructive reset or reseed behavior.
• No seed execution.
• No database migrations.
• No new CRM behavior.
• No file download or ZIP template generation.

Persistent setup runs and resume behavior remain deferred to D.7.8.

Validation

• npm run typecheck -- --pretty false passed.
• npx oxlint src/features/setup/api/types.ts src/features/setup/api/service.ts src/features/setup/api/queries.ts src/features/setup/api/use-csv-commit.ts src/features/setup/api/use-setup-verification.ts src/features/setup/components/setup-wizard.tsx src/app/dashboard/administration/setup/page.tsx src/config/nav-config.ts passed.
• Existing dev server was already running at http://localhost:3000.
• curl.exe -I -L --max-time 20 http://localhost:3000/dashboard/administration/setup returned 200 OK.

Residual Notes

• plans/task-d.7.6.md was already untracked during implementation and was not modified as part of this delivery.
• The wizard is intentionally session-only until the D.7.8 setup-state persistence slice.