rckrdmrd/erp-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f95b8d4577
erp-core/docs/04-modelado/requerimientos-funcionales/mgn-015/RF-MGN-015-002-gestion-suscripciones-tenant.md

5.7 KiB
Raw Blame History

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

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)