Skip to main content

Historia de Usuario: Módulo de Parseo y Almacenamiento de Líneas (DELTA)

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 parseo (Aplicativo DELTA)
Para que pueda leer archivos EDI desde la carpeta /outcoming, extraer cada línea de pedido y almacenarla estructuradamente en la base de datos para su posterior procesamiento por la máquina de estados.

✅ Criterios de Aceptación​

  • El aplicativo DELTA debe monitorear la carpeta SFTP /outcoming para nuevos archivos listos para parseo.
  • Por cada archivo detectado, DELTA debe leer su contenido.
  • DELTA debe parsear la estructura del archivo EDI para extraer cada línea de pedido individual.
  • Para cada línea extraída, se deben insertar los siguientes datos en la tabla file_lines de PostgreSQL:
    • file_id: FK al archivo procesado en processed_files.
    • line_number_in_file: Número secuencial de la línea dentro del archivo.
    • client_order_reference, product_sku, quantity: Campos clave del pedido.
    • parsed_data: JSONB con datos adicionales relevantes.
    • sm_state: Inicializado al estado NEW_LINE (según HLD Sección 6.3).
    • Otros campos (validation_error_details, oracle_order_id, etc.) inicializados a NULL o valores por defecto.
    • retry_count: Inicializado a 0.
  • Una vez parseadas todas las líneas (o se ha intentado), DELTA debe actualizar el registro en processed_files:
    • parsing_status_id: A 'SUCCESS' o 'ERROR' (de cat_generic_processing_statuses).
    • parsing_error: Mensaje de error si el parseo falló.
    • total_lines: Número total de líneas parseadas.
    • overall_status_id: 'PARSED_WITH_ERRORS' o 'PARSED_SUCCESSFULLY' (de cat_file_overall_statuses).
  • Si un archivo no puede ser parseado por formato inválido, debe moverse a /error_delta y registrarse el error.
  • DELTA debe ser tolerante a fallos: un error en una línea no debe bloquear el resto.
  • El proceso debe ser idempotente: no debe volver a parsear archivos con parsing_status_id 'SUCCESS' o 'ERROR'.
  • Debe exponer métricas Prometheus de archivos parseados, líneas generadas y tiempo promedio de parseo.
  • Logs detallados deben registrar el inicio/fin de parseo por archivo y cualquier error a nivel de línea o archivo.

🧪 Definition of Done (DoD)​

  • Aplicativo DELTA implementado y monitoreando /outcoming.
  • Archivos válidos parseados y líneas insertadas en file_lines con estado NEW_LINE.
  • Estado de parseo y total_lines actualizados en processed_files.
  • Archivos con errores irreparables se mueven a /error_delta y se actualiza processed_files.
  • Idempotencia probada para archivos ya parseados.
  • Métricas Prometheus disponibles.
  • Logs adecuados generados.
  • Configuración externalizada y documentada.

📦 Consideraciones Técnicas​

  • DELTA puede ser una app standalone (Java, Python) o proceso Spring Batch.
  • Usar librerías robustas para parseo EDI según el formato.
  • Considerar inserciones batch para mejor rendimiento.
  • Verificar parsing_status_id antes de parsear para idempotencia.

🛠️ Consideraciones para Producción​

🔐 Seguridad​

  • Validar que los archivos de /outcoming provengan de origen confiable (flujo Camel).
  • Limitar permisos del proceso DELTA solo a las carpetas y DB necesarias.

🧠 Eficiencia e Idempotencia​

  • Optimizar queries para verificar estado de parseo.
  • Para archivos grandes, considerar parseo en streaming para evitar alto uso de memoria.
  • Permitir procesamiento paralelo de múltiples archivos.

🧪 Observabilidad y Logging​

  • Métricas:
    • delta.files.parsed.count
    • delta.lines.created.count
    • delta.file.parsing.time.mean
  • Logs con file_id para trazabilidad de archivos.
  • Alertas para errores recurrentes o acumulación de archivos sin parsear en /outcoming.