template-saas/orchestration/_archive/planes/PLAN-SPRINT-2-ONBOARDING.md

PLAN SPRINT 2 - Onboarding Wizard Backend

Proyecto: template-saas Sprint: 2 Objetivo: Implementar endpoints backend para completar el wizard de onboarding Fecha Inicio: 2026-01-10 SP Total: 8

---

RESUMEN EJECUTIVO

Estado Actual

• Frontend: 95% completo (4-step wizard implementado)
• Backend: 0% - Endpoints faltantes
• Database: 100% - Schemas listos

Gap a Cerrar

El frontend tiene un wizard de 4 pasos pero el backend no tiene los endpoints necesarios:

1. GET /onboarding/status - Obtener estado del onboarding
2. POST /onboarding/complete - Marcar onboarding como completado
3. POST /tenants - Crear nuevo tenant
4. PATCH /tenants/current - Actualizar tenant actual
5. POST /users/invite - Enviar invitaciones
6. GET /plans - Listar planes disponibles

---

TAREAS DEL SPRINT

ONB-001: Crear Onboarding Module

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: ONB-004

Archivos a Leer

archivos:
  - apps/frontend/src/hooks/useOnboarding.ts  # Ver endpoints esperados
  - apps/backend/src/modules/auth/auth.controller.ts  # Patron de controller
  - apps/backend/src/modules/billing/services/billing.service.ts  # Patron de service

Entregables

entregables:
  - apps/backend/src/modules/onboarding/onboarding.module.ts
  - apps/backend/src/modules/onboarding/onboarding.controller.ts
  - apps/backend/src/modules/onboarding/onboarding.service.ts
  - apps/backend/src/modules/onboarding/dto/onboarding-status.dto.ts
  - apps/backend/src/modules/onboarding/dto/complete-onboarding.dto.ts
  - apps/backend/src/modules/onboarding/__tests__/onboarding.service.spec.ts

Endpoints a Implementar

GET /onboarding/status

• Retorna estado actual del onboarding del tenant
• Response: { step: number, completed: boolean, data: OnboardingData }
• Verifica: tenant.status, subscription, team members

POST /onboarding/complete

• Marca onboarding como completado
• Actualiza tenant.status de 'pending' a 'active'
• Envia email de bienvenida
• Registra en audit log

Criterios de Aceptacion

• Endpoints funcionando
• Tests unitarios (>80% cobertura)
• Integrado en app.module.ts

---

ONB-002: Extender Tenants Module

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: ONB-003

Archivos a Leer

archivos:
  - apps/backend/src/modules/tenants/tenants.controller.ts
  - apps/backend/src/modules/tenants/tenants.service.ts
  - apps/frontend/src/pages/onboarding/steps/CompanyStep.tsx  # Ver campos necesarios
  - apps/database/ddl/schemas/tenants/tables/01-tenants.sql  # Schema

Entregables

entregables:
  - apps/backend/src/modules/tenants/dto/create-tenant.dto.ts
  - apps/backend/src/modules/tenants/dto/update-tenant.dto.ts
  - apps/backend/src/modules/tenants/tenants.controller.ts  # Modificar
  - apps/backend/src/modules/tenants/tenants.service.ts  # Modificar
  - apps/backend/src/modules/tenants/__tests__/tenants.service.spec.ts

Endpoints a Implementar

POST /tenants

• Crea nuevo tenant
• Request body: { name, slug, domain?, logo_url?, settings? }
• Valida unicidad de slug
• Crea con status 'pending'
• Asigna plan Free por defecto

GET /tenants/current

• Retorna tenant del usuario autenticado
• Incluye settings, plan, subscription_status

PATCH /tenants/current

• Actualiza tenant del usuario actual
• Campos editables: name, logo_url, settings (timezone, locale, etc.)
• Valida permisos (solo admin)

Criterios de Aceptacion

• CRUD completo funcionando
• Validacion de slug unico
• Tests unitarios

---

ONB-003: Extender Users Module (Invitaciones)

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: ONB-002

Archivos a Leer

archivos:
  - apps/backend/src/modules/users/users.controller.ts
  - apps/backend/src/modules/users/users.service.ts
  - apps/backend/src/modules/email/services/email.service.ts
  - apps/frontend/src/pages/onboarding/steps/InviteStep.tsx  # Ver campos
  - apps/database/ddl/schemas/users/tables/05-invitations.sql  # Schema

Entregables

entregables:
  - apps/backend/src/modules/users/dto/invite-user.dto.ts
  - apps/backend/src/modules/users/services/invitation.service.ts
  - apps/backend/src/modules/users/users.controller.ts  # Modificar
  - apps/backend/src/modules/users/__tests__/invitation.service.spec.ts

Endpoints a Implementar

POST /users/invite

• Envia invitacion por email
• Request body: { email, role: 'admin'|'member'|'viewer' }
• Crea registro en invitations table
• Genera token unico
• Envia email con link de invitacion

GET /users/invitations

• Lista invitaciones pendientes del tenant
• Incluye status: pending, accepted, expired

POST /users/invitations/:token/resend

• Reenvia email de invitacion
• Genera nuevo token
• Extiende expiracion

DELETE /users/invitations/:id

• Cancela invitacion pendiente

Criterios de Aceptacion

• Flujo de invitacion completo
• Emails enviados correctamente
• Tests unitarios

---

ONB-004: Agregar Plans Endpoint

Agente: Backend-Agent SP: 2 Dependencia: Ninguna Paralelo con: ONB-001

Archivos a Leer

archivos:
  - apps/backend/src/modules/billing/billing.controller.ts
  - apps/backend/src/modules/billing/entities/plan.entity.ts
  - apps/frontend/src/pages/onboarding/steps/PlanStep.tsx  # Ver estructura esperada
  - apps/database/ddl/schemas/plans/seeds/01-seed-plans.sql  # Datos

Entregables

entregables:
  - apps/backend/src/modules/billing/controllers/plans.controller.ts
  - apps/backend/src/modules/billing/services/plans.service.ts
  - apps/backend/src/modules/billing/dto/plan-response.dto.ts
  - apps/backend/src/modules/billing/__tests__/plans.service.spec.ts

Endpoints a Implementar

GET /plans

• Lista planes disponibles (publico o autenticado)
• Response: Array de planes con:
  • id, name, slug, description, tagline
  • price_monthly, price_yearly, currency
  • features (array), limits (object)
  • is_popular, trial_days
• Filtra solo is_active = true, is_visible = true
• Ordena por sort_order

GET /plans/:id

• Detalle de un plan especifico
• Incluye plan_features relacionados

Criterios de Aceptacion

• Endpoint publico funcionando
• Respuesta compatible con frontend
• Tests unitarios

---

EJECUCION DEL SPRINT

Orden de Ejecucion

Dia 1-2:
  ├── ONB-001 (Backend-Agent #1)  ──► Paralelo
  └── ONB-004 (Backend-Agent #2)  ──► Paralelo

Dia 3-4:
  ├── ONB-002 (Backend-Agent #1)  ──► Paralelo
  └── ONB-003 (Backend-Agent #2)  ──► Paralelo

Dia 5:
  └── Integracion y validacion (QA-Agent)

Comandos de Validacion

# Ejecutar tests del modulo onboarding
cd apps/backend && npm run test -- --testPathPattern=onboarding

# Ejecutar tests del modulo tenants
cd apps/backend && npm run test -- --testPathPattern=tenants

# Ejecutar tests del modulo users
cd apps/backend && npm run test -- --testPathPattern=users

# Test de integracion
cd apps/backend && npm run test:e2e -- --testPathPattern=onboarding

Metricas de Exito

Metrica	Objetivo
Endpoints nuevos	8-10
Tests nuevos	~30
Cobertura modulos	>85%
Frontend integrado	100%

---

INTEGRACION CON FRONTEND

Hook useOnboarding.ts - Endpoints Esperados

// Endpoints que el frontend espera:
GET  /onboarding/status          → OnboardingStatus
GET  /tenants/current            → Tenant
PATCH /tenants/current           → Tenant
POST /users/invite               → Invitation[]
GET  /plans                      → Plan[]
POST /billing/subscription       → Subscription (ya existe)
POST /onboarding/complete        → { success: boolean }

Flujo de Onboarding

1. Usuario registra cuenta (auth/register)
   └── Crea user + tenant con status='pending'

2. Redirect a /onboarding
   └── GET /onboarding/status → determina step actual

3. Step 1: Company Info
   └── PATCH /tenants/current → actualiza nombre, logo, settings

4. Step 2: Invite Team
   └── POST /users/invite (multiple) → envia emails

5. Step 3: Select Plan
   └── GET /plans → muestra opciones
   └── POST /billing/subscription → selecciona plan

6. Step 4: Complete
   └── POST /onboarding/complete → activa tenant
   └── Redirect a /dashboard

---

ACTUALIZACIONES POST-SPRINT

Inventarios a Actualizar

• orchestration/PROJECT-STATUS.md - RF-007.4 completado
• orchestration/analisis/VALIDACION-PLAN-VS-REQUERIMIENTOS.md

Documentacion a Actualizar

• docs/api/onboarding.md - Documentar endpoints

---

REFERENCIAS

• apps/frontend/src/pages/onboarding/ - Wizard frontend
• apps/frontend/src/hooks/useOnboarding.ts - Hook con API calls
• orchestration/analisis/ANALISIS-MAESTRO-TEMPLATE-SAAS.md - RF-007.4

---

Creado: 2026-01-10 Sprint: 2 de 5 Estado: COMPLETADO

---

REPORTE DE EJECUCION

Fecha Finalizacion: 2026-01-10

Resultados

Tarea	Archivos Creados	Tests
ONB-001: Onboarding Module	8 archivos	16 tests
ONB-002: Tenants Module	5 archivos	25 tests
ONB-003: User Invitations	6 archivos	17 tests
ONB-004: Plans Endpoint	4 archivos	16 tests

Endpoints Implementados

Endpoint	Método	Descripción
/onboarding/status	GET	Estado del onboarding
/onboarding/complete	POST	Completar onboarding
/tenants	POST	Crear tenant
/tenants/current	GET	Obtener tenant actual
/tenants/current	PATCH	Actualizar tenant
/users/invite	POST	Enviar invitación
/users/invitations	GET	Listar invitaciones
/users/invitations/:token/resend	POST	Reenviar invitación
/users/invitations/:id	DELETE	Cancelar invitación
/plans	GET	Listar planes
/plans/:id	GET	Detalle de plan

Cobertura de Nuevos Módulos

Módulo	Statements	Lines
onboarding.service.ts	96.96%	96.87%
tenants.controller.ts	100%	100%
tenants.service.ts	100%	100%
invitation.service.ts	98.80%	98.76%
plans.service.ts	97.22%	96.96%

Métricas Finales Sprint 2

• Tests nuevos: +66 (710 → 776)
• Test suites nuevos: +3 (31 → 34)
• RF-007.4 (Onboarding Wizard): COMPLETADO