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"]

1. 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).
2. 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).
3. 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 (modules)"] -->|"Contiene 1..N"| W["Widgets (widgets)"]
    W -->|"Contiene 1..N"| V["Vistas (views)"]
    V -->|"Muestra datos de"| E["Entidades (entities)"]
    E -->|"Tiene asociadas 1..N"| P["Propiedades (properties)"]
    E -->|"Define 1..N"| F["Formularios (forms)"]
    V -.->|"Vincula 1..N vía view_forms"| F

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).

4. Formularios (forms) y Vinculación a Vistas (view_forms)

Los formularios determinan el diseño, campos y distribución de la captura y edición de datos dentro del panel lateral (drawer). Una entidad puede disponer de múltiples formularios adaptados a distintos contextos de trabajo:

• Formularios (forms):
  • Configuran la cuadrícula del panel lateral, soportando entre 1 y 6 columnas adaptables (columns_count) y un ancho de panel proporcional de 20% a 100% de la pantalla (drawer_width_factor).
  • Estructuran los campos en layout_config mediante el parámetro col_span por columna.
  • Campos clave: id_form, id_entity, name, columns_count, drawer_width_factor, layout_config.
• Vinculación a Vistas (view_forms):
  • Asocia y prioriza los formularios disponibles para cada vista operativa.
  • Campos clave: id_view_form, id_view, id_form, is_primary, is_edit_default, order.
  • Comportamiento en la interfaz:
    • Botón Primario (is_primary: true): Formulario predeterminado ejecutado al pulsar el botón principal de creación en la barra de herramientas (ej. + Nuevo Pedido).
    • Menú Desplegable de Variantes: Si la vista tiene formularios secundarios asignados, se despliega una flecha junto al botón principal para elegir capturas alternativas (ej. “Alta Rápida” o “Entrada Detallada”).
    • Formulario de Edición por Defecto (is_edit_default: true): Formulario que se abre automáticamente al editar o consultar un registro existente desde la cuadrícula.

5. Módulos Especiales de Configuración (en Ajustes)

Además de los módulos y vistas operativas del negocio, la barra lateral de configuración del sistema (linkSelect) incluye herramientas administrativas clave:

• Formularios (FormsConfigView): Diseñador visual para componer la estructura de formularios por entidad, calibrar columnas (1 a 6), ajustar el ancho del panel drawer (drawer_width_factor) y organizar la distribución y visibilidad de los campos (col_span).
• Automatizaciones (AutomationsConfigView): Asistente visual paso a paso y editor de código JSON para construir reglas del motor ECA v2 (disparadores, condiciones y pipelines de acciones).
• Plantillas de Reportes: Entorno de diseño y edición JSON con previsualización en vivo para la exportación de documentos PDF.
• Identidad y Marca: Personalización de logotipos (default, claro y oscuro), dimensiones y fondo de pantalla del portal de acceso.
• Usuarios y Roles: Control de acceso granular y asignación de credenciales.
• Alertas del Sistema: Definición de reglas automáticas de notificación para eventos y vencimientos.

---

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 con selector asistido)
objList (6)	ObjectList	null (Directo 1:N o Junction N:M)	Colecciones y sub-tablas relacionales con soporte directo 1:N y N:M con tabla junction, visualización embebida, expansión y edición en pantalla completa
array (8)	Array	text	Lista desplegable de opciones fijas

---

Relaciones y Sub-tablas: Listas de Objetos (objList)

Para modelar colecciones de registros secundarios o sub-tablas embebidas dentro de un objeto principal, Axol Systems utiliza propiedades de tipo objList. El motor admite dos modalidades relacionales según las necesidades del flujo de negocio:

1. Relaciones Directas 1:N (Uno a Muchos)

Utilizadas cuando los registros secundarios pertenecen en exclusiva al objeto padre (por ejemplo, las partidas de una factura, los renglones de una orden de compra o el desglose de movimientos):

• Almacenamiento Directo: Los registros hijos residen en su tabla foránea (foreign_table) y referencian al objeto contenedor mediante una clave foránea (FK), sin requerir tablas intermedias.
• Comportamiento en UI: El sistema detecta automáticamente la cardinalidad directa 1:N y oculta el botón “Agregar existente” en la sub-tabla, restringiendo la acción únicamente a la creación de nuevos registros dependientes.

2. Relaciones N:M (Muchos a Muchos) mediante Tablas de Unión (junction_n0_n1)

Utilizadas cuando múltiples registros primarios pueden asociar y compartir los mismos registros secundarios (por ejemplo, asignar productos a múltiples catálogos o listas de precios), o bien para desacoplar el esquema físico:

• Tablas Intermedias: El sistema gestiona tablas de unión con nomenclatura estandarizada junction_n0_n1 (o configurada mediante junction_table), donde:
  • n0 es el identificador numérico o nombre de la tabla primaria.
  • n1 es el identificador numérico o nombre de la tabla foránea.

Estructura de la Tabla Junction:

• id_junction_n0_n1: Identificador único UUID del vínculo relacional.

• 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 o contenedor de la lista).

• id_obj_table1: UUID del objeto foráneo (registro asociado como miembro de la lista).

• Comportamiento en UI: Permite tanto la creación de nuevos ítems como la selección y vinculación de registros ya existentes a través de un selector asistido.

---

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.