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 Última actualización: 2026-01-30 (Correcciones basadas en implementación real)

Conceptual Foundation:

Este documento describe el patrón específico de consolidación en informes.

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:

  • Búsqueda global: Consulta information_schema.tables para obtener TODOS los schemas que contienen la tabla requerida
  • Sin filtrado por sucursal: Incluye schemas de todas las sucursales disponibles
  • Sin filtrado por nivel: Incluye tanto schemas de tipo SUCURSAL como CAJA
  • Control de acceso: Los permisos se validan a nivel de permiso de módulo para informes consolidados

Implementación técnica:

php
// Ejemplo: Balance de Comprobación
$schemaService = new SchemaService($conn);
$schemasObjetivo = $schemaService->getSchemasWithTable('items');
// Devuelve: ['suc0001', 'suc0001caja0001', 'suc0002', 'suc0002caja0001', ...]

Ejemplo:

Usuario en: suc0001caja0001
Tabla items disponible en:
  - suc0001 (nivel SUCURSAL)
  - suc0001caja0001 (nivel CAJA)
  - suc0002 (nivel SUCURSAL)
  - suc0002caja0001 (nivel CAJA)

Schemas a consultar: TODOS los anteriores
Schemas excluidos: Ninguno (excepto 'public' si no tiene la tabla)

Nota importante: Este enfoque simplificado es adecuado para la implementación inicial. La documentación en RA-002 menciona que configuracion_niveles_tablas podría utilizarse en versiones futuras para mayor control granular.

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: Búsqueda multi-schema simplificada ​

Descripción: El sistema busca TODOS los schemas disponibles que contienen la tabla requerida mediante consulta directa a information_schema.tables.

Implementación actual:

  • NO consulta configuracion_niveles_tablas
  • Devuelve todos los schemas donde existe la tabla (SUCURSAL, CAJA, cualquier nivel)
  • Sin filtrado por configuración de niveles

Fundamento: Simplificación del patrón de consolidación para la implementación inicial del Balance de Comprobación.

Consideración futura: La consulta de configuracion_niveles_tablas podría implementarse en versiones futuras para mayor control granular.

RA-003: Consolidación global sin restricción por sucursal ​

Descripción: La consolidación incluye TODAS las sucursales disponibles en la organización, independientemente de la ubicación actual del usuario.

Implementación actual:

  • Consolida todos los schemas donde existe la tabla requerida
  • NO filtra por sucursal del usuario
  • Incluye tanto schemas de tipo SUCURSAL como CAJA de todas las sucursales

Fundamento:

  • Proporcionar visión empresarial completa
  • Simplificar implementación inicial
  • Basado en premisa que usuarios con permiso de informes consolidados requieren visión global

Ejemplo:

Usuario en: suc0001caja0001
Con consolidación activa:
  ✅ Consolida: suc0001, suc0001caja0001, suc0002, suc0002caja0001, suc0003, etc.
  ✅ Incluye TODAS las sucursales y cajas de la organización

Nota de seguridad: Los permisos del usuario para acceder a informes consolidados deben evaluarse a nivel de permiso de módulo (CONTABILIDAD_INF_CONSOLIDADOS), no a nivel de sucursal individual.

Consideración futura: Podría implementarse filtrado por sucursal en fase 2 para permitir consolidaciones parciales.

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

RA-007: Mezcla de niveles de schema sin jerarquía ​

Descripción: La consolidación permite mezclar datos de diferentes niveles de schema (SUCURSAL y CAJA) sin validación de compatibilidad ni jerarquía.

Comportamiento:

  • Una misma consolidación puede incluir:
    • Schemas de nivel SUCURSAL: suc0001, suc0002
    • Schemas de nivel CAJA: suc0001caja0001, suc0002caja0001
  • Algunas sucursales pueden tener datos en nivel SUCURSAL, otras en nivel CAJA
  • Algunas sucursales pueden tener cajas configuradas, otras no
  • Todos los datos se consolidan por igual sin jerarquía

Ejemplo de mezcla:

Organización con configuración mixta:

suc0001 (datos en nivel SUCURSAL)
  ├─ suc0001caja0001 (datos en nivel CAJA)
  └─ suc0001caja0002 (datos en nivel CAJA)

suc0002 (datos en nivel SUCURSAL)
  └─ (sin cajas configuradas)

suc0003 (sin datos en nivel SUCURSAL)
  ├─ suc0003caja0001 (datos en nivel CAJA)
  └─ suc0003caja0002 (datos en nivel CAJA)

Consolidación incluye:
  ✅ suc0001 (nivel SUCURSAL)
  ✅ suc0001caja0001 (nivel CAJA)
  ✅ suc0001caja0002 (nivel CAJA)
  ✅ suc0002 (nivel SUCURSAL)
  ✅ suc0003caja0001 (nivel CAJA)
  ✅ suc0003caja0002 (nivel CAJA)

Implicaciones:

  • Agregación simple: Los valores se suman directamente sin considerar jerarquías
  • Sin validación de duplicación: No se verifica si suc0001 y suc0001caja0001 tienen datos duplicados
  • Responsabilidad de configuración: Es responsabilidad de la organización configurar correctamente qué nivel usa cada sucursal

Advertencia: Si una organización tiene datos tanto en nivel SUCURSAL como en nivel CAJA para la misma entidad, puede haber duplicación en los totales consolidados. La configuración correcta mediante configuracion_niveles_tablas (a nivel de empresa) es fundamental para evitar este problema.

Consideración futura: Podría implementarse validación de jerarquías para detectar y alertar sobre posibles duplicaciones.

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".
2026-01-301.3SistemaCorrección de reglas arquitecturales para reflejar implementación real: RA-002 actualizada (no consulta configuracion_niveles_tablas), RA-003 reescrita (consolida todas las sucursales sin restricción), sección "Determinación de Schemas Objetivo" actualizada (búsqueda global), agregada RA-007 (mezcla de niveles sin jerarquía). Basado en análisis del código fuente de Balance de Comprobación.