Skip to main content

Historia de Usuario: Job Batch para Orquestar Creación de Pedidos en Oracle

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

🎯 Historia de Usuario​

Como Sistema de Integración EDI
Quiero un proceso Spring Batch (Job de Creación de Pedidos)
Para que pueda leer líneas de pedido validadas (S_VALIDATED) o pendientes de reintento (S_PENDING_RETRY), disparar su procesamiento a través de la máquina de estados para crear el pedido en Oracle Fusion, gestionando la lógica de reintentos.

✅ Criterios de Aceptación​

  • Se debe implementar un Job de Spring Batch (oracleOrderCreationJob).
  • El ItemReader del job debe leer registros de la tabla file_lines donde sm_state sea VALIDATED o PENDING_RETRY.
  • El ItemProcessor del job debe, para cada file_line leída:
    • Obtener su line_id.
    • Si el estado es VALIDATED, invocar al OrderLineStateMachineManager enviando el evento EV_CREATE_IN_ORACLE.
    • Si el estado es PENDING_RETRY, invocar el evento EV_RETRY_ORACLE_CREATION.
  • La acción asociada al estado S_CREATING_IN_ORACLE en la State Machine debe:
    • Incrementar retry_count (o tomar el valor del contexto de la SM) y actualizar last_oracle_attempt_at.
    • Llamar a la API de creación de pedidos de Oracle Fusion.
    • Basado en la respuesta de Oracle y las guardias de la SM:
      • Éxito: Transicionar a S_ORACLE_CREATION_SUCCESSFUL. Actualizar sm_state y guardar oracle_order_id.
      • Fallo reintentable (y retry_count < MAX_RETRIES): Transicionar a S_PENDING_RETRY. Actualizar sm_state y oracle_api_error_details.
      • Fallo no reintentable (o retry_count >= MAX_RETRIES): Transicionar a S_ORACLE_CREATION_FAILED_TERMINAL. Actualizar sm_state y oracle_api_error_details.
  • La acción de entrada a S_ORACLE_CREATION_FAILED_TERMINAL debe disparar una notificación mediante el Notification_Service.
  • El Job debe ser configurable y registrar métricas y logs detallados.
  • Al finalizar el procesamiento exitoso de una línea (S_ORACLE_CREATION_SUCCESSFUL) o un fallo terminal (S_VALIDATION_FAILED, S_ORACLE_CREATION_FAILED_TERMINAL), se deben actualizar los contadores successful_lines o failed_lines en la tabla processed_files para el archivo correspondiente (esto puede ser una acción de la SM o un paso posterior del batch).

🧪 Definition of Done (DoD)​

  • oracleOrderCreationJob implementado y configurado.
  • Lee líneas en VALIDATED o PENDING_RETRY correctamente.
  • Envía eventos EV_CREATE_IN_ORACLE o EV_RETRY_ORACLE_CREATION al OrderLineStateMachineManager.
  • La SM ejecuta la creación en Oracle, maneja reintentos y actualiza sm_state, retry_count, oracle_order_id, oracle_api_error_details en file_lines.
  • Notificaciones se envían en fallos terminales.
  • Contadores en processed_files se actualizan.
  • Job maneja errores y es reiniciable.
  • Métricas y logs del job implementados.

📦 Consideraciones Técnicas​

  • Similar al Job de Validación: JpaPagingItemReader o JdbcCursorItemReader.
  • ItemProcessor integra con OrderLineStateMachineManager.
  • Cliente HTTP robusto para Oracle Fusion APIs.
  • La actualización de contadores en processed_files puede requerir lógica adicional para agregar por file_id, posiblemente en un ItemWriteListener o un paso de resumen del job.

🛠️ Consideraciones para Ambientes Productivos​

🔐 Seguridad​

  • Asegurar credenciales para la API de Oracle Fusion.

🧠 Eficiencia e Idempotencia​

  • Ajustar tamaño de chunk. Paralelización/particionamiento si es viable.
  • Lógica de reintento en la SM debe ser robusta. Implementar backoff exponencial para reintentos si la API de Oracle lo sugiere para ciertos errores.

🧪 Observabilidad y Logging​

  • Métricas de Spring Batch y logs con line_id y file_id.
  • Alertas para fallos en la creación de pedidos o si muchas líneas quedan en PENDING_RETRY.