prisma-esperto

name	prisma-esperto
description	Esperto in Prisma ORM con configurazione centralizzata via prisma.config.ts per MongoDB, evitando warning nell'editor e gestendo il versionamento multi-ambiente.

💎 Prisma Esperto (Spec-Driven)

Questa skill trasforma l'agente in un esperto di Prisma ORM, con un focus specifico sulla gestione di MongoDB e l'utilizzo della configurazione tramite prisma.config.ts introdotta nelle versioni più recenti di Prisma (v6+).

🛠️ Configurazione Core

1. Spec-as-Truth per il Database

Tutte le modifiche al database devono essere trattate come parte dell'architettura spec-driven. Il file prisma/schema.prisma è la sorgente della verità per i modelli.

2. Centralizzazione della Configurazione (prisma.config.ts)

Per garantire la compatibilità tra ambienti e pulizia nel codice:

⚠️ IMPORTANTE Prisma 6.x vs 7.x:

• Prisma 6.x (versione corrente del progetto): Il campo url = env("DATABASE_URL") è OBBLIGATORIO nello schema. prisma.config.ts può essere usato per configurazioni aggiuntive ma NON sostituisce l'url nel datasource.
• Prisma 7.x (futuro): La url potrà essere rimossa dallo schema e gestita interamente via prisma.config.ts.

• Schema Prisma (Prisma 6.x - Versione Corrente): Deve contenere l'URL per compatibilità.

  datasource db {
    provider = "mongodb"
    url      = env("DATABASE_URL")
  }
  

• Configurazione Dinamica: Utilizzare prisma.config.ts per configurazioni aggiuntive.

  import { defineConfig, env } from "prisma/config";
  
  export default defineConfig({
    schema: 'prisma/schema.prisma',
    datasource: {
      url: env('DATABASE_URL'),
    },
  });
  

• Build Docker/CI: Durante la fase di build, fornire un DATABASE_URL fittizio per prisma generate:

  RUN DATABASE_URL="mongodb://dummy:27017/dummy" bun run prisma generate
  

3. Allineamento Versioni (Local vs Server)

• L'agente deve monitorare la versione di prisma e @prisma/client nel package.json.
• Versione Corrente Progetto: ^6.19.0.
• Durante i deploy, assicurarsi che il comando prisma generate venga eseguito con la stessa versione usata in locale per evitare incompatibilità nel runtime.

🚀 Workflow Operativi (GSD)

Phase G (Goal)

• Identificare i cambiamenti necessari allo schema (nuovi modelli, indici, relazioni).
• Verificare che il piano di modifica non violi i vincoli di MongoDB (es. limiti sugli indici o tipi di dati).

Phase S (State)

• Analizzare apps/backend/prisma/schema.prisma e apps/backend/prisma.config.ts.
• Verificare la raggiungibilità del database (Locale o Remote) usando DATABASE_URL.
• Controllare se ci sono drift tra lo schema e il database reale.

Phase D (Design)

• Eseguire bun x prisma generate dopo ogni modifica manuale allo schema.
• Utilizzare bun x prisma db push per sincronizzare lo schema con MongoDB (dato che MongoDB non usa migrazioni classiche).
• Verificare i tipi generati per assicurarsi che i service del backend siano allineati.

⚠️ Regole Mandatorie e Best Practices

• Sicurezza: Mai committare file .env o esporre il DATABASE_URL nei log.
• Performance: In MongoDB, Prisma non supporta i join nativi. Usare query ottimizzate e, se necessario, denormalizzare i dati seguendo le specifiche del progetto.
• Validazione: Dopo ogni modifica allo schema, eseguire i test del backend per prevenire regressioni.
• Editor-Friendly: Mantenere lo schema pulito da configurazioni ambientali che mandano in errore i plugin di VSCode o altri editor.

📡 Deploy & Server

Quando si opera sui server di deploy:

1. Verificare sempre la versione di node/bun e prisma sul server.
2. Assicurarsi che DATABASE_URL nel server punti al database di produzione corretto.
3. Eseguire npx prisma generate come parte del processo di build sul server.