npm package: @itbaf/tournaments-models
Description: Modelos **Prisma (MySQL)** reutilizables para integraciones de **torneos**: clients, apiKeys, regions, countries, tournaments, editions, scores, scoreCriteria y más.   Incluye **schema Prisma**, **migraciones versionadas** y **cliente Prisma** listo para 
Latest version: 1.1.1

# @itbaf/tournaments-models

Modelos **Prisma (MySQL)** reutilizables para integraciones de **torneos**: clients, apiKeys, regions, countries, tournaments, editions, scores, scoreCriteria y más.  
Incluye **schema Prisma**, **migraciones versionadas** y **cliente Prisma** listo para usar en múltiples proyectos.

---

## Índice

1. [Objetivo de la librería](#objetivo-de-la-librería)  
2. [Tecnologías que utiliza](#tecnologías-que-utiliza)  
3. [Instalación rápida](#instalación-rápida)  
4. [Configuración de entorno (.env)](#configuración-de-entorno-env)  
5. [Uso en un proyecto consumidor](#uso-en-un-proyecto-consumidor)  
   - [5.1 Usar el cliente Prisma del paquete](#51-usar-el-cliente-prisma-del-paquete)  
   - [5.2 Ejecutar migraciones del paquete](#52-ejecutar-migraciones-del-paquete)  
   - [5.3 Modelos disponibles](#53-modelos-disponibles)  
6. [Desarrollo de la librería](#desarrollo-de-la-librería)  
   - [6.1 Agregar/editar modelos o relaciones](#61-agregareditar-modelos-o-relaciones)  
   - [6.2 Crear nuevas migraciones](#62-crear-nuevas-migraciones)  
   - [6.3 Probar localmente](#63-probar-localmente)  
   - [6.4 Publicar una nueva versión en npm](#64-publicar-una-nueva-versión-en-npm)  
   - [6.5 Actualización y Migraciones](#65-actualización-y-migraciones)  
7. [Notas y troubleshooting](#notas-y-troubleshooting)  
8. [Licencia](#licencia)  

---

## Objetivo de la librería

Centralizar el **modelo de datos** de torneos (y sus integraciones) en un solo paquete para:  
- Evitar duplicar esquemas entre servicios y funciones.  
- Desplegar **migraciones** de forma consistente desde cada proyecto consumidor.  
- Reutilizar un **PrismaClient** listo para usar con todos los modelos de torneos.  
- Mantener consistencia en la estructura de datos entre diferentes aplicaciones.

---

## Tecnologías que utiliza

- **TypeScript** (ESM)  
- **Prisma ORM** (datasource MySQL)  
- **Node.js** 18+  
- **Migraciones** gestionadas por Prisma  

---

## Instalación rápida

```bash
npm i @itbaf/tournaments-models
# o
pnpm add @itbaf/tournaments-models
# o
yarn add @itbaf/tournaments-models
```

> El paquete incluye su propio `schema.prisma`, migraciones y cliente Prisma generado.  
> El **cliente Prisma** del paquete se genera automáticamente en la instalación.

---

## Configuración de entorno (.env)

En el **proyecto consumidor**, definí la variable `DATABASE_URL` (MySQL). Ejemplos:

```bash
# .env del proyecto consumidor
DATABASE_URL="mysql://usuario:password@host:3306/nombre_db"
```

> Esta URL es la que usarán las **migraciones** del paquete cuando se ejecuten desde tu proyecto.

---

## Uso en un proyecto consumidor

### 5.1 Usar el cliente Prisma del paquete

```ts
import { db } from '@itbaf/tournaments-models'

const prisma = db()

// Ejemplos de uso
const tournaments = await prisma.tournament.findMany()
const regions = await prisma.region.findMany({ where: { enabled: true } })
const scores = await prisma.score.findMany({ 
  include: { 
    country: true, 
    edition: true 
  } 
})
```

### 5.2 Ejecutar migraciones del paquete

```bash
npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
```

O bien en `package.json`:

```jsonc
{
  "scripts": {
    "tournaments:migrate": "prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma"
  }
}
```

### 5.3 Modelos disponibles

La librería incluye los siguientes modelos:

- **Client**: Clientes que pueden crear torneos
- **ApiKey**: Claves de API para autenticación
- **Region**: Regiones geográficas habilitadas por cliente
- **Country**: Países del mundo
- **RegionCountry**: Relación muchos-a-muchos entre regiones y países
- **Tournament**: Torneos creados por clientes
- **TournamentEdition**: Ediciones de torneos con fechas y criterios
- **Score**: Puntuaciones de usuarios en torneos
- **ScoreCriterion**: Criterios de puntuación para torneos

---

## Desarrollo de la librería

### 6.1 Agregar/editar modelos o relaciones
Editá `prisma/schema.prisma`.

### 6.2 Crear nuevas migraciones
```bash
npx prisma migrate dev --name <descripcion> --schema ./prisma/schema.prisma
```

### 6.3 Probar localmente
```bash
npm i
npx prisma generate --schema ./prisma/schema.prisma
npm run build
export DATABASE_URL="mysql://user:pass@localhost:3306/prueba"
npx prisma migrate deploy --schema ./prisma/schema.prisma
```

### 6.4 Publicar una nueva versión en npm
```bash
npm run release:patch   # fixes
npm run release:minor   # nuevas features
npm run release:major   # cambios incompatibles
```

Luego en el consumidor:
```bash
npm update @itbaf/tournaments-models
npm run tournaments:migrate
```

### 6.5 Actualización y Migraciones

#### **Importante: Flujo de actualización para proyectos consumidores**

Cuando se publica una nueva versión del paquete, los proyectos consumidores deben seguir este flujo:

1. **Actualizar el paquete:**
   ```bash
   npm update @itbaf/tournaments-models
   # o
   npm install @itbaf/tournaments-models@latest
   ```

2. **Verificar si hay nuevas migraciones:**
   ```bash
   # Listar migraciones pendientes
   npx prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
   ```

3. **Aplicar migraciones pendientes:**
   ```bash
   npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
   ```

4. **Regenerar el cliente Prisma (si es necesario):**
   ```bash
   npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
   ```

#### **Scripts recomendados para package.json del consumidor:**

```jsonc
{
  "scripts": {
    "tournaments:update": "npm update @itbaf/tournaments-models && npm run tournaments:migrate",
    "tournaments:migrate": "prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma",
    "tournaments:status": "prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma"
  }
}
```

#### **Cuándo ejecutar migraciones:**

- ✅ **SÍ ejecutar:** Al instalar/actualizar el paquete
- ✅ **SÍ ejecutar:** Al hacer deploy en producción
- ✅ **SÍ ejecutar:** Al cambiar de versión del paquete
- ❌ **NO ejecutar:** En cada build/compilación del proyecto
- ❌ **NO ejecutar:** En cada request HTTP

---

## Notas y troubleshooting

- Node 18+ recomendado.  
- Si el consumer no tiene Prisma CLI:  
  ```bash
  npx -p prisma prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
  ```  
- `prisma/generated/client` se crea con `prisma generate`, no hace falta versionarlo.  
- Las migraciones (`prisma/migrations`) sí se versionan.  

### **Problemas comunes con migraciones:**

#### **Error: "Migration failed"**
```bash
# Verificar estado de migraciones
npx prisma migrate status --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

# Si hay conflictos, resetear y aplicar desde cero
npx prisma migrate reset --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
```

#### **Error: "Database schema is out of sync"**
```bash
# Regenerar cliente Prisma
npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma

# Verificar que el schema coincida con la base de datos
npx prisma db pull --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
```

#### **Migraciones en entornos de CI/CD:**
```bash
# Script recomendado para pipelines
npm ci
npx prisma migrate deploy --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
npx prisma generate --schema node_modules/@itbaf/tournaments-models/prisma/schema.prisma
```

### **Versionado semántico del paquete:**

- **PATCH** (1.0.1): Solo fixes, no requieren migraciones
- **MINOR** (1.1.0): Nuevas features, pueden requerir migraciones
- **MAJOR** (2.0.0): Cambios incompatibles, siempre requieren migraciones

> **Nota:** Antes de actualizar a una versión MAJOR, revisar el changelog y las migraciones pendientes.

---

## Licencia

MIT