@camtom-backend/contracts - Guía de Uso e Integración

Este paquete actúa como la única fuente de verdad para la definición de datos en el ecosistema Camtom. Contiene el esquema de la base de datos (Prisma), el cliente de base de datos generado y los esquemas de validación (Zod) compartidos entre el Backend y el Frontend.

📦 1. Despliegue y Publicación

Estructura del Paquete

El paquete utiliza "Subpath Exports" para separar claramente las dependencias del servidor (Prisma Client) de las del cliente (Zod Schemas), evitando que código pesado de servidor llegue al bundle del frontend.

• @camtom-backend/contracts/prisma/client: Cliente de Base de Datos (Solo Backend).
• @camtom-backend/contracts/schemas/*: Esquemas de Validación (Backend y Frontend).

Comandos de Construcción

Antes de desplegar o publicar, es necesario generar los artefactos:

# Dentro de packages/contracts-system
npm install
npm run build

Este comando ejecuta internamente:

1. prisma generate: Genera el Prisma Client y los Zod Schemas basados en prisma/schema.prisma.
2. tsc: Compila el código TypeScript a JavaScript (ESM y CommonJS) en la carpeta dist/.
3. Copia de definiciones de tipos (.d.ts) para soportar intellisense.

Publicación

Si utilizas un registro privado (ej. Verdaccio, AWS CodeArtifact, GitHub Packages) o npmjs org:

1. Asegúrate de incrementar la versión en package.json.
2. Ejecuta:

   npm publish --access restricted

Nota sobre Monorepo: Si estás trabajando localmente en el monorepo, asegúrate de que los package.json de dev_nodejs y dev_front apunten a la versión correcta o usen workspaces ("file:../../packages/contracts-system" o la versión definida en el workspace root).

🖥️ 2. Uso en Backend (Node.js / FastAPI)

Nota: Actualmente optimizado para Node.js/TypeScript. Para Python (FastAPI), se recomienda usar el cliente de Prisma para Python o mantener los modelos Pydantic sincronizados manualmente por ahora, aunque existen generadores de Pydantic para Prisma.

Instalación

npm install @camtom-backend/contracts

Implementación (Patrón Singleton)

El paquete ya exporta una instancia optimizada de Prisma Client. No necesitas instanciar PrismaClient manualmente.

Ejemplo: Servicio de Lifeline

// dev_nodejs/src/modules/Lifeline/services/lifelinePrisma.service.ts
import { db } from '@camtom-backend/contracts/prisma/client'; // Importar la instancia DB
import { LifelineSchema } from '@camtom-backend/contracts/schemas/lifeline'; // Importar tipos/validación

export class LifelinePrismaService {
  
  async createLifeline(data: unknown) {
    // 1. Validar datos (opcional si confías en el input, pero recomendado)
    const validatedData = LifelineSchema.parse(data);

    // 2. Usar Prisma Client directamente
    const lifeline = await db.lifeline.create({
      data: {
        ...validatedData,
        // Manejo de fechas u otros campos específicos
        createdAt: new Date(),
      }
    });

    return lifeline;
  }

  async getLifeline(id: string) {
    return await db.lifeline.findUnique({
      where: { id }
    });
  }
}

🎨 3. Uso en Frontend (React)

El frontend solo debe importar los esquemas, nunca el cliente de base de datos.

Instalación

npm install @camtom-backend/contracts

Asegúrate de que zod también esté instalado como peer dependency si es necesario.

Integración en Formularios (React Hook Form)

Utiliza los esquemas generados para validar formularios automáticamente.

Ejemplo: Formulario de Creación

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { LifelineSchema } from '@camtom-backend/contracts/schemas/lifeline';
import type { z } from 'zod';

// Inferir el tipo TypeScript directamente del esquema
type LifelineFormValues = z.infer<typeof LifelineSchema>;

export const CreateLifelineForm = () => {
  const { register, handleSubmit, formState: { errors } } = useForm<LifelineFormValues>({
    // Conectar el validador Zod del paquete compartido
    resolver: zodResolver(LifelineSchema), 
    defaultValues: {
      status: 'DRAFT',
      // ...
    }
  });

  const onSubmit = (data: LifelineFormValues) => {
    // 'data' ya está tipado y validado aquí
    console.log("Enviando al backend:", data);
    // api.post('/lifelines', data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("referenceId")} placeholder="Referencia" />
      {errors.referenceId && <span className="error">{errors.referenceId.message}</span>}
      
      <button type="submit">Guardar</button>
    </form>
  );
};

🛡️ 4. Buenas Prácticas y Flujo de Trabajo

Flujo de Desarrollo (Haciendo cambios en la BD)

1. Editar: Modifica packages/contracts-system/prisma/schema.prisma.
2. Validar: Ejecuta npx prisma validate para asegurar que el esquema es correcto.
3. Generar: Ejecuta npm run build en la carpeta del paquete. Esto actualiza:
   • Los tipos de TypeScript.
   • El Cliente de Prisma.
   • Los Esquemas Zod.
4. Consumir: Reinicia los servidores de desarrollo (Node/React) para que tomen los nuevos tipos.

Control de Versiones (Versioning)

• Usa Versionado Semántico (SemVer).
• Si cambias una columna obligatoria a opcional -> Minor change (compatible hacia atrás usualmente).
• Si eliminas una columna o la haces obligatoria -> Major change (Breaking change).
• Asegúrate de que Backend y Frontend usen versiones compatibles del paquete.

Tipado Estricto

Evita crear interfaces manuales (interface ILifeline { ... }) en el frontend o backend. Siempre infiere los tipos desde el esquema Zod o los tipos de Prisma exportados.

// ✅ CORRECTO
import type { Lifeline } from '@camtom-backend/contracts/prisma/client';
import { LifelineSchema } from '@camtom-backend/contracts/schemas/lifeline';
type LifelineInput = z.infer<typeof LifelineSchema>;

// ❌ INCORRECTO
interface Lifeline {
  id: string;
  reference: string;
  // ... duplicación manual propensa a errores
}

Solución de Problemas Comunes

• Error: "PrismaClient is unable to be run in the browser":

  • Causa: Estás importando @camtom-backend/contracts/prisma/client en un archivo de React.
  • Solución: Asegúrate de importar solo desde @camtom-backend/contracts/schemas/* en el frontend.

• Error de Tipos en VS Code:

  • A veces VS Code no detecta los cambios en node_modules. Reinicia el servidor de TypeScript (Cmd+Shift+P -> "TypeScript: Restart TS Server").