miinventario-v2/docs/01-epicas/MII-010-paquetes-recarga.md

# MII-010: Paquetes de Recarga

---
id: MII-010
type: Epic
status: Completado
priority: P1
phase: 3
story_points: 8
created_date: 2026-01-10
updated_date: 2026-01-13
simco_version: "4.0.0"
---

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | MII-010 |
| **Nombre** | Paquetes de Recarga |
| **Fase** | 3 - Monetizacion |
| **Prioridad** | P1 |
| **Story Points** | 8 |
| **Estado** | Completado |

---

## 1. Descripcion

Implementar el catalogo de paquetes de recarga de creditos con precios fijos en MXN y equivalencia dinamica de creditos basada en el motor de costos.

### Objetivo

Ofrecer opciones de compra claras y atractivas para los usuarios, con transparencia en la cantidad de creditos que reciben.

---

## 2. Requerimientos Relacionados

| RF | Descripcion | Prioridad |
|----|-------------|-----------|
| FR-090 | Paquetes predefinidos: $50, $100, $200, $500 MXN | P0 |
| FR-091 | Equivalencia dinamica calculada por motor de costos | P0 |
| FR-092 | Promociones: bonos temporales (+10% creditos) | P2 |

---

## 3. Criterios de Aceptacion

### AC-001: Ver Paquetes
```gherkin
DADO que quiero comprar creditos
CUANDO veo la lista de paquetes
ENTONCES veo los paquetes disponibles con:
  - Precio en MXN
  - Cantidad de creditos
  - Sesiones aproximadas que puedo hacer
  - Descuento si aplica
```

### AC-002: Equivalencia Dinamica
```gherkin
DADO que los costos de IA cambian
CUANDO el motor recalcula equivalencias
ENTONCES los paquetes muestran creditos actualizados
Y el usuario siempre obtiene valor justo
```

### AC-003: Seleccionar Paquete
```gherkin
DADO que veo los paquetes
CUANDO selecciono uno
ENTONCES paso al flujo de pago
Y veo el resumen antes de confirmar
```

### AC-004: Promociones Activas
```gherkin
DADO que hay una promocion activa
CUANDO veo los paquetes
ENTONCES veo el badge de promocion
Y los creditos adicionales que obtendre
Y la fecha de expiracion de la oferta
```

### AC-005: Paquete Recomendado
```gherkin
DADO que soy usuario frecuente
CUANDO veo los paquetes
ENTONCES el sistema recomienda uno basado en mi uso
Y explica por que es la mejor opcion
```

---

## 4. Tareas Tecnicas

| ID | Tarea | Estimacion | Estado |
|----|-------|------------|--------|
| T-001 | Crear modulo packages en NestJS | 1 SP | Completado |
| T-002 | Implementar entidad Package | 1 SP | Completado |
| T-003 | Crear calculo de equivalencia dinamica | 2 SP | Completado |
| T-004 | Implementar sistema de promociones | 2 SP | Completado |
| T-005 | Crear pantalla de paquetes en mobile | 1 SP | Completado |
| T-006 | Implementar recomendacion de paquete | 1 SP | Completado |

---

## 5. Modelo de Datos

### Tabla: packages
```sql
CREATE TABLE packages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  slug VARCHAR(50) UNIQUE,
  price_mxn DECIMAL(10,2) NOT NULL,
  base_credits DECIMAL(12,4),
  is_popular BOOLEAN DEFAULT false,
  sort_order INT DEFAULT 0,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- base_credits: null = dinamico, valor = fijo
```

### Tabla: promotions
```sql
CREATE TABLE promotions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  type VARCHAR(50), -- 'BONUS_PERCENT', 'BONUS_FIXED', 'DISCOUNT_PERCENT'
  value DECIMAL(10,4),
  applies_to VARCHAR(50), -- 'ALL', 'PACKAGE_ID', 'FIRST_PURCHASE'
  package_id UUID REFERENCES packages(id),
  min_purchase DECIMAL(10,2),
  max_uses INT,
  current_uses INT DEFAULT 0,
  valid_from TIMESTAMP,
  valid_until TIMESTAMP,
  is_active BOOLEAN DEFAULT true,
  created_at TIMESTAMP DEFAULT NOW()
);
```

### Tabla: package_history
```sql
CREATE TABLE package_history (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  package_id UUID REFERENCES packages(id),
  credits_per_peso DECIMAL(10,6),
  avg_cogs_mxn DECIMAL(10,4),
  calculated_at TIMESTAMP DEFAULT NOW()
);
```

---

## 6. Paquetes Predeterminados

| Paquete | Precio MXN | Creditos* | Sesiones** | Popular |
|---------|------------|-----------|------------|---------|
| Basico | $50 | ~4-6 | ~3-5 | No |
| Popular | $100 | ~8-12 | ~6-10 | Si |
| Ahorro | $200 | ~18-26 | ~14-20 | No |
| Pro | $500 | ~48-70 | ~38-55 | No |

*Creditos varian segun COGS actual
**Sesiones estimadas promedio

---

## 7. Calculo de Equivalencia

```typescript
function calculatePackageCredits(priceMXN: number): PackageDetails {
  // Obtener costo promedio por sesion
  const avgCOGS = getAverageCOGS(); // ej: $8 MXN
  const pricePerSession = avgCOGS * 2; // ej: $16 MXN

  // Calcular creditos base
  const creditValue = pricePerSession; // 1 credito = 1 sesion promedio
  const baseCredits = priceMXN / creditValue;

  // Aplicar promociones
  const promos = getActivePromotions(priceMXN);
  let bonusCredits = 0;
  for (const promo of promos) {
    if (promo.type === 'BONUS_PERCENT') {
      bonusCredits += baseCredits * (promo.value / 100);
    }
  }

  return {
    baseCredits,
    bonusCredits,
    totalCredits: baseCredits + bonusCredits,
    estimatedSessions: Math.floor(baseCredits + bonusCredits),
    promotions: promos
  };
}
```

---

## 8. Endpoints API

| Metodo | Endpoint | Descripcion | Auth |
|--------|----------|-------------|------|
| GET | /packages | Listar paquetes activos | JWT |
| GET | /packages/:id | Detalle de paquete | JWT |
| GET | /packages/recommended | Paquete recomendado | JWT |
| GET | /promotions/active | Promociones activas | JWT |

---

## 9. Pantallas Mobile

| Pantalla | Componentes |
|----------|-------------|
| **PackagesScreen** | Lista cards, promociones, CTA |
| **PackageDetailModal** | Desglose, comparador |
| **PromosBanner** | Ofertas activas |

---

## 10. UI de Paquetes

```
┌─────────────────────────────────────────┐
│          RECARGAR CREDITOS              │
├─────────────────────────────────────────┤
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 🔥 OFERTA: +10% CREDITOS        │   │
│  │    Valido hasta 15 Ene          │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  BASICO                         │   │
│  │  $50 MXN                        │   │
│  │  ─────────                      │   │
│  │  4.5 creditos                   │   │
│  │  ~3-4 inventarios               │   │
│  │                    [Comprar]    │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  ⭐ POPULAR                      │   │
│  │  $100 MXN                       │   │
│  │  ─────────                      │   │
│  │  9.0 creditos + 0.9 BONUS       │   │
│  │  ~8-10 inventarios              │   │
│  │  Mejor valor                    │   │
│  │                    [Comprar]    │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  AHORRO                         │   │
│  │  $200 MXN                       │   │
│  │  ─────────                      │   │
│  │  20.0 creditos + 2.0 BONUS      │   │
│  │  ~18-22 inventarios             │   │
│  │                    [Comprar]    │   │
│  └─────────────────────────────────┘   │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │  PRO                            │   │
│  │  $500 MXN                       │   │
│  │  ─────────                      │   │
│  │  55.0 creditos + 5.5 BONUS      │   │
│  │  ~50-60 inventarios             │   │
│  │                    [Comprar]    │   │
│  └─────────────────────────────────┘   │
│                                         │
└─────────────────────────────────────────┘
```

---

## 11. Recomendacion Inteligente

```typescript
function getRecommendedPackage(userId: string): Package {
  const user = getUser(userId);
  const usage = getUserUsageStats(userId);

  // Usuario nuevo: recomendar Popular
  if (usage.totalSessions < 3) {
    return packages.find(p => p.slug === 'popular');
  }

  // Calcular sesiones mensuales promedio
  const avgMonthly = usage.sessionsLast30Days;

  // Recomendar segun uso
  if (avgMonthly < 5) return packages.find(p => p.slug === 'basico');
  if (avgMonthly < 15) return packages.find(p => p.slug === 'popular');
  if (avgMonthly < 30) return packages.find(p => p.slug === 'ahorro');
  return packages.find(p => p.slug === 'pro');
}
```

---

## 12. Dependencias

### Entrada (Requiere)
- MII-009: Wallet y Creditos

### Salida (Bloquea)
- MII-011: Pagos con Tarjeta
- MII-012: Pagos OXXO
- MII-013: Pagos 7-Eleven

---

## 13. Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Confusion precios dinamicos | Media | Medio | UI clara, tooltips |
| Abuso de promos | Baja | Bajo | Limites, validacion |
| COGS muy variable | Baja | Medio | Suavizar cambios, minimos |

---

## 14. Notas de Implementacion

- Cachear calculos de equivalencia (TTL 1h)
- No cambiar creditos despues de compra iniciada
- Guardar historico de equivalencias
- A/B test de precios y presentacion

---

## 15. Referencias

- [REQUERIMIENTOS-FUNCIONALES.md](../00-vision-general/REQUERIMIENTOS-FUNCIONALES.md) - Seccion 5.10
- [MII-009](./MII-009-wallet-creditos.md) - Sistema de creditos
- [VISION-PROYECTO.md](../00-vision-general/VISION-PROYECTO.md) - Modelo de negocio

---

**Ultima Actualizacion:** 2026-01-10