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

id	type	title	code	status	phase	priority	created_at	updated_at	simco_version	story_points	dependencies
EPIC-MCH-019	Epic	MCH-019: Tienda de Tokens	MCH-019	Completado	5	P1	2026-01-07	2026-01-17	4.0.1	21	blocks depends_on

MCH-019: Tienda de Tokens

Metadata

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

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

Historias de Usuario

MCH-US-180: Catalogo de Paquetes de Tokens

Story Points: 3

Como usuario de MiChangarrito Quiero ver los paquetes de tokens disponibles con sus precios y beneficios Para elegir el que mejor se adapte a mis necesidades de uso de IA

Criterios de Aceptacion

• [CA-180-1] El catalogo muestra los 4 paquetes definidos (Basico, Popular, Pro, Ultra)
• [CA-180-2] Cada paquete muestra cantidad de tokens, precio y precio por token
• [CA-180-3] El paquete "Popular" se destaca visualmente como recomendado
• [CA-180-4] Los precios se muestran en la moneda local del tenant
• [CA-180-5] Solo se muestran paquetes activos (active = true)

Tareas

ID	Tarea	Estimacion
MCH-TT-180-01	Crear endpoint GET /tokens/packages	2h
MCH-TT-180-02	Implementar TokenPackageCard component	2h
MCH-TT-180-03	Crear TokenShop grid layout	2h
MCH-TT-180-04	Agregar seed de paquetes de tokens	1h

---

MCH-US-181: Compra de Tokens con Tarjeta

Story Points: 5

Como usuario de MiChangarrito Quiero comprar tokens usando mi tarjeta de credito o debito Para tener acceso inmediato a funciones de IA sin salir de la aplicacion

Criterios de Aceptacion

• [CA-181-1] El usuario puede seleccionar un paquete y proceder al pago
• [CA-181-2] La integracion con Stripe procesa el pago de forma segura
• [CA-181-3] Los tokens se acreditan inmediatamente tras pago exitoso
• [CA-181-4] Se genera registro en token_purchases con stripe_payment_id
• [CA-181-5] El usuario recibe confirmacion visual y notificacion del acreditamiento
• [CA-181-6] En caso de error, se muestra mensaje claro y se registra el fallo

Tareas

ID	Tarea	Estimacion
MCH-TT-181-01	Crear endpoint POST /tokens/purchase	3h
MCH-TT-181-02	Implementar integracion Stripe Checkout	4h
MCH-TT-181-03	Crear webhook para confirmar pagos	3h
MCH-TT-181-04	Implementar UI de checkout con Stripe Elements	3h
MCH-TT-181-05	Crear pantalla de confirmacion de compra	2h

---

MCH-US-182: Compra de Tokens en OXXO

Story Points: 3

Como usuario de MiChangarrito sin tarjeta bancaria Quiero generar un voucher para pagar en OXXO Para poder comprar tokens usando efectivo

Criterios de Aceptacion

• [CA-182-1] El usuario puede seleccionar OXXO como metodo de pago
• [CA-182-2] Se genera voucher con codigo de barras y monto a pagar
• [CA-182-3] El voucher incluye fecha de vencimiento (72 horas)
• [CA-182-4] Los tokens se acreditan automaticamente al confirmar pago via webhook
• [CA-182-5] El usuario puede ver el estado de vouchers pendientes
• [CA-182-6] Se envia notificacion cuando el pago es confirmado

Tareas

ID	Tarea	Estimacion
MCH-TT-182-01	Implementar Stripe OXXO payment method	3h
MCH-TT-182-02	Crear componente de voucher descargable	2h
MCH-TT-182-03	Configurar webhook para pagos OXXO	2h
MCH-TT-182-04	Implementar listado de vouchers pendientes	2h

---

MCH-US-183: Visualizacion de Saldo y Consumo

Story Points: 3

Como usuario de MiChangarrito Quiero ver mi saldo de tokens actual y el consumo reciente Para saber cuantos tokens me quedan y planificar mis compras

Criterios de Aceptacion

• [CA-183-1] El saldo se muestra en el header de la aplicacion (TokenBalance)
• [CA-183-2] El saldo se actualiza en tiempo real tras cada operacion
• [CA-183-3] Al hacer click en el saldo, se muestra detalle con consumo reciente
• [CA-183-4] Se muestra estimacion de consultas restantes basado en promedio
• [CA-183-5] El componente es responsive y se adapta a movil

Tareas

ID	Tarea	Estimacion
MCH-TT-183-01	Crear endpoint GET /tokens/balance	2h
MCH-TT-183-02	Implementar TokenBalance component en header	2h
MCH-TT-183-03	Crear cache de balance con Redis	2h
MCH-TT-183-04	Implementar actualizacion en tiempo real (WebSocket)	3h

---

MCH-US-184: Historial de Consumo de Tokens

Story Points: 3

Como usuario de MiChangarrito Quiero ver el historial detallado de consumo de tokens por operacion Para entender como uso mis tokens y optimizar mi consumo

Criterios de Aceptacion

• [CA-184-1] El historial muestra fecha, tipo de operacion y tokens consumidos
• [CA-184-2] Se puede filtrar por rango de fechas y tipo de operacion
• [CA-184-3] Se muestra grafica de consumo por dia/semana/mes
• [CA-184-4] El historial incluye paginacion para grandes volumenes
• [CA-184-5] Se puede exportar el historial a CSV

Tareas

ID	Tarea	Estimacion
MCH-TT-184-01	Crear endpoint GET /tokens/usage con filtros	2h
MCH-TT-184-02	Crear endpoint GET /tokens/usage/summary	2h
MCH-TT-184-03	Implementar TokenUsageHistory component	3h
MCH-TT-184-04	Agregar grafica de consumo con Recharts	2h
MCH-TT-184-05	Implementar exportacion a CSV	1h

---

MCH-US-185: Alertas de Saldo Bajo

Story Points: 4

Como usuario de MiChangarrito Quiero recibir alertas cuando mi saldo de tokens este bajo Para recargar a tiempo y no quedarme sin acceso a funciones de IA

Criterios de Aceptacion

• [CA-185-1] Se envia alerta cuando el saldo llega al umbral configurado (default 100)
• [CA-185-2] Se envia alerta critica cuando el saldo llega a 20 tokens
• [CA-185-3] Las alertas se envian por los canales configurados (push, WhatsApp)
• [CA-185-4] El usuario puede configurar sus umbrales y canales preferidos
• [CA-185-5] No se envian alertas duplicadas en menos de 24 horas
• [CA-185-6] La alerta incluye CTA directo a la tienda de tokens

Tareas

ID	Tarea	Estimacion
MCH-TT-185-01	Implementar servicio de monitoreo de saldo	3h
MCH-TT-185-02	Crear job de verificacion de umbrales	2h
MCH-TT-185-03	Integrar con sistema de notificaciones push	2h
MCH-TT-185-04	Integrar con WhatsApp Business API	3h
MCH-TT-185-05	Crear UI de configuracion de alertas	2h
MCH-TT-185-06	Implementar control de alertas duplicadas	1h

---

Resumen de Historias de Usuario

ID	Historia	Story Points	Prioridad
MCH-US-180	Catalogo de Paquetes de Tokens	3	Alta
MCH-US-181	Compra de Tokens con Tarjeta	5	Alta
MCH-US-182	Compra de Tokens en OXXO	3	Alta
MCH-US-183	Visualizacion de Saldo y Consumo	3	Alta
MCH-US-184	Historial de Consumo de Tokens	3	Media
MCH-US-185	Alertas de Saldo Bajo	4	Media
Total		21

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