# 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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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

```bash
# 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

```typescript
// 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