logistic-usa

1. Descripción general

Según el pom.xml, el proyecto se describe como "Logistic from USA". Es un microservicio batch (runner) que procesa pedidos pendientes de EE.UU., los envía al almacén OWD (Order Warehouse Distribution) mediante XML sobre HTTP, y reporta la información fiscal de los pedidos a TaxJar para cumplimiento tributario.

2. Información técnica

Campo	Valor
artifactId	logistic-usa
groupId	com.hawkersco
version	1.0.25
Java	25
Spring Boot	4.0.6
Tipo de artefacto	jar (ejecutable, Spring Boot batch/CLI, spring.main.web-application-type=none)
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 2 CommandLineRunner, ambos activos.

Orden	Runner	Propósito
1	LogisticUsaRunner	Obtiene pedidos USA no procesados, construye el XML (JAXB) y lo envía a OWD
2	LogisticUsaRunnerTaxJar	Reporta a TaxJar la información fiscal de los pedidos; llama a System.exit() al terminar

• .config — LogisticUsaConfiguration (beans de servicios de logistics-commons), OwdXmlProperties, NaiveHostnameVerifier y NaiveSSLSocketFactory (SSL "trust-all" para el certificado autofirmado de OWD).
• .model — OwdApiRequest, OwdApiResponse, SkuFacilityRule.
• .utils — LogisticUsaConst, LogisticUsaUtils.

flowchart TD
    A["1. LogisticUsaRunner"] -->|XML JAXB| B[OWD SOAP/XML API]
    B -->|éxito| C[(logistics · Shipment)]
    B -->|error, ≥4 reintentos| D[GCS + Slack]
    E["2. LogisticUsaRunnerTaxJar"] -->|datos fiscales| F[TaxJar API]
    E -->|System.exit al terminar| G[Fin del proceso]

Flujo: el runner 1 obtiene los pedidos USA pendientes, construye el XML de la petición (JAXB) y lo envía a OWD sobre una conexión con verificación SSL deshabilitada (certificado autofirmado); en éxito marca el pedido como enviado y guarda el registro de envío; en fallo incrementa el contador de reintentos y sube el XML de error a GCS, notificando a Slack tras 4 fallos. El runner 2 procesa los pedidos a través de TaxJar para el reporte de impuestos de EE.UU.

4. Dependencias principales

Dependencia	Propósito
spring-web	RestClient/@HttpExchange
spring-boot-starter-mail	Soporte de correo (declarado, sin uso aparente en los runners actuales)
com.taxjar:taxjar-java	SDK oficial de la API de TaxJar
com.hawkersco:owd-client	Cliente para la API SOAP/XML de OWD
com.hawkersco:logistics-commons	Entidades JPA (Order, Shipment, OrderError) y servicios
com.hawkersco:sfcc-commons	Modelos de pedido de Salesforce Commerce Cloud
com.hawkersco:slack-client	Notificaciones de error
com.hawkersco:pi-function-commons	DateUtils, utilidades de GCS

5. API / Endpoints

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

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
OWD (secure.owd.com)	HTTP con XML (JAXB), SSL "trust-all" (certificado autofirmado)	Saliente	Envío del pedido para su preparación/despacho en almacén
TaxJar	HTTP REST (SDK oficial)	Saliente	Reporte de transacciones fiscales
Google Cloud Storage (bucket pi-logistics-segment)	API de GCS	Saliente	Archivado de XML de error
Slack	HTTP (SlackClient)	Saliente	Alertas tras 4 intentos fallidos
PostgreSQL (logistics)	JDBC	Entrante/Saliente	Lectura de pedidos pendientes y actualización de estado

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), pese a que el CLAUDE.md afirma que este fichero está en .gitignore.

Clave	Descripción
spring.datasource.*	Credenciales de la BD logistics
owd.auth.client.url / .xml.clientid / .xml.clientauthorization	Credenciales y configuración de la API OWD
owd.xml.*	Parámetros fijos de la petición OWD (regla de backorder, regla de instalación, tipo de pago, etc.)
taxjar.auth.key	Clave de la API de TaxJar
slack.client.url / .auth.token / .channel.id / .channel-atc-mx.id	Configuración de Slack

⚠️ 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 clave de autorización del cliente OWD, y la clave de la API de TaxJar. Además, la conexión con OWD deshabilita intencionadamente la validación de certificados SSL (NaiveHostnameVerifier/NaiveSSLSocketFactory, "trust-all"), lo que expone a riesgo de intermediación si el tránsito de red no es de confianza. Ninguna credencial se ha reproducido en este documento. Se recomienda:

1. Rotar la contraseña de BD, la clave de OWD y la clave de TaxJar.
2. Evaluar si el "trust-all" SSL de OWD es estrictamente necesario (certificado autofirmado del proveedor) o si puede sustituirse por un truststore específico.
3. Sustituir los valores hardcodeados de application.properties por credenciales de un entorno de desarrollo aislado.

8. Persistencia

Base de datos PostgreSQL logistics (spring.jpa.hibernate.ddl-auto=none). Entidades relevantes: Order, Shipment, OrderError. Entity scan vía PersistenceManagedTypesScanner. No hay Flyway/Liquibase en este repositorio.

9. Procesos programados y mensajería

No hay @Scheduled ni listeners de colas: la periodicidad la impone el CronJob de Kubernetes, que ejecuta el contenedor cada 5 minutos (schedule: "0/5 * * * *", concurrencyPolicy: Forbid). Se ejecutan en orden los 2 runners de la tabla de la sección 3.

10. Ejecución en local

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

# Compilar sin tests
mvn -B -DskipTests clean install

# Compilar con tests
mvn clean install

# Ejecutar tests
mvn test

# Ejecutar un test concreto
mvn test -Dtest=LogisticUsaApplicationTests#contextLoads

Al ser un CommandLineRunner, no expone Actuator/health: la verificación se hace revisando el log de consola o el estado de los pedidos en la BD logistics.

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/logistic-usa:<tag>. El CLAUDE.md menciona una imagen base eclipse-temurin:25-jdk-alpine, que no coincide con la configuración real vía Jib.
• 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, consistente con lo descrito en el CLAUDE.md.

Job de Jenkins: https://jenkins-pi.hawkersco.net/job/logistic-usa/

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). El envío a OWD captura errores por pedido, incrementando el contador de reintentos y archivando el XML de error en GCS; tras 4 fallos se notifica a Slack. Logging mediante java.util.logging.Logger/SLF4J según la clase.

13. Notas y consideraciones

• CLAUDE.md afirma que application.properties está en .gitignore, pero el fichero está presente y con credenciales reales legibles directamente en el repositorio de trabajo (mismo patrón detectado en showroom-flash-create-db, theiconic-create-db y update-stock).
• La clase OwdSoapClientConfiguration citada en CLAUDE.md no existe con ese nombre: la configuración SSL "trust-all" real vive repartida entre NaiveHostnameVerifier, NaiveSSLSocketFactory y LogisticUsaConfiguration — el comportamiento descrito (verificación de certificado deshabilitada intencionadamente) es correcto, pero el nombre de clase citado no se corresponde con ningún fichero del árbol de código actual.
• El resto de la arquitectura descrita en CLAUDE.md (dos runners con su orden correcto, integración OWD/TaxJar/Slack/GCS, reintentos) coincide con el código real, verificado directamente en LogisticUsaRunner y LogisticUsaRunnerTaxJar.
• Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties y sobre la validación SSL deshabilitada.