Skip to main content

Historia de Usuario: Módulo de Recepción e Indexación de Archivos (Apache Camel)

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

🎯 Historia de Usuario​

Como Sistema de Integración EDI
Quiero contar con un módulo de recepción e indexación basado en Apache Camel
Para que pueda procesar archivos EDI desde múltiples fuentes (SFTP, SOAP), registrar sus metadatos esenciales y moverlos a una ubicación de procesamiento posterior, manteniendo trazabilidad completa.

✅ Criterios de Aceptación​

  • El proceso de Apache Camel debe monitorear continuamente la carpeta SFTP /incoming para nuevos archivos.
  • El sistema debe exponer un endpoint de servicio web SOAP para recibir archivos EDI. Los archivos recibidos vía SOAP se depositarán en la carpeta SFTP /incoming.
  • El módulo debe ser desarrollado usando Apache Camel y desplegado como un componente (microservicio o parte de una aplicación Spring Boot) dentro del ecosistema EDI.
  • Por cada archivo detectado/recibido, se deben extraer y guardar en la tabla processed_files de PostgreSQL los siguientes metadatos:
    • file_name: Nombre original del archivo.
    • received_at: Timestamp de recepción.
    • source_id: FK a cat_file_sources (identificando si es 'SFTP' o 'SOAP').
    • sftp_path_incoming: Ruta SFTP original (si aplica).
    • file_hash: Checksum del archivo (ej. SHA-256) para validación de integridad (opcional).
    • metadata_registration_status_id: Estado del registro (ej. 'SUCCESS', 'ERROR').
    • metadata_registration_error: Mensaje de error si falla el registro.
    • parsing_status_id: Inicializado a estado 'PENDING'.
    • overall_status_id: Inicializado a estado 'RECEIVED'.
  • Si el registro de metadatos es exitoso, el archivo debe moverse de /incoming a /outcoming.
  • En caso de error durante el registro o movimiento, el archivo debe moverse a /error_camel y los estados en processed_files deben reflejar el fallo.
  • El servicio debe ser idempotente (evitar reprocesamiento de archivos con el mismo nombre y timestamp).
  • Toda la información debe persistirse en PostgreSQL.
  • El componente debe exponer métricas Prometheus (vía Spring Boot Actuator).
  • Se debe incluir trazabilidad mediante logs con IDs de correlación (ExchangeID, breadcrumbId).
  • Deben ser configurables externamente: credenciales y rutas SFTP, endpoint SOAP, parámetros de polling.
  • El origen del archivo (source_id) debe registrarse correctamente (SFTP o SOAP).

🧪 Definition of Done (DoD)​

  • Rutas Apache Camel implementadas para SFTP y SOAP.
  • Archivos de /incoming (directos o vía SOAP) procesados y registrados en processed_files.
  • Archivos exitosamente registrados se mueven a /outcoming.
  • Archivos fallidos se mueven a /error_camel y se registra el error.
  • Idempotencia implementada y validada.
  • Métricas disponibles en /actuator/prometheus.
  • El módulo no falla si un archivo individual genera error.
  • Configuración externalizada.
  • Logs con niveles INFO, ERROR, DEBUG y trazabilidad implementados.
  • Documentación de operación y monitoreo incluida.

📦 Consideraciones Técnicas​

  • Componentes Camel a usar: sftp, sql o jpa, cxf o spring-ws, log, bean, direct/seda.
  • DSL: Java o Kotlin.
  • Usar idempotentRepository basado en base de datos (clave: file_name + received_at).
  • Implementar transaccionalidad en rutas que combinan base de datos y movimiento de archivos.

🛠️ Consideraciones para Ambientes Productivos​

🔐 Seguridad​

  • Validar extensiones y tamaño de archivo antes de procesar.
  • Asegurar credenciales SFTP y certificados SOAP con Spring Cloud Config, Vault u otro sistema.
  • Deshabilitar endpoints no esenciales (JMX si no se usa).
  • Verificar dependencias con OWASP Dependency-Check.

🧠 Eficiencia e Idempotencia​

  • Ajustar maxMessagesPerPoll y delay según el volumen esperado.
  • Considerar rutas asíncronas (seda, disruptor) para alto volumen.
  • Usar base de datos como idempotentRepository para consistencia en clústeres.

🧪 Observabilidad y Logging​

  • Métricas Prometheus relevantes:
    • camel.route.exchanges.succeeded
    • camel.route.exchanges.failed
    • camel.route.processing.time.mean
  • Logs con ExchangeID y breadcrumbId para trazabilidad completa.