panels-origin/db

Base de datos (Postgres + Liquibase)

PANELS usa Postgres organizado como monolito modular: dos bases de datos físicamente separadas en el mismo servidor/instancia por ambiente.

Base de datos	Esquema(s)	Changelog	Qué vive ahí
panels_platform	public	db/platform/	Control plane SaaS: tenants, platform_users (identidad de PANELS como operador), smtp_settings. Solo lo tocan las rutas /v1/saas/*.
panels_product	iam	db/iam/	Identidad/roles/permisos de cada tenant (ej. usuarios de ARCTEC). Aislado de core -- sin JOIN/FK cruzado.
panels_product	core	db/core/	Negocio: empresas, personal, obras, expedientes, presupuesto, nómina, gafetes.

No hay FK real entre panels_platform y panels_product (bases distintas), ni entre los esquemas iam y core (aislamiento a propósito). tenant_id es una referencia lógica validada en la capa de aplicación. Ver el plan de migración para el detalle de la arquitectura y las reglas del monolito modular.

Aprovisionamiento (una vez por ambiente, antes de Liquibase)

Ver db/provision/README.md: crea los 6 roles de Postgres (panels_{platform,iam,core}_{owner,app}), las 2 bases de datos, los esquemas iam/core, la extensión citext, y los usuarios ACL de Redis. Incluye dev-local.sh para reproducir todo esto en una máquina de desarrollo sin depender de Coolify, y verify-isolation.sh para confirmar que el aislamiento realmente se cumple.

Aplicar migraciones

En Coolify no se corre a mano: el servicio migrate de docker-compose.yml aplica all --context-filter=!dev en cada deploy, antes de levantar api.

A mano (Java 17+ y credenciales _owner, nunca _app):

# Local, después de correr db/provision/dev-local.sh:
set -a && source .env.dev-local && set +a
./db/update.sh all --context-filter=dev    # dev: incluye datos de demo
./db/update.sh all --context-filter='!dev' # staging/producción: solo esquema + catálogos

# Un solo módulo
./db/update.sh core --context-filter='!dev'
./db/update.sh iam --context-filter='!dev'
./db/update.sh platform --context-filter='!dev'

Importante: Liquibase, si NO se le pasa --context-filter, corre TODOS los changesets sin importar su context -- incluidos los de context="dev". No pasar el filtro en staging/producción NO es "modo seguro por defecto", es lo contrario: cargaría el tenant/empresas/proyecto de demostración. Por eso --context-filter es obligatorio siempre, nunca opcional.

npm run db:migrate corre ./db/update.sh all. Las migraciones ya NO corren automáticamente al arrancar la API -- son un paso explícito de deploy (a diferencia del runLiquibase() que existía con SQLite).

Contexts de Liquibase:

• Sin context: changesets de esquema y catálogos requeridos (risk_levels, document_types, etc.) -- corren en todos los ambientes.
• context="dev": datos de demostración (tenant/empresas/proyecto ARCTEC) -- nunca en staging/producción. Siempre pasar --context-filter explícito; no confiar en el default de Liquibase.

Nuevos cambios de schema

Un changeset nuevo en db/{platform,iam,core}/changesets/, referenciado en el changelog-master.xml correspondiente. Reglas:

• Nunca editar un changeset ya aplicado en un ambiente compartido -- crear uno nuevo.
• Usar dbms:postgresql en vez de context para lógica específica de motor.
• No añadir migraciones directamente en api/*.ts.
• Las herramientas (Liquibase + driver JDBC de Postgres) viven en db/tools/ (gitignored); bootstrap-tools.sh las descarga.

Bootstrap del primer usuario administrador

El password_hash (PBKDF2) no lo puede generar un changeset SQL. El primer platform_admin y el primer tenant_admin de un tenant nuevo se crean con scripts/bootstrap-admin.ts (ver Fase 4 del plan de migración), no con lógica de seed en el arranque de la API ni con datos hardcodeados en Liquibase.

Funciones RPC (core.fn_*)

A partir del changeset 006-rpc-infra.sql, el esquema core expone la lógica de negocio como funciones PostgreSQL invocadas desde la API con SELECT core.fn_nombre($1::jsonb). La capa TypeScript no debe usar db.prepare() contra tablas de core en rutas de negocio; solo api/rpc.ts ejecuta el SELECT del RPC.

Envelope de respuesta (BD)

Toda función devuelve un jsonb con esta forma:

{
  "ok": true,
  "code": "OK",
  "layer": "db",
  "message": "Mensaje detallado en español",
  "context": { "fn": "fn_empresa_get", "id": 5 },
  "data": { },
  "errors": null
}

• code: código de negocio (OK, CREATED, VALIDATION, NOT_FOUND, CONFLICT, INTERNAL, …).
• layer: siempre "db" desde Postgres.
• message: texto legible y específico (nunca genérico).
• context: metadatos seguros para depuración (nombre de función, ids).
• data: payload de éxito; errors: mapa de campos en validación.

Helpers en 006-rpc-infra.sql: rpc_ok, rpc_err, rpc_created, rpc_from_exception.

Contrato API

api/http_errors.ts mapea code → HTTP y añade status al body. respondRpc() preserva layer y message de la BD; respondApiError() construye envelopes de capa "api".

Convenciones al añadir funciones

1. Un solo parámetro payload jsonb.
2. Prefijo fn_ para funciones que devuelven envelope.
3. SECURITY INVOKER y SET search_path = core.
4. Errores de negocio con RETURN core.rpc_err(...); constraints de Postgres capturados en EXCEPTION y traducidos a mensajes claros.
5. GRANT EXECUTE ... TO panels_core_app en el mismo changeset.
6. Comentario de ejemplo SELECT core.fn_*(...) en el SQL.

Changesets RPC: 006 (infra) … 015 (documentos). Ver changelog-master.xml.