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

5.3 KiB Raw Permalink Blame History