erp-core/docs/04-modelado/requerimientos-funcionales/mgn-015/RF-MGN-015-005-registro-uso-metricas.md

RF-MGN-015-005: Registro de Uso y Métricas

Módulo: MGN-015 - Billing y Suscripciones Prioridad: P1 Story Points: 8 Estado: Definido Fecha: 2025-11-24

Descripción

El sistema debe registrar y monitorear el uso de recursos por tenant para: (1) validar límites según el plan contratado, (2) facturar uso adicional cuando aplique, y (3) proporcionar métricas de consumo a los administradores. Los recursos monitoreados incluyen usuarios activos, empresas, almacenamiento, y transacciones.

Actores

• Actor Principal: Sistema (registro automático)
• Actores Secundarios:
  • Tenant Owner (consulta de uso)
  • Administrador de Plataforma (análisis global)

Precondiciones

1. Tenant con suscripción activa
2. Plan con límites definidos
3. Sistema de métricas configurado

Flujo Principal - Registro de Uso

1. Usuario realiza acción que consume recurso
2. Sistema intercepta acción vía middleware/trigger
3. Sistema verifica límite según plan actual
4. Si dentro del límite: Permite acción, registra uso
5. Si excede límite:
   • Verifica si plan permite uso adicional facturable
   • Si permite: Registra como uso adicional
   • Si no permite: Bloquea acción con mensaje claro

Flujos Alternativos

FA-1: Validación de Usuarios

1. Admin intenta crear nuevo usuario
2. Sistema consulta billing.can_add_user(tenant_id)
3. Función verifica: usuarios_activos < max_users del plan
4. Si válido: Permite creación
5. Si excede: Muestra "Límite de usuarios alcanzado. Upgrade necesario."

FA-2: Validación de Empresas

1. Admin intenta crear nueva empresa
2. Sistema consulta límite de empresas del plan
3. Si válido: Permite creación
4. Si excede: Muestra "Límite de empresas alcanzado"

FA-3: Monitoreo de Almacenamiento

1. Sistema calcula uso de almacenamiento periódicamente
2. Si uso > 80%: Notifica al tenant owner
3. Si uso > 100%: Bloquea nuevas subidas
4. Usuario debe liberar espacio o upgrade

FA-4: Dashboard de Uso

1. Tenant owner accede a panel de uso
2. Sistema muestra:
   • Usuarios: 8/10 (80%)
   • Empresas: 1/1 (100%)
   • Almacenamiento: 2.5GB/5GB (50%)
3. Sistema muestra gráfica histórica de uso
4. Sistema recomienda upgrade si uso > 80%

Reglas de Negocio

• RN-1: Uso se registra en tiempo real para recursos críticos
• RN-2: Almacenamiento se calcula cada 6 horas
• RN-3: max_users = NULL significa usuarios ilimitados
• RN-4: Uso histórico se mantiene por 12 meses
• RN-5: Alertas se envían al 80% y 100% de uso
• RN-6: Bloqueo suave: advertencia pero permite continuar
• RN-7: Bloqueo duro: impide acción completamente

Métricas Monitoreadas

Métrica	Tipo	Límite en Plan	Uso Adicional
Usuarios activos	Conteo	max_users	No
Empresas	Conteo	max_companies	No
Almacenamiento	GB	max_storage_gb	Sí ($X/GB)
Transacciones/mes	Conteo	max_transactions	Sí ($X/1000)
API calls/mes	Conteo	max_api_calls	Sí ($X/10000)

Criterios de Aceptación

• Sistema valida límite de usuarios antes de crear
• Sistema valida límite de empresas antes de crear
• Sistema monitorea uso de almacenamiento
• Tenant owner puede ver dashboard de uso actual
• Sistema muestra alertas al acercarse a límites
• Sistema bloquea acciones cuando se exceden límites
• Sistema registra histórico de uso por período
• Admin puede ver métricas globales de todos los tenants
• Sistema calcula uso adicional para facturación

Entidades Involucradas

• Principales:
  • billing.usage_records (id, tenant_id, metric_type, quantity, period_start/end)
• Relacionadas:
  • billing.subscriptions (plan con límites)
  • billing.subscription_plans (definición de límites)
  • billing.invoices (facturación de uso adicional)

Dashboard de Uso

┌─────────────────────────────────────────────────────┐
│ USO DEL PLAN: Professional                          │
├─────────────────────────────────────────────────────┤
│                                                     │
│ Usuarios          ████████░░ 8/10 (80%)            │
│                   ⚠️ Próximo al límite              │
│                                                     │
│ Empresas          ██████████ 1/1 (100%)            │
│                   🚫 Límite alcanzado              │
│                                                     │
│ Almacenamiento    █████░░░░░ 2.5/5 GB (50%)        │
│                   ✓ OK                              │
│                                                     │
│ API Calls (mes)   ███░░░░░░░ 3K/10K (30%)          │
│                   ✓ OK                              │
│                                                     │
├─────────────────────────────────────────────────────┤
│ [Upgrade Plan] para aumentar límites                │
└─────────────────────────────────────────────────────┘

Funciones de Validación

-- Verificar si puede agregar usuario
SELECT billing.can_add_user('tenant-uuid');
-- Returns: true/false

-- Obtener uso actual
SELECT billing.get_current_usage('tenant-uuid', 'users');
-- Returns: { current: 8, limit: 10, percentage: 80 }

-- Verificar feature habilitada
SELECT billing.has_feature('tenant-uuid', 'api_access');
-- Returns: true/false

Referencias

• RF-MGN-015-001 - Planes (límites)
• RF-MGN-015-002 - Suscripciones

Notas Técnicas

• Tabla: billing.usage_records
• Trigger: En auth.users para conteo de usuarios
• Trigger: En companies.companies para conteo de empresas
• Job: Cálculo de almacenamiento cada 6 horas
• Cache: Uso actual en Redis para validaciones rápidas
• Agregación: Métricas mensuales para histórico

Dependencias

• RF Requeridos: RF-MGN-015-001, RF-MGN-015-002
• Relacionado con: RF-MGN-015-004 (Facturación de uso adicional)