# MCH-018: Planes y Suscripciones

## Metadata
- **Codigo:** MCH-018
- **Fase:** 5 - Monetizacion
- **Prioridad:** P0
- **Estado:** Completado
- **Fecha inicio:** 2026-01-06
- **Fecha fin:** 2026-01-07

## Descripcion

Sistema de planes de suscripcion para monetizar MiChangarrito: dos planes principales (Changarrito y Tiendita), facturacion mensual, y gestion de ciclos de pago.

## Objetivos

1. Definir planes disponibles
2. Proceso de suscripcion
3. Facturacion recurrente
4. Gestion de ciclo de vida
5. Upgrade/downgrade de plan

## Alcance

### Incluido
- Plan Changarrito ($99/mes)
- Plan Tiendita ($199/mes)
- Trial de 14 dias
- Facturacion via Stripe
- Cancelacion y pausas
- Historial de facturacion

### Excluido
- Planes anuales (fase posterior)
- Planes enterprise personalizados
- Facturacion fiscal mexicana (MCH-027)

## Planes

### Plan Changarrito - $99/mes
```
✓ App movil completa
✓ Punto de venta basico
✓ Hasta 500 productos
✓ 1 usuario
✓ 500 tokens IA/mes
✓ Soporte por WhatsApp
✗ WhatsApp Business propio
✗ Predicciones de inventario
```

### Plan Tiendita - $199/mes
```
✓ Todo de Changarrito
✓ Productos ilimitados
✓ Hasta 5 usuarios
✓ 2,000 tokens IA/mes
✓ WhatsApp Business propio
✓ Predicciones de inventario
✓ Reportes avanzados
✓ Entregas a domicilio
✓ Soporte prioritario
```

## Modelo de Datos

### Tablas (schema: subscriptions)

**plans**
- id, name, code, price
- currency, interval (month/year)
- features (JSONB), token_quota
- max_products, max_users
- stripe_price_id, status

**subscriptions**
- id, tenant_id, plan_id
- status (trialing/active/past_due/cancelled)
- stripe_subscription_id
- current_period_start, current_period_end
- trial_end, cancelled_at

**invoices**
- id, subscription_id, amount
- status, stripe_invoice_id
- paid_at, pdf_url

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| GET | /subscriptions/plans | Listar planes |
| GET | /subscriptions/current | Suscripcion actual |
| POST | /subscriptions/subscribe | Suscribirse |
| POST | /subscriptions/cancel | Cancelar |
| POST | /subscriptions/resume | Reanudar |
| PUT | /subscriptions/change-plan | Cambiar plan |
| GET | /subscriptions/invoices | Historial facturas |
| POST | /subscriptions/webhook | Webhook Stripe |

## Flujos

### Nueva Suscripcion
```
1. Usuario selecciona plan
2. Ingresa metodo de pago (Stripe)
3. Se crea suscripcion con trial
4. Usuario tiene acceso inmediato
5. Al terminar trial, se cobra automaticamente
```

### Cancelacion
```
1. Usuario solicita cancelar
2. Confirmacion requerida
3. Suscripcion marcada para cancelar
4. Acceso hasta fin del periodo
5. Datos preservados 30 dias
```

### Upgrade
```
1. Usuario en Changarrito
2. Solicita upgrade a Tiendita
3. Se calcula prorateo
4. Pago de diferencia
5. Features activadas inmediatamente
```

## Estados de Suscripcion

```
trialing ──► active ──► past_due ──► cancelled
                │           │
                └───────────┴──► paused
```

| Estado | Descripcion | Acceso |
|--------|-------------|--------|
| trialing | En periodo de prueba | Completo |
| active | Pagando normalmente | Completo |
| past_due | Pago fallido (grace period) | Limitado |
| cancelled | Cancelada | Sin acceso |
| paused | Pausada temporalmente | Sin acceso |

## Integracion Stripe

### Subscription Billing
```typescript
const subscription = await stripe.subscriptions.create({
  customer: customer.stripe_id,
  items: [{ price: plan.stripe_price_id }],
  trial_period_days: 14,
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent']
});
```

### Webhooks Manejados
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`
- `invoice.payment_failed`

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| DDL subscriptions | Completado | `10-subscriptions.sql` |
| subscriptions.module | Completado | `modules/subscriptions/` |
| Stripe integration | Completado | `providers/stripe.provider.ts` |
| Plans UI | Pendiente | `pages/Plans.tsx` |
| Billing UI | Pendiente | `pages/Billing.tsx` |

## Dependencias

### Depende de
- MCH-005 (Stripe integration base)
- MCH-002 (Auth)

### Bloquea a
- MCH-019 (Tokens)
- MCH-020 (Pagos online)

## Criterios de Aceptacion

- [x] Planes se muestran correctamente
- [x] Suscripcion se crea en Stripe
- [x] Trial de 14 dias funciona
- [x] Cobro recurrente funciona
- [x] Cancelacion funciona
- [ ] Upgrade/downgrade funciona

## Configuracion

```typescript
// plans seed
[
  {
    name: 'Changarrito',
    code: 'changarrito',
    price: 99,
    currency: 'MXN',
    token_quota: 500,
    max_products: 500,
    max_users: 1,
    stripe_price_id: 'price_xxx'
  },
  {
    name: 'Tiendita',
    code: 'tiendita',
    price: 199,
    currency: 'MXN',
    token_quota: 2000,
    max_products: null, // unlimited
    max_users: 5,
    stripe_price_id: 'price_yyy'
  }
]
```

---

**Ultima actualizacion:** 2026-01-07