Logistics Commons

1. Descripción general

logistics-commons es una librería JAR compartida que centraliza toda la capa de acceso a datos del dominio logístico de Hawkers. Proporciona las entidades JPA, los repositorios Spring Data y los servicios de acceso que los microservicios de logística consumen vía Maven, evitando que cada servicio duplique el modelo de datos y las queries contra la base de datos PostgreSQL de logistics.

El proyecto no es un microservicio independiente: no expone endpoints REST ni tiene punto de entrada. Su propósito es ser importado como dependencia por otros proyectos del ecosistema (runners de procesado de pedidos, integradores con Dynamics 365, gestores de devoluciones, etc.).

Cubre los siguientes subdominios:

Pedidos (Order, OrderLine, OrderShipmentStatus…): ciclo de vida completo de un pedido, incluyendo sus estados financiero, logístico y de integración con ERP.
Envíos (Shipment, ShipmentLine, ShipmentRequest, ShipmentStatusHistory): creación de envíos, líneas y registro de peticiones a transportistas.
Devoluciones (Return, ReturnLine, ReturnLog…): subdomain completo de gestión de devoluciones con métodos, razones, estados y usuarios Auth0.
Transportistas y logística (Carrier, Source, ShippingMethod, PickupPoint…): catálogos de operadores logísticos y puntos de recogida.
Marketplaces e integraciones externas (OrderMarketplace, MeliNotification, GioNotification, OrderPrivalia…): entidades de seguimiento de pedidos procedentes de canales de marketplace.
SFCC / SFSC / OWD (SfccShippingMethod, SfscJob, OwdStock…): entidades de sincronización con Salesforce Commerce Cloud y tiendas físicas.

2. Información técnica

Propiedad	Valor
`artifactId`	`logistics-commons`
`groupId`	`com.hawkersco`
`version`	`1.0.25-SNAPSHOT`
Java	25
Spring Boot	4.0.6
Tipo de artefacto	JAR (librería, sin `main` class)
Módulos	Proyecto mono-módulo
Repositorio Maven	Google Artifact Registry — `europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven`

3. Arquitectura y diseño

Paquetes principales

com.hawkersco.logisticscommons
├── dao/              # 67 entidades JPA (@Entity + Lombok)
├── repository/       # 60+ interfaces Spring Data JPA (ListCrudRepository + JpaSpecificationExecutor)
├── service/          # 62 servicios @Service (uno por entidad)
├── specification/    # OrderSpecification — predicados JPA dinámicos
├── model/            # ApiResponsePag — wrapper paginado genérico
├── utils/            # OrderLineComparator
└── LogisticCommonsUtils.java  # @Component con la lógica de negocio transversal

Patrón de capas

Cada entidad del dominio sigue el mismo patrón:

DAO (entidad JPA)
  └── Repository (ListCrudRepository + queries nativas)
        └── Service (@Service — delega 1:1 al Repository)

LogisticCommonsUtils es el único componente con lógica de negocio no trivial: resuelve el transportista por idSource y persiste envíos, líneas y registros de petición.

Flujo principal: creación de envío

flowchart TD
    A[Microservicio consumidor] --> B[LogisticCommonsUtils.saveShipmentFromOrder]
    B --> C{resolveCarrierForSource\nswitch idSource}
    C -->|ID encontrado| D[CarrierService.findById]
    C -->|null| E[Retorna null]
    D --> F[Crear Shipment\nestado CREATED]
    F --> G[ShipmentService.save]
    G --> H[Shipment persistido]
    A --> I[createShipmentLineFromOrderLine]
    I --> J[ShipmentLine sin persistir]
    A --> K[saveShipmentRequest\nregistro log petición transportista]
    K --> L[ShipmentRequestService.save]

Enrutamiento de transportistas por `idSource`

Transportista (ID)	`idSource` values
Europa (10)	1, 8, 14, 17, 27, 30, 31, 32, 41, 42, 29, 43, 44, 45, 46, 62, 63, 64, 66, 67, 72
Australia (4)	2, 9, 20, 78
Colombia (5)	3, 10, 16, 28, 40, 59, 60, 73
México Logisfashion (7)	4, 15, 18
México Cubbo (12)	11, 47, 48, 52, 55
UK (1)	5
USA (6)	6, 12
Eyewear (11)	7, 13
Loopas (8)	19, 21, 22, 23, 24, 25, 26
RuniF (9)	39
GR (20)	69, 61
IT (18)	58, 68
DE (17)	57, 70
GB (1023)	71, 74

4. Dependencias principales

Dependencia	Versión	Propósito
`spring-boot-starter`	4.0.6 (BOM)	Base Spring Boot (autoconfiguración, contexto)
`spring-boot-starter-data-jpa`	4.0.6 (BOM)	Spring Data JPA + Hibernate 7
`postgresql`	42.7.11	Driver JDBC PostgreSQL
`lombok`	1.18.46	Generación de código boilerplate (getters, setters, constructores)
`jackson-databind`	2.21.x (BOM)	Serialización/deserialización JSON
`hibernate-spatial`	BOM	Soporte de tipos geométricos en Hibernate
`jts-core`	1.20.0	Tipos geométricos JTS (usado por Hibernate Spatial)
`gson`	2.14.0	Serialización JSON alternativa (usado en entidades `Return` con `@SerializedName`)
`spring-boot-starter-test`	4.0.6 (BOM)	Tests (scope test)

Nota sobre el build: maven-compiler-plugin requiere annotationProcessorPaths explícito para Lombok porque Spring Boot 4 + Java 25 no lo resuelve automáticamente.

5. API / Endpoints

No aplica a este proyecto.

Este proyecto es una librería JAR sin controladores REST. No expone ningún endpoint HTTP.

6. Integraciones externas

Este proyecto no se comunica directamente con sistemas externos. Modela las integraciones como campos en las entidades para que los microservicios consumidores puedan coordinar el estado de cada integración.

Sistema externo	Dirección del flujo	Entidades relacionadas
Dynamics 365 (ERP)	Saliente (flag de estado)	`Order.isSendDynamics`, `Order.cdDynamicsStatus` (+ variantes `_uat`, `_gold`)
SFCC (Salesforce Commerce Cloud)	Bidireccional (estado)	`Order.sfccShippingMethod`, `SfccShippingMethod`, `SfccStore`
SFSC (Store Commerce / tiendas físicas)	Saliente (flag de estado)	`Order.isUpdatedSfsc`, `SfscJob`, `SfscProduct`
Mercado Libre	Entrante (notificaciones)	`MeliNotification`, `OrderMarketplace`
GIO	Entrante (notificaciones)	`GioNotification`
Privalia	Bidireccional	`OrderPrivalia`, `SkuEyeglassesSoldInPrivalia`
Transportistas (Logisfashion, Cubbo, 99Minutos, Cooper…)	Saliente (peticiones)	`ShipmentRequest`, `Shipment`, `Carrier`
PostgreSQL (BD logistics)	Bidireccional	Todas las entidades

7. Configuración

application.properties

Clave	Descripción	Valor de ejemplo
`spring.jpa.database-platform`	Dialecto Hibernate	`org.hibernate.dialect.PostgreSQLDialect`

El DataSource (URL, usuario, contraseña) no está definido en esta librería: lo aporta cada microservicio consumidor en su propia configuración o mediante variables de entorno.

Variables de entorno requeridas por los consumidores

Variable	Descripción
`SPRING_DATASOURCE_URL`	URL JDBC de la base de datos de logistics
`SPRING_DATASOURCE_USERNAME`	Usuario de la BD
`SPRING_DATASOURCE_PASSWORD`	Contraseña de la BD

Distribución Maven

La librería se publica en Google Artifact Registry. Los microservicios consumidores necesitan el wagon configurado:

<repositories>
  <repository>
    <id>artifact-registry</id>
    <url>artifactregistry://europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven</url>
  </repository>
</repositories>

8. Persistencia

Base de datos

PostgreSQL. El esquema es gestionado externamente (no hay Flyway ni Liquibase en este proyecto). Las tablas deben existir previamente en la BD de logistics.

Entidades principales

Entidad JPA	Tabla PostgreSQL	Descripción
`Order`	`"order"` (entrecomillada — palabra reservada SQL)	Pedido con 100+ campos: estados, dirección, montos, flags de integración
`OrderLine`	`order_line`	Líneas de pedido (productos + cantidades)
`OrderShipmentStatus`	`order_shipment_status`	Historial de transiciones de estado del envío de un pedido
`Shipment`	`shipment`	Envío asociado a un pedido; referencia al transportista y seguimiento externo
`ShipmentLine`	`shipment_line`	Líneas del envío (relación con líneas de pedido)
`ShipmentRequest`	`shipment_request`	Log de peticiones/respuestas a la API del transportista
`ShipmentStatusHistory`	`shipment_status_history`	Historial de estados del envío reportado por el transportista
`Return`	`return`	Cabecera de devolución; integraciones Dynamics en estados create/receive/payment
`ReturnLine`	`return_line`	Líneas de devolución
`ReturnLog`	`return_log`	Trazabilidad de operaciones sobre devoluciones
`Carrier`	`carrier`	Catálogo de transportistas
`Source`	`source`	Catálogo de fuentes/canales de pedidos
`Customer`	`customer`	Clientes
`OrderMarketplace`	`order_marketplace`	Metadatos de pedidos provenientes de marketplaces
`MeliNotification`	`meli_notification`	Notificaciones recibidas de Mercado Libre
`PickupPoint`	`pickup_point`	Puntos de recogida (clave compuesta via `@IdClass`)

Convenciones de nomenclatura de campos

Prefijo	Significado
`id_*`	Clave primaria o clave foránea
`cd_*`	Código/identificador de negocio
`ds_*`	Descripción o cadena de texto
`dt_*`	Fecha/timestamp
`nm_*`	Valor numérico/contador
`is_*`	Booleano (flag)

Entidades con clave compuesta (`@IdClass`)

ReturnLineReason / ReturnLineReasonIdClass
ReturnCountryMethod / ReturnCountryMethodIdClass
ReturnAuth0UserStore / ReturnAuth0UserStoreId
PickupPoint / PickupPointIdClass

9. Procesos programados y mensajería

No aplica a este proyecto.

Esta librería no contiene @Scheduled, listeners de Kafka/RabbitMQ ni runners batch. Dicha lógica reside en los microservicios consumidores que usan esta librería.

10. Ejecución en local

Requisitos previos

Java 25
Maven 3.9+
Acceso a Google Artifact Registry (credenciales gcloud configuradas para el wagon)

Compilar e instalar en repositorio local

# Compilar únicamente
./mvnw compile

# Ejecutar tests
./mvnw test

# Instalar en ~/.m2 (para que otros proyectos locales la consuman)
./mvnw clean install

# Publicar en Artifact Registry
./mvnw clean deploy

Importar como dependencia en otro proyecto

<dependency>
  <groupId>com.hawkersco</groupId>
  <artifactId>logistics-commons</artifactId>
  <version>1.0.25-SNAPSHOT</version>
</dependency>

Verificación

Al ser una librería sin servidor embebido, no hay endpoint /actuator/health. La verificación se hace comprobando que el contexto Spring arranca correctamente en el microservicio consumidor.

11. Despliegue

Aspecto	Detalle
Tipo de artefacto	JAR publicado en Google Artifact Registry
Registro	`europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven`
CI/CD	Pendiente de verificar (no hay ficheros de pipeline en el repositorio)
Docker	No aplica — es una librería, no se dockeriza de forma independiente
Kubernetes	No aplica — se despliega embebida en los servicios consumidores

Los microservicios consumidores declaran la dependencia Maven en su pom.xml y el artefacto es descargado desde Artifact Registry en tiempo de build/despliegue.

Job de Jenkins:

https://jenkins-pi.hawkersco.net/job/logistics-commons/

12. Manejo de errores y logging

Estrategia de excepciones

LogisticCommonsUtils captura Exception en saveNewStatusOrder y registra el mensaje como WARN con Lombok @Slf4j.
saveShipmentRequest captura ParseException de stringToDate y la registra como WARN.
Los servicios delegantes no añaden manejo de errores propio; las excepciones se propagan al microservicio consumidor.

Logging

Lombok @Slf4j en LogisticCommonsUtils.
Logs de nivel WARN para errores recuperables (fallo al guardar status, fallo en parseo de fecha).
No hay configuración logback.xml ni log4j2.xml en la librería; el microservicio consumidor es responsable de configurar el destino y formato de los logs.

13. Notas y consideraciones

Deuda técnica

Inyección de dependencias en LogisticCommonsUtils: usa @Autowired en campos, que viola el estándar de inyección por constructor definido en las guías de refactoring del proyecto. Pendiente migrar a @RequiredArgsConstructor.
Servicios sin @RequiredArgsConstructor: la mayoría de los @Service usan @Autowired en campo en lugar de inyección por constructor.
Query literal con fecha hardcodeada en OrderRepository: findByOrdersFulfillFromDate tiene las fechas '2020-11-11' y '2020-11-13' hardcodeadas en la query SQL. Probablemente es una query de uso puntual nunca eliminada.
getOrderStatusList no implementado: OrderService.getOrderStatusList siempre retorna null. TODO pendiente.
ApiResponsePag no es un record: dado que no es una entidad JPA, podría convertirse a record según los estándares Java 25, pero actualmente usa Lombok @Data.
Return entidad con convención de nombres inconsistente: a diferencia de las demás entidades, Return mezcla el prefijo estándar (id_return, is_*) con nombres sin prefijo (created, updated, user_id, user_email). Esto puede indicar que fue creada desde un sistema externo con un esquema diferente.
Múltiples queries por canal marketplace: OrderRepository tiene métodos específicos por canal (Aliexpress, Coppel, Liverpool, Shein, TikTok, Decathlon…) con lógica similar pero sin refactorizar al método genérico findPendingSendLogistic. El comentario /* CLEAN CODE */ en el repositorio señala que existe la intención de migrar a ese método genérico.
Hibernate Spatial / JTS incluido pero no verificado en entidades visibles: hibernate-spatial y jts-core están en el pom.xml, pero ninguna entidad de las leídas declara campos de tipo geométrico explícitamente. Puede estar en entidades no revisadas o ser una dependencia residual.

1. Descripción general​

2. Información técnica​

3. Arquitectura y diseño​

Paquetes principales​

Patrón de capas​

Flujo principal: creación de envío​

Enrutamiento de transportistas por idSource​

4. Dependencias principales​

5. API / Endpoints​

6. Integraciones externas​

7. Configuración​

application.properties​

Variables de entorno requeridas por los consumidores​

Distribución Maven​

8. Persistencia​

Base de datos​

Entidades principales​

Convenciones de nomenclatura de campos​

Entidades con clave compuesta (@IdClass)​

9. Procesos programados y mensajería​

10. Ejecución en local​

Requisitos previos​

Compilar e instalar en repositorio local​

Importar como dependencia en otro proyecto​

Verificación​

11. Despliegue​

12. Manejo de errores y logging​

Estrategia de excepciones​

Logging​

13. Notas y consideraciones​

Deuda técnica​