---
id: EPIC-MCH-019
type: Epic
title: "MCH-019: Tienda de Tokens"
code: MCH-019
status: Pendiente
phase: 5
priority: P1
created_at: 2026-01-07
updated_at: 2026-01-17
simco_version: "4.0.1"
story_points: 21
dependencies:
  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
```typescript
// 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

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

---

**Ultima actualizacion:** 2026-01-17