meli-create-db

1. Descripción general

Según el pom.xml, el proyecto se describe como "Mercado libre create orders to DB". Es un microservicio batch (runner) que sincroniza pedidos pagados de Mercado Libre México con la base de datos de logística, y genera las etiquetas de envío enrutando cada pedido según su tipo de fulfillment (Cubbo para cross-docking, 99minutos para fulfillment propio).

2. Información técnica

Campo	Valor
`artifactId`	`meli-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	`MeliCreateDbRunner`	Obtiene pedidos pagados del vendedor `213735934`, deduplica y persiste `Customer → Order → Shipment → OrderMarketplace`
2	`MeliGenerateLabelRunner`	Procesa pedidos `PENDING_LABEL`/`PENDING_LABEL_CALM`, enruta por tipo de fulfillment y genera la etiqueta; llama a `System.exit()` al terminar

.config — MeliCreateDbConfig (más de 20 beans de servicios de logistics-commons).
.utils — MeliCreateDbUtils (transformación de datos; obtiene el SKU del ítem desde la API de Meli cuando no viene en la respuesta del pedido).

flowchart TD
    A["1. MeliCreateDbRunner"] -->|pedidos pagados vendedor 213735934, lotes de 50| B[Mercado Libre API]
    A --> C[(logistics · Order/Shipment)]
    D["2. MeliGenerateLabelRunner"] -->|"cross_docking / xd_drop_off"| E[REVIEW_ORDER_DIVIDED_CUBBO]
    D -->|fulfillment| F[REVIEW_ORDER_DIVIDED · 99minutos]
    D -->|ZPL → PDF| G[Labelary API]
    D -->|guarda base64| C

Flujo: el runner 1 pagina los pedidos pagados del vendedor (retrospectiva de 1 día habitualmente, 15 días a las 11:00 y 23:00), con 5 segundos de espera entre lotes; los transforma y persiste. El runner 2 procesa los pedidos pendientes de etiqueta, los enruta según el tipo de fulfillment (Cubbo o 99minutos), descarga la etiqueta ZPL de Meli, la convierte a PDF vía Labelary, y la guarda en Base64 en BD.

4. Dependencias principales

Dependencia	Propósito
`spring-boot-starter`	Núcleo de Spring Boot (sin web, es un runner CLI)
`com.hawkersco:meli-client`	Cliente `@HttpExchange` para la API de Mercado Libre
`com.hawkersco:labelary-client`	Conversión de etiquetas ZPL a PDF
`com.hawkersco:logistics-commons`	Entidades JPA (`Order`, `Customer`, `Shipment`, `OrderMarketplace`) y servicios
`com.hawkersco:slack-client`	Notificaciones de error
`com.hawkersco:pi-function-commons`	Utilidades de fecha/directorio/zip

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 (`MeliClient`), OAuth2 `client_credentials`	Entrante	Lectura de pedidos pagados y descarga de etiquetas ZPL
Labelary API	HTTP (`LabelaryClient`)	Saliente	Conversión de etiquetas ZPL a PDF
Servidor SFTP (`sftp.hawkersco.com`, usuario `logisfashion`)	SFTP	Saliente	Integración con logística LogisFashion
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 (directamente en propiedades, sin pasar por el servicio interno de credenciales)
`spring.datasource.*`	Credenciales de la BD `logistics`
`logisfashion.ftp.*`	Credenciales SFTP para la integración LogisFashion
`labelary.client.url`	URL de la API Labelary (pública)
`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), y la contraseña SFTP de LogisFashion. Ninguna credencial se ha reproducido en este documento. Se recomienda:

Rotar el client secret de Mercado Libre, la contraseña de BD y la contraseña SFTP.
Sustituir los valores hardcodeados de application.properties por credenciales de un entorno de desarrollo aislado.
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, Customer, Shipment, 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, que ejecuta el contenedor cada hora (schedule: "0 * * * *"). 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 y credenciales válidas de Mercado Libre.

# Compilar
./mvnw clean install

# Compilar sin tests (CI/CD)
sudo mvn -B -DskipTests clean install

# Ejecutar el JAR
java -Xmx2g -jar target/meli-create-db.jar

No hay tests automatizados configurados en este repositorio. 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-create-db:<tag>.
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. El CLAUDE.md describe escaneo KICS y análisis SonarQube que no aparecen en el Jenkinsfile actual (mismo patrón detectado en varios proyectos hermanos de este lote).

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

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). Los errores se notifican a Slack; logging mediante java.util.logging.Logger/SLF4J según la clase.

13. Notas y consideraciones

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 (los 2 runners y su orden, el enrutamiento por tipo de fulfillment, la retrospectiva de 1/15 días, el uso de Labelary) coincide con el código real, verificado directamente en MeliCreateDbRunner y MeliGenerateLabelRunner.
Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties.

1. Descripción general​

2. Información técnica​

3. Arquitectura y diseño​

4. Dependencias principales​

5. API / Endpoints​

6. Integraciones externas​

7. Configuración​

⚠️ Alerta de seguridad​

8. Persistencia​

9. Procesos programados y mensajería​

10. Ejecución en local​

11. Despliegue​

12. Manejo de errores y logging​

13. Notas y consideraciones​