# 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