erp-core/docs/08-epicas/EPIC-MGN-021-ai-tokens.md

# EPICA: EPIC-MGN-021 - Control y Facturacion de Tokens IA

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-MGN-021 |
| **Nombre** | Control y Facturacion de Tokens IA |
| **Modulo** | billing, ai |
| **Fase** | Fase 5 - AI Integration |
| **Prioridad** | P0 |
| **Estado** | Backlog |
| **Story Points** | 26 |
| **Sprint(s)** | Sprint 24-26 |

---

## Descripcion

Sistema de control, medicion y facturacion del uso de tokens de IA en la plataforma. Incluye tracking en tiempo real, limites por plan, alertas de consumo, y facturacion automatica por uso excedente.

---

## Objetivo de Negocio

- Controlar costos de IA por tenant
- Monetizar uso de IA como servicio adicional
- Evitar abuso del sistema
- Proporcionar transparencia en consumo

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-MGN021-001 | Como sistema, quiero registrar tokens usados en cada llamada IA | P0 | 5 | Backlog |
| US-MGN021-002 | Como tenant owner, quiero ver mi consumo de tokens | P0 | 3 | Backlog |
| US-MGN021-003 | Como sistema, quiero validar limites de tokens antes de ejecutar | P0 | 5 | Backlog |
| US-MGN021-004 | Como tenant owner, quiero recibir alertas de consumo alto | P0 | 3 | Backlog |
| US-MGN021-005 | Como sistema, quiero calcular costo de tokens en factura | P0 | 5 | Backlog |
| US-MGN021-006 | Como admin, quiero configurar precios de tokens | P0 | 3 | Backlog |
| US-MGN021-007 | Como tenant owner, quiero comprar paquete de tokens adicionales | P1 | 3 | Backlog |

**Total Story Points:** 27 SP

---

## Criterios de Aceptacion

**Funcionales:**
- [ ] Registro de cada llamada IA con tokens input/output
- [ ] Dashboard de consumo por periodo
- [ ] Desglose por tipo de operacion (WA, asistente, embeddings)
- [ ] Validacion de limite antes de ejecutar
- [ ] Bloqueo o degradacion al exceder limite
- [ ] Alertas configurables (50%, 80%, 100%)
- [ ] Linea en factura por tokens excedentes
- [ ] Compra de paquetes adicionales

**No Funcionales:**
- [ ] Registro asincrono (no impactar latencia)
- [ ] Precision de +/- 1% en conteo
- [ ] Retencion de 12 meses de historial

---

## Tipos de Tokens

| Metrica | Descripcion | Precio/1K |
|---------|-------------|-----------|
| ai_input_tokens | Tokens de entrada (prompts) | $0.003 USD |
| ai_output_tokens | Tokens de salida (respuestas) | $0.015 USD |
| ai_embeddings | Tokens de embeddings | $0.0001 USD |
| whatsapp_ai_conversations | Conversaciones WA procesadas | $0.05 USD/conv |

---

## Limites por Plan

| Plan | Tokens Incluidos | Overage |
|------|------------------|---------|
| Starter | 100,000/mes | No permitido |
| Growth | 500,000/mes | A precio de lista |
| Enterprise | Negociable | A precio de lista |

---

## Flujo de Tracking

```
[Llamada a AI API]
       |
       v
[AI Service Wrapper]
       |
       ├── Contar tokens input
       ├── Llamar API externa
       ├── Contar tokens output
       |
       v
[Token Logger (async)]
       |
       ├── Insertar en usage_records
       ├── Actualizar contador periodo
       |
       v
[Limit Checker]
       |
       ├── Si < limite: OK
       ├── Si > warning: alertar
       └── Si > limite: bloquear/degradar
```

---

## Alertas

| Nivel | Threshold | Accion |
|-------|-----------|--------|
| Info | 50% | Email informativo |
| Warning | 80% | Email + push + in-app |
| Critical | 95% | Email + llamada (enterprise) |
| Blocked | 100% | Bloqueo de nuevas llamadas |

---

## Dependencias

**Depende de:**
- EPIC-MGN-016 Billing (facturacion)
- EPIC-MGN-017 Stripe (cobro)
- EPIC-MGN-018 WhatsApp (uso de IA)

**Bloquea:**
- Ninguna (habilita facturacion justa)

---

## Desglose Tecnico

**Database:**
- [ ] Extender billing.usage_records
- [ ] Vista: vw_ai_usage_summary
- [ ] Tabla: ai_token_packages (paquetes adicionales)

**Backend:**
- [ ] Service: AITokenService
- [ ] Middleware: TokenTrackingMiddleware
- [ ] Job: UsageAlertJob
- [ ] Job: MonthlyUsageBillingJob

**Frontend:**
- [ ] Dashboard de consumo IA
- [ ] Configuracion de alertas
- [ ] Compra de paquetes

---

## Modelo de Datos

```sql
-- Paquetes de tokens adicionales
CREATE TABLE billing.ai_token_packages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL REFERENCES core_tenants.tenants(id),

    tokens_purchased INT NOT NULL,
    price_paid DECIMAL(10,2) NOT NULL,
    currency VARCHAR(3) DEFAULT 'USD',

    tokens_remaining INT NOT NULL,
    expires_at TIMESTAMPTZ,

    purchased_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    stripe_payment_id VARCHAR(50)
);

-- Vista de uso agregado
CREATE VIEW billing.vw_ai_usage_current AS
SELECT
    tenant_id,
    SUM(CASE WHEN metric_type = 'ai_input_tokens' THEN value ELSE 0 END) AS input_tokens,
    SUM(CASE WHEN metric_type = 'ai_output_tokens' THEN value ELSE 0 END) AS output_tokens,
    SUM(CASE WHEN metric_type = 'ai_embeddings' THEN value ELSE 0 END) AS embedding_tokens,
    SUM(value) AS total_tokens
FROM billing.usage_records
WHERE period = to_char(CURRENT_DATE, 'YYYY-MM')
  AND metric_type LIKE 'ai_%'
GROUP BY tenant_id;
```

---

**Creado por:** Requirements-Analyst
**Fecha:** 2025-12-05