logistic-gb

1. Descripción general

Según el pom.xml, el proyecto se describe como "Logistic GB 3". Es un microservicio batch (runner) que sincroniza pedidos pendientes del Reino Unido desde la base de datos de logística hacia la API de SprintLogistics GB, con archivado de las respuestas en Google Cloud Storage y alertas por Slack tras fallos repetidos.

2. Información técnica

Campo	Valor
artifactId	logistic-gb
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 un único CommandLineRunner (LogisticGbRunner).

• .config — LogisticGbConfiguration (beans de propiedades: GcsBucketProperties, SlackChannelProperties, HawkersOrdersProperties), LogisticGbConst (constantes, formato de zona horaria).
• .utils — LogisticGbUtils (validación de pedido, construcción del request, subida a GCS, alertas Slack).

flowchart TD
    A[LogisticGbRunner] -->|findByOrdersNoProcessedGb| B[(logistics · Order)]
    B --> C{pedido de test?}
    C -->|sí| D[marca TEST, omite]
    C -->|no| E[SprintlogisticsGbV2Client.sendOrder]
    E -->|éxito| F[GCS response/ok/ + estado INIT]
    E -->|error| G[GCS response/ko/]
    G -->|≥4 reintentos| H[OrderError + Slack]

Flujo: obtiene los pedidos GB no procesados; los pedidos de prueba (marcados por una cadena en raw_data) se marcan como TEST y se omiten; el resto se convierte a OrdersSprintLogisticsV2Request y se envía a la API v2 de SprintLogistics GB; la petición y la respuesta (éxito o error) se archivan en GCS bajo {app}/response/{ok|ko}/aaaa/mm/dd/; si un pedido alcanza 4 intentos fallidos, se persiste un OrderError y se notifica al canal de Slack de ATC con un enlace directo a infranete.hawkersco.net.

4. Dependencias principales

Dependencia	Propósito
spring-boot-starter	Núcleo de Spring Boot (sin web, es un runner CLI)
spring-boot-starter-thymeleaf	Motor de plantillas (soporte auxiliar, sin generación de PDF en este runner)
commons-fileupload, commons-io	Utilidades de fichero
com.googlecode.json-simple:json-simple	Parseo JSON auxiliar
com.hawkersco:sprintlogistics-client	Cliente @HttpExchange para la API v2 de SprintLogistics GB (SprintlogisticsGbV2Client)
com.hawkersco:logistics-commons	Entidades JPA (Order, OrderError) y servicios
com.hawkersco:slack-client	Notificaciones de error
com.hawkersco:pi-function-commons	Utilidades compartidas

5. API / Endpoints

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

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
SprintLogistics GB API v2 (api-v2.sprintlogistics.com)	HTTP Basic Auth (SprintlogisticsGbV2Client)	Saliente	Envío de pedidos (sendOrder)
Google Cloud Storage (bucket pi-logistics-segment)	API de GCS	Saliente	Archivado de peticiones/respuestas (éxito/error)
Slack	HTTP (SlackClient)	Saliente	Alerta al canal ATC 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).

Clave	Descripción
spring.datasource.*	Credenciales de la BD logistics
gcs.bucket.name	Bucket de GCS para archivado de respuestas
sprintlogistics-gb-v2.api.url / .username / .password	Credenciales HTTP Basic de la API v2 de SprintLogistics GB (usuario/contraseña en formato UUID)
slack.client.url / .auth.token / .channel.id / .channel-atc.id	Configuración de Slack
hawkers.orders.test	Marcador de pedidos de prueba

⚠️ 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), las credenciales UUID de autenticación de la API de SprintLogistics GB v2, y el token de bot de Slack. Ninguno de estos valores se ha reproducido en este documento. Se recomienda:

1. Rotar la contraseña de BD, las credenciales de SprintLogistics y el token de Slack.
2. Sustituir los valores hardcodeados de application.properties por credenciales de un entorno de desarrollo aislado.
3. Revisar el historial de control de versiones, ya que estas credenciales pueden seguir expuestas en commits anteriores.

8. Persistencia

Base de datos PostgreSQL logistics (spring.jpa.hibernate.ddl-auto=none, esquema externo). Entidades relevantes: Order, OrderError. Entity scan vía PersistenceManagedTypesScanner sobre com.hawkersco.logisticscommons.dao, repositorios vía @EnableJpaRepositories. 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 (k8s/cronjob.yaml), que ejecuta el contenedor cada 5 minutos (schedule: "0/5 * * * *", concurrencyPolicy: Forbid). Único runner, descrito en la sección 3.

10. Ejecución en local

Requisitos previos: JDK 25, Maven, acceso a la BD logistics y credenciales válidas de la API de SprintLogistics GB v2.

# Compilar sin tests
mvn -B -DskipTests clean install

# Ejecutar el JAR
java -jar target/logistic-gb-*.jar

# Build Docker
docker build -t logistic-gb .

No existen tests en este repositorio (src/test/java/ vacío, jenkins/scripts/test.sh es un no-op). 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-gb:<tag>.
• Orquestación: Kubernetes CronJob en el clúster GKE pi-cluster-hw, namespace pi, con credenciales de cuenta de servicio de GCP montadas por volumen, ejecutándose cada 5 minutos.
• CI/CD (Jenkins): pipeline real de 3 etapas — Checkout → Build & Push → Deploy to GKE. El CLAUDE.md describe un pipeline con KICS IaC security scan y SonarQube que no existen en el Jenkinsfile actual (mismo patrón detectado en varios proyectos hermanos de este lote).

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

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). sendOrderToSprintLogistics captura RestClientResponseException y delega a LogisticGbUtils.processOrderError para archivar el error en GCS, sin interrumpir el procesamiento del resto de pedidos. Tras 4 intentos fallidos, se persiste un OrderError y se notifica a Slack. Logging mediante java.util.logging.Logger estándar (consola).

13. Notas y consideraciones

• CLAUDE.md describe la integración con una versión de API distinta a la real: menciona el cliente genérico SprintlogisticsGbConf contra https://api.sprintlogistics.com, pero el código real usa SprintlogisticsGbV2Client contra https://api-v2.sprintlogistics.com (propiedad sprintlogistics-gb-v2.api.*) — es decir, el proyecto ya usa la versión 2 de la API de SprintLogistics GB, no la v1 descrita en el documento.
• Pipeline de Jenkins más simple de lo documentado: ver hallazgo en la sección 11.
• El resto de la arquitectura descrita en CLAUDE.md (flujo de procesamiento, pedidos de prueba, reintentos, archivado en GCS, alerta Slack tras 4 fallos) coincide con el código real, verificado directamente en LogisticGbRunner.
• Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties.