TapTrack-Hub/.paul/phases/14-onboarding-wizard

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