📑 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
| Componente | Descripción |
|---|---|
| API REST Administrativa y Operativa | Expone 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ón | Servicios adaptadores (FacturaConnectorService, ClienteConnectorService, PedidoConnectorService, RubrosConnectorService) que consultan el esquema billing.*. |
| Motor de Reglas y Transformaciones | Pipeline 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 XML | Interpreta 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.