67 lines
2.7 KiB
Markdown
67 lines
2.7 KiB
Markdown
# Phase 14: Onboarding Wizard + Welcome Email
|
||
|
||
**Status:** Not started
|
||
**Depends on:** Phase 9 (Email — welcome email template)
|
||
|
||
## Goal
|
||
|
||
When a new school is registered, automatically send a welcome email with the license key
|
||
and setup instructions. Super admin has a visual onboarding checklist in SchoolDetailPage
|
||
to track setup completion and activate the school.
|
||
|
||
## Planned Scope
|
||
|
||
### Backend
|
||
|
||
**Welcome email auto-send on school creation**
|
||
- `POST /api/schools` — after school + license are created, fire `onboarding.send_welcome_email` task
|
||
- Template `welcome.html` — school name, license key (formatted), setup URL, portal login URL
|
||
|
||
**New Celery task: `onboarding.send_welcome_email(school_id)`**
|
||
- Renders `welcome.html` with school + license data
|
||
- Sends to `school.billing_email` or `school.contact_email`
|
||
- Logs to `email_logs` (Phase 9)
|
||
|
||
**`onboarding_completed_at` column on School**
|
||
- Set when super admin clicks "Complete Onboarding" / "Activate School"
|
||
|
||
**New endpoint: `POST /api/schools/{id}/activate`**
|
||
- Sets `school.status = active` + `school.onboarding_completed_at = now()`
|
||
- Validates that license exists and billing plan is set
|
||
|
||
**"Resend welcome email" endpoint**
|
||
- `POST /api/schools/{id}/resend-welcome` — re-fires the welcome email task
|
||
|
||
### Frontend
|
||
|
||
**SchoolDetailPage.vue** — Onboarding Checklist panel
|
||
- Visible when `school.status == pending`
|
||
- Steps with checkmarks:
|
||
1. School created ✓ (always done)
|
||
2. License issued (check if license exists)
|
||
3. Billing plan set (check if subscription exists)
|
||
4. SMS credits added (check if sms_credits > 0)
|
||
5. Welcome email sent (check if email_logs has a welcome email for this school)
|
||
6. School admin account created (check if any school_admin users linked)
|
||
- "Resend Welcome Email" button
|
||
- "Activate School" button (calls POST /api/schools/{id}/activate)
|
||
- Disabled until steps 1–3 are complete
|
||
|
||
**welcome.html** Jinja2 email template
|
||
- School name, license key (large monospace display)
|
||
- Step-by-step setup instructions
|
||
- Link to Hub portal: `{HUB_BASE_URL}/login`
|
||
- Contact support link
|
||
|
||
## Key Files to Create/Modify
|
||
|
||
- `backend/app/models/school.py` — add `onboarding_completed_at` column
|
||
- `backend/app/tasks/onboarding.py` (new) — send_welcome_email task
|
||
- `backend/app/worker.py` — include onboarding tasks
|
||
- `backend/app/routers/schools.py` — auto-trigger welcome email on create,
|
||
add POST /{id}/activate, POST /{id}/resend-welcome
|
||
- `backend/app/templates/email/welcome.html` (new)
|
||
- `backend/migrations/versions/006_onboarding_fields.py` (new)
|
||
- `frontend/src/pages/SchoolDetailPage.vue` — onboarding checklist panel
|
||
- `frontend/src/lib/api.ts` — activateSchool, resendWelcomeEmail
|