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

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