Documentación del Sistema

Appearance

Sistema de Búsqueda Multi-Schema para Operaciones Transaccionales ​

Tipo: Arquitectural Alcance: Todos los módulos con tablas transaccionales configurables Estado: Planificado Fecha: 2025-12-29

Descripción General ​

Este documento describe el sistema arquitectural de búsqueda multi-schema para operaciones transaccionales (consulta, eliminación, modificación) en tablas configurables. Es una solución transversal aplicable a cualquier módulo que tenga tablas con configuración de niveles de schema.

Problema Arquitectural ​

El sistema Bautista utiliza una arquitectura multi-schema 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, suc0001caja0002, etc.) - Datos por caja

Configuración Dinámica de Niveles:

Las tablas pueden residir en diferentes niveles de schema según la configuración de cada empresa, definida en el campo configuracion_niveles_tablas de la tabla sistema:

json
{
  "movimi": [2, 3],      // Tabla en niveles Sucursal y Caja
  "caja": [3],           // Tabla solo en nivel Caja
  "iteban": [1, 2],      // Tabla en niveles Empresa y Sucursal
  "ordcon": [1]          // Tabla solo en nivel Empresa
}

Si no hay configuración personalizada, se usan los niveles por defecto definidos en las migraciones de la tabla.

El Problema de Búsqueda ​

El mecanismo de búsqueda de tablas en la base de datos solo funciona hacia arriba en la jerarquía (de nivel inferior a superior):

✅ Búsquedas que funcionan (nivel inferior → superior):

  • Desde Caja puede buscar en Sucursal → OK
  • Desde Sucursal puede buscar en Empresa → OK

❌ Búsquedas que NO funcionan (nivel superior → inferior o entre adyacentes):

  • Desde Empresa NO puede buscar en Sucursal o Caja → ERROR
  • Desde Sucursal NO puede buscar en Caja → ERROR
  • Desde Caja0001 NO puede buscar en Caja0002 (adyacentes) → ERROR

Impacto en Operaciones Transaccionales ​

Este problema afecta todas las operaciones sobre registros distribuidos en múltiples schemas:

1. Consultas/Reimpresiones ​

Escenario:

  • Usuario opera desde: suc0001caja0002
  • Orden de pago registrada en: suc0001caja0001

Problema:

  • El sistema busca solo en caja0002
  • NO busca en caja0001 (schema adyacente)
  • NO encuentra la orden
  • Resultado: "Orden de pago no encontrada" ❌

2. Eliminaciones en Cascada ​

Escenario:

  • Comprobante registrado en: suc0001 (nivel sucursal)
  • Movimientos registrados en: suc0001caja0001 (nivel caja)

Problema:

  • El sistema busca movimientos solo en suc0001
  • NO busca en suc0001caja0001 (nivel inferior)
  • Solo elimina el comprobante
  • Resultado: Movimientos quedan huérfanos ❌

3. Modificaciones ​

Escenario:

  • Usuario opera desde: suc0001caja0002
  • Movimiento a corregir en: suc0001caja0001

Problema:

  • El sistema busca solo en caja0002
  • NO encuentra el movimiento en caja0001
  • Resultado: "Movimiento no encontrado" ❌

Consecuencias Operativas ​

  • Operaciones fallidas: Usuarios no pueden consultar/modificar/eliminar registros de otras cajas
  • Datos inconsistentes: Eliminaciones parciales generan registros huérfanos
  • Reportes incompletos: Solo se ven datos del schema actual
  • Complejidad operativa: Usuarios deben recordar en qué caja se registró cada operación
  • Pérdida de productividad: Operaciones simples requieren intervención técnica

Solución Arquitectural ​

Sistema de Búsqueda Multi-Schema Inteligente ​

Implementar un mecanismo que soporte todas las operaciones transaccionales (consulta, eliminación, modificación) en múltiples schemas:

  1. Detecta configuración de niveles: Consulta dónde puede estar la tabla según configuración empresarial
  2. Genera lista de schemas relevantes: Basándose en la sucursal del usuario y los niveles configurados
  3. Optimiza búsquedas: Solo activa multi-schema cuando la configuración indica múltiples niveles
  4. Ejecuta operaciones exhaustivas: Busca/modifica/elimina registros en todos los schemas correspondientes
  5. Mantiene consistencia de schema: Los recursos relacionados se consultan del mismo schema
  6. Garantiza atomicidad: Transacciones que incluyen todas las operaciones o revierten todo

Operaciones Soportadas ​

1. Consulta/Lectura (Prioritaria) ​

Casos de uso:

  • Reimprimir comprobantes de cualquier caja de la sucursal
  • Listar movimientos de todas las cajas
  • Consultar estado de registros en múltiples schemas
  • Generar reportes consolidados

Comportamiento:

  • El sistema busca en todos los schemas configurados para la tabla
  • Consolida los resultados de todos los schemas
  • Incluye información de origen (en qué caja/schema se encontró cada registro)
  • Retorna resultados completos al usuario

2. Eliminación en Cascada (Prioritaria) ​

Casos de uso:

  • Eliminar comprobantes con movimientos en múltiples schemas
  • Eliminar registros padre con hijos distribuidos
  • Limpieza de datos relacionados

Comportamiento:

  • El sistema busca registros a eliminar en todos los schemas configurados
  • Ejecuta eliminaciones en todos los schemas encontrados
  • Garantiza atomicidad: todas las eliminaciones exitosas o ninguna
  • Si falla en algún schema, revierte todas las eliminaciones

3. Modificación (Futuro) ​

Casos de uso:

  • Corregir movimientos registrados en otra caja
  • Actualizar datos de registros en cualquier schema
  • Modificaciones masivas por criterio

Comportamiento:

  • El sistema busca el registro en todos los schemas configurados
  • Identifica el schema donde reside el registro
  • Ejecuta la modificación en ese schema específico
  • Mantiene consistencia consultando recursos relacionados del mismo schema

Componentes del Sistema ​

1. Sistema de Migraciones Configurables (Existente) ​

Permite definir en qué niveles de schema se crea cada tabla mediante configuración dinámica por empresa.

2. Configuración de Niveles (Existente) ​

Campo configuracion_niveles_tablas en tabla sistema que almacena la configuración de niveles por tabla.

Gestión via comando de consola:

  • Ver configuración actual de una empresa
  • Configurar niveles personalizados para una tabla
  • Remover configuración personalizada (usar defaults)

3. Servicio de Búsqueda Multi-Schema (Nuevo) ​

Servicio que implementa operaciones multi-schema:

Responsabilidades:

  • Leer configuración de niveles de tabla
  • Determinar schemas relevantes según sucursal del usuario
  • Ejecutar consultas/eliminaciones/modificaciones en múltiples schemas
  • Consolidar resultados
  • Mantener consistencia de schema en recursos relacionados

Reglas de Arquitectura ​

RA-001: Activación basada en configuración de niveles ​

Descripción: La búsqueda multi-schema se activa automáticamente cuando la configuración de niveles de la tabla indica que puede residir en múltiples schemas.

Aplicable a: Todas las operaciones (consulta, eliminación, modificación)

Comportamiento:

  • Si tabla configurada con múltiples niveles → buscar en todos los schemas correspondientes
  • Si tabla configurada con un solo nivel → buscar solo en schema actual
  • Si no hay configuración personalizada → usar niveles por defecto de la tabla

Ejemplo:

Tabla: movimi
Configuración: [2, 3] (Sucursal y Caja)
Usuario en: suc0001caja0001
→ Buscar en: suc0001, suc0001caja0001, suc0001caja0002, etc.

Tabla: ordcon
Configuración: [1] (solo Empresa)
Usuario en: suc0001caja0001
→ Buscar en: public solamente

RA-002: Alcance limitado por sucursal ​

Descripción: La búsqueda multi-schema incluye únicamente los schemas de la sucursal actual del usuario, nunca schemas de otras sucursales.

Aplicable a: Todas las operaciones

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

Ejemplo:

Usuario en: suc0001caja0001
Niveles de tabla: [2, 3]
→ Incluye: suc0001, suc0001caja0001, suc0001caja0002
→ Excluye: suc0002, suc0003, suc0002caja0001, etc.

RA-003: Consistencia de schema en recursos relacionados ​

Descripción: Cuando se encuentra un registro en un schema específico mediante búsqueda multi-schema, todos los recursos relacionados deben consultarse en el mismo schema donde se encontró el registro.

Aplicable a: Principalmente consulta y eliminación

Fundamento: Garantizar consistencia de datos al mantener las relaciones entre recursos en su contexto original de schema.

Ejemplo:

Usuario actual en: suc0001caja0001
Movimiento encontrado en: suc0001caja0002

Al consultar la caja del movimiento:
  ✅ Correcto: Consultar caja en suc0001caja0002
  ❌ Incorrecto: Consultar caja en suc0001caja0001 (schema del usuario)

RA-004: Transaccionalidad atómica ​

Descripción: Las operaciones que afectan múltiples schemas (eliminación, modificación) deben ejecutarse en una transacción atómica: todas exitosas o ninguna.

Aplicable a: Eliminación y modificación (no aplica a consulta)

Comportamiento:

  • Iniciar transacción antes de ejecutar operaciones
  • Ejecutar operaciones en cada schema
  • Si alguna falla → revertir todos los cambios
  • Si todas exitosas → confirmar transacción

Fundamento: Evitar estados parciales e inconsistentes.

RA-005: Extensibilidad por módulo ​

Descripción: El sistema debe ser extensible a cualquier tabla transaccional de cualquier módulo que tenga configuración de niveles.

Requisitos para nueva tabla:

  1. Definir niveles por defecto en la migración de la tabla
  2. Opcionalmente configurar niveles personalizados en configuracion_niveles_tablas
  3. El servicio del módulo implementa el patrón de búsqueda multi-schema
  4. No requiere cambios en infraestructura base

Módulos aplicables:

  • ✅ Tesorería: movimi, caja (implementación inicial)
  • ⏭️ Tesorería: iteban (extensión futura)
  • ⏭️ Ventas: Tablas transaccionales con niveles
  • ⏭️ Compras: Tablas transaccionales con niveles
  • ⏭️ Stock: Tablas transaccionales con niveles
  • ⏭️ Otros módulos: Según necesidad

Consideraciones Técnicas ​

Rendimiento ​

Optimización por configuración:

  • Si tabla configurada con un solo nivel → operación simple (rápida)
  • Si tabla configurada con múltiples niveles → operación multi-schema (más lenta pero correcta)

Caché de configuración:

  • La configuración de niveles se mantiene en memoria
  • Solo se reconsulta cuando se detectan cambios

Volumenes esperados:

  • Sucursal típica: 2-5 cajas
  • Operaciones en 2-5 schemas es aceptable
  • Prioridad: correctitud > velocidad

Impacto por operación:

  • Consulta: Ligeramente más lenta (búsqueda en N schemas)
  • Eliminación: Más lenta (transacción en N schemas)
  • Modificación: Similar (búsqueda + actualización en 1 schema)

Seguridad ​

Control de acceso:

  • Solo schemas de la sucursal del usuario
  • Validar permisos antes de ejecutar operaciones
  • Auditar todos los schemas accedidos

Integridad transaccional:

  • Transacciones atómicas (todo o nada)
  • No permitir estados parciales
  • Reversión completa en caso de error

Auditoría ​

Información a registrar:

OperaciónInformación Adicional
ConsultaSchemas consultados, resultados encontrados por schema
EliminaciónSchemas afectados, registros eliminados por schema
ModificaciónSchema donde se modificó, datos anteriores y nuevos

Criterios de Aceptación Generales ​

Configuración ​

  • [ ] AC-001: El sistema consulta correctamente la configuración de niveles para determinar dónde puede estar la tabla
  • [ ] AC-002: Si no hay configuración personalizada, usa niveles por defecto de la tabla
  • [ ] AC-003: Cuando la configuración indica un solo nivel, usa operaciones en schema actual (sin multi-schema)

Consulta/Lectura ​

  • [ ] AC-004: Los usuarios pueden consultar registros creados en cualquier caja/schema de la sucursal
  • [ ] AC-005: Los resultados incluyen información del schema de origen
  • [ ] AC-006: Los listados muestran registros de todos los schemas configurados

Eliminación ​

  • [ ] AC-007: Al eliminar un registro padre, elimina todos los registros hijos de todos los schemas posibles según configuración
  • [ ] AC-008: No quedan registros huérfanos después de eliminar un registro padre
  • [ ] AC-009: Las eliminaciones multi-schema son atómicas (todas o ninguna)

Modificación (Futuro) ​

  • [ ] AC-010: Los usuarios pueden modificar registros ubicados en cualquier schema de la sucursal
  • [ ] AC-011: La modificación se ejecuta en el schema correcto donde reside el registro

Consistencia ​

  • [ ] AC-012: Cuando se consulta un registro en un schema específico, los recursos relacionados se consultan en el mismo schema

Auditoría ​

  • [ ] AC-013: Las operaciones multi-schema registran todos los schemas donde se ejecutó cada acción

Seguridad ​

  • [ ] AC-014: Un usuario de una sucursal no puede acceder a datos de otra sucursal
  • [ ] AC-015: Los intentos de acceso no autorizado se registran en auditoría

Extensibilidad ​

  • [ ] AC-016: El sistema permite agregar nuevas tablas transaccionales sin cambios estructurales en la lógica multi-schema

Implementaciones por Módulo ​

Este documento sirve como índice y referencia arquitectural. Cada módulo que implemente este sistema debe tener su propio documento de implementación:

Implementaciones Actuales ​

Implementaciones Futuras ​

  • Tesorería - Movimientos Bancarios

    • Tabla: iteban
    • Estado: Pendiente

  • Ventas - Comprobantes y Movimientos

    • Tablas: Por definir
    • Estado: Pendiente

  • Stock - Movimientos de Inventario

    • Tablas: Por definir
    • Estado: Pendiente

Cada implementación debe referenciar este documento y especificar:

  • Tablas específicas del módulo
  • Operaciones soportadas (consulta/eliminación/modificación)
  • Casos de uso del dominio
  • Reglas de negocio específicas
  • Validaciones particulares del módulo

Preguntas Frecuentes ​

1. ¿Esto afecta las consultas normales de lectura? ​

Sí, de manera positiva. Las consultas ahora pueden encontrar registros en cualquier schema de la sucursal, no solo en el schema actual. Esto es especialmente útil para reimpresiones y listados.

2. ¿Qué pasa si cambio la configuración de niveles con datos existentes? ​

Los datos permanecen en los schemas donde fueron creados. Solo cambia:

  • Dónde se crean NUEVOS datos
  • Dónde se busca para todas las operaciones

Cuidado: Reducir niveles podría dejar datos inaccesibles.

3. ¿Se puede desactivar para una tabla específica? ​

Sí, configurando la tabla con un solo nivel. El sistema detecta esto automáticamente y usa operaciones simples.

4. ¿Afecta el rendimiento? ​

Mínimamente. La verificación de configuración es rápida. Solo cuando hay múltiples niveles configurados se ejecutan operaciones multi-schema, que son ligeramente más lentas pero necesarias para correctitud.

5. ¿Cómo se mantiene la consistencia entre recursos relacionados? ​

Los recursos relacionados (ej: caja y movimiento) siempre se consultan del mismo schema. El schema de origen se preserva durante toda la operación.

6. ¿Las modificaciones también funcionan en múltiples schemas? ​

Sí, pero de manera diferente:

  • Búsqueda: Se busca en todos los schemas
  • Modificación: Se ejecuta solo en el schema donde se encontró el registro
  • Esto mantiene la consistencia de datos

Referencias ​

Documentación Técnica ​

  • Sistema de Migraciones: Gestión de niveles de tablas
  • Configuración de Niveles: Comando de gestión de niveles por empresa

Documentación de Negocio ​

  • Implementación Tesorería: Aplicación específica a movimi y caja

Historial de Cambios ​

FechaVersiónAutorDescripción
2025-12-291.2SistemaEliminación de tecnicismos de código. Documento enfocado en requisitos de negocio sin ejemplos de código PHP/SQL.
2025-12-291.1SistemaCorrección de enfoque: el sistema no es solo para eliminación, sino para TODAS las operaciones transaccionales (consulta, eliminación, modificación).
2025-12-291.0SistemaCreación del documento arquitectural.