# MGN-015: Billing y Suscripciones

## Descripción del Módulo

El módulo de Billing y Suscripciones gestiona todo el ciclo de vida comercial de la plataforma SaaS, incluyendo la definición de planes, gestión de suscripciones, cobros automáticos, facturación, y monitoreo de uso. También soporta un modo single-tenant para instalaciones on-premise.

## Requerimientos Funcionales

| ID | Nombre | Prioridad | Story Points | Estado |
|----|--------|-----------|--------------|--------|
| [RF-MGN-015-001](./RF-MGN-015-001-gestion-planes-suscripcion.md) | Gestión de Planes de Suscripción | P0 | 8 | Definido |
| [RF-MGN-015-002](./RF-MGN-015-002-gestion-suscripciones-tenant.md) | Gestión de Suscripciones de Tenant | P0 | 13 | Definido |
| [RF-MGN-015-003](./RF-MGN-015-003-metodos-pago.md) | Gestión de Métodos de Pago | P0 | 8 | Definido |
| [RF-MGN-015-004](./RF-MGN-015-004-facturacion-cobros.md) | Facturación y Cobros | P0 | 13 | Definido |
| [RF-MGN-015-005](./RF-MGN-015-005-registro-uso-metricas.md) | Registro de Uso y Métricas | P1 | 8 | Definido |
| [RF-MGN-015-006](./RF-MGN-015-006-modo-single-tenant.md) | Modo Single-Tenant | P1 | 5 | Definido |
| [RF-MGN-015-007](./RF-MGN-015-007-pricing-por-usuario.md) | Pricing por Usuario (Per-Seat) | P0 | 13 | Definido |

**Total Story Points:** 68

## Dependencias

### Dependencias Internas
- **MGN-001 (Autenticación):** Gestión de tenants y usuarios
- **MGN-002 (Core):** Configuraciones del sistema
- **MGN-004 (Financiero):** Generación de asientos contables por cobros de suscripción
- **MGN-014 (Mensajería):** Notificaciones de eventos y auditoría de cambios

### Dependencias Externas
- Gateway de pagos (Stripe, Conekta, MercadoPago)
- PAC para CFDI (Facturama, SW Sapien)
- Servicio de email para notificaciones

### Es Dependencia de (Bloqueante para)
- **MGN-016 (Pagos):** Feature flags de integraciones habilitadas
- **MGN-017 (WhatsApp):** Feature flags de canales habilitados
- **MGN-018 (AI Agents):** Control de consumo de tokens y límites

## Diagrama de Dependencias entre RFs

```
RF-001 (Planes)
    │
    ▼
RF-002 (Suscripciones) ──────► RF-006 (Single-Tenant)
    │
    ▼
RF-003 (Métodos Pago)
    │
    ▼
RF-004 (Facturación)
    │
    ▼
RF-005 (Uso/Métricas)
```

## Actores del Módulo

| Actor | Descripción | RFs Relacionados |
|-------|-------------|------------------|
| Super Admin | Administrador de plataforma SaaS | RF-001 |
| Tenant Owner | Propietario de organización | RF-002, RF-003, RF-004, RF-005 |
| Sistema | Procesos automáticos | RF-002, RF-004, RF-005 |
| Gateway | Procesador de pagos externo | RF-003, RF-004 |

## Entidades Principales

- `billing.subscription_plans` - Definición de planes disponibles
- `billing.subscriptions` - Suscripciones activas por tenant
- `billing.tenant_owners` - Propietarios de cuenta
- `billing.payment_methods` - Métodos de pago tokenizados
- `billing.invoices` - Facturas generadas
- `billing.invoice_lines` - Líneas de detalle de factura
- `billing.payments` - Registro de pagos/transacciones
- `billing.usage_records` - Métricas de uso por período
- `billing.coupons` - Cupones de descuento
- `billing.coupon_redemptions` - Cupones aplicados
- `billing.subscription_history` - Historial de cambios

## Modos de Operación

### SaaS Multi-Tenant
- Múltiples organizaciones en una instancia
- Billing y cobros automáticos activos
- Límites según plan contratado
- Registro público de nuevos tenants

### Single-Tenant On-Premise
- Una organización por instancia
- Billing deshabilitado/oculto
- Sin límites de uso
- Branding personalizable

## Notas de Implementación

1. **Seguridad de Pagos:** Nunca almacenar datos sensibles de tarjetas; usar tokenización del gateway
2. **CFDI:** Requerido para clientes mexicanos con RFC
3. **Reintentos:** Política de 3 intentos (días 1, 3, 7) antes de suspender
4. **Histórico:** Mantener facturas y registros por 5 años mínimo
5. **Caché:** Uso actual en Redis para validaciones rápidas de límites