How kvtral/pg-state_machine works
Este proyecto es un módulo o librería de PostgreSQL para implementar una máquina de estados configurable dinámicamente. Su propósito es permitir en una base de datos la configuración de estados y transiciones, asociándola a tablas específicas para así gestionar, validar y registrar las transiciones de estado de los objetos (filas) de esas tablas mediante funciones sql y triggers.
A continuación se detalla cómo elaborar un diagrama de diseño del sistema que capture con precisión la arquitectura de la solución:
Componentes Principales
• Tablas de configuración y registro:
• máquina_estado: Define la máquina de estados.
• maquina_estado_estados: Define los posibles estados.
• maquina_estado_transiciones: Configura las transiciones válidas entre estados.
• maquina_estado_clase_relacion: Asociación entre la máquina de estados y las tablas de negocio.
• objeto_instancia_eventos_transicion: Registra el historial de transiciones de cada objeto.
• API de funciones:
• Funciones para crear, consultar y eliminar máquinas de estado, estados y transiciones (por ejemplo, me_maquina_estado_crear, me_estado_crear, me_transicion_crear, etc.).
• Función única para realizar cambios en el estado (me_objeto_cambiar_estado) utilizando un ENUM de comandos de transición (AVANZAR, RETROCEDER, REINICIAR, SETEAR).
• Scripts de instalación y ejemplos:
• maquina_estado_instalar.sh: Script de instalación que asegura la ejecución correcta de todos los scripts PL.
• ejemplos.sql: Presenta un ejemplo completo de uso de la configuración y funcionamiento de la máquina de estados.
Relaciones e Interacciones
• El diagrama debe reflejar la forma en que una máquina de estados configura principalmente las tablas de estados y transiciones.
• Dibuje líneas o flechas que muestren:
• La creación de máquinas de estado que, a través del script de instalación, dispone los componentes necesarios (tablas, triggers, funciones).
• La relación entre las máquinas de estado y los objetos de las tablas asociadas vía la tabla maquina_estado_clase_relacion.
• La interacción entre los distintos componentes: al insertar un objeto en una tabla asociada, un trigger (definido también vía un script) lo asigna al estado inicial y, posteriormente, las funciones API permiten cambiar su estado y registrar la transición en objeto_instancia_eventos_transicion.
• Es importante marcar el flujo de datos: desde la configuración inicial de la máquina y estados hacia los cambios de estado mediante la API de funciones, con validaciones de transiciones en cada paso.
Patrones Arquitectónicos y Principios de Diseño
• Modularidad: Separa la lógica de definición (creación de máquinas, estados y transiciones) de la lógica operativa (acción de cambiar de estado, validaciones, registro histórico).
• Integración directa con PostgreSQL: Todo se implementa como scripts SQL, funciones y triggers, lo que convierte la base de datos en el motor de la lógica.
• Validación y consistencia: La función de validación (me_transicion_validacion) asegura que la máquina se configure de forma cronológica y evita inconsistencias, lo que debe reflejarse en el diagrama.
Tecnologías y Herramientas Relevantes
• PostgreSQL: Se usa el lenguaje de procedimientos (PL/pgSQL) para las funciones, triggers y scripts.
• Scripts de shell: maquina_estado_instalar.sh se encarga de la instalación ordenada.
Directrices para Construir el Diagrama de Sistema
• Utilice etiquetas claras para identificar cada componente (tabla, función, trigger, script de instalación).
• Dibuje bloques para piezas lógicas grandes:
• Bloque de "Configuración de Máquina de Estados" que incluya las tablas (máquina, estados, transiciones, asociación) y las funciones de creación/configuración.
• Bloque de "Operaciones de Estado" que contenga la API para cambiar estado, la función de validación y el registro del historial.
• Bloque "Integración y Ejecución" que muestre la relación con los clientes (aplicaciones o usuarios que ejecutan consultas) y el script de instalación que organiza todos los scripts SQL.
• Agregue flechas direccionales para indicar el flujo de información o dependencias. Por ejemplo, desde “aplicación cliente” o “ejemplo” hacia la API, y desde ésta hacia las tablas subyacentes.
• Use diferentes colores o formas para distinguir entre componentes:
• Funciones/API: Agrupe las funciones en un bloque o utilice formas diferenciadas (por ejemplo, cilindros para representar procesos).
• Triggers y scripts de instalación: Podrían representarse con íconos o anotaciones a los márgenes del diagrama.
Adaptación para el Tipo de Proyecto
• Al tratarse de una solución embebida en PostgreSQL y centrada en la gestión de estados, enfatice la integración en la capa de datos.
• Por tanto, no es un clásico “full-stack” con interfaz de usuario y API REST, sino un módulo SQL que se integra en la lógica de negocio de la base de datos. Esto debe reflejarse en la separación clara entre operaciones de configuración (administrar la máquina de estados) y las operaciones de ejecución (cambiar estado y registrar transiciones).
Elementos a Incluir en el Diagrama
• Cada componente debe estar claramente etiquetado: “Tabla: maquina_estado”, “Función: me_objeto_cambiar_estado”, etc.
• Flechas direccionales para indicar el flujo de datos:
• Desde la creación/configuración (creación de máquinas y estados) hacia la asociación de clases y activación de triggers.
• Desde la API de transición hacia el registro en la tabla de eventos.
• Distinción visual usando colores o íconos para diferenciar entre:
• Componentes de configuración (tablas y scripts de instalación).
• Componentes operativos (funciones y triggers).
• Ejemplos y flujos de uso.
En resumen, el diagrama debe capturar cómo se inicializa la máquina de estados, qué componentes estructurales (tablas, funciones, triggers) se utilizan y cómo interactúan junto a la API para gestionar los cambios de estados en los objetos de las tablas asociadas. Este enfoque modular y detallado permitirá a cualquier ingeniero comprender la arquitectura de este potente módulo de máquinas de estados para PostgreSQL, facilitando tanto su mantenimiento como futuras mejoras.