meli-co-create-db

1. Descripción general

Según el pom.xml, el proyecto se describe como "Mercado libre colombia create orders to DB". Es un microservicio batch (runner) que sincroniza pedidos pagados de Mercado Libre Colombia con la base de datos de logística, y genera las etiquetas de envío (convertidas de ZPL2 a PDF vía Labelary) para los pedidos pendientes.

2. Información técnica

Campo	Valor
artifactId	meli-co-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 2 CommandLineRunner, ambos activos.

Orden	Runner	Propósito
1	MeliCoCreateDbRunner	Obtiene pedidos pagados de Mercado Libre (últimos 7 días, 20 días una vez al día a las 7:00 hora Colombia), en lotes de 50, y los persiste
2	MeliCoGenerateLabelRunner	Genera etiquetas de envío para pedidos PENDING_LABEL; llama a System.exit() al terminar

• .config — MeliCoCreateDbConfig (wiring de beans).
• .utils — MeliCoCreateDbUtils (transformación de datos y persistencia).

flowchart TD
    A["1. MeliCoCreateDbRunner"] -->|pedidos pagados, lotes de 50| B[Mercado Libre API]
    A -->|"MC + PackID/OrderID"| C[(logistics · Order/Shipment)]
    D["2. MeliCoGenerateLabelRunner"] -->|descarga ZPL2| B
    D -->|convierte a PDF| E[Labelary API]
    D -->|sube| F[SFTP servientrega]
    D -->|guarda base64| C

Flujo: el runner 1 obtiene los pedidos pagados de Mercado Libre Colombia (seller_id fijo, estado paid), los transforma y persiste como Order/OrderLine/Customer/Shipment, fijando el estado a REVIEW_ORDER_DIVIDED (fulfillment) o REVIEW_ORDER_DIVIDED_SERVIENTREGA (cross-docking) según el tipo de envío. El runner 2 descarga la etiqueta ZPL2 de los pedidos en PENDING_LABEL, la convierte a PDF vía Labelary, la sube por SFTP a Servientrega, la guarda en Base64 en OrderMarketplace, y actualiza el estado a PENDING_SHIPMENT (o ERROR_LABEL si falla). El identificador de fuente de Mercado Libre Colombia es 59L; el nombre interno del pedido es "MC" + PackID/OrderID.

4. Dependencias principales

Dependencia	Propósito
spring-boot-starter, spring-boot-starter-web	Núcleo de Spring Boot
com.hawkersco:meli-client	Cliente @HttpExchange para la API de Mercado Libre (pedidos, packs, ítems, envíos, etiquetas)
com.hawkersco:pi-generate-credentials-client	Obtención de tokens OAuth2 vía el servicio interno de credenciales
com.hawkersco:labelary-client	Conversión de etiquetas ZPL2 a PDF
com.hawkersco:logistics-commons	Entidades JPA (Order, OrderLine, Shipment, Customer) y servicios
com.hawkersco:slack-client	Notificaciones de error
com.hawkersco:pi-function-commons	Utilidades compartidas

Todas las dependencias internas excluyen explícitamente spring-cloud-starter-openfeign/feign-core, confirmando la migración completa a @HttpExchange/RestClient (sin Feign) en este proyecto y sus librerías compartidas.

5. API / Endpoints

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

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
Mercado Libre API	HTTP REST (MeliCoClient), OAuth2 client_credentials	Entrante/Saliente	Lectura de pedidos pagados, descarga de etiquetas ZPL2
Servicio interno pi-generate-credentials	HTTP	Entrante	Obtención de tokens de acceso a Mercado Libre
Labelary API	HTTP (LabelaryClient)	Saliente	Conversión de etiquetas ZPL2 a PDF
Servidor SFTP (sftp.hawkersco.com, usuario servientrega)	SFTP	Saliente	Subida de etiquetas generadas
Slack	HTTP (SlackClient)	Saliente	Notificaciones de error
PostgreSQL (logistics)	JDBC	Entrante/Saliente	Lectura/escritura de pedidos 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
meli.credentials.url / .granttype / .clientid / .clientsecret	Credenciales OAuth2 client_credentials de Mercado Libre
spring.datasource.*	Credenciales de la BD logistics
labelary.client.url	URL de la API Labelary (pública, sin credenciales)
credentials-client.api.host	URL del servicio interno pi-generate-credentials
ftp.server / .port / .user / .pass / .dir	Credenciales SFTP hacia Servientrega
slack.client.url / .auth.token / .channel.id	Configuración de Slack

⚠️ Alerta de seguridad

El fichero src/main/resources/application.properties (perfil local) contiene actualmente credenciales reales en texto plano: client secret OAuth2 de Mercado Libre, 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 hacia Servientrega, y el token de bot de Slack. Ninguna credencial se ha reproducido en este documento. Se recomienda:

1. Rotar el client secret de Mercado Libre, la contraseña de BD, la contraseña SFTP 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). Entidades relevantes: Order, OrderLine, Shipment, Customer, OrderMarketplace. 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 hora (schedule: "0 * * * *"). Se ejecutan en orden los 2 runners de la tabla de la sección 3; entre lotes de la API de Mercado Libre se espera 5000ms para respetar límites de tasa.

10. Ejecución en local

Requisitos previos: JDK 25, Maven, acceso a la BD logistics, credenciales válidas de Mercado Libre y del servidor SFTP.

# Compilar sin tests
./mvnw clean install -DskipTests

# Compilar con tests
./mvnw clean install

# Ejecutar tests
./mvnw test

# Ejecutar el JAR
java -jar target/meli-co-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 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/meli-co-create-db:<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 hora.
• CI/CD (Jenkins): pipeline real de 3 etapas — Checkout → Build & Push → Deploy to GKE.

Job de Jenkins: https://jenkins-pi.hawkersco.net/job/meli-co-create-db/

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). Los errores de generación de etiqueta marcan el pedido como ERROR_LABEL; los estados DELIVERED/CANCELLED tienen su propia lógica de recuperación (DELIVERED → INIT, CANCELLED → actualiza y omite). Logging mediante java.util.logging.Logger/SLF4J según la clase.

13. Notas y consideraciones

• CLAUDE.md verificado y consistente con el código: el orden de ejecución de los 2 runners, la máquina de estados del pedido, los identificadores clave (59L, prefijo "MC") y los clientes externos coinciden con lo observado directamente en MeliCoCreateDbRunner y MeliCoGenerateLabelRunner. Es uno de los CLAUDE.md más precisos de este lote.
• Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties.