michangarrito/docs/01-epicas/MCH-019-tienda-tokens.md

MCH-019: Tienda de Tokens

Metadata

• Codigo: MCH-019
• Fase: 5 - Monetizacion
• Prioridad: P1
• Estado: Pendiente
• Fecha estimada: Sprint 11-12

Descripcion

Sistema de compra de tokens adicionales para funciones de IA: paquetes de tokens, saldo disponible, consumo por operacion, y alertas de saldo bajo.

Objetivos

1. Paquetes de tokens disponibles
2. Compra via Stripe/OXXO
3. Saldo y consumo visible
4. Alertas de saldo bajo
5. Historial de consumo

Alcance

Incluido

• 4 paquetes de tokens
• Compra con tarjeta (Stripe)
• Compra en OXXO (Stripe)
• Saldo en tiempo real
• Consumo por operacion
• Alertas configurables

Excluido

• Tokens como moneda interna
• Transferencia entre usuarios
• Venta de tokens a terceros

Paquetes de Tokens

Paquete	Tokens	Precio	Precio/Token
Basico	1,000	$29	$0.029
Popular	3,000	$69	$0.023
Pro	8,000	$149	$0.019
Ultra	20,000	$299	$0.015

Modelo de Datos

Tablas (schema: subscriptions)

token_packages

• id, name, tokens, price
• currency, stripe_price_id
• popular (boolean), active

token_purchases

• id, tenant_id, package_id
• tokens, amount, status
• stripe_payment_id, purchased_at

token_usage

• id, tenant_id, operation
• tokens_used, metadata (JSONB)
• created_at

token_balances (materialized view o cache)

• tenant_id, balance, last_updated

Consumo de Tokens

Operaciones y Costos

Operacion	Tokens	Descripcion
chat_message	3-10	Segun longitud
product_ocr	5	Reconocimiento de producto
audio_transcription	8	Transcripcion de audio
sales_report	15	Generacion de reporte
inventory_prediction	20	Prediccion de demanda

Calculo de Consumo

// Basado en tokens del LLM
const tokensUsed = Math.ceil(
  (inputTokens + outputTokens) / 100
);

Endpoints API

Metodo	Endpoint	Descripcion
GET	/tokens/packages	Paquetes disponibles
GET	/tokens/balance	Saldo actual
POST	/tokens/purchase	Comprar paquete
GET	/tokens/usage	Historial de consumo
GET	/tokens/usage/summary	Resumen de consumo

Flujos

Compra de Tokens

1. Usuario ve que tiene saldo bajo
2. Abre tienda de tokens
3. Selecciona paquete
4. Paga con tarjeta o elige OXXO
5. Si tarjeta: tokens acreditados inmediatamente
6. Si OXXO: tokens acreditados al confirmar pago

Consumo de Tokens

1. Usuario hace pregunta al chat IA
2. Sistema verifica saldo
3. Si suficiente: procesa pregunta
4. Descuenta tokens usados
5. Si bajo: alerta de saldo bajo
6. Si insuficiente: sugiere comprar mas

Alerta de Saldo Bajo

[Push + WhatsApp]
"⚠️ Tu saldo de tokens esta bajo

Te quedan 45 tokens (~5 consultas).
Recarga para seguir usando el asistente IA.

[Comprar tokens]"

UI Components

TokenBalance (Header)

• Icono de moneda
• Saldo actual
• Click para ver tienda

TokenShop

• Grid de paquetes
• Precio y ahorro
• Boton comprar

TokenUsageHistory

• Tabla de operaciones
• Fecha, tipo, tokens
• Grafica de consumo

TokenLowAlert

• Modal o banner
• Saldo actual
• CTA comprar

Entregables

Entregable	Estado	Archivo
token_packages seed	Completado	seeds/token-packages.sql
tokens.service	Pendiente	services/tokens.service.ts
TokenShop UI	Pendiente	components/tokens/TokenShop.tsx
TokenBalance UI	Pendiente	components/tokens/TokenBalance.tsx

Dependencias

Depende de

• MCH-018 (Suscripciones - Stripe setup)
• MCH-010 (MCP Server - consumo)

Bloquea a

• MCH-012, MCH-013 (Uso de tokens en chats)

Criterios de Aceptacion

• Paquetes se muestran correctamente
• Compra con tarjeta funciona
• Compra con OXXO funciona
• Saldo se actualiza en tiempo real
• Consumo se registra por operacion
• Alertas de saldo bajo funcionan

Configuracion por Tenant

// Umbrales de alerta
{
  tokens: {
    low_balance_threshold: 100,
    critical_balance_threshold: 20,
    alert_channels: ['push', 'whatsapp']
  }
}

---

Ultima actualizacion: 2026-01-07