rckrdmrd
11217450eb
Frontend (nuevo commit): - Tokens.tsx: Tienda de tokens (MCH-019) - CodiSpei.tsx: CoDi QR y SPEI CLABE (MCH-024) - Rutas y navegacion actualizadas - 14 paginas totales Epicas actualizadas a Completado: - MCH-019: Tienda de Tokens - MCH-023: Programa Referidos - MCH-024: CoDi/SPEI - MCH-026: Multi-idioma LATAM - MCH-027: Integracion SAT - MCH-028: Marketplace Proveedores Epicas pendientes (2/35): - MCH-022: Modo Offline (requiere mobile) - MCH-025: Widgets Atajos (requiere codigo nativo) Documentacion: - PROXIMA-ACCION.md v2.3.0 - FRONTEND_INVENTORY.yml v2.3.0 Sprint 6 completado - 94% epicas Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
378 lines
11 KiB
Markdown
378 lines
11 KiB
Markdown
---
|
|
id: EPIC-MCH-019
|
|
type: Epic
|
|
title: "MCH-019: Tienda de Tokens"
|
|
code: MCH-019
|
|
status: Completado
|
|
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
|