Sk 02 Drizzle Orm Database Schema

Tablas y campos (resumen)

• negocios:
  • tieneDivisiones (controla obligatoriedad de centroCostoId en movimientos)
  • umbralAlerta, umbralCritico (semaforo)
  • activo
• centrosCosto:
  • padreId (self-ref), tipo, descripcion, negocioId, activo
• categorias:
  • negocioId nullable (null = global)
  • requiereAprobacion, montoMaxSinAprobacion, activa
• cuentasBanco:
  • negocioId nullable
  • esGlobal (true = visible en todos los negocios)
  • cuentas compartidas (N:M) vía cuentaNegocio
• cuentaNegocio (N:M):
  • cuentaId, negocioId, fechaAsignacion, unique index (uq_cuenta_negocio)
• movimientos:
  • multi-tenant: negocioId NOT NULL
  • divisiones: centroCostoId nullable (según negocios.tieneDivisiones)
  • categoría: categoriaId nullable
  • estado: PENDIENTE/APROBADO/RECHAZADO/PAGADO/CANCELADO
  • pago: efectuado, fechaPago, pagadoPor
  • traspaso: traspasoRefId (vínculo a espejo)
• auditLogs: bitácora de auditoría (evento, recurso, userId, negocioId, detalles JSON string)
• cotizaciones / cotizacionItems
• roles, usuarios, usuarioNegocio

Importaciones correctas

import { db } from '@/lib/db';
import {
  usuarios,
  negocios,
  usuarioNegocio,
  cuentasBanco,
  cuentaNegocio,
  categorias,
  centrosCosto,
  movimientos,
  cotizaciones,
  cotizacionItems,
  auditLogs,
} from '@/lib/drizzle';
import {
  eq,
  and,
  or,
  gte,
  lte,
  like,
  ilike,
  inArray,
  isNull,
  isNotNull,
  desc,
  asc,
  sql,
  count,
} from 'drizzle-orm';

Patrones de query

Select básico

await db
  .select()
  .from(movimientos)
  .where(and(eq(movimientos.negocioId, negocioId), eq(movimientos.activo, true)))
  .orderBy(desc(movimientos.createdAt));

Join

await db
  .select({
    movimiento: movimientos,
    cuenta: { nombre: cuentasBanco.nombre },
  })
  .from(movimientos)
  .leftJoin(cuentasBanco, eq(movimientos.cuentaBancoId, cuentasBanco.id))
  .where(eq(movimientos.negocioId, negocioId));

Transacción (obligatoria)

await db.transaction(async (tx) => {
  const [mov1] = await tx.insert(movimientos).values({ ... }).returning();
  const [mov2] = await tx.insert(movimientos).values({ traspasoRefId: mov1.id, ... }).returning();
  return { mov1, mov2 };
});

Paginación (listado + total)

const [items, [{ total }]] = await Promise.all([
  db.select().from(movimientos).where(conditions).limit(limit).offset((page - 1) * limit),
  db.select({ total: count() }).from(movimientos).where(conditions),
]);

Migraciones (reglas)

• No modificar migraciones ya aplicadas.
• Campos nuevos en tablas con datos existentes: preferir nullable.
• Agregar índices para campos usados frecuentemente en WHERE.
• Flujo: editar drizzle.ts → npm run db:generate → npm run db:migrate → npm run build.

Regla de estados (impacto financiero)

• Arqueo (saldo caja/cuenta): solo estado = 'PAGADO' suma/resta movimientos.
• Reportes financieros: estado IN ('APROBADO','PAGADO') (ver ESTADOS_EJECUTADOS en src/services/reporte.service.ts).