1c847fbe04
- Rename _archivo to _archive (standard convention) - Move analisis/, planes/ to _archive/ - Archive extra root files - Update _MAP.md with standardized structure Standard: SIMCO-ESTANDAR-ORCHESTRATION v1.0.0 Level: PROVIDER (L1A) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
384 lines
10 KiB
Markdown
384 lines
10 KiB
Markdown
# 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
|