allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

task-d.7.6

Browse Source
This commit is contained in:
phaichayon
2026-07-03 09:51:36 +07:00
parent b7589017ab
commit 110c2f9e7f
10 changed files with 1376 additions and 392 deletions
Download Patch File Download Diff File Expand all files Collapse all files

486
plans/task-d.7.6.md Normal file
View File

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