487 lines
9.5 KiB
Markdown
487 lines
9.5 KiB
Markdown
# 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
|