rckrdmrd
928eb795e6
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Cambios en backend y frontend Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
226 lines
5.0 KiB
Markdown
226 lines
5.0 KiB
Markdown
# 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
|