Skip to main content

📑 Generador de Addendas XML (msa-facturacion-generador-addendas)

El microservicio Generador de Addendas XML es un componente desacoplado y de alto rendimiento dentro del ecosistema de Facturación Electrónica de Alpura (CFDI 4.0). Su responsabilidad única consiste en recibir la información canónica de facturación (encabezado y detalle), procesarla mediante un motor dinámico de plantillas y reglas de transformación, y generar el fragmento XML correspondiente al nodo <cfdi:Addenda> exigido por cada cadena comercial (Soriana, OXXO, Walmart, Tiendas 3B, Chedraui, Comercial City Fresko, etc.) para comprobantes de Ingreso (I) y Egreso (E).

El microservicio no realiza el timbrado fiscal ni altera el CFDI base; únicamente entrega la addenda estructurada, validada y formateada al orquestador de facturación.


📌 Objetivos Principales​

  • Desacoplamiento del Monolito (Patrón Strategy): Permite la transición gradual y transparente desde el flujo heredado (Legacy / Oracle OBI) hacia un flujo de consulta distribuido y paralelo (Assembled).
  • Concurrencia de Alto Rendimiento (Scatter-Gather): Implementa el patrón Scatter-Gather con Structured Concurrency y Virtual Threads (Java 21 LTS), ejecutando consultas paralelas a los conectores de facturación con política estricta de Fail-Fast.
  • Gobierno por Configuración (Zero-Code / Zero-Downtime): Las plantillas de estructura XML, tokens canónicos, tokens custom (fijos y calculados) y reglas de transformación se gestionan íntegramente en base de datos mediante API REST administrativa sin requerir redespliegues.
  • Motor Híbrido de Renderizado: Compatibilidad 100% con plantillas tradicionales Alpura (placeholders $Token$ y marcador <cfdi:DetalleAddenda/>) y soporte nativo para plantillas modernas basadas en directivas Thymeleaf XML (th:each, th:text, [(${...})]).
  • Coexistencia y Conmutación Controlada: Soporte para alternar entre flujos a voluntad mediante una bandera opcional en el request ("legacy": true/false) o mediante perfiles de Spring Boot (addenda.orchestration.mode).
  • Caché y Rendimiento: Invalidación reactiva de plantillas en caché (L1 Caffeine / L2 Redis) ante eventos de publicación (/publicar).

🏗️ Componentes del Sistema​

ComponenteDescripción
API REST Administrativa y OperativaExpone endpoints para la generación en runtime (/generar), previsualización de borradores (/previsualizar) y administración CRUD de plantillas, tokens y reglas.
Orquestador Strategy (Legacy vs Assembled)Evalúa la precedencia de ruteo (bandera en JSON vs default en Spring) para despachar la petición a la estrategia Legacy (OBI) o Assembled.
Coordinador Scatter-Gather (StructuredTaskScope)Ejecuta en hilos virtuales (VirtualThreads) las consultas concurrentes a los conectores de encabezado, detalle, clientes y rubros con corte inmediato ante cualquier fallo (Fail-Fast).
Conectores de Datos FacturaciónServicios adaptadores (FacturaConnectorService, ClienteConnectorService, PedidoConnectorService, RubrosConnectorService) que consultan el esquema billing.*.
Motor de Reglas y TransformacionesPipeline secuencial que evalúa fórmulas matemáticas BigDecimal, reglas de mapeo condicional (=, <>, =r, <>r) y formateadores de longitud/fecha ({Size_N_M}, {DateFormat_...}).
Motor de Renderizado Thymeleaf XMLInterpreta el contexto estructurado, evalúa tokens y genera el bloque XML final bien formado validando contra XSD (opcional).
DB Relacional (PostgreSQL)Almacena los catálogos de plantillas (cat_addenda_plantillas), tokens canónicos (cat_addenda_tokens), custom tokens (cat_addenda_plantilla_custom_tokens) y bitácora de auditoría.

📖 Contenido de la Documentación​

  • 📐 High-Level Design (HLD): Especificación arquitectónica detallada, diagrama de componentes, flujos de secuencia, motor de reglas, concurrencia estructurada y modelo de datos.
  • 📚 Diccionario de Datos y Catálogo de Defaults: Diccionario formal de entidades, catálogos de plantillas, tokens canónicos estándar, custom tokens, reglas de transformación y matriz de defaults.
  • 🔌 Manual de Integración y Endpoints: Guía práctica de consumo de la API REST, autenticación OAuth2, especificación de contratos, headers y ejemplos de payloads.
  • 📄 Especificación OpenAPI 3.1: Contrato de interfaz OpenAPI descargable con todos los endpoints y esquemas JSON.