task-d.7.11
This commit is contained in:
phaichayon
340
plans/task-d.7.11.md
Normal file
340
plans/task-d.7.11.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# Task D.7.11 – First-Run Bootstrap Setup Mode
|
||||
|
||||
## Objective
|
||||
|
||||
Implement first-run setup mode for ALLA OS.
|
||||
|
||||
When the database is newly migrated and the system has not been initialized, the app must automatically redirect users to a public bootstrap setup page without requiring login.
|
||||
|
||||
The bootstrap setup page allows uploading required CSV files, validates them, commits setup data, creates the first organization and administrator, marks setup as completed, and then redirects the user to login.
|
||||
|
||||
---
|
||||
|
||||
## Desired Flow
|
||||
|
||||
npm install
|
||||
npm run db:generate
|
||||
npm run db:migrate
|
||||
npm run dev
|
||||
|
||||
Open browser
|
||||
|
||||
If setup is not completed:
|
||||
|
||||
redirect to
|
||||
|
||||
/administration/setup
|
||||
|
||||
No login required.
|
||||
|
||||
User uploads CSV files:
|
||||
|
||||
- users.csv
|
||||
- organizations.csv
|
||||
- memberships.csv
|
||||
- master-options.csv
|
||||
- branches.csv
|
||||
- product-types.csv
|
||||
- document-sequences.csv
|
||||
- approval-workflows.csv
|
||||
- approval-steps.csv
|
||||
- approval-matrix.csv
|
||||
- customers.csv
|
||||
- contacts.csv
|
||||
- leads.csv
|
||||
- opportunities.csv
|
||||
- quotations.csv
|
||||
- quotation-items.csv
|
||||
- quotation-parties.csv
|
||||
- quotation-topics.csv
|
||||
- quotation-topic-items.csv
|
||||
|
||||
Click Setup
|
||||
|
||||
System validates CSV
|
||||
|
||||
System commits data
|
||||
|
||||
System creates first admin
|
||||
|
||||
System marks setup completed
|
||||
|
||||
Redirect to login
|
||||
|
||||
User logs in and starts using the system
|
||||
|
||||
---
|
||||
|
||||
## Key Concept
|
||||
|
||||
There are now two setup modes:
|
||||
|
||||
1. Bootstrap Setup
|
||||
|
||||
Used before first login.
|
||||
|
||||
Route:
|
||||
|
||||
/administration/setup
|
||||
|
||||
No login required only when setup is not completed.
|
||||
|
||||
2. Admin Setup / Maintenance Setup
|
||||
|
||||
Used after login.
|
||||
|
||||
Route:
|
||||
|
||||
/dashboard/administration/setup
|
||||
|
||||
Requires super_admin.
|
||||
|
||||
---
|
||||
|
||||
## Required Behavior
|
||||
|
||||
## First Run Detection
|
||||
|
||||
Create setup status check:
|
||||
|
||||
System is not initialized when:
|
||||
|
||||
- no completed setup_run exists
|
||||
or
|
||||
- no super_admin user exists
|
||||
or
|
||||
- no organization exists
|
||||
or
|
||||
- no admin membership exists
|
||||
|
||||
System is initialized when:
|
||||
|
||||
- setup_run status = completed
|
||||
- at least one super_admin exists
|
||||
- at least one organization exists
|
||||
- admin membership exists
|
||||
|
||||
---
|
||||
|
||||
## Middleware Redirect
|
||||
|
||||
Update middleware behavior:
|
||||
|
||||
If setup is not completed:
|
||||
|
||||
allow only:
|
||||
|
||||
/administration/setup
|
||||
/api/setup/bootstrap/*
|
||||
/api/setup/templates
|
||||
/_next/*
|
||||
static assets
|
||||
|
||||
redirect all other routes to:
|
||||
|
||||
/administration/setup
|
||||
|
||||
If setup is completed:
|
||||
|
||||
/administration/setup redirects to:
|
||||
|
||||
/auth/sign-in
|
||||
|
||||
or
|
||||
|
||||
/dashboard
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap Setup Page
|
||||
|
||||
Create:
|
||||
|
||||
src/app/administration/setup/page.tsx
|
||||
|
||||
This page must not use dashboard layout.
|
||||
|
||||
It should be a clean public setup page.
|
||||
|
||||
Show:
|
||||
|
||||
- System status
|
||||
- Required CSV upload
|
||||
- Template checklist
|
||||
- Preview result
|
||||
- Setup button
|
||||
- Completion screen
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap APIs
|
||||
|
||||
Create public-but-guarded bootstrap APIs:
|
||||
|
||||
GET /api/setup/bootstrap/status
|
||||
|
||||
POST /api/setup/bootstrap/preview
|
||||
|
||||
POST /api/setup/bootstrap/commit
|
||||
|
||||
POST /api/setup/bootstrap/complete
|
||||
|
||||
These APIs do not require login only while setup is incomplete.
|
||||
|
||||
After setup is completed, these APIs must reject public access.
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap Security
|
||||
|
||||
Even though no login is required, it must be protected by first-run rules.
|
||||
|
||||
Rules:
|
||||
|
||||
- Bootstrap APIs are enabled only when setup is incomplete.
|
||||
- Once completed, bootstrap APIs return 403.
|
||||
- Commit requires previewHash.
|
||||
- Commit re-runs preview.
|
||||
- Commit rejects hash mismatch.
|
||||
- Setup complete requires successful commit.
|
||||
- Never expose secrets.
|
||||
- Passwords from users.csv must be hashed.
|
||||
- No raw CSV contents are persisted.
|
||||
|
||||
Optional safety:
|
||||
|
||||
Require BOOTSTRAP_SETUP_TOKEN from .env if present.
|
||||
|
||||
If env exists:
|
||||
|
||||
User must enter token before setup.
|
||||
|
||||
---
|
||||
|
||||
## CSV Upload UX
|
||||
|
||||
The page should show required groups:
|
||||
|
||||
Foundation:
|
||||
|
||||
- users.csv
|
||||
- organizations.csv
|
||||
- memberships.csv
|
||||
- master-options.csv
|
||||
- branches.csv
|
||||
- product-types.csv
|
||||
|
||||
Document / Approval:
|
||||
|
||||
- document-sequences.csv
|
||||
- approval-workflows.csv
|
||||
- approval-steps.csv
|
||||
- approval-matrix.csv
|
||||
|
||||
Business optional:
|
||||
|
||||
- customers.csv
|
||||
- contacts.csv
|
||||
- leads.csv
|
||||
- opportunities.csv
|
||||
- quotations.csv
|
||||
- quotation-items.csv
|
||||
- quotation-parties.csv
|
||||
- quotation-topics.csv
|
||||
- quotation-topic-items.csv
|
||||
|
||||
Allow partial setup:
|
||||
|
||||
Required minimum:
|
||||
|
||||
- users.csv
|
||||
- organizations.csv
|
||||
- memberships.csv
|
||||
- master-options.csv
|
||||
- branches.csv
|
||||
- product-types.csv
|
||||
- document-sequences.csv
|
||||
- approval-workflows.csv
|
||||
- approval-steps.csv
|
||||
- approval-matrix.csv
|
||||
|
||||
Business CSV can be optional.
|
||||
|
||||
---
|
||||
|
||||
## Setup Completion
|
||||
|
||||
After successful commit:
|
||||
|
||||
- create setup_run completed
|
||||
- create seed_manifests
|
||||
- mark setup status completed
|
||||
- redirect to /auth/sign-in
|
||||
|
||||
Show message:
|
||||
|
||||
Setup completed. Please login with the administrator account from users.csv.
|
||||
|
||||
---
|
||||
|
||||
## Reuse Existing D.7 Work
|
||||
|
||||
Reuse:
|
||||
|
||||
- CSV templates from D.7.3
|
||||
- CSV preview engine from D.7.4
|
||||
- CSV commit engine from D.7.5
|
||||
- setup state from D.7.8
|
||||
- seed manifest from D.7.8
|
||||
- plugin profiles from D.7.9
|
||||
|
||||
Do not rewrite import engine.
|
||||
|
||||
---
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Dashboard setup redesign
|
||||
- New CSV format
|
||||
- Reset/reseed
|
||||
- Plugin marketplace
|
||||
- Production public setup after completed
|
||||
- Anonymous setup after system is initialized
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Fresh database redirects to /administration/setup without login.
|
||||
- /administration/setup works before first login.
|
||||
- Bootstrap setup page can upload CSV files.
|
||||
- Preview validates CSV files.
|
||||
- Setup commit imports required setup data.
|
||||
- First admin user is created.
|
||||
- Organization is created.
|
||||
- Setup run is marked completed.
|
||||
- User is redirected to login.
|
||||
- After completion, /administration/setup no longer allows public setup.
|
||||
- After completion, dashboard setup requires super_admin.
|
||||
- Existing /dashboard/administration/setup remains available for maintenance.
|
||||
- No duplicate CSV validation/import logic is created.
|
||||
- Typecheck passes.
|
||||
|
||||
---
|
||||
|
||||
## Suggested Test
|
||||
|
||||
1. Drop/reset database.
|
||||
2. Run migration.
|
||||
3. Run dev server.
|
||||
4. Open `/`.
|
||||
5. Confirm redirect to `/administration/setup`.
|
||||
6. Upload required CSV files.
|
||||
7. Preview.
|
||||
8. Commit setup.
|
||||
9. Confirm redirect to login.
|
||||
10. Login with admin from CSV.
|
||||
11. Open dashboard.
|
||||
12. Confirm CRM works.
|
||||
13. Try opening `/administration/setup` again.
|
||||
14. Confirm public setup is blocked.
|
||||
Reference in New Issue
Block a user