Ajuste de Configuración Inicial de Niveles (Tablas Vacías)

Módulo: Core Tipo: Process Estado: Planificado Fecha: 2026-01-22

Alcance: Este proceso aplica EXCLUSIVAMENTE a tablas vacías durante la configuración inicial del sistema. No migra datos existentes.

---

Descripción

Problema de Negocio

Durante la instalación y configuración inicial del sistema, puede ocurrir que el cliente defina una configuración de nivel para ciertas tablas (por ejemplo, nivel sucursal) pero luego, antes de comenzar a usar el sistema con datos reales, decida cambiar esa configuración a nivel compartido (nivel 1).

Escenario típico:

1. Se instala el sistema para un nuevo cliente
2. El cliente solicita que la tabla "clientes" sea nivel 2 (por sucursal)
3. Se crea la estructura: suc0001.clientes, suc0002.clientes, etc. (todas vacías)
4. Antes de cargar datos, el cliente cambia de opinión: quiere todos los clientes unificados
5. Se necesita reconfigurar a nivel 1: la tabla debe estar en public.clientes

Actualmente no existe un mecanismo automatizado para este ajuste de configuración inicial.

Valor de Negocio

• Flexibilidad en configuración inicial: Permite ajustar la configuración antes del primer uso sin intervención técnica compleja
• Prevención de errores: Evita que se carguen datos en una estructura incorrecta
• Rapidez de implementación: El cliente puede corregir decisiones de configuración sin esperar soporte técnico
• Sincronización de estructura: Asegura que la tabla en public tenga todas las migraciones aplicadas correctamente

Contexto Actual

Existe el proceso de migración directa (AASchemaDataMigration) que mueve estructura desde public hacia esquemas de sucursales. Este requerimiento aborda el proceso inverso simple: ajustar la configuración cuando las tablas aún están vacías, típico de la fase de configuración inicial antes del primer uso del sistema.

---

Frontend (Perspectiva de Usuario)

Vistas

• Panel de administración de configuración de niveles: Vista donde el administrador puede ver y modificar la configuración de nivel de cada tabla del sistema

Interacciones del Usuario

1. Consultar configuración actual: El administrador puede ver qué nivel tiene configurado cada tabla del sistema
2. Cambiar nivel de tabla: El administrador modifica el nivel de una tabla de sucursal (2 o 3) a compartido (1)
3. Confirmar ajuste de configuración: El sistema valida que las tablas estén vacías y solicita confirmación
4. Ver resultado: El sistema muestra confirmación de ajuste exitoso

Permisos

Permiso	Descripcion	Acciones permitidas
Visualizar configuracion de niveles	Ver la configuracion actual de niveles de tablas	Consultar configuracion
Modificar configuracion de niveles	Cambiar el nivel de almacenamiento de tablas	Modificar niveles durante fase de configuracion inicial

Estados de UI

• Estado inicial: Muestra configuración actual de niveles de tablas
• Estado de validación: Verifica que las tablas estén vacías antes de permitir el cambio
• Estado de confirmación: Solicita confirmación indicando que se ajustará la estructura
• Estado de éxito: Confirma que la configuración fue ajustada correctamente
• Estado de error: Muestra error si las tablas tienen datos (no se permite el ajuste)

---

Backend (Perspectiva de Datos de Negocio)

Entidades de Negocio

Configuracion de Nivel de Tabla

Representa la configuracion de nivel de almacenamiento de cada tabla del sistema.

Registro de Ajuste de Configuracion

Representa una operacion de ajuste de configuracion inicial ejecutada (auditoría simple).

Datos Necesarios

Configuracion de Nivel de Tabla

• Nombre de la entidad de negocio (ej: clientes, proveedores, etc.)
• Nivel actual configurado (1: compartido, 2: sucursal, 3: caja)
• Niveles permitidos para esta entidad
• Fecha de ultima modificacion de la configuracion

Registro de Ajuste de Configuracion

• Identificador unico del ajuste
• Entidad de negocio afectada
• Nivel origen (sucursal o caja)
• Nivel destino (compartido)
• Fecha y hora del ajuste
• Usuario que realizó el ajuste
• Resultado (exitoso, fallido)

Relaciones de Negocio

• Cada entidad de negocio tiene una unica configuracion de nivel activa
• Un registro de ajuste pertenece a un usuario administrador que lo realizó
• La configuracion de nivel tiene historial de cambios para auditoria

Validaciones de Negocio

1. Validacion de nivel actual: Solo se puede ejecutar ajuste si la tabla esta actualmente en nivel sucursal (2) o caja (3)
2. Validacion de tablas vacías: CRÍTICO - Verificar que TODAS las instancias de la tabla (en todos los esquemas de sucursales) estén completamente vacías (0 registros)
3. Validacion de estructura: Confirmar que la estructura en esquemas de sucursales tiene migraciones aplicadas que public necesita sincronizar
4. Validacion de permisos: Confirmar que el usuario tiene permisos de administración de configuración

---

Reglas de Negocio

RN-001: Detección Automática de Cambio de Configuración en Fase Inicial

Descripcion: El sistema debe detectar cuando se modifica la configuración de nivel de una tabla de nivel sucursal/caja a nivel compartido durante la configuración inicial.

Condicion: El administrador guarda un cambio de configuración de nivel de cualquier tabla.

Accion:

• Si el nivel anterior era 2 o 3 y el nuevo nivel es 1, el sistema debe verificar si las tablas están vacías
• Si las tablas están vacías, activar el proceso de ajuste de configuración
• Si alguna tabla tiene datos, RECHAZAR el cambio e informar que no es posible (requiere proceso de migración con datos)

RN-002: Validación de Tablas Vacías (Crítica)

Descripcion: El proceso SOLO puede ejecutarse si todas las instancias de la tabla en todos los esquemas de sucursales están completamente vacías.

Condicion: Se intenta cambiar una tabla de nivel sucursal a nivel compartido.

Accion:

• Consultar todas las sucursales activas de la empresa
• Para cada sucursal, verificar si existe la tabla
• Contar registros en cada instancia de la tabla
• Si cualquier instancia tiene aunque sea 1 registro, RECHAZAR el cambio
• Solo proceder si TODAS las instancias tienen 0 registros

RN-003: Sincronización de Estructura de Datos

Descripcion: Al ajustar la configuración, el sistema debe asegurar que la tabla en public tenga la estructura correcta con todas las migraciones aplicadas.

Condicion: Se va a cambiar la configuración de nivel.

Accion:

• Identificar qué migraciones de Phinx se aplicaron a los esquemas de sucursales para esa tabla
• Verificar qué migraciones faltan en public para esa tabla
• Aplicar las migraciones faltantes a public (si la tabla no existe, crearla; si existe, actualizarla)
• No duplicar migraciones que ya existen en public
• Asegurar que public.{tabla} quede con la estructura más actualizada

RN-004: Limpieza de Esquemas de Sucursales

Descripcion: Después de ajustar la configuración, las tablas vacías en los esquemas de sucursales ya no son necesarias.

Condicion: Se completó exitosamente el ajuste de configuración a nivel 1.

Accion:

• Eliminar la tabla de todos los esquemas de sucursales (opcional, por limpieza)
• O mantenerlas vacías para futuras reconfiguraciones (a decidir según conveniencia)

RN-005: Auditoría Simple

Descripcion: Todas las operaciones de ajuste de configuración deben quedar registradas para auditoría.

Condicion: Se ejecuta cualquier acción relacionada con el ajuste de configuración.

Accion:

• Registrar el cambio de configuración con usuario, fecha, entidad, nivel origen y nivel destino
• Registrar si fue exitoso o fallido
• Si falló, registrar el motivo (ej: "tablas con datos", "error al aplicar migraciones", etc.)

---

Casos de Uso

Caso 1: Ajuste Exitoso de Configuración Inicial (Tablas Vacías)

Actor: Administrador del sistema

Precondiciones:

• El administrador tiene permisos de administración de configuración
• La entidad "clientes" está configurada en nivel 2 (sucursal)
• Las tablas suc0001.clientes, suc0002.clientes, suc0003.clientes existen pero están completamente vacías (0 registros)
• El sistema fue recién instalado y aún no se cargaron datos de producción
• Se aplicaron migraciones de Phinx a los esquemas de sucursales, pero public.clientes no existe o está desactualizada

Flujo principal:

1. El administrador accede al panel de configuración de niveles
2. El administrador selecciona la entidad "clientes"
3. El administrador cambia el nivel de 2 (sucursal) a 1 (compartido)
4. El sistema verifica automáticamente que todas las instancias de la tabla estén vacías
5. El sistema detecta que suc0001.clientes, suc0002.clientes, suc0003.clientes tienen 0 registros
6. El sistema muestra pantalla de confirmación:
   • "Las tablas están vacías. Se ajustará la configuración."
   • "Se sincronizará la estructura en public.clientes"
   • "Las tablas en esquemas de sucursales se limpiarán"
7. El administrador confirma la operación
8. El sistema identifica las migraciones aplicadas en suc0001.clientes
9. El sistema aplica esas migraciones a public.clientes (crea o actualiza la estructura)
10. El sistema actualiza la configuración de nivel a 1
11. El sistema registra el ajuste en auditoría
12. El sistema muestra confirmación: "Configuración ajustada exitosamente"

Postcondiciones:

• public.clientes existe con estructura correcta y actualizada
• Configuración de nivel actualizada a 1
• Ajuste registrado en auditoría
• Las tablas de sucursales pueden eliminarse o mantenerse vacías (según implementación)

Flujos alternativos:

• Tablas con datos (no permitido):
  1. El administrador intenta cambiar el nivel
  2. El sistema detecta que suc0002.clientes tiene 45 registros
  3. El sistema RECHAZA el cambio
  4. El sistema muestra error: "No se puede ajustar la configuración. La tabla suc0002.clientes tiene 45 registros. Este proceso solo aplica a tablas vacías durante la configuración inicial."
  5. La configuración permanece sin cambios

Caso 2: Ajuste con Estructura Desactualizada en Public

Actor: Administrador del sistema

Precondiciones:

• La entidad "proveedores" está configurada en nivel 2 (sucursal)
• Las tablas en sucursales están vacías: suc0001.proveedores (0 registros), suc0002.proveedores (0 registros)
• Se aplicaron 3 migraciones a los esquemas de sucursales agregando campos
• public.proveedores existe pero le faltan esos 3 campos (estructura desactualizada)

Flujo principal:

1. El administrador accede al panel de configuración de niveles
2. El administrador selecciona la entidad "proveedores"
3. El administrador cambia el nivel de 2 a 1
4. El sistema verifica que todas las instancias estén vacías: ✓
5. El sistema detecta que public.proveedores existe pero está desactualizada
6. El sistema identifica 3 migraciones pendientes de aplicar
7. El sistema muestra confirmación:
   • "Las tablas están vacías"
   • "Se aplicarán 3 actualizaciones de estructura a public.proveedores"
8. El administrador confirma
9. El sistema aplica las 3 migraciones faltantes a public.proveedores
10. El sistema actualiza la configuración de nivel a 1
11. El sistema muestra confirmación exitosa

Postcondiciones:

• public.proveedores tiene la estructura actualizada con todos los campos
• Configuración de nivel actualizada a 1
• Ajuste registrado en auditoría

Flujos alternativos:

• Error al aplicar migraciones:
  1. El sistema intenta aplicar las migraciones a public.proveedores
  2. Una migración falla por conflicto de estructura
  3. El sistema REVIERTE los cambios
  4. El sistema muestra error: "No se pudo aplicar la migración X a public.proveedores: [detalle del error]"
  5. La configuración permanece en nivel 2
  6. El administrador debe contactar soporte técnico

---

Consideraciones

Seguridad

• Solo usuarios con rol de administrador del sistema pueden modificar configuración de niveles
• El proceso debe validar permisos antes de ejecutar

Auditoría

• Registrar cada ajuste de configuración con usuario, fecha, entidad, nivel origen y nivel destino
• Registrar si fue exitoso o fallido y el motivo del fallo
• Los registros de auditoría no deben poder modificarse ni eliminarse

Rendimiento

• El proceso es muy rápido ya que solo ajusta estructura sin mover datos
• No requiere ventanas de mantenimiento
• Solo aplica migraciones de estructura, lo cual es una operación rápida

Volumen Esperado

• Aplica exclusivamente a tablas vacías (0 registros)
• Puede manejar empresas con cualquier cantidad de sucursales ya que solo verifica que estén vacías

---

Dependencias

Funcionalidades Relacionadas

• Configuración de niveles de tablas (ini.sistema): Sistema existente que define el nivel de cada tabla
• Migración directa de esquemas (AASchemaDataMigration): Proceso existente que migra de compartido a sucursales
• Sistema de esquemas por sucursal: Arquitectura multi-tenant que crea esquemas por sucursal
• Sistema de migraciones Phinx: Proceso que aplica cambios de estructura a las tablas

Procesos de Negocio Relacionados

• Instalación y configuración inicial del sistema: Este proceso se ejecuta típicamente durante esta fase
• Alta de sucursales: Determina qué esquemas de sucursales existen y deben verificarse

Servicios Externos

• Ninguno. El proceso es completamente interno al sistema.

---

Criterios de Aceptación

Detección y Validación

• [ ] AC-001: Al cambiar la configuración de nivel de una tabla de nivel 2 o 3 a nivel 1, el sistema verifica automáticamente si todas las instancias de la tabla están vacías
• [ ] AC-002: Si alguna instancia de la tabla tiene registros (> 0), el sistema RECHAZA el cambio y muestra mensaje claro: "No se puede ajustar. La tabla [esquema].[tabla] tiene [N] registros. Este proceso solo aplica a tablas vacías."
• [ ] AC-003: Si todas las instancias están vacías (0 registros), el sistema permite continuar con el ajuste

Sincronización de Estructura

• [ ] AC-004: El sistema identifica qué migraciones de Phinx se aplicaron a los esquemas de sucursales para esa tabla
• [ ] AC-005: El sistema aplica automáticamente las migraciones faltantes a public.[tabla] (crea la tabla si no existe, actualiza si existe)
• [ ] AC-006: El sistema no intenta aplicar migraciones que ya existen en public.[tabla]
• [ ] AC-007: Si ocurre un error al aplicar migraciones, el sistema revierte los cambios y mantiene la configuración en su nivel original

Actualización de Configuración

• [ ] AC-008: Solo después de sincronizar exitosamente la estructura, el sistema actualiza la configuración de nivel a 1
• [ ] AC-009: La configuración queda persistida correctamente y se aplica en futuros accesos

Auditoría

• [ ] AC-010: El sistema registra cada intento de ajuste con: usuario, fecha, entidad, nivel origen, nivel destino, resultado (exitoso/fallido)
• [ ] AC-011: Si el ajuste falla, el registro de auditoría incluye el motivo específico del fallo
• [ ] AC-012: Los registros de auditoría son inmutables (no se pueden editar ni eliminar)

Interfaz de Usuario

• [ ] AC-013: Los mensajes de error son claros e indican la acción a tomar
• [ ] AC-014: El mensaje de confirmación explica claramente que se sincronizará la estructura en public
• [ ] AC-015: El usuario recibe confirmación visual clara cuando el ajuste es exitoso

---

Notas Adicionales

Escenario de Negocio Típico

Instalación inicial y cambio de configuración antes del primer uso:

1. Se instala Sistema Bautista para un nuevo cliente
2. Durante la configuración, el cliente solicita que "clientes" sea nivel 2 (por sucursal)
3. El sistema crea suc0001.clientes, suc0002.clientes, suc0003.clientes (todas vacías)
4. Antes de cargar datos, el cliente dice: "Prefiero que todos los clientes estén unificados"
5. El administrador cambia la configuración de nivel 2 a nivel 1
6. El sistema sincroniza la estructura en public.clientes y ajusta la configuración
7. El cliente puede comenzar a usar el sistema con la configuración correcta

Alcance y Limitaciones

Alcance actual:

• ✅ Ajuste de configuración para tablas completamente vacías (0 registros)
• ✅ Sincronización de estructura de base de datos (migraciones de Phinx)
• ✅ Validación estricta de que no existan datos

Fuera de alcance (para futuras versiones):

• ❌ Migración de tablas con datos existentes
• ❌ Consolidación de registros desde múltiples sucursales
• ❌ Resolución de conflictos de identificadores
• ❌ Trazabilidad de origen de registros
• ❌ Capacidad de reversión compleja

Importante: Si una tabla tiene aunque sea 1 registro, este proceso NO aplica. Se necesitará desarrollar un proceso de migración con datos más adelante.

Preguntas Pendientes de Definición

1. ¿Se deben eliminar las tablas vacías de los esquemas de sucursales después del ajuste, o mantenerlas por si se revierte la configuración?
2. ¿Se debe notificar al administrador por correo cuando se completa el ajuste?

Glosario

• Nivel 1 (Compartido): Datos almacenados en el esquema public, accesibles por todas las sucursales
• Nivel 2 (Sucursal): Datos almacenados en el esquema de cada sucursal (suc0001, suc0002, etc.), segregados entre sucursales
• Nivel 3 (Caja): Datos almacenados en el esquema de cada caja, con máxima segregación
• Migración directa (AASchemaDataMigration): Proceso existente que mueve estructura/datos desde public hacia esquemas de sucursales
• Ajuste de configuración inicial: Este proceso - sincroniza estructura desde sucursales hacia public solo cuando las tablas están vacías
• Esquema: Contenedor lógico de datos en PostgreSQL que permite la segregación multi-tenant
• Tablas vacías: Tablas que existen en la estructura de base de datos pero tienen 0 registros (COUNT(*) = 0)

---

Historial de Cambios

Fecha	Version	Autor	Descripcion
2026-01-22	1.0	Sistema	Creacion del documento de requerimientos de negocio