Prisma Migration Skill

Gestiona cambios en el schema de Prisma y migraciones de forma segura.

When to Activate

Agregar un nuevo modelo al schema
Agregar o modificar campos en un modelo existente
Crear o modificar relaciones entre modelos
Agregar nuevos enums
Crear indices para optimizar queries
Cambiar tipos de datos de campos existentes

Pasos

1. Modificar el Schema (`prisma/schema.prisma`)

model NuevoModelo {
  id        Int      @id @default(autoincrement())
  campo     String
  campoOpt  String?
  estado    EstadoAlta @default(PENDIENTE)

  // Relacion N:1
  usuario   Usuario  @relation(fields: [usuarioId], references: [id])
  usuarioId Int

  // Relacion N:M (implicita)
  companies Company[]

  // Timestamps
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  // Indices
  @@index([usuarioId])
  @@index([estado])
}

2. Generar y Aplicar Migracion

# Desarrollo: crea migracion con nombre descriptivo
cd ocralis_backend
npx prisma migrate dev --name add_nuevo_modelo

# Staging/Produccion: aplica migraciones pendientes (sin generar)
npx prisma migrate deploy

# Solo desarrollo (sin historial de migracion):
npx prisma db push

3. Regenerar el Cliente Prisma

npx prisma generate

4. Verificar con Prisma Studio

npx prisma studio

Modelos Existentes

| Modelo | Descripcion | |--------|-------------| | Usuario | Cuentas de usuario con tier, roles, OAuth, ubicacion, billing | | Company | Entidad empresarial (CIF, CCC, direccion fiscal, cert SALTRA) | | Establishment | Ubicaciones fisicas con geolocalizacion | | Employee | Perfiles de trabajadores (documento, NSS, contrato, geolocalizacion) | | EmployeeCompanies | Join table implicita Employee ↔ Company (N:M) | | Tramite | Procedimientos (alta/baja) con estado y PDF resolucion |

Enums Existentes

enum Provider      { EMAIL GOOGLE GITHUB SSO CUSTOM }
enum Role          { USER SUPERUSER ADMIN SUPPORT GUEST }
enum SubscriptionTier { FREE BASIC PRO ENTERPRISE CUSTOM }
enum TipoTramite   { ALTA BAJA SUSPENDIDO INACTIVO }
enum EstadoAlta    { PENDIENTE EN_PROCESO COMPLETADO ERROR }
enum BillingCycle  { MONTHLY ANNUAL }
enum Status        { INACTIVE PENDING ACTIVE CANCELED EXPIRED }

Convenciones del Proyecto

| Concepto | Convencion | |----------|-----------| | IDs | Int @id @default(autoincrement()) | | Timestamps | createdAt DateTime @default(now()) + updatedAt DateTime @updatedAt | | Foreign Keys | {modelo}Id (ej: usuarioId, companyId, establishmentId) | | Enums | enum NombreEnum { VALOR1 VALOR2 } en PascalCase | | Provider | postgresql con Supabase | | Modelos | PascalCase singular (Employee, no Employees) | | Campos | camelCase (firstName, no first_name) | | Campos opcionales | String? con ? | | Valores default | @default(value) o @default(now()) | | Migraciones | Nombre descriptivo en snake_case: add_campo_to_modelo |

Precauciones

Nunca eliminar campos en produccion sin migracion de datos previa
Nunca cambiar tipos de campos con datos existentes sin @map o migracion manual
Usar npx prisma migrate dev solo en desarrollo local
Usar npx prisma migrate deploy en staging/produccion
Hacer backup de la base de datos antes de migraciones destructivas
Probar migraciones en staging antes de produccion

Checklist

[ ] Schema modificado correctamente con convenciones
[ ] Migracion generada con nombre descriptivo (--name)
[ ] Cliente Prisma regenerado (npx prisma generate)
[ ] Servidor reiniciado para cargar cambios
[ ] Verificado con Prisma Studio
[ ] Actualizar CLAUDE.md si cambia el modelo de datos
[ ] Actualizar README.md del backend