# 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

```sql
-- 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](./RF-MGN-015-001-gestion-planes-suscripcion.md) - Planes (límites)
- [RF-MGN-015-002](./RF-MGN-015-002-gestion-suscripciones-tenant.md) - 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)