Esquemas y tablas

La base de datos PostgreSQL de Zentto organiza las tablas en esquemas lógicos que corresponden a los módulos funcionales del ERP. El bootstrap de los esquemas está en web/api/sqlweb-pg/baseline/000_schemas.sql; los cambios posteriores llegan por migraciones Goose. Las funciones usp_* viven en public.

Esquemas del sistema (28)

Esquema	Área	Contenido
cfg	Configuración	Empresa, sucursales, monedas, tasas, secuencias, parámetros, tokens de servicio, auth del backoffice
sec	Seguridad	Usuarios, roles, permisos (RBAC), accesos por empresa
master	Maestros	Productos, clientes, proveedores, categorías, almacenes, listas de precios, impuestos
doc	Documentos	Presupuestos, pedidos y vistas legacy. ⚠️ Las facturas de venta NO viven aquí (ver `ar`)
ar	Cuentas por cobrar	`ar.SalesDocument` = registro canónico de facturas/NC/ND de venta (los SP `usp_Doc_SalesDocument_*` escriben aquí) + saldos, cobros, aplicaciones
ap	Cuentas por pagar	Saldos de proveedores, pagos, retenciones (IVA/ISLR)
acct	Contabilidad	Plan de cuentas, asientos, períodos, centros de costo, policies contables
pay	Pagos	Métodos de pago, bancos, conciliación, liquidaciones (settlements)
fin	Finanzas	Bancos/cuentas propias, flujo de caja, dinero en tránsito
inv	Inventario	Kardex, movimientos, lotes, conteos, valuación
pur	Compras	Procurement: órdenes, recepciones, cotizaciones de proveedor
sales	Ventas	Vendedores, comisiones, pipeline de venta
pos	Punto de venta	Cajas, turnos, ventas POS, periféricos
rest	Restaurante	Mesas, áreas, comandas, menú, cocina
store	Tienda online	Catálogo público, carrito server-side, pedidos e-commerce, clientes compradores
crm	CRM	Contactos, leads, deals, actividades (el schema con más SPs: ~157)
cms	CMS	Contenido, landings, branding por tenant
hr	RRHH	Empleados, cargos, nómina, prestaciones, asistencia
mfg	Manufactura	BOM, órdenes de producción, centros de trabajo
fleet	Flota	Vehículos, mantenimientos, asignaciones
logistics	Logística	Despachos, envíos, tracking (portal shipping)
geo	Geolocalización	Entidades vivas, geocercas, rutas (integración con el microservicio zentto-geo)
fiscal	Fiscal VE	Series, correlativos, libros, config de máquinas fiscales y proveedores (HKA)
audit	Auditoría	`audit.AuditLog` — bitácora de mutaciones (middleware audit-trail)
integration	Integraciones	Conectores externos, webhooks, credenciales de integración
platform	Plataforma	Recursos de plataforma multi-app (licencias, addons)
sys	Sistema	`sys.TenantDatabase`, `sys.TenantBackup`, cola de limpieza, métricas backoffice
zsys	Sistema (interno)	Utilidades internas del motor (governance, meta)

Tablas clave por esquema

cfg (Configuración)

cfg.Company           -- Empresa (multi-tenant)
cfg.Branch            -- Sucursales
cfg.Currency          -- Monedas (VES, USD, EUR, ...)
cfg.ExchangeRate      -- Tasas de cambio diarias
cfg.SystemParam       -- Parámetros clave-valor
cfg.Sequence          -- Secuencias de numeración (facturas, NC, ...)
cfg.ServiceToken      -- Tokens server-to-server (solo hash SHA-256)
cfg.BackofficeAuth    -- Secret TOTP del backoffice (única fuente de verdad)

sec (Seguridad)

sec.User              -- Usuarios del ERP (mapeados al UUID de zentto-auth por empresa)
sec.Role              -- Roles
sec.UserRole          -- Asignación usuario-rol
sec.Permission        -- Permisos granulares (RBAC por módulo+acción)
sec.RolePermission    -- Asignación rol-permiso

ar (facturación de venta)

ar.SalesDocument      -- Registro canónico de facturas, NC y ND de venta
ar.SalesDocumentLine  -- Detalle
-- Los SP usp_Doc_SalesDocument_* escriben aquí; el schema doc conserva
-- vistas legacy vacías. Verificar SIEMPRE contra ar.* al reportar ventas.

Convenciones de nombres

Tablas: PascalCase singular entre comillas — master."Product"
Columnas: PascalCase — "CompanyId", "CreatedAtUtc"
Primary keys: [Tabla]Id — "ProductId"
Fechas: sufijo Utc, almacenadas en UTC-0
Soft delete: "IsActive" BOOLEAN (o "IsDeleted" según el módulo — cuidado con upserts que reviven registros borrados)
Multi-tenant: toda tabla transaccional tiene "CompanyId"; en el modelo compartido aplica Row-Level Security con el GUC app.current_company_id
Funciones: usp_[schema]_[entity]_[action] en public, llamadas en snake_case exacto

Row-Level Security (multi-tenant compartido)

Desde la migración 00179, las tablas del modelo compartido tienen políticas RLS por CompanyId. La API fija el scope por request: cada llamada con empresa corre en una transacción con SELECT set_config('app.current_company_id', $1, true). Procesos sin empresa (backoffice, cron, provisioning) usan el pool directo con BYPASSRLS controlado. Al escribir SPs: si la función lee tablas con RLS, el GUC debe estar fijado — un valor vacío se maneja con NULLIF(current_setting('app.current_company_id', true), '').

Legacy: datos del VB6

Las tablas del sistema VB6 original (esquema dbo en SQL Server) ya no se acceden desde la aplicación: la incorporación de clientes legacy se hace con el Zentto Migrador, que lee el SQL Server del cliente y carga los datos al modelo canónico PostgreSQL. No existe puente en vivo.