task-d.7.6

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

@@ -0,0 +1,71 @@
+# 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.