Arquitectura de Datos (Meta-modelo)

La arquitectura de datos de Axol Systems se diseña bajo un paradigma de meta-modelado. Esto significa que la base de datos no solo guarda los registros operativos de tu negocio (como productos o facturas), sino que también guarda las definiciones de lo que son esos registros, cómo se deben ver en la interfaz de usuario, y qué validaciones deben cumplir.

Este enfoque permite adaptar la aplicación cliente (Flutter) a nuevos flujos de trabajo agregando o modificando filas en las tablas del sistema, sin necesidad de re-copilar o re-desplegar el código.

La Trinidad de Datos

El motor de modelado se organiza alrededor de tres conceptos base:

flowchart LR
    A[Objetos] -->|"Tienen estructura definida por"| B[Propiedades]
    B -->|"Se almacenan y persisten en"| C["Tablas PostgreSQL"]

Objetos: Representan la unidad principal de información del sistema (un registro individual, como un cliente específico o un artículo de inventario). Cada objeto tiene un identificador único (UUID).
Propiedades: Definen el esquema, tipo de dato y las validaciones de los objetos. Una propiedad puede ser simple (un texto) o compleja (una fórmula dinámica, una referencia a otro objeto, o una lista relacional).
Tablas: El soporte físico de persistencia en PostgreSQL donde los objetos se almacenan y se relacionan según las reglas de su Entidad correspondiente.

Estructura de Configuración de Interfaz y Navegación

El cliente dinámico de Axol Systems lee la estructura visual desde las tablas de configuración del sistema en el siguiente orden jerárquico:

flowchart TD
    M[Módulos] -->|"Contiene 1..N"| W[Widgets]
    W -->|"Contiene 1..N"| V[Vistas]
    V -->|"Muestra datos de una"| E[Entidades]
    E -->|"Tiene asociadas 1..N"| P[Propiedades]

1. Módulos (`modules`)

Representan las secciones principales del menú de navegación de la aplicación. Clasifican las áreas operativas del negocio y deciden qué iconos y textos mostrar en el menú principal.

Campos clave: id_module, text, icon, icon_catalog (para fuentes tipográficas de iconos).

2. Widgets (`widgets`)

Son contenedores visuales que estructuran cómo se consume una entidad dentro de un módulo. Asocian un tipo de visualización a una entidad específica.

Tipos soportados: Actualmente el motor se centra en el widget de tabla (representado con el entero 0), renderizado en el cliente como un grid interactivo (PlutoGrid).
Campos clave: id_widget, widget (tipo), id_entity, id_module.

3. Vistas (`views`)

Configuran de forma precisa la presentación de la información dentro del Widget. Una misma entidad puede tener múltiples vistas para diferentes propósitos (por ejemplo, una vista de “Inventario Aprobado” y otra de “Inventario Rechazado” para la entidad Stock).

Campos clave: id_view, view_name, id_entity, view_type, dynamic_values.
Opciones en dynamic_values:
- only_view: Fuerza la vista a modo solo lectura (bloquea creación/edición/eliminación).
- column_hide: Lista de columnas ocultas en la cuadrícula.
- column_width: Ancho personalizado de columnas.
- automation_buttons_config: Cambia el botón primario de acción (ej. en lugar de “Nuevo” ejecutar una automatización específica).

Relación entre Entidades y Propiedades

Las entidades y propiedades son la traducción técnica del modelo de negocio en la base de datos:

Entidades (`entities`)

Clasifican el tipo de objeto y definen en qué tabla pública de PostgreSQL se guardará la información de dichos objetos.

Campos clave: id_entity, entity_name, table_name (tabla física), event_table (tabla donde se registran los eventos de auditoría y cambios).

Propiedades (`properties`)

Son los atributos individuales asignados a una entidad. Cada propiedad tiene un índice (index_prop), un nombre legible (prop_name), y un tipo de dato lógico (data_type) que se traduce a su equivalente en Dart (Flutter) y PostgreSQL:

Tipo Lógico (`data_type`)	Tipo en Flutter (Dart)	Tipo en PostgreSQL	Uso Común
text (0)	`String`	`text`	Nombres, códigos simples (una sola línea)
longText (1)	`String`	`text`	Descripciones largas, comentarios
double (2)	`double`	`double precision`	Cantidades, importes numéricos
time (3)	`DateTime`	`timestamp`	Fechas de registro, transacciones
bool (4)	`bool`	`boolean`	Checks de estado, confirmaciones
reference (5)	`String` / `ObjectModel`	`uuid`	Relaciones 1-N (FK a un objeto foráneo)
objList (6)	`ObjectList`	`null` (Usa tabla junction)	Relaciones N-M (Lista de objetos foráneos)
array (8)	`Array`	`text`	Lista desplegable de opciones fijas

Relaciones Muchos a Muchos: Tablas de Unión (`junction_n0_n1`)

Para dar soporte a propiedades complejas de tipo “Lista de Objetos” (objList) sin acoplar el esquema físico, el sistema genera tablas de unión intermedias.

La nomenclatura de estas tablas es estandarizada: junction_n0_n1, donde:

n0 es el número identificador de la tabla primaria.
n1 es el número identificador de la tabla foránea.

Estructura de la Tabla Junction:

id_junction_n0_n1: Identificador único UUID del vínculo.
column_table0: Nombre de la propiedad de tipo objList en la tabla primaria que originó la relación.
id_obj_table0: UUID del objeto primario (propietario de la lista).
id_obj_table1: UUID del objeto foráneo (miembro de la lista).

Filtros Persistentes en Vistas

Las vistas permiten configurar filtros SQL que persisten en el servidor, limitando los registros que el cliente puede visualizar en esa vista específica. Se estructuran en formato JSONB dentro del campo de la vista y admiten evaluación lógica encadenada:

[
  {
    "property_key": "2a9cea9e-d4e9-4a1f-bf39-8ad2dcf314da",
    "oper": "eq",
    "value": "Inventario A",
    "log_op": "and"
  },
  {
    "property_key": "8b8cba8e-c3e8-5a2f-cf40-9bd3dcf415db",
    "oper": "eq",
    "value": "ACTIVO",
    "log_op": "or"
  }
]

[!IMPORTANT] Precedencia Lógica en Filtros: El motor de Axol concatena secuencialmente los filtros en la cláusula WHERE de SQL. Puesto que en PostgreSQL el operador AND tiene mayor precedencia que OR, la base de datos siempre evaluará primero las condiciones agrupadas por AND.

Por ejemplo, A AND B OR C AND D se interpretará lógicamente como (A AND B) OR (C AND D).

Valores Dinámicos en Propiedades (`dynamic_values`)

El objeto dynamic_values (JSONB) configurado en cada propiedad permite modificar el comportamiento operativo y visual de las entidades en tiempo de ejecución.

Los valores dinámicos soportados actualmente son:

formula: Permite definir operaciones matemáticas, evaluaciones lógicas (if), formateo de unidades, redondeo (round) y lectura de estados previos ({snapshot:...}) para realizar cálculos dinámicos en caliente.
visible: Define expresiones condicionales lógicas o valores booleanos directos para mostrar u ocultar propiedades en tiempo real según el estado del registro.

[!TIP] Guía Detallada y Ejemplos de Producción: Para consultar la sintaxis completa, operadores soportados, ejemplos de JSONB y el cuadro comparativo de visibilidad, consulta la sección dedicada de Valores Dinámicos en Propiedades.

Arquitectura de Datos (Meta-modelo)

La Trinidad de Datos

Estructura de Configuración de Interfaz y Navegación

1. Módulos (modules)

2. Widgets (widgets)

3. Vistas (views)