# RF-MGN-015-002: Gestión de Suscripciones de Tenant

**Módulo:** MGN-015 - Billing y Suscripciones
**Prioridad:** P0 (MVP para SaaS)
**Story Points:** 13
**Estado:** Definido
**Fecha:** 2025-11-24

## Descripción

El sistema debe permitir la gestión completa del ciclo de vida de las suscripciones de los tenants, incluyendo la contratación inicial, upgrades/downgrades entre planes, renovaciones automáticas, y cancelaciones. Cada tenant tiene exactamente una suscripción activa que determina sus límites y funcionalidades disponibles.

## Actores

- **Actor Principal:** Tenant Owner (propietario de la organización)
- **Actores Secundarios:**
  - Administrador de Plataforma (gestión manual)
  - Sistema (renovaciones automáticas, validaciones)

## Precondiciones

1. Usuario debe ser `tenant_owner` o `super_admin`
2. Tenant debe existir en el sistema
3. Plan de destino debe estar activo (is_active = true)
4. Método de pago válido (excepto para plan free)

## Flujo Principal - Contratar Suscripción

1. Nuevo tenant se registra en el sistema
2. Sistema crea automáticamente suscripción con plan por defecto (free)
3. Sistema establece período de prueba según configuración del plan
4. Tenant Owner accede a panel de suscripción
5. Sistema muestra plan actual, uso, y opciones de upgrade
6. Usuario selecciona nuevo plan y ciclo de facturación
7. Sistema calcula precio prorrateado si aplica
8. Usuario confirma y proporciona método de pago
9. Sistema procesa pago y actualiza suscripción
10. Sistema registra cambio en historial

## Flujo Alternativo - Upgrade de Plan

### FA-1: Upgrade Inmediato
1. Usuario solicita upgrade a plan superior
2. Sistema calcula diferencia prorrateada del período actual
3. Sistema cobra diferencia al método de pago
4. Sistema actualiza plan inmediatamente
5. Nuevos límites y features disponibles de inmediato

### FA-2: Downgrade al Fin del Período
1. Usuario solicita downgrade a plan inferior
2. Sistema valida que uso actual no exceda límites del nuevo plan
3. Si excede: Sistema muestra advertencia y requiere reducción
4. Sistema programa cambio para fin del período actual
5. Usuario mantiene plan actual hasta renovación

### FA-3: Cancelación
1. Usuario solicita cancelar suscripción
2. Sistema muestra fecha de fin de acceso
3. Sistema ofrece opción de retención (descuento)
4. Usuario confirma cancelación
5. Sistema marca suscripción como `pending_cancellation`
6. Acceso continúa hasta fin del período pagado
7. Al vencer: estado cambia a `canceled`

### FA-4: Renovación Automática
1. Sistema detecta suscripción próxima a vencer (3 días)
2. Sistema intenta cobrar al método de pago principal
3. Si exitoso: Renueva período, envía confirmación
4. Si falla: Marca como `past_due`, notifica usuario
5. Reintenta cobro según política (día 1, 3, 7)
6. Si todos fallan: Suspende suscripción

## Reglas de Negocio

- **RN-1:** Un tenant solo puede tener una suscripción activa
- **RN-2:** Upgrades se aplican inmediatamente con cobro prorrateado
- **RN-3:** Downgrades se aplican al fin del período actual
- **RN-4:** Cancelaciones mantienen acceso hasta fin del período pagado
- **RN-5:** Plan free no requiere método de pago
- **RN-6:** Período de gracia para pagos fallidos: 7 días
- **RN-7:** Suscripciones suspendidas mantienen datos por 30 días
- **RN-8:** Cambio de ciclo (mensual↔anual) aplica en próxima renovación

## Criterios de Aceptación

- [ ] Tenant owner puede ver su suscripción actual y uso
- [ ] Tenant owner puede upgrade a plan superior con pago prorrateado
- [ ] Tenant owner puede downgrade (programado para fin de período)
- [ ] Sistema valida límites antes de permitir downgrade
- [ ] Tenant owner puede cancelar suscripción
- [ ] Sistema renueva automáticamente suscripciones activas
- [ ] Sistema maneja fallos de pago con reintentos
- [ ] Historial de cambios de suscripción disponible
- [ ] Notificaciones por email en eventos clave
- [ ] Super admin puede gestionar cualquier suscripción

## Entidades Involucradas

- **Principales:**
  - billing.subscriptions (id, tenant_id, plan_id, status, billing_cycle, current_period_start/end)
  - billing.subscription_history (registro de todos los cambios)
- **Relacionadas:**
  - billing.subscription_plans (plan contratado)
  - billing.tenant_owners (propietario autorizado)
  - billing.payment_methods (método de cobro)
  - billing.invoices (facturas generadas)

## Estados de Suscripción

```
trialing → active → past_due → suspended → canceled
                  ↓
            pending_cancellation → canceled
```

| Estado | Descripción |
|--------|-------------|
| trialing | Período de prueba activo |
| active | Suscripción pagada y activa |
| past_due | Pago fallido, en período de gracia |
| suspended | Acceso suspendido por falta de pago |
| pending_cancellation | Cancelación programada |
| canceled | Suscripción terminada |

## Referencias

- [RF-MGN-015-001](./RF-MGN-015-001-gestion-planes-suscripcion.md) - Gestión de Planes
- [RF-MGN-015-003](./RF-MGN-015-003-metodos-pago.md) - Métodos de Pago
- [Billing Schema DDL](../database-design/schemas/billing-schema-ddl.sql)

## Notas Técnicas

- **Tabla principal:** `billing.subscriptions`
- **Trigger:** `log_subscription_change()` registra todo cambio en historial
- **Función:** `billing.get_tenant_plan(tenant_id)` retorna plan actual
- **Función:** `billing.can_add_user(tenant_id)` valida límite de usuarios
- **Jobs programados:**
  - Renovación automática (diario)
  - Reintentos de pago (días 1, 3, 7)
  - Suspensión por falta de pago (día 8)

## Dependencias

- **RF Requeridos:** RF-MGN-015-001 (Planes deben existir)
- **Bloqueante para:**
  - RF-MGN-015-003 (Métodos de Pago)
  - RF-MGN-015-004 (Facturación)