Valores Dinámicos en Propiedades

En la arquitectura de datos de Axol Systems, las propiedades (properties) cuentan con un campo de configuración de tipo JSONB llamado dynamic_values. Este diccionario permite otorgar comportamientos dinámicos en tiempo de ejecución a los atributos de una entidad sin necesidad de modificar el código fuente de la aplicación cliente ni el esquema físico de PostgreSQL.

Actualmente, las dos llaves dinámicas principales para controlar el comportamiento y la lógica visual de las propiedades son formula y visible.

---

1. Fórmulas y Cálculos Dinámicos (formula)

La llave "formula" permite definir expresiones lógicas, aritméticas y de transformación que el cliente Flutter evalúa dinámicamente sobre los registros en caliente. Se configura dentro del atributo dynamic_values de cualquier propiedad (como numéricas, de texto o virtuales) que requiera cálculo automático al interactuar con la interfaz.

Sintaxis y Capacidades del Motor de Fórmulas

El motor de evaluación de fórmulas de Axol soporta las siguientes características de sintaxis:

A. Referencias a Columnas

Para hacer referencia al valor de otra propiedad dentro del mismo objeto o contexto, se utiliza el código técnico de la columna (ej. t0c1, t0c2) o la sintaxis explícita con llaves {t0c1}.

B. Operadores Aritméticos Base

Admite las operaciones matemáticas estándar con precedencia de operadores y agrupación mediante paréntesis (...):

• Suma (+)
• Resta (-)
• Multiplicación (*)
• División (/)

C. Redondeo y Formateo de Resultados (round y r)

• Redondeo (round): round(expresión, decimales, [dirección])
  • Permite especificar el número de decimales a conservar.
  • Opcionalmente acepta una dirección de redondeo: 'up' (hacia arriba) o 'down' (hacia abajo).
• Unidad de retorno (r): r(unidad); o r(unidad, round(decimales, dirección));
  • Establece la unidad de medida asignada al resultado del cálculo.
  • Ejemplo: r(USD, round(2, up)); t0c1 * t0c2

D. Evaluación Condicional Ternaria (if)

Permite aplicar lógica condicional para retornar distintos valores según se cumpla o no una premisa:

• Sintaxis: if : condición ? valor_si_verdadero : valor_si_falso
• Operadores de comparación: ==, !=, >, >=, <, <=.
• Ejemplo: if : t0c1 > 100 ? t0c1 * 0.9 : t0c1

E. Acceso a Estados Anteriores ({snapshot:...})

Permite consultar el valor que tenía una columna antes de ser modificada en la sesión actual de edición:

• Sintaxis: {snapshot:t0c1}
• Uso común: Cálculo de variaciones netas, deltas de inventario o comparaciones históricas inmediatas.

F. Palabras Clave Especiales

• now: Retorna la fecha y hora actual (DateTime.now()).
• res: Hace referencia al resultado de la sentencia previa en fórmulas compuestas multilínea (separadas por punto y coma ;).

G. Agregaciones Relacionales

Soporta cálculos agregados sobre listas de objetos vinculados (como SumObjList y Subtract).

Ejemplos de Configuración JSON para formula

Ejemplo 1: Cálculo con Descuento Condicional y Redondeo

{
  "formula": "if : t0c3 > 0 ? round(t0c1 * t0c2, 2) : 0"
}

Ejemplo 2: Cálculo con Formateo de Unidad y Lectura de Snapshot

{
  "formula": "r(USD, round(2)); t0c1 - {snapshot:t0c1}"
}

---

2. Visibilidad Dinámica por Expresión (visible)

La llave "visible" dentro del objeto dynamic_values controla si una propiedad debe ser renderizada o permanecer oculta en la interfaz de usuario en tiempo real, evaluando dinámicamente los datos del registro actual.

Formatos Aceptados

1. Booleano Directo

• "visible": true: La propiedad es siempre visible en la interfaz.
• "visible": false: La propiedad se mantiene oculta.
• Nota: Si la llave "visible" se omite en dynamic_values, el sistema asume true por defecto.

2. Expresión Condicional Dinámica (String)

Permite definir una condición lógica mediante una cadena de texto que el motor de evaluación (MathService) ejecuta dinámicamente:

• Si la expresión evalúa a true, la columna o campo del formulario se muestra.
• Si evalúa a false, el campo se oculta automáticamente de la pantalla sin alterar los datos del objeto.

Ejemplos de Expresiones para visible

Ejemplo A: Visibilidad basada en umbral numérico

Muestra la propiedad únicamente cuando la columna de cantidad (t0c1) sea mayor a 0:

{
  "visible": "t0c1 > 0"
}

Ejemplo B: Visibilidad basada en estado de catálogo

Muestra el campo de motivo de cancelación solo cuando el estado (t0c2) sea igual a 'RECHAZADO':

{
  "visible": "t0c2 == 'RECHAZADO'"
}

Ejemplo C: Condicional ternario explícito

{
  "visible": "if : t0c3 != '' ? true : false"
}

---

3. Cuadro Comparativo: visible vs visible_in vs virtual

Para garantizar un modelado correcto de metadatos, es importante diferenciar las tres llaves relacionadas con visibilidad y persistencia en dynamic_values:

Atributo	Tipo de Control	Naturaleza	Ejemplo de Configuración
visible	Lógica de negocio sobre datos	Dinámico (se evalúa en caliente ante cambios en los campos)	"visible": "t0c1 > 100"
visible_in	Pantalla o Contexto UI	Estático (filtra según el modo: creación, edición, etc.)	"visible_in": ["form_create", "form_edit"]
virtual	Persistencia en Base de Datos	Estructural (define si el campo existe en la tabla física de PostgreSQL)	"virtual": { "is": true }