Auro Client

1. Descripción general

auro-client es una librería cliente reutilizable (JAR) que encapsula todas las llamadas a la API externa de Auro, proveedor logístico integrado en el ecosistema de microservicios de Hawkers. El proyecto no expone ningún endpoint REST propio; en su lugar, se publica en el registro de artefactos Maven interno y es consumido por otros microservicios que necesiten interactuar con Auro.

La librería gestiona de forma transparente la autenticación mediante token Bearer (con caché de 1 hora), de modo que los servicios consumidores no necesitan implementar ninguna lógica de autenticación. Expone operaciones para:

• Consultar stock de foto (foto-stock).
• Enviar documentos/pedidos a Auro.
• Consultar inventario.
• Consultar el estado de pedidos.
• Cancelar documentos/pedidos.
• Obtener información detallada de documentos.

2. Información técnica

Propiedad	Valor
artifactId	auro-client
groupId	com.hawkersco
version	1.0.25-SNAPSHOT
Java	25
Spring Boot	4.0.6
Tipo de artefacto	JAR (librería, no ejecutable)
Módulos	Proyecto único (no multi-módulo)

3. Arquitectura y diseño

El proyecto sigue la estructura estándar de una librería de cliente HTTP con autoconfiguración de Spring Boot:

com.hawkersco.auroclient
├── client/
│   ├── AuroClient.java           # Interfaz @HttpExchange con las 6 operaciones
│   └── AuroTokenClient.java      # Interfaz @HttpExchange para obtención de token
├── config/
│   ├── AuroClientAutoConfiguration.java  # @AutoConfiguration principal
│   ├── AuroClientConfig.java             # @Configuration auxiliar (activa AuroAuthProperties)
│   ├── AuroAuthProperties.java           # Record de propiedades de autenticación
│   ├── CacheStore.java                   # Cache genérica con Guava
│   └── CacheStoreBeans.java              # Bean de cache con TTL de 5h
└── pojo/
    ├── StockAuroRequest / StockAuroResponse
    ├── OrderAuroRequest
    ├── InventoryAuroRequest / InventoryAuroResponse
    ├── StatusAuroRequest / StatusOrdersAuro
    ├── CancelOrderAuroRequest
    └── DocumentOrderAuroRequest / DocumentOrderAuroResponse

Flujo principal de autenticación y llamada

sequenceDiagram
    participant Consumidor as Microservicio consumidor
    participant AuroClient
    participant CacheStore
    participant AuroTokenClient
    participant AuroAPI as API Auro

    Consumidor->>AuroClient: llamada (ej. postDocumentos)
    AuroClient->>CacheStore: get("token")
    alt Token en caché
        CacheStore-->>AuroClient: token válido
    else Token ausente o expirado
        AuroClient->>AuroTokenClient: getToken(headers)
        AuroTokenClient->>AuroAPI: POST /api/auth/token
        AuroAPI-->>AuroTokenClient: { "token": "..." }
        AuroTokenClient-->>AuroClient: token
        AuroClient->>CacheStore: add("token", token)
    end
    AuroClient->>AuroAPI: POST /api/genericRequest/ + Bearer token
    AuroAPI-->>AuroClient: respuesta
    AuroClient-->>Consumidor: ResponseEntity

La autoconfiguración (AuroClientAutoConfiguration) se activa condicionalmente con @ConditionalOnProperty(prefix = "auro.auth.client", name = "url"), por lo que solo se inicializa si la URL de Auro está configurada.

El registro de la autoconfiguración se realiza mediante el fichero estándar de Spring Boot:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

4. Dependencias principales

Dependencia	Versión	Propósito
spring-boot-starter	(gestionada SB4)	Base de Spring Boot (contexto, autoconfiguración)
spring-web	(gestionada SB4)	RestClient + @HttpExchange / HttpServiceProxyFactory
org.json:json	20251224	Parseo manual de la respuesta JSON del endpoint de token
org.projectlombok:lombok	1.18.46	Generación de boilerplate en POJOs (getters, setters, constructores)
com.fasterxml.jackson.core:jackson-databind	(gestionada SB4)	Serialización/deserialización Jackson en POJOs
com.google.code.gson:gson	(gestionada SB4)	Anotaciones @SerializedName en POJOs (soporte dual)
com.google.guava:guava	33.6.0-jre	Implementación de caché en CacheStore (CacheBuilder)
spring-boot-starter-test	(gestionada SB4)	Testing (scope test)

5. API / Endpoints

No aplica a este proyecto. auro-client es una librería cliente JAR que no expone endpoints REST propios. Las operaciones que encapsula sobre la API de Auro se detallan en la sección 6.

6. Integraciones externas

API de Auro (logística)

Todos los métodos del cliente envían POST al endpoint genérico /api/genericRequest/. La operación concreta se discrimina mediante el campo function en el body JSON.

Método cliente	Campo function (implícito)	Dirección	Descripción
getFotoStock	—	Saliente	Consulta stock de foto en almacén Auro
postDocumentos	—	Saliente	Envía pedidos/documentos a Auro
getInventory	—	Saliente	Consulta inventario en almacén Auro
getStatus	—	Saliente	Consulta el estado de pedidos en Auro
cancelDocumentos	—	Saliente	Cancela documentos/pedidos en Auro
getDocumentos	—	Saliente	Obtiene información detallada de documentos Auro

El endpoint de autenticación es POST /api/auth/token, al que se llama mediante AuroTokenClient pasando credenciales por headers (app, username, password).

Protocolo: HTTPS REST. Formato: JSON. Autenticación: Bearer token (obtenido dinámicamente, cacheado 1 hora).

7. Configuración

No se incluye ningún application.properties en la librería. Las propiedades deben ser inyectadas por la aplicación consumidora.

Propiedades requeridas (auro.auth.client)

Propiedad	Descripción	Ejemplo de valor
auro.auth.client.url	URL base de la API Auro (activa la autoconfiguración)	https://api.auro.example.com
auro.auth.client.app	Identificador de aplicación para el endpoint de auth	hawkers-app
auro.auth.client.username	Usuario para autenticación en Auro	${AURO_USERNAME}
auro.auth.client.password	Contraseña para autenticación en Auro	${AURO_PASSWORD}

Importante: Si auro.auth.client.url no está definida, los beans AuroClient y AuroTokenClient no se registran (condición @ConditionalOnProperty).

Variables de entorno recomendadas

Variable	Propiedad mapeada
AURO_URL	auro.auth.client.url
AURO_APP	auro.auth.client.app
AURO_USERNAME	auro.auth.client.username
AURO_PASSWORD	auro.auth.client.password

8. Persistencia

No aplica a este proyecto. La librería no accede a ninguna base de datos. DataSourceAutoConfiguration está excluida implícitamente al no incluir ningún starter de datos. El único estado que persiste en memoria es la caché del token Bearer.

9. Procesos programados y mensajería

No aplica a este proyecto. No existen jobs @Scheduled, listeners de colas/topics ni runners batch.

10. Ejecución en local

auro-client es una librería JAR, no una aplicación ejecutable. No tiene servidor embebido ni endpoint de health.

Requisitos previos

• Java 25
• Maven 3.x
• Acceso al registro de artefactos Maven interno (europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven) para resolver dependencias internas si las hubiera.

Compilar e instalar en repositorio local

# Compilar sin tests
./mvnw -B -DskipTests clean install

# Compilar con tests (cuando existan)
./mvnw clean install

Publicar en Artifact Registry

mvn deploy -DskipTests

Uso como dependencia en un microservicio consumidor

<dependency>
    <groupId>com.hawkersco</groupId>
    <artifactId>auro-client</artifactId>
    <version>1.0.25-SNAPSHOT</version>
</dependency>

La autoconfiguración se activa automáticamente. El servicio consumidor no debe usar @EnableFeignClients apuntando a los paquetes de esta librería.

11. Despliegue

El pipeline de Jenkins (Jenkinsfile) consta de dos etapas:

1. Checkout — descarga el código del repositorio.
2. Publish to Artifact Registry — ejecuta mvn deploy -DskipTests para publicar el JAR en Google Artifact Registry.

Parámetro	Valor
JDK	JDK25 (tool Jenkins)
Maven	Maven3 (tool Jenkins)
Repositorio	europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven (Artifact Registry GCP)

No existe Dockerfile ni despliegue como servicio independiente; el artefacto es un JAR publicado en el registro Maven.

Job de Jenkins:

https://jenkins-pi.hawkersco.net/job/auro-client/

12. Manejo de errores y logging

La librería no implementa ninguna estrategia propia de manejo de excepciones ni logging estructurado. Las excepciones de red o HTTP propagadas por RestClient (como RestClientException) son responsabilidad del servicio consumidor.

El parseo del token en AuroClientAutoConfiguration utiliza org.json.JSONObject.getString("token"), lo que lanzará una JSONException si la respuesta del endpoint de autenticación no contiene el campo token.

No hay configuración de logback ni de niveles de log específicos en la librería.

13. Notas y consideraciones

• Doble serialización (Jackson + Gson): Los POJOs del paquete pojo/ contienen anotaciones de Jackson (@JsonProperty) y Gson (@SerializedName) simultáneamente. Esto permite que los microservicios consumidores usen cualquiera de las dos librerías para deserializar las respuestas de Auro. La coexistencia es intencional pero puede generar confusión en mantenimientos futuros.

• Dos instancias de caché independientes: Existe una caché de 1 hora en AuroClientAutoConfiguration (usada por el interceptor de AuroClient) y otra de 5 horas registrada como bean CacheStore<String> en CacheStoreBeans. Esta segunda cache de 5 horas está disponible en el contexto Spring pero no es utilizada internamente por ningún componente de la librería. Los servicios consumidores podrían inyectarla, pero su propósito concreto no está documentado en el código.

• Respuesta String en la mayoría de métodos: Cinco de los seis métodos de AuroClient devuelven ResponseEntity<String> en lugar de un tipo concreto, dejando la deserialización al servicio consumidor. Solo getDocumentos devuelve un tipo tipado (DocumentOrderAuroResponse). Esto puede facilitar la flexibilidad pero reduce la seguridad de tipos.

• Sin tests implementados: El directorio src/test/ no existe. La dependencia spring-boot-starter-test está declarada pero no hay ninguna prueba. Pendiente implementar cobertura.

• AuroClientApplication.java: Existe una clase principal de Spring Boot en el paquete raíz, lo que es inusual para una librería. No tiene funcionalidad operativa y probablemente sea un artefacto residual de la generación inicial del proyecto con Spring Initializr.

• Activación condicional: La propiedad auro.auth.client.url actúa como interruptor de toda la autoconfiguración. Si no está presente, el contexto arranca sin los beans de Auro, lo que es el comportamiento correcto para librerías reutilizables.