Skip to main content

Historia de Usuario: Configuración Núcleo de Máquina de Estados (Spring State Machine)

Versión: 1.0
Fecha: 2025-06-03
Autor: Arquitecto de Tecnologías

🎯 Historia de Usuario​

Como Desarrollador del Sistema EDI
Quiero definir e implementar la configuración central de Spring State Machine para el ciclo de vida de las file_lines
Para que se establezca un modelo de estados, eventos, transiciones, acciones y guardias robusto y reutilizable que orqueste el procesamiento de cada línea de pedido.

✅ Criterios de Aceptación​

  • Se debe definir una configuración de Spring State Machine (OrderLineStateMachineConfiguration) que incluya todos los estados especificados en el HLD (Sección 6.3):
    • NEW_LINE, VALIDATING, VALIDATED, VALIDATION_FAILED, CREATING_IN_ORACLE, ORACLE_CREATION_SUCCESSFUL, PENDING_RETRY, ORACLE_CREATION_FAILED_TERMINAL.
  • Se deben definir todos los eventos especificados en el HLD (Sección 6.4):
    • EV_VALIDATE, EV_VALIDATION_SUCCESS, EV_VALIDATION_FAILURE, EV_CREATE_IN_ORACLE, EV_ORACLE_CREATION_SUCCESS, EV_ORACLE_CREATION_FAILURE_RETRYABLE, EV_RETRY_ORACLE_CREATION, EV_ORACLE_CREATION_FAILURE_TERMINAL.
  • Se deben configurar todas las transiciones entre estados disparadas por los eventos correspondientes, según el diagrama de estados (HLD Sección 6.2).
  • Se deben implementar las acciones de entrada a los estados clave (HLD Sección 6.5):
    • S_VALIDATING (on entry): Preparar para invocar servicio de validación Oracle.
    • S_CREATING_IN_ORACLE (on entry): Preparar para invocar API de creación Oracle e incrementar retry_count.
    • S_ORACLE_CREATION_FAILED_TERMINAL (on entry): Preparar para invocar Notification_Service.
  • Las acciones deben ser implementadas como beans de Spring (@Bean o componentes) e inyectadas en la configuración de la SM.
  • Se deben implementar guardias para las transiciones críticas (HLD Sección 6.5):
    • CREATING_IN_ORACLE -> PENDING_RETRY: Verificar si el error es reintentable y retry_count < MAX_RETRIES.
    • CREATING_IN_ORACLE -> ORACLE_CREATION_FAILED_TERMINAL: Verificar si el error no es reintentable o retry_count >= MAX_RETRIES.
    • MAX_RETRIES debe ser configurable.
  • Se debe configurar la persistencia de la máquina de estados usando RepositoryStateMachinePersist (o un persister custom) para guardar/restaurar el estado (sm_state) y variables extendidas (retry_count, validation_error_details, oracle_api_error_details, oracle_order_id) en la tabla file_lines usando line_id como identificador.
  • Se debe implementar OrderLineStateMachineManager (HLD Sección 6.7) como servicio Spring que:
    • Acepte un line_id y un evento.
    • Cargue (o cree) la instancia de la SM para ese line_id.
    • Envíe el evento.
    • Persista el estado después de la transición.
  • La configuración debe ser testeable unitariamente.

🧪 Definition of Done (DoD)​

  • Configuración OrderLineStateMachineConfiguration creada y funcional.
  • Estados, eventos, transiciones, acciones y guardias definidos según el HLD.
  • StateMachinePersister configurado con file_lines.
  • OrderLineStateMachineManager implementado.
  • Pruebas unitarias para transiciones, acciones y guardias implementadas.
  • MAX_RETRIES es configurable.

📦 Consideraciones Técnicas​

  • Usar Spring State Machine Core y Spring State Machine Data JPA/JDBC.
  • Definir Estados y Eventos como enum para type-safety.
  • Acciones y guardias deben ser componentes Spring bien definidos y testeables.
  • Usar ExtendedState para pasar line_id, retry_count, etc., si no se persisten directamente.
  • Asegurar transaccionalidad entre acciones y persistencia de estado.

🛠️ Consideraciones para Ambientes Productivos​

🔐 Seguridad​

  • Las acciones que interactúan con servicios externos (Oracle API, Notificaciones) deben usar clientes seguros y bien configurados.

🧠 Eficiencia e Idempotencia​

  • OrderLineStateMachineManager debe manejar concurrencia si múltiples procesos acceden al mismo line_id.
  • Persistencia eficiente y rápida.

🧪 Observabilidad y Logging​

  • Logging detallado dentro de acciones, guardias y listeners.
  • Métricas de Micrometer o personalizadas: transiciones exitosas, fallos de acción, etc.
  • Usar StateMachineListener para eventos auditables.