order-sfcc-create-db

1. Descripción general

Según el pom.xml, el proyecto se describe como "Save salesforce orders to DB". Es un microservicio batch (runner) que descarga por SFTP los ficheros XML de pedidos generados por Salesforce Commerce Cloud para todas las tiendas del grupo (Hawkers, Northweek, Bratleboro, en sus distintas regiones), los procesa en paralelo agrupados por prefijo de tienda, y los persiste en la base de datos de logística.

2. Información técnica

Campo	Valor
artifactId	order-sfcc-create-db
groupId	com.hawkersco
version	1.0.25
Java	25
Spring Boot	4.0.6
Tipo de artefacto	jar (ejecutable, Spring Boot batch/CLI)
Módulos	No aplica (proyecto de módulo único)

3. Arquitectura y diseño

No es una API REST: es una aplicación Spring Boot CLI con un CommandLineRunner (OrderSfccCreateDbRunner) que despacha el procesamiento a un servicio asíncrono.

• .config — AsyncConfig (pool de hilos), HwThreadsProperties (lista de prefijos de tienda por hilo), OrderSfccCreateDbConfig/OrderSfccCreateDbConfiguration.
• .services — OrderSfccCreateDbService (procesamiento asíncrono por grupo de prefijo, @Async).
• .utils — OrderSfccCreateDbUtils (~654 líneas: desmarshalling XML vía JAXB, comprobación de fraude, creación de líneas de pedido/envío, persistencia).

flowchart TD
    A[OrderSfccCreateDbRunner] -->|descarga| B[SFTP /src/pending/]
    A -->|agrupa por prefijo hw.threads| C[OrderSfccCreateDbService · async]
    C -->|JAXB unmarshal| D[OrderSfccCreateDbUtils]
    D -->|comprobación de fraude, transforma| E[(logistics · Order/Customer/Shipment)]
    D -->|éxito| F[SFTP /src/processed/]
    D -->|error| G[SFTP /src/orders_errors/ + Slack]

Flujo: el runner descarga los ficheros XML pendientes de SFTP, los agrupa por prefijo de tienda (configurado en hw.threads[0..12]), y despacha el procesamiento de cada grupo de forma asíncrona; cada fichero se desmarshalla con JAXB, se valida (incluyendo comprobación de fraude), se transforma a las entidades de dominio (Order, Customer, Shipment, líneas), y se persiste; en éxito el fichero se mueve a la carpeta de procesados, en error se mueve a la carpeta de errores y se notifica a Slack.

4. Dependencias principales

Dependencia	Propósito
spring-boot-starter	Núcleo de Spring Boot (sin web, es un runner CLI)
com.hawkersco:logistics-commons	Entidades JPA (Order, Customer, Shipment) y servicios
com.hawkersco:sfcc-commons	Modelo XML de SFCC generado por JAXB (ComplexTypeOrder, etc.)
com.hawkersco:slack-client	Notificaciones de error/fraude
com.hawkersco:pi-function-commons	Utilidades SFTP y de fecha

5. API / Endpoints

No aplica a este proyecto. Es un batch/runner sin capa REST.

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
Servidor SFTP (sftp.hawkersco.com, usuario pro_sfcc)	SFTP	Entrante/Saliente	Descarga de pedidos XML pendientes, archivado tras procesar o error
Slack	HTTP (SlackClient)	Saliente	Alertas de error general y de fraude (canal específico)
PostgreSQL (logistics)	JDBC	Saliente	Persistencia de pedidos, clientes y envíos

7. Configuración

En producción (application-pro.properties) las credenciales llegan por variables de entorno inyectadas como Secret de Kubernetes; en local (application.properties) el repositorio contiene actualmente valores reales hardcodeados (ver alerta de seguridad).

Clave	Descripción
spring.datasource.*	Credenciales de la BD logistics
sftp.host / .port / .user / .password / .remote-dir	Credenciales SFTP
hawkers.regex.source	Expresiones regulares que identifican los IDs de tienda SFCC por marca/región
hawkers.order.premiumcountrylist	Países con recargo de envío premium
hawkers.cp.madeira	Códigos postales de Madeira (Portugal insular)
hw.threads[n]	Lista de prefijos de fichero que procesa cada hilo asíncrono (en local, solo un prefijo de prueba está activo; el resto están comentados)
slack.client.url / .auth.token / .channel.id / .channel-atc.id	Configuración de Slack (canal general y canal de alertas de fraude)

⚠️ Alerta de seguridad

El fichero src/main/resources/application.properties (perfil local) contiene actualmente credenciales reales en texto plano: contraseña de la base de datos PostgreSQL logistics (la misma ya señalada como expuesta en múltiples proyectos de este ecosistema), la contraseña SFTP, y el token de bot de Slack. Ninguna se ha reproducido en este documento. Se recomienda rotar estas tres credenciales y sustituir los valores hardcodeados por credenciales de un entorno de desarrollo aislado.

8. Persistencia

Base de datos PostgreSQL logistics (spring.jpa.hibernate.ddl-auto=none). Entidades relevantes: Order, Customer, Shipment, líneas de pedido. No hay Flyway/Liquibase en este repositorio.

9. Procesos programados y mensajería

No hay @Scheduled; el procesamiento por prefijo se hace vía @Async dentro de una misma invocación. La periodicidad la impone el CronJob de Kubernetes, que ejecuta el contenedor cada 5 minutos (schedule: "0/5 * * * *").

10. Ejecución en local

Requisitos previos: JDK 25, Maven, acceso a la BD logistics y credenciales SFTP válidas.

# Compilar
./mvnw clean install

# Compilar sin tests
./mvnw -DskipTests clean install

# Ejecutar tests
./mvnw test

# Ejecutar el JAR
java -jar target/order-sfcc-create-db-1.0.25.jar

Al ser un CommandLineRunner, no expone Actuator/health: la verificación se hace revisando el log de consola o los ficheros movidos en el servidor SFTP.

11. Despliegue

• Imagen: construida con jib-maven-plugin (base eclipse-temurin:25-jre, containerizingMode=packaged), publicada en europe-west3-docker.pkg.dev/pi-saldum/pi-repo/order-sfcc-create-db:<tag>. El CLAUDE.md menciona una imagen base amazoncorretto:25-alpine, que no coincide con la configuración real vía Jib (mismo patrón de imagen base desactualizada detectado en muchos proyectos hermanos, aunque aquí con una distribución de JDK distinta a la habitual eclipse-temurin citada en otros documentos).
• Orquestación: Kubernetes CronJob en el clúster GKE pi-cluster-hw, namespace pi, ejecutándose cada 5 minutos.
• CI/CD (Jenkins): pipeline real de 3 etapas — Checkout → Build & Push → Deploy to GKE. El CLAUDE.md describe KICS security scan y SonarQube que no aparecen en el Jenkinsfile actual (mismo patrón detectado en varios proyectos hermanos de este lote).

Job de Jenkins: https://jenkins-pi.hawkersco.net/job/order-sfcc-create-db/

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). Cada fichero se procesa de forma independiente: un fallo mueve el fichero a la carpeta de errores en SFTP y notifica a Slack, sin interrumpir el procesamiento del resto de ficheros/hilos. Logging vía SLF4J/java.util.logging según la clase.

13. Notas y consideraciones

• Pipeline de Jenkins e imagen base más simples/distintos de lo documentado: ver hallazgo en la sección 11.
• El resto de la arquitectura descrita en CLAUDE.md (flujo SFTP → agrupación por prefijo → procesamiento asíncrono → persistencia, variables de entorno de producción, configuración de negocio) coincide con el código real, verificado directamente en OrderSfccCreateDbRunner y la configuración de application.properties.
• Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties.