allagroup/alla-allaos-fullstack

Template

Fork 0

Files

phaichayon 110c2f9e7f task-d.7.6

2026-07-03 09:51:36 +07:00

9.5 KiB

Raw Blame History

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

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:

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:

Open /dashboard/administration/setup as super_admin.
Run readiness.
View template pack.
Upload valid CSV batch.
Run preview.
Confirm previewHash appears.
Run dryRun commit.
Run commit.
Re-run verification.
Confirm finish summary.
Modify selected file after preview.
Confirm previewHash clears.
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

9.5 KiB Raw Blame History Unescape Escape

Task D.7.6 – Dashboard Setup Wizard UI

Objective

Review Before Implementation

Implementation Scope

Route and Navigation

Wizard Steps

Step 1 – System Readiness

Step 2 – Template Pack

Step 3 – CSV Upload

Step 4 – CSV Preview

Step 5 – CSV Commit

Step 6 – Verification

Step 7 – Finish

UI Requirements

UX Requirements

State Management

API Integration Rules

CSV File Change Rules

Out Of Scope

Deliverables

Acceptance Criteria

Suggested Verification

Follow-up

9.5 KiB

Raw Blame History