theiconic-create-db

1. Descripción general

Según el pom.xml, el proyecto se describe como "Create orders the iconic to db". Es un microservicio batch (runner) que sincroniza pedidos pendientes del marketplace The Iconic con la base de datos de logística, creando el grafo completo de entidades (pedido, marketplace, líneas, envío) y notificando a Slack ante errores.

2. Información técnica

Campo	Valor
artifactId	theiconic-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

Solo 4 clases Java, tal y como describe el CLAUDE.md (verificado):

• TheiconicCreateDbApplication — @SpringBootApplication, punto de entrada. Los clientes REST de theiconic-client y slack-client se autoconfiguran desde esas librerías (@HttpExchange + RestClient).
• TheiconicCreateDbRunner — CommandLineRunner con toda la lógica de negocio: pagina pedidos pendientes, deduplica, crea el grafo de entidades y llama a System.exit().
• TheiconicCreateDbConfig — beans de configuración de Spring.
• TheiconicRestCreateDbUtils — transformación de datos: mapea las respuestas de la API de The Iconic a las entidades del dominio de logística.

flowchart TD
    A[TheiconicCreateDbRunner] -->|getOrdersPending, paginado 100| B[The Iconic Seller Center API]
    A -->|si no existe, sourceId=20| C[(logistics · Order/OrderMarketplace)]
    A -->|OrderMarketplace → Order → OrderLines → Shipment| C
    A -.->|error de shipment con source no registrada| D[Slack]

Flujo: pagina los pedidos pendientes de The Iconic (limit=100); por cada uno, comprueba si ya existe (por sourceId=20 + ID externo) y, si no, elimina cualquier registro huérfano de OrderMarketplace con el mismo número de pedido, genera el nombre interno ("MKTCIC" + 7 dígitos con ceros de relleno, a partir del último OrderMarketplace + 1), crea cliente, pedido, estado de envío (PENDING_SHIPMENT) y líneas, e intenta guardar el envío; si falla por una fuente no registrada, notifica a Slack. Los errores se capturan por pedido sin interrumpir el resto del lote.

4. Dependencias principales

Dependencia	Propósito
spring-boot-starter	Núcleo de Spring Boot (sin web, es un runner CLI)
com.hawkersco:theiconic-client	Cliente @HttpExchange para la API de The Iconic Seller Center
com.hawkersco:logistics-commons	Entidades JPA (Order, OrderMarketplace, OrderLine, etc.) y servicios
com.hawkersco:slack-client	Cliente @HttpExchange para notificaciones
com.hawkersco:pi-function-commons	DateUtils
com.google.code.gson:gson (transitiva)	Serialización del payload crudo del pedido
Lombok (annotation processor)	Generación de código boilerplate

5. API / Endpoints

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

6. Integraciones externas

Sistema	Protocolo	Dirección	Detalle
The Iconic Seller Center API	HTTP REST (TheIconicRestClient)	Entrante	Lectura paginada de pedidos pendientes
Slack	HTTP (SlackClient)	Saliente	Notificación de error cuando la fuente de un envío no está registrada
PostgreSQL (logistics)	JDBC	Saliente	Persistencia de clientes, pedidos, líneas 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), pese a que el CLAUDE.md afirma que este fichero está en .gitignore.

Clave	Descripción
spring.datasource.*	Credenciales de la BD logistics
theiconic.api.url	URL de la API de The Iconic Seller Center
theiconic.api.userId / .key	Credenciales de autenticación de la API
theiconic.api.grantType / .clientId / .clientSecret	Credenciales OAuth client_credentials de The Iconic
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: contraseña de la base de datos PostgreSQL logistics, clave y credenciales OAuth completas de la API de The Iconic (userId, key, clientId, clientSecret), y token de bot de Slack (el mismo ya señalado en otros proyectos de este ecosistema). Ninguno de estos valores se ha reproducido en este documento. Se recomienda:

1. Rotar la contraseña de BD, las credenciales de la API de The Iconic 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, OrderMarketplace, OrderLine, OrderShipmentStatus, Customer. 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 * * * *", concurrencyPolicy: Forbid, activeDeadlineSeconds: 3600). Ú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 The Iconic.

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

# Compilar con tests
./mvnw clean install

# Ejecutar tests
./mvnw test

# Ejecutar la aplicación localmente
./mvnw spring-boot:run

Al ser un CommandLineRunner, no expone Actuator/health: la verificación se hace revisando el log de consola o los pedidos reflejados 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/theiconic-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, con credenciales de cuenta de servicio de GCP montadas por volumen (GOOGLE_APPLICATION_CREDENTIALS), aunque no se ha encontrado uso de APIs de Google en el código de este proyecto (mismo patrón detectado en showroom-update-stock).
• CI/CD (Jenkins): pipeline real de 3 etapas — Checkout → Build & Push → Deploy to GKE. El CLAUDE.md describe un pipeline de 5 etapas (Build → Test → Push → Deployment → Clean) que no coincide con el Jenkinsfile actual (mismo patrón detectado en varios proyectos hermanos de este lote).

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

12. Manejo de errores y logging

No hay una estrategia de excepciones centralizada (no hay @ControllerAdvice, es un runner). processOrder envuelve la creación del grafo de entidades en un único try/catch genérico, registrando Level.SEVERE por pedido sin interrumpir el resto del lote. Un fallo al guardar el envío por una fuente no registrada se notifica explícitamente a Slack. Logging mediante java.util.logging.Logger estándar (consola).

13. Notas y consideraciones

• Importes de envío y subtotal duplicados del total, no calculados: setOrderAmounts asigna el mismo valor (grandTotal) a nmOrderTotalAmt, nmOrderSubtotalAmt y nmOrderShippingAmt — es decir, el subtotal y el gasto de envío almacenados en BD son siempre idénticos al importe total del pedido, en lugar de derivarse del desglose real proporcionado por The Iconic. Solo el impuesto (nmOrderTaxAmt) se calcula aparte (10% del total). Esto no está documentado en CLAUDE.md y puede producir datos financieros incorrectos en reportes que dependan del desglose de subtotal/envío de este marketplace.
• CLAUDE.md afirma que application.properties está en .gitignore, pero el fichero está presente y con credenciales reales legibles directamente en el repositorio de trabajo (mismo patrón detectado en showroom-flash-create-db).
• 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 (las 4 clases, el flujo de ejecución, el formato de nombre de pedido MKTCIC, los valores hardcodeados de sourceId=20, estado PENDING_SHIPMENT, shippingMethodId=1, orderServiceTypeId=7) coincide con el código real, verificado directamente en TheiconicCreateDbRunner y TheiconicRestCreateDbUtils.
• Ver alerta de seguridad en la sección 7 sobre credenciales reales expuestas en application.properties.