SFCC Commons

1. Descripción general

sfcc-commons es una librería Java compartida que proporciona la capa de mapeo XML ↔ Java para los formatos de intercambio de datos de Salesforce Commerce Cloud (SFCC). Los modelos están generados a partir de los esquemas XSD oficiales de SFCC (demandware.com/xml/impex/*) mediante JAXB.

El objetivo es centralizar en un único artefacto todas las clases de dominio necesarias para parsear o construir los XML de importación/exportación de SFCC (pedidos, catálogo, inventario, tarifas, tiendas y devoluciones), de forma que los microservicios consumidores no dupliquen este código ni definan sus propias representaciones.

Se publica como JAR en Google Artifact Registry y se consume como dependencia Maven por otros servicios del ecosistema Hawkers que integran con SFCC.

2. Información técnica

Campo	Valor
artifactId	sfcc-commons
groupId	com.hawkersco
version	1.0.25-SNAPSHOT
Java	25
Spring Boot	4.0.6
Tipo artefacto	JAR (librería)
Módulos	Proyecto único (no multi-módulo)

Spring Boot se usa exclusivamente para gestión de dependencias y build. No existe contexto de aplicación en runtime (no hay @SpringBootApplication activo con lógica de negocio, controladores ni servicios).

3. Arquitectura y diseño

La librería no sigue una arquitectura en capas tradicional. Su estructura es plana por dominio SFCC:

com.hawkersco.sfcccommons/
├── SfccUtils.java                  ← único utilitario no generado
├── catalog/                        ← catálogo de productos (~111 clases)
├── inventory/                      ← inventario/stock (~11 clases)
├── models/
│   ├── order/                      ← pedidos (~61 clases)
│   │   └── comp/                   ← sub-tipos de componentes de pago (2 clases)
│   └── store/                      ← tiendas (~13 clases)
├── pricebook/                      ← tarifas (~14 clases)
└── returned/                       ← devoluciones (2 clases)

Convenciones de nomenclatura

Prefijo	Significado
ComplexType*	Tipos complejos JAXB (mayoría de clases de modelo)
SimpleType*	Enumeraciones JAXB
SharedType*	Tipos reutilizados en múltiples schemas
ObjectFactory	Registry JAXB (@XmlRegistry), uno por paquete

Clases raíz por dominio

Paquete	Clase raíz	Namespace XML
catalog/	Catalog	http://www.demandware.com/xml/impex/catalog/2006-10-31
models/order/	Orders	http://www.demandware.com/xml/impex/order/2006-10-31
inventory/	Inventory	http://www.demandware.com/xml/impex/inventory/2007-05-31
pricebook/	Pricebooks	http://www.demandware.com/xml/impex/pricebook/2006-10-31
models/store/	Stores	Pendiente de verificar
returned/	OrderReturns	Sin namespace estándar SFCC (clase manual)

Patrón JAXB

Todas las clases raíz usan @XmlRootElement + @XmlAccessorType(XmlAccessType.FIELD). Las colecciones se inicializan de forma lazy en el getter:

public List<ComplexTypeOrder> getOrder() {
    if (order == null) {
        order = new ArrayList<>();
    }
    return this.order;
}

SfccUtils

Única clase utilitaria no generada. Mantiene un JAXBContext estático pre-inicializado para Orders (para evitar el coste de creación por cada llamada) y expone dos métodos:

// Parsea un XML de pedidos SFCC y devuelve el objeto raíz
public Orders createOrdersSalesForce(String ordersXml) throws JAXBException

// Parsea y devuelve directamente la lista plana de pedidos
public List<ComplexTypeOrder> getListOrders(String orderXml) throws JAXBException

flowchart LR
    XML["XML string\n(SFCC export)"] -->|SfccUtils.getListOrders| JAXB["JAXBContext\n(estático)"]
    JAXB -->|Unmarshall| Orders["Orders"]
    Orders --> Order["List<ComplexTypeOrder>"]

4. Dependencias principales

Dependencia	Versión	Propósito
spring-boot-starter	4.0.6	Gestión de dependencias / build management
org.glassfish.jaxb:jaxb-runtime	4.0.5	Implementación Jakarta JAXB (marshalling XML)
org.projectlombok:lombok	1.18.42	Generación de código boilerplate en compilación
spring-boot-starter-test	4.0.6	Testing (scope test)
com.google.cloud.artifactregistry:artifactregistry-maven-wagon	2.2.1	Publicación en Google Artifact Registry

5. API / Endpoints

No aplica a este proyecto.

Es una librería JAR. No expone ningún endpoint HTTP.

6. Integraciones externas

Sistema	Protocolo	Dirección	Descripción
Salesforce Commerce Cloud	XML/JAXB	Entrante	Los schemas XSD de SFCC definen el contrato de los modelos
Google Artifact Registry	HTTPS/Maven	Saliente	Publicación del JAR en europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven
Microservicios Hawkers	Maven dep	Saliente	Otros servicios consumen esta librería como dependencia

7. Configuración

No aplica a este proyecto.

Al ser una librería sin runtime de Spring Boot activo, no existe application.yml ni propiedades de configuración. La única configuración relevante es el repositorio de distribución Maven, definido en pom.xml:

Propiedad	Valor (sin credenciales)
distributionManagement.url	artifactregistry://europe-west3-maven.pkg.dev/pi-saldum/pi-repo-maven

La autenticación con Artifact Registry se gestiona mediante la extensión artifactregistry-maven-wagon y las credenciales de la cuenta de servicio del agente de Jenkins (no embebidas en el código).

8. Persistencia

No aplica a este proyecto.

No utiliza ninguna base de datos ni mecanismo de persistencia.

9. Procesos programados y mensajería

No aplica a este proyecto.

No existen jobs @Scheduled, listeners de colas ni runners batch.

10. Ejecución en local

Requisitos previos

• Java 25
• Maven 3.x (o usar el wrapper ./mvnw incluido)
• Acceso a Google Artifact Registry configurado en ~/.m2/settings.xml (para resolver dependencias internas si las hubiera)

Compilar e instalar en repositorio local

# Build sin tests (equivalente al pipeline de CI)
./mvnw -B -DskipTests clean install

# Build con tests (actualmente el directorio de tests está vacío)
./mvnw clean install

Publicar en Artifact Registry (requiere permisos)

./mvnw deploy -DskipTests

Como es una librería, no hay endpoint de health ni servidor que arrancar. La verificación correcta es que mvn install termine con BUILD SUCCESS y el JAR aparezca en ~/.m2/repository/com/hawkersco/sfcc-commons/.

11. Despliegue

El pipeline de Jenkins realiza dos etapas:

1. Checkout: clona el repositorio.
2. Publish to Artifact Registry: ejecuta mvn deploy -DskipTests con JDK25 y Maven3.

El JAR resultante se publica en Google Artifact Registry y queda disponible para todos los microservicios que lo declaren como dependencia Maven.

Job de Jenkins:

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

12. Manejo de errores y logging

• SfccUtils lanza JAXBException en caso de fallo de parseo; la gestión de la excepción queda delegada al consumidor.
• El bloque static de inicialización del JAXBContext lanza ExceptionInInitializerError si JAXB no puede inicializarse, lo que provoca un fallo temprano y explícito en el arranque del servicio consumidor.
• Al ser una librería sin runtime propio, no hay logging configurado ni framework de logs definido.

13. Notas y consideraciones

• Clases generadas: la gran mayoría de clases bajo catalog/, models/order/, inventory/, pricebook/ y models/store/ fueron generadas a partir de los XSD de SFCC (generación original en 2020). Cualquier modificación manual se perderá si se regeneran desde el schema.
• returned/OrderReturns: clase generada manualmente (o adaptada), ya que no sigue el namespace estándar de SFCC (demandware.com/xml/impex). Pendiente de verificar si existe un XSD de origen.
• SfccUtils solo cubre Orders: el JAXBContext estático inicializado es únicamente para Orders. Para parsear Catalog, Inventory, Pricebooks o Stores el consumidor debe crear su propio JAXBContext. No existe utilidad equivalente para los demás dominios.
• Tests vacíos: el directorio src/test existe pero no contiene ningún test. El pipeline omite tests con -DskipTests. Sería recomendable añadir tests de round-trip (marshal/unmarshal) para detectar regresiones al actualizar versiones de JAXB.
• Versión SNAPSHOT: la versión 1.0.25-SNAPSHOT indica que es inestable/en desarrollo. Los consumidores deben usar una versión release en entornos productivos estables.