# RF-MGN-015-001: Gestión de Planes de Suscripción

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

## Descripción

El sistema debe permitir la definición y gestión de planes de suscripción que determinan las características, límites y precios disponibles para los tenants. Los planes son globales (no pertenecen a un tenant específico) y definen qué funcionalidades están disponibles para cada nivel de servicio.

## Actores

- **Actor Principal:** Administrador de Plataforma (super_admin)
- **Actores Secundarios:** Sistema (validación automática de límites)

## Precondiciones

1. Usuario debe tener rol `super_admin` o `platform_admin`
2. Schema `billing` debe existir en la base de datos

## Flujo Principal

1. Administrador accede al panel de administración de planes
2. Sistema muestra lista de planes existentes (free, basic, professional, enterprise)
3. Administrador puede:
   - Ver detalles de cada plan
   - Crear nuevo plan
   - Editar plan existente
   - Activar/desactivar plan
4. Al crear/editar plan, administrador define:
   - Código único (ej: "basic", "pro")
   - Nombre visible (ej: "Plan Básico")
   - Descripción
   - Precios (mensual, anual)
   - Límites (usuarios, empresas, almacenamiento)
   - Features habilitadas (JSON)
   - Días de prueba
   - Orden de visualización
5. Sistema valida datos y guarda cambios
6. Cambios se reflejan inmediatamente para nuevas suscripciones

## Flujos Alternativos

### FA-1: Plan con Suscripciones Activas
1. Si administrador intenta eliminar plan con suscripciones activas
2. Sistema muestra error: "No se puede eliminar plan con suscripciones activas"
3. Sistema sugiere desactivar plan en su lugar

### FA-2: Cambio de Precio
1. Si se modifica precio de un plan
2. Sistema pregunta: "¿Aplicar a suscripciones existentes en próxima renovación?"
3. Administrador selecciona opción
4. Sistema registra cambio en historial

## Reglas de Negocio

- **RN-1:** Códigos de plan deben ser únicos (ej: "basic", "pro", "enterprise")
- **RN-2:** Debe existir al menos un plan por defecto para nuevos tenants
- **RN-3:** Plan "single_tenant" es especial y no visible públicamente
- **RN-4:** Features se definen como JSON: `{"inventory": true, "sales": true, ...}`
- **RN-5:** max_users = NULL significa usuarios ilimitados
- **RN-6:** Precio 0 indica plan gratuito
- **RN-7:** Cambios de precio no afectan suscripciones existentes hasta renovación

## Criterios de Aceptación

- [ ] Super admin puede listar todos los planes de suscripción
- [ ] Super admin puede crear nuevos planes con todos sus atributos
- [ ] Super admin puede editar planes existentes
- [ ] Super admin puede activar/desactivar planes
- [ ] Planes desactivados no aparecen en página de precios pública
- [ ] Plan por defecto se asigna automáticamente a nuevos tenants
- [ ] Sistema valida unicidad de código de plan
- [ ] Features se almacenan como JSONB para flexibilidad
- [ ] Historial de cambios de planes se registra

## Entidades Involucradas

- **Principales:**
  - billing.subscription_plans (id, code, name, price_monthly, price_yearly, max_users, features)
- **Relacionadas:**
  - billing.subscriptions (referencia plan_id)
  - auth.tenants (campo plan para retrocompatibilidad)

## Referencias

- [ALCANCE-POR-MODULO.md - MGN-015](../../01-definicion-modulos/ALCANCE-POR-MODULO.md#mgn-015-billing)
- [Billing Schema DDL](../database-design/schemas/billing-schema-ddl.sql)

## Notas Técnicas

- **Tabla:** `billing.subscription_plans`
- **No tiene tenant_id:** Los planes son globales del sistema
- **Features JSON ejemplo:**
  ```json
  {
    "inventory": true,
    "sales": true,
    "financial": true,
    "purchase": true,
    "crm": false,
    "projects": false,
    "reports_basic": true,
    "reports_advanced": false,
    "api_access": false,
    "white_label": false
  }
  ```
- **Función de verificación:** `billing.has_feature(tenant_id, 'feature_name')`

## Dependencias

- **RF Dependientes:** Ninguno (funcionalidad base de billing)
- **Bloqueante para:** RF-MGN-015-002 (Gestión de Suscripciones)