Documentación del Sistema

Appearance

Consolidación de Informes Multi-Schema ​

Tipo: Arquitectural Alcance: Todos los módulos con informes/reportes Estado: En Uso (Implementación de referencia en Contabilidad) Fecha: 2025-12-31

Descripción General ​

Este documento describe el patrón arquitectural de consolidación de informes que permite generar reportes unificados combinando datos de múltiples sucursales/schemas en el Sistema Bautista. Es una solución transversal aplicable a cualquier módulo que genere informes (Contabilidad, Ventas, Compras, Stock, CRM, etc.).

Arquitectura Multi-Schema ​

Contexto Técnico ​

El Sistema Bautista utiliza una arquitectura multi-schema de PostgreSQL con tres niveles de segregación de datos:

Niveles de Schema:

  1. LEVEL_EMPRESA (1): Schema public - Datos compartidos por toda la empresa
  2. LEVEL_SUCURSAL (2): Schemas sucXXXX (suc0001, suc0002, etc.) - Datos por sucursal
  3. LEVEL_CAJA (3): Schemas sucXXXXcajaXXXX (suc0001caja0001, etc.) - Datos por caja

Datos Compartidos (LEVEL_EMPRESA) ​

Las siguientes entidades residen en public y son compartidas por todas las sucursales:

Datos Maestros:

  • Plan de cuentas contables (cuentas)
  • Ejercicios contables (ejerci)
  • Tipos de comprobantes (comprob)
  • Alícuotas de IVA (aliva)
  • Conceptos de retenciones (congan, boniret, etc.)
  • Bancos (bancos)
  • Provincias y localidades (provincia, localidades)
  • Usuarios y permisos (usuarios, grupos, permisos)

Ventaja para consolidación: Todas las sucursales usan los mismos datos maestros, no hay necesidad de mapeo entre sucursales.

Datos Transaccionales (Configurables) ​

Las tablas transaccionales pueden residir en diferentes niveles según la configuración de cada empresa mediante el campo configuracion_niveles_tablas en la tabla sistema.

Ejemplos:

  • Movimientos contables (movimi): LEVEL_EMPRESA, LEVEL_SUCURSAL y/o LEVEL_CAJA
  • Asientos contables (nroasien): LEVEL_EMPRESA y/o LEVEL_SUCURSAL
  • Comprobantes de venta: LEVEL_SUCURSAL y/o LEVEL_CAJA
  • Movimientos de stock: LEVEL_SUCURSAL

Patrón de Consolidación ​

Problema ​

Cuando un usuario necesita un informe consolidado (ej: Balance General de todas las sucursales), el sistema debe:

  1. Consultar datos de múltiples schemas
  2. Agregar/consolidar los resultados
  3. Mantener la trazabilidad del origen de cada dato
  4. Respetar permisos por sucursal del usuario

Solución: Consolidación Multi-Schema ​

Principios:

  1. Búsqueda multi-schema: Consultar datos en todos los schemas relevantes
  2. Agregación: Sumar/consolidar datos de las mismas entidades (ej: misma cuenta contable)
  3. Trazabilidad: Identificar el schema de origen de cada dato
  4. Respeto de permisos: Solo incluir sucursales donde el usuario tenga permisos

Componentes del Patrón ​

1. Activación por Usuario ​

El usuario activa la consolidación mediante un indicador visual (checkbox, toggle):

  • Por defecto: Reportes muestran solo datos del schema actual
  • Con consolidación activa: Reportes incluyen datos de todas las sucursales elegibles

2. Determinación de Schemas Objetivo ​

El sistema determina qué schemas consultar basándose en:

  • Configuración de niveles: Consulta configuracion_niveles_tablas para saber en qué niveles están las tablas
  • Sucursal del usuario: Solo schemas de la sucursal actual (nunca schemas de otras sucursales)
  • Permisos del usuario: Solo schemas donde el usuario tiene permisos del módulo

Ejemplo:

Usuario en: suc0001caja0001
Tabla movimi con niveles: [LEVEL_SUCURSAL, LEVEL_CAJA]
Schemas a consultar: suc0001, suc0001caja0001, suc0001caja0002, etc.
Schemas excluidos: suc0002, suc0003, public

3. Búsqueda Multi-Schema ​

Para cada schema objetivo:

  1. Establecer search_path al schema
  2. Ejecutar query del informe
  3. Agregar identificador de schema al resultado
  4. Consolidar resultados de todos los schemas

4. Agregación de Datos ​

Reglas de agregación:

  • Datos maestros compartidos: Se consultan una sola vez desde public
  • Datos transaccionales: Se suman/agregan por entidad común
    • Ejemplo: Saldos de cuenta 1100 = suma(saldo_suc0001 + saldo_suc0002 + ...)
  • Trazabilidad: Cada registro conserva identificación de schema de origen

5. Presentación ​

El informe consolidado debe:

  • Indicar claramente que es un reporte consolidado
  • Listar sucursales incluidas y excluidas
  • Mostrar origen de cada dato (opcionalmente)
  • Calcular totales consolidados correctamente
  • Permitir desglose por sucursal

Reglas Arquitecturales ​

RA-001: Datos maestros compartidos ​

Descripción: Los datos maestros residen en LEVEL_EMPRESA y son únicos para toda la organización.

Implicación: No hay mapeo ni compatibilidad a validar - todas las sucursales usan los mismos.

Ejemplos:

  • Plan de cuentas contables
  • Ejercicios contables (períodos)
  • Conceptos de retenciones
  • Tipos de comprobantes

RA-002: Configuración dinámica de niveles ​

Descripción: El sistema consulta configuracion_niveles_tablas para determinar en qué schemas buscar datos.

Comportamiento:

  • Si tabla tiene múltiples niveles configurados → búsqueda multi-schema
  • Si tabla tiene un solo nivel → búsqueda simple en schema actual
  • Si no hay configuración personalizada → usar niveles por defecto de la tabla

RA-003: Alcance limitado por sucursal ​

Descripción: La consolidación incluye únicamente schemas de la sucursal actual del usuario.

Fundamento: Mantener segregación de datos y respetar permisos por sucursal.

Ejemplo:

Usuario en sucursal 0001:
  ✅ Puede consolidar: suc0001, suc0001caja0001, suc0001caja0002
  ❌ No puede consolidar: suc0002, suc0003

RA-004: Validación de permisos ​

Descripción: El usuario solo ve datos consolidados de sucursales donde tiene permisos del módulo.

Validación: Antes de ejecutar queries, verificar permisos del usuario en cada schema.

RA-005: Trazabilidad obligatoria ​

Descripción: Todo dato en un informe consolidado debe poder rastrearse a su schema de origen.

Implementación:

  • Agregar columna schema_origen o sucursal a resultados
  • Mantener identificación durante toda la agregación
  • Incluir en exportaciones (Excel, PDF)

RA-006: Rendimiento aceptable ​

Descripción: La consolidación debe tener rendimiento aceptable considerando que consulta múltiples schemas.

Pautas:

  • Para 2-5 sucursales: tiempo similar a reportes normales (segundos)
  • Para 10+ sucursales: puede requerir hasta 30-60 segundos
  • Mostrar indicador de progreso para operaciones > 3 segundos
  • Considerar caché para datos maestros compartidos

Implementación por Módulo ​

Este documento define el patrón general. Cada módulo debe crear su propia documentación específica que:

  1. Referencie este documento para el patrón arquitectural
  2. Liste los informes específicos que soportarán consolidación
  3. Defina reglas particulares del dominio de negocio
  4. Especifique agregaciones propias del módulo

Módulos con Consolidación ​

  • ✅ Contabilidad (Implementación de referencia):
    • Balance de Comprobación ✅ Implementado (2025-12-31)
    • Libro Diario General ⏭️ Pendiente
    • Libro Mayor ⏭️ Pendiente
    • Balance General ⏭️ Pendiente
    • Estado de Resultados ⏭️ Pendiente
    • Ver: docs/features/contabilidad/consolidacion-informes-contables.md
  • ⏭️ Ventas: Informes de facturación, estadísticas de ventas
  • ⏭️ Compras: Informes de compras, proveedores
  • ⏭️ Stock: Informes de inventario, movimientos
  • ⏭️ CRM: Informes de clientes, oportunidades
  • ⏭️ Tesorería: Informes de caja, bancos

Consideraciones Técnicas ​

Seguridad ​

Control de acceso:

  • Validar permisos del usuario en cada schema antes de consultar
  • No permitir acceso a schemas de otras sucursales
  • Auditar accesos a datos consolidados

Integridad transaccional:

  • Consolidación es solo lectura - no modifica datos originales
  • Datos permanecen en sus schemas correspondientes

Auditoría ​

Información a registrar:

EventoDatos a Capturar
Generación de informe consolidadoUsuario, timestamp, módulo, tipo de informe
Schemas consultadosLista de schemas incluidos
ResultadosCantidad de registros por schema

Performance ​

Optimizaciones:

  • Caché de configuración: Mantener configuracion_niveles_tablas en memoria
  • Consultas paralelas: Consultar múltiples schemas en paralelo cuando sea posible
  • Límites razonables: Considerar límite de sucursales por consolidación
  • Paginación: Para grandes volúmenes, implementar paginación o generación asíncrona

Expectativas:

  • Prioridad: correctitud > velocidad
  • Aceptable: 5-10 segundos para consolidar 5 sucursales
  • Considerar: Generación en background para > 10 sucursales

Extensiones Futuras ​

Selección de Sucursales (Fase 2) ​

Permitir al usuario seleccionar manualmente qué sucursales incluir en lugar de todas:

  • Selector visual con checkboxes
  • Persistencia de selección durante la sesión
  • Filtrado de resultados por sucursal

Nota: Esta funcionalidad es opcional y puede implementarse después de la consolidación automática básica.

Otras Extensiones ​

  • Consolidación programada: Generación automática de reportes consolidados
  • Alertas consolidadas: Notificaciones basadas en datos de múltiples sucursales
  • Dashboards consolidados: Visualizaciones en tiempo real
  • Exportación mejorada: Formatos específicos para consolidación (Excel con múltiples hojas por sucursal)

Referencias ​

Documentación Relacionada ​

  • Multi-Schema Transactional Operations: docs/architecture/multi-schema-transactional-operations-process.md
  • Configuración de Niveles: Campo configuracion_niveles_tablas en tabla sistema

Implementaciones por Módulo ​

  • Contabilidad: docs/features/contabilidad/consolidacion-informes-contables.md

Historial de Cambios ​

FechaVersionAutorDescripcion
2025-12-301.0SistemaCreación del documento de patrón arquitectural de consolidación multi-schema. Extracción de conceptos generales desde documentación de módulo de contabilidad.
2025-12-311.1SistemaAgregada sección de Implementación describiendo utilidades reutilizables para consolidación multi-schema.
2025-12-311.2SistemaPrimera implementación de referencia del patrón: Balance de Comprobación en módulo de Contabilidad. Consolidación de todas las sucursales disponibles sin restricción por ubicación del usuario. Estado actualizado a "En Uso".