rckrdmrd
3bba4ce6d7
Sprint 3-4 deliverables: - 28 epics documented (MCH-001 to MCH-028) - 7 development phases fully documented - DATABASE_INVENTORY.yml, BACKEND_INVENTORY.yml, FRONTEND_INVENTORY.yml - Task traces for database and frontend 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
195 lines
4.2 KiB
Markdown
195 lines
4.2 KiB
Markdown
# 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
|