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:

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:

# 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:

# 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:

# ====== 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
   • 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
   • 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:

npm run dev

Prueba que los endpoints nuevos funcionan:

# 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:

# 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:

# 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"

# 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"

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

Error: "Cannot find module 'stripe'"

# 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.