MIGRATION_GUIDE.md

# 🗂️ Guía de Migración de Base de Datos - Stripe Integration

## 📋 Descripción General

Este proyecto ha sido actualizado con:
- **Integración Stripe**: Pagos, checkout, webhooks
- **Renovación Automática**: Suscripciones recurrentes mensuales
- **Contabilidad Exacta**: Modelo `Earning` para cada pago
- **Cancelación Cliente**: Cancelar suscripciones cuando quieran

Para esto, necesitas ejecutar una **migración de BD** que agregue campos nuevos a las tablas.

---

## ⚙️ Pre-requisitos

✅ Tienes PostgreSQL o SQLite instalado y funcionando  
✅ Tu `.env` tiene `DATABASE_URL` configurado  
✅ Ejecutaste `npm install stripe` (ya hecho)  
✅ Node.js 18+ instalado

---

## 🚀 Paso 1: Ejecutar la Migración

Abre la terminal en la raíz del proyecto:

```bash
cd c:\Users\gemag\sofia-cloud
npx prisma migrate dev --name add_stripe_and_renewals
```

**¿Qué pasa?**
1. Prisma detecta cambios en `prisma/schema.prisma` (campos Stripe nuevos)
2. Genera un archivo de migración en `prisma/migrations/`
3. **Aplica automáticamente** la migración a tu BD local
4. Regenera el cliente Prisma

**Salida esperada:**
```
✓ Created new migration: ./prisma/migrations/202501xx_add_stripe_and_renewals/migration.sql
✓ Database has been updated
✓ Generated Prisma Client
```

**Si hay error:**
```bash
# Revertir si algo sale mal:
npx prisma migrate resolve --rolled-back <nombre-migracion>
```

---

## ✅ Paso 2: Verificar la Migración

Confirma que los campos nuevos existen en la BD:

```bash
# Ver estado de migraciones
npx prisma migrate status

# Ver el contenido de la BD
npx prisma studio
```

En Prisma Studio deberías ver en la tabla `InfluencerSubscription`:
- ✅ `stripeSubscriptionId` (string, opcional)
- ✅ `stripeCustomerId` (string, opcional)
- ✅ `nextRenewalDate` (DateTime)
- ✅ `autoRenew` (boolean, default: true)

Y en tabla `Earning`:
- ✅ `subscriptionId` (foreign key)
- ✅ `stripePaymentIntentId` (string, opcional)
- ✅ `isRecurring` (boolean, default: false)
- ✅ `paymentStatus` (enum: pending, completed, failed)
- ✅ `paymentMethod` (string, opcional)

---

## 🔑 Paso 3: Configurar Variables de Entorno

Edita tu `.env` (o `.env.local`) y agrega:

```env
# ====== STRIPE KEYS ======
# Obtén estos de: https://dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY="sk_test_XXXXX..."    # Para testing
# En producción: sk_live_XXXXX...

STRIPE_WEBHOOK_SECRET="whsec_XXXXX..."  # De https://dashboard.stripe.com/webhooks
```

### 📌 Cómo obtener las keys:

1. **STRIPE_SECRET_KEY**
   - Ve a [dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys)
   - Mira en la sección "Secret Key"
   - Copia la que empiece con `sk_test_` (para desarrollo)

2. **STRIPE_WEBHOOK_SECRET**
   - Ve a [dashboard.stripe.com/webhooks](https://dashboard.stripe.com/webhooks)
   - Haz click en "+ Add endpoint"
   - **Endpoint URL**: `http://localhost:3000/api/payments/webhook` (local)
   - **Eventos**: Selecciona estos:
     - `checkout.session.completed`
     - `customer.subscription.created`
     - `customer.subscription.deleted`
     - `customer.subscription.updated`
     - `invoice.payment_succeeded`
     - `invoice.payment_failed`
   - Click "Add endpoint"
   - Verás el "Signing secret" (empieza con `whsec_`)
   - Cópialo y agrégalo a `.env`

---

## 🧪 Paso 4: Verificar la Instalación (Local)

Inicia el servidor:

```bash
npm run dev
```

Prueba que los endpoints nuevos funcionan:

```bash
# 1. Ver si puedes llegar al checkout
curl http://localhost:3000/api/payments/checkout

# 2. Ver si el webhook está listo
curl http://localhost:3000/api/payments/webhook

# Resultado esperado: 405 Method Not Allowed (porque es POST, no GET)
# ✅ Eso significa que el endpoint existe
```

---

## 📤 Paso 5: Para Producción (VPS/Hosting)

Cuando subes a un VPS o servidor:

```bash
# 1. Subir código (git push)
git add .
git commit -m "Add Stripe integration and auto-renewal"
git push origin main

# 2. En el servidor VPS:
cd /ruta/del/proyecto
npm install stripe        # Instala Stripe
npx prisma migrate deploy # Aplica migraciones sin preguntar

# 3. Actualizar .env en producción:
# - STRIPE_SECRET_KEY: sk_live_XXXXX... (clave VIVA, no test)
# - STRIPE_WEBHOOK_SECRET: del webhook en producción
# - DATABASE_URL: URL de BD producción

npm run build
npm start
```

---

## 📊 Campos Nuevos en la BD

### InfluencerSubscription

| Campo | Tipo | Descripción |
|-------|------|------------|
| `stripeSubscriptionId` | string | ID de suscripción en Stripe (ej: sub_12345) |
| `stripeCustomerId` | string | ID de cliente en Stripe (ej: cus_XXXXX) |
| `nextRenewalDate` | DateTime | Fecha próxima renovación (calculada cada pago) |
| `autoRenew` | boolean | Si es true, se renueva automáticamente |

### Earning

| Campo | Tipo | Descripción |
|-------|------|------------|
| `subscriptionId` | string | FK a InfluencerSubscription |
| `stripePaymentIntentId` | string | ID de pago en Stripe |
| `isRecurring` | boolean | true si viene de renovación automática |
| `paymentStatus` | enum | "pending" \| "completed" \| "failed" |
| `paymentMethod` | string | "stripe" \| "manual" \| etc |

---

## 🔍 Verificación Post-Migración

Ejecuta esto para confirmar todo está bien:

```bash
# 1. Ver migrations aplicadas
npx prisma migrate status

# 2. Ver esquema generado
npx prisma generate

# 3. Compilar proyecto
npm run build

# Si los 3 pasos pasan sin ERROR ✅, estás listo
```

---

## ⚠️ Si Algo Sale Mal

### Error: "Column does not exist"
```bash
# La migración se aplicó solo parcialmente
# Revertir y intentar de novo:
npx prisma migrate resolve --rolled-back add_stripe_and_renewals
npx prisma migrate dev --name add_stripe_and_renewals
```

### Error: "STRIPE_SECRET_KEY not set"
```bash
# Olvidaste agregar la key a .env
# Agrega: STRIPE_SECRET_KEY="sk_test_XXXXX"
# Reinicia el servidor: npm run dev
```

### Error: "Cannot find module 'stripe'"
```bash
# Stripe no está instalado
npm install stripe
npx prisma generate
npm run dev
```

---

## 📞 Resumen de Pasos (Quick Reference)

| # | Paso | Comando | Resultado |
|---|------|---------|-----------|
| 1 | Migrar BD | `npx prisma migrate dev --name add_stripe_and_renewals` | ✅ Campos nuevos en tablas |
| 2 | Verificar | `npx prisma studio` | ✅ Ver nuevos campos |
| 3 | Config env | Editar `.env` | ✅ Keys Stripe agregadas |
| 4 | Webhook Stripe | Agregar endpoint en dashboard | ✅ Webhooks conectados |
| 5 | Compilar | `npm run build` | ✅ Sin errores |
| 6 | Testear | `npm run dev` + curl | ✅ Endpoints funcionan |

---

## ✨ ¡Listo! Ahora puedes:

✅ Crear suscripciones en Stripe  
✅ Procesar pagos automáticos mensuales  
✅ Rastrear earnings por pago exacto  
✅ Cancelar suscripciones cuando el cliente quiera  
✅ Ver reportes con contabilidad exacta  

**¿Preguntas? Ejecuta los pasos en orden y reporta cualquier error.**