workspace-v1/projects/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

-- 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