@javalabs/prisma-client 1.0.0 → 1.0.1

package/README.md

@@ -1,20 +1,20 @@
-# @tupay/prisma-client
+# @javalabs/prisma-client
 
-Cliente Prisma compartido para los microservicios de Tupay. Este paquete proporciona una capa de abstracción sobre Prisma ORM con soporte para multi-tenancy y utilidades de migración de datos.
+Cliente Prisma compartido para los microservicios de Tupay. Este paquete proporciona una capa de abstracción sobre Prisma ORM con soporte para multi-tenancy (usando esquemas de base de datos separados por tenant) y utilidades de migración y gestión de base de datos.
 
 ## Instalación
 
 ```bash
-npm install @tupay/prisma-client
+npm i @javalabs/prisma-client
 ```
 
 ## Características
 
-- **Cliente Prisma Singleton**: Implementación eficiente del cliente Prisma como singleton
-- **Soporte Multi-tenant**: Conexión a diferentes esquemas de base de datos para diferentes inquilinos
-- **Integración con NestJS**: Módulo global para aplicaciones NestJS
-- **Utilidades de Migración**: Scripts para migración de datos y esquemas
-- **Herramientas de Gestión de BD**: Scripts para crear, eliminar y restablecer bases de datos
+- **Cliente Prisma Singleton**: Implementación eficiente del cliente Prisma (<mcsymbol name="PrismaService" filename="prisma.service.ts" path="/Users/alejandroperez/tupay/packages/prisma-client/src/prisma.service.ts" startline="5" type="class">) para el esquema `public`.
+- **Soporte Multi-tenant**: Conexión a diferentes esquemas de base de datos para diferentes inquilinos a través de <mcsymbol name="PrismaFactoryService" filename="prisma-factory.service.ts" path="/Users/alejandroperez/tupay/packages/prisma-client/src/prisma-factory.service.ts" startline="10" type="class">. Los tenants suelen identificarse por su API Key, que se usa como nombre del esquema.
+- **Integración con NestJS**: Módulo global (<mcsymbol name="PrismaModule" filename="prisma.module.ts" path="/Users/alejandroperez/tupay/packages/prisma-client/src/prisma.module.ts" startline="6" type="class">) para facilitar la inyección en aplicaciones NestJS.
+- **Utilidades de Migración**: Scripts para migración de esquemas y datos entre entornos.
+- **Herramientas de Gestión de BD**: Scripts para crear esquemas de tenants, sincronizar estructuras, resetear bases de datos y corregir tipos de datos.
 
 ## Diagramas
 
@@ -22,63 +22,66 @@ npm install @tupay/prisma-client
 
 ```mermaid
 graph TD
-    A[Aplicación] --> B[PrismaFactoryService]
-    B --> C[Cliente Prisma - Tenant 1]
-    B --> D[Cliente Prisma - Tenant 2]
-    B --> E[Cliente Prisma - Tenant N]
-    C --> F[(Base de Datos - Schema Tenant 1)]
-    D --> F
-    E --> F
-    B --> G[Cliente Prisma - Public]
-    G --> F
+    A[Aplicación] --> B(PrismaFactoryService);
+    B -- Obtener cliente para Tenant X --> C{Cliente Prisma - Tenant X};
+    B -- Obtener cliente para Tenant Y --> D{Cliente Prisma - Tenant Y};
+    C --> E[(Base de Datos - Schema Tenant X)];
+    D --> F[(Base de Datos - Schema Tenant Y)];
+    A --> G(PrismaService);
+    G -- Cliente por defecto --> H{Cliente Prisma - Public};
+    H --> I[(Base de Datos - Schema Public)];
 ```
 
 ### Flujo de Migración de Datos
 
 ```mermaid
 sequenceDiagram
-    participant S as Base de Datos Origen
-    participant M as Script de Migración
-    participant T as Base de Datos Destino
+    participant S as Base de Datos Origen (SOURCE_DATABASE_URL)
+    participant M as Script de Migración (`migrate:data`)
+    participant T as Base de Datos Destino (DATABASE_URL - Tenants)
 
     M->>S: Consulta datos de origen
     S-->>M: Retorna datos
-    M->>M: Procesa y transforma datos
-    M->>T: Migra datos a destino
+    M->>M: Procesa y transforma datos (considerando dependencias)
+    M->>T: Migra datos a esquemas de tenants en destino
     T-->>M: Confirma migración
 
-    Note over M: Ordenamiento por dependencias
+    Note over M: Ordenamiento por dependencias (ForeignKeyManager)
     Note over M: Manejo de tipos de datos
-    Note over M: Migración por fases
+    Note over M: Migración por fases (si aplica)
 ```
 
 ### Estructura del Proyecto
 
 ```mermaid
 graph LR
-    A[prisma-client] --> B[src]
-    A --> C[prisma]
-    B --> D[scripts]
-    B --> E[index.ts]
-    B --> F[prisma.module.ts]
-    B --> G[prisma.service.ts]
-    B --> H[prisma-factory.service.ts]
-    D --> I[data-migration]
-    D --> J[reset-database.ts]
-    D --> K[schema-sync.ts]
-    D --> L[create-tenant-schemas.ts]
-    I --> M[dependency-manager.ts]
-    I --> N[schema-utils.ts]
-    I --> O[migration-phases.ts]
+    A[@javalabs/prisma-client] --> B[src];
+    A --> C[prisma];
+    B --> D[scripts];
+    B --> E[index.ts];
+    B --> F[prisma.module.ts];
+    B --> G[prisma.service.ts];
+    B --> H[prisma-factory.service.ts];
+    D --> I[data-migration];
+    D --> J[reset-database.ts];
+    D --> K[schema-sync.ts];
+    D --> L[create-tenant-schemas.ts];
+    D --> M[migrate-schema-structure.ts];
+    D --> N[fix-data-types.ts];
+    I --> O[dependency-manager.ts];
+    I --> P[schema-utils.ts];
+    I --> Q[migration-phases.ts];
 ```
 
 ## Uso Básico
 
 ### En aplicaciones NestJS
 
-```typescript
+Importa el `PrismaModule` en tu módulo principal:
+
+```typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md
 import { Module } from "@nestjs/common";
-import { PrismaModule } from "@tupay/prisma-client";
+import { PrismaModule } from "@javalabs/prisma-client"; // <--- Updated import path
 
 @Module({
   imports: [PrismaModule],
@@ -86,121 +89,167 @@ import { PrismaModule } from "@tupay/prisma-client";
 export class AppModule {}
 ```
 
-Luego, inyecta el servicio donde lo necesites:
+Luego, inyecta los servicios donde los necesites:
 
-```typescript
+```typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md
 import { Injectable } from "@nestjs/common";
-import { PrismaService, PrismaFactoryService } from "@tupay/prisma-client";
+import { PrismaService, PrismaFactoryService } from "@javalabs/prisma-client"; // <--- Updated import path
 
 @Injectable()
 export class MyService {
   constructor(
-    private prismaService: PrismaService,
-    private prismaFactoryService: PrismaFactoryService
+    private prismaService: PrismaService, // Cliente para el schema 'public'
+    private prismaFactoryService: PrismaFactoryService // Fábrica para clientes de tenants
   ) {}
 
   // Usar el cliente principal (schema public)
-  async findAllUsers() {
-    return this.prismaService.client.users.findMany();
+  async findAllPublicData() {
+    // Asume que tienes un modelo 'PublicData' en tu schema.prisma
+    // return this.prismaService.client.publicData.findMany();
+    return "Ejemplo: Accediendo a datos públicos";
   }
 
   // Usar un cliente específico para un tenant
   async findTenantUsers(tenantId: string) {
+    // tenantId suele ser la API Key que identifica al schema
     const tenantClient = this.prismaFactoryService.getClient(tenantId);
+    // Asume que tienes un modelo 'users' en tu schema.prisma
     return tenantClient.users.findMany();
   }
 }
 ```
 
-### En aplicaciones no-NestJS
+### En aplicaciones no-NestJS (o scripts)
+
+Puedes importar directamente la instancia `prisma` (cliente para el schema `public`). Para acceder a tenants, necesitarías instanciar `PrismaFactoryService` manualmente o usar los scripts proporcionados.
 
-```typescript
-import { prisma } from "@tupay/prisma-client";
+```typescript:/Users/alejandroperez/tupay/packages/prisma-client/README.md
+import { prisma } from "@javalabs/prisma-client"; // <--- Updated import path
 
 async function main() {
-  const users = await prisma.users.findMany();
-  console.log(users);
+  // Ejemplo: Acceder a datos del schema 'public'
+  // const publicData = await prisma.publicData.findMany();
+  // console.log(publicData);
+  console.log("Ejemplo: Accediendo a datos públicos desde script");
 }
 
 main()
   .catch(console.error)
-  .finally(() => prisma.$disconnect());
+  .finally(async () => {
+      await prisma.$disconnect();
+  });
+
 ```
 
 ## Scripts de Utilidad
 
-Este paquete incluye varios scripts útiles para la gestión de bases de datos:
+Estos scripts se ejecutan generalmente con `npm run <script_name>` o `node dist/scripts/<script_file>.js` después de compilar (`npm run build`).
 
 ### Migración de Datos
 
+Migra datos desde `SOURCE_DATABASE_URL` a los esquemas de tenants en `DATABASE_URL`.
+
 ```bash
-# Migrar datos entre bases de datos
+# Migrar datos (requiere confirmación)
 npm run migrate:data
 
-# Migrar datos forzando la operación
+# Migrar datos forzando la operación (sin confirmación)
 npm run migrate:data:force
 
-# Migrar datos con confirmación automática
+# Migrar datos con confirmación automática 'yes'
 npm run migrate:data:yes
 ```
 
-### Gestión de Esquemas
+### Gestión de Esquemas (Prisma Migrate)
+
+Gestiona la evolución del esquema de la base de datos usando Prisma Migrate. Estos comandos aplican los cambios definidos en `prisma/migrations` al schema `public`. Para aplicar a tenants, ver "Scripts Avanzados".
 
 ```bash
-# Generar cliente Prisma
+# Generar cliente Prisma basado en schema.prisma
 npm run generate
 
-# Ejecutar migraciones de desarrollo
+# Crear una nueva migración SQL basada en cambios al schema.prisma (desarrollo)
 npm run migrate:dev
 
-# Desplegar migraciones
+# Aplicar migraciones pendientes a la base de datos (producción/despliegue)
 npm run migrate:deploy
 ```
 
 ## Scripts Avanzados
 
-El paquete también incluye scripts para casos de uso más avanzados:
+Scripts para tareas más complejas de administración multi-tenant. Ejecutar con `node dist/scripts/<script_file>.js` después de `npm run build`.
 
 ### Creación de Esquemas para Tenants
 
+Crea los esquemas de base de datos para cada tenant (basado en API Keys encontradas en `SOURCE_DATABASE_URL`).
+
 ```bash
-# Compilar el proyecto
+# Compilar el proyecto si no está compilado
 npm run build
 
 # Ejecutar el script para crear esquemas de tenant
 node dist/scripts/create-tenant-schemas.js
 ```
 
-### Migración de Estructura de Esquemas
+### Migración de Estructura de Esquemas (Tenants)
+
+Aplica la estructura definida en `prisma/schema.prisma` a todos los esquemas de tenants existentes en `DATABASE_URL` usando `prisma db push`. Útil para asegurar que todos los tenants tengan la misma estructura base.
 
 ```bash
-# Migrar la estructura de esquemas entre bases de datos
+# Compilar el proyecto si no está compilado
+npm run build
+
+# Ejecutar el script para aplicar la estructura a los schemas de tenants
 node dist/scripts/migrate-schema-structure.js
 ```
 
 ### Sincronización de Esquemas
 
+Genera un script SQL para sincronizar esquemas (potencialmente entre `public` y tenants, o entre tenants). Revisa el script antes de aplicarlo.
+
 ```bash
-# Generar un script SQL para sincronizar esquemas
+# Compilar el proyecto si no está compilado
+npm run build
+
+# Generar el script SQL de sincronización
 node dist/scripts/schema-sync.js
 ```
 
 ### Reseteo de Base de Datos
 
+Resetea la base de datos (¡CUIDADO: Borra datos!).
+
 ```bash
-# Resetear la base de datos
+# Compilar el proyecto si no está compilado
+npm run build
+
+# Resetear la base de datos (schema public y potencialmente tenants, revisar script)
 node dist/scripts/reset-database.js
 
 # Resetear y recrear la base de datos
 node dist/scripts/reset-database.js --recreate
 ```
 
+### Corrección de Tipos de Datos
+
+Intenta corregir inconsistencias en tipos de datos (ej. numéricos almacenados como texto, valores de enums inválidos) en los esquemas de los tenants.
+
+```bash
+# Compilar el proyecto si no está compilado
+npm run build
+
+# Ejecutar el script para corregir tipos de datos
+node dist/scripts/fix-data-types.js
+```
+
 ## Variables de Entorno
 
-El paquete requiere las siguientes variables de entorno:
+El paquete y sus scripts dependen de las siguientes variables de entorno (generalmente definidas en un archivo `.env`):
 
-- `DATABASE_URL`: URL de conexión a la base de datos principal
-- `SOURCE_DATABASE_URL`: URL de conexión a la base de datos de origen (para migraciones)
+- `DATABASE_URL`: URL de conexión a la base de datos principal (PostgreSQL) donde residen los esquemas `public` y de los tenants.
+  - Ejemplo: `postgresql://user:password@host:port/database`
+- `SOURCE_DATABASE_URL`: URL de conexión a la base de datos de origen, utilizada principalmente por los scripts de migración de datos y creación de esquemas.
+  - Ejemplo: `postgresql://user:password@source_host:port/source_database`
 
 ## Desarrollo
 
@@ -208,10 +257,10 @@ El paquete requiere las siguientes variables de entorno:
 # Instalar dependencias
 npm install
 
-# Compilar el proyecto
+# Compilar el proyecto (genera archivos en dist/)
 npm run build
 
-# Generar cliente Prisma
+# Generar cliente Prisma (después de cambios en schema.prisma)
 npm run generate
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javalabs/prisma-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Shared Prisma client for Tupay microservices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",