Guía de Referencia: Gestión de Automatismos y Consistencia en Entrada de Datos (APIs y Sistemas Interactivos)

1. Introducción y Problemática General

El modelo tradicional de entrada de datos basado en triggers individuales por campo (eventos on-change) presenta fallos críticos cuando el sistema se automatiza mediante APIs o procesos por lotes.

El conflicto principal:

• Dependencia del Orden: En un sistema de triggers, el resultado final varía según el orden en que se asignen los campos (ej: asignar primero la Cuenta y luego la Dirección, o viceversa).
• Efecto Cascada Incontrolado: Un cambio automático puede sobrescribir una intención explícita del usuario que fue enviada en el mismo paquete de datos.
• Dependencias Circulares: Campos que se calculan entre sí (ej: Unidades de Producto vs. Unidades de Embalaje) generan bucles infinitos o resultados impredecibles si no hay un "ancla" de decisión.

---

2. La Solución: Arquitectura de Resolución por Estratos

En lugar de reaccionar a cada campo, el sistema debe tratar la entrada de datos como un contrato de estado final. La solución consiste en procesar los datos en capas jerárquicas (estratos) donde cada capa solo puede leer de la anterior.

Los 5 Estratos de Procesamiento:

1. Estrato 0 (Captura de Intención): Se recibe el JSON y se marcan todos los campos presentes como "Valores Explícitos" (Anclas). Estos valores son inmutables durante el proceso de cálculo automático.
2. Estrato 1 (Resolución de Identidad): Se validan y cargan las claves primarias (IDs de clientes, productos, etc.).
3. Estrato 2 (Enriquecimiento de Maestros): Se rellenan los campos vacíos (null) consultando las fichas maestras (ej: traer la moneda de la ficha del cliente). Regla de Oro: Si el campo ya venía en el Estrato 0, el maestro NO lo sobrescribe.
4. Estrato 3 (Cálculos Derivados Simples): Se calculan datos que dependen de los estratos anteriores (ej: Tipo de Cambio basado en Fecha y Moneda).
5. Estrato 4 (Cálculos de Totales y Validación de Coherencia): Se calculan impuestos, totales y se verifica que los datos calculados coincidan con los explícitos (si el usuario envió ambos).

---

3. Lógica de "Anclaje" para Dependencias Circulares

Para resolver casos donde los campos se calculan entre sí (como UnidadesProducto y UnidadesEmbalaje), se aplica la Matriz de Intencionalidad:

1. Identificar el Ancla: El sistema detecta qué campo envió el usuario en el JSON.
   • Si envió UnidadesProducto El sistema calcula UnidadesEmbalaje.
   • Si envió UnidadesEmbalaje El sistema calcula UnidadesProducto.
2. Desempate por Defecto: Si el usuario no envía ninguno, el sistema debe tener una regla de negocio predefinida (ej: "Siempre manda la unidad de producto y se asume 1").
3. Validación de Conflicto: Si el usuario envía ambos y no cuadran con el factor de conversión, el sistema no debe intentar arreglarlo; debe devolver un error de validación (400 Bad Request).

---

4. Implementación Técnica en Sistemas de Triggers Existentes

Si el sistema ya está construido sobre triggers, no es necesario reescribirlo, sino "orquestarlo" mediante el patrón de Hidratación Muda:

Paso a paso del flujo:

1. Desactivación de Eventos: Al recibir la petición de la API, se desactivan temporalmente todos los triggers del objeto de datos.
2. Carga del JSON: Se vuelcan los datos al objeto. Se guarda internamente una lista de qué campos fueron informados (el "mapa de intención").
3. Ejecución del Orquestador: Se llama a una función centralizada que ejecuta los estratos en orden (1 -> 2 -> 3 -> 4), disparando manualmente solo los cálculos necesarios para los campos que quedaron vacíos.
4. Estabilización y Reactivación: Una vez el objeto es coherente, se vuelven a activar los triggers para permitir que el usuario humano (si el sistema es híbrido) siga trabajando de forma interactiva.

---

5. Resumen de Reglas de Oro para el Diseño de APIs

• Determinismo: A igual entrada, siempre igual salida. El orden de los campos en el JSON no debe importar.
• Prioridad del Dato Explícito: Lo que el usuario escribe es "Ley". El automatismo solo actúa en el "Espacio en Blanco".
• Fallo Temprano: Ante incoherencias matemáticas entre datos enviados (ej: precio unitario x cantidad != total enviado), informar del error en lugar de recalcular.
• Inmutabilidad por Capas: Ningún proceso de un estrato puede modificar datos de un estrato superior o depender de datos de su mismo nivel.

---

Ejemplo de Matriz de Decisión para Unidades:

Entrada API	Acción del Orquestador
Producto	Cargar Embalaje Maestro -> UnidadesProducto=1 -> Calcular UnidadesEmbalaje
Producto + Up	Cargar Embalaje Maestro -> Usar UnidadesProducto -> Calcular UnidadesEmbalaje
Producto + Ue	Cargar Embalaje Maestro -> Usar UnidadesEmbalaje -> Calcular UnidadesProducto
Producto + Ue + Up	Validar Coherencia. Si UnidadesProducto / UnidadesEmbalaje == Factor, OK. Si no, ERROR.

---

Este documento sirve como base para la transición de un sistema de gestión reactivo a uno basado en estados consistentes.