Documento de Diseño de Alto Nivel (HLD)
Microservicio Generador de Addendas XML (msa-facturacion-generador-addendas)
| Atributo | Detalle |
|---|---|
| Proyecto | Nueva Facturación Electrónica Alpura |
| Componente | msa-facturacion-generador-addendas |
| Versión del Documento | 1.0.0 |
| Fecha | Noviembre 2026 |
| Estado | Aprobado para Construcción |
| Referencias | Diccionario de Datos, Manual de Endpoints, 17 Diagramas de Arquitectura (Sección 6) |
1. Resumen Ejecutivo y Alcance
El microservicio Generador de Addendas es una pieza central en el ecosistema de facturación electrónica de Alpura. Su responsabilidad única consiste en recibir la información de facturación (encabezado y detalle), procesarla mediante un motor dinámico desacoplado y generar el nodo XML <cfdi:Addenda> correspondiente a cada cadena comercial (Soriana, OXXO, Walmart, Tiendas 3B, etc.).
El microservicio no realiza el timbrado fiscal ni la alteración del CFDI base; únicamente entrega la addenda estructurada y validada al sistema de facturación.
1.1 Objetivos Principales
- Desacoplamiento del Monolito: Permitir la transición gradual desde el flujo heredado (Legacy / OBI) hacia un flujo de consulta distribuido y paralelo (Assembled).
- Concurrencia de Alto Rendimiento: Implementar el patrón Scatter-Gather con Structured Concurrency (Java 21) y política estricta de Fail-Fast.
- Gobierno por Configuración: Las plantillas de estructura, placeholders (tokens), reglas de transformación y reglas de cálculo se gestionan en base de datos sin requerir redespliegues.
- Coexistencia y Conmutación Controlada: Soporte para alternar flujos a voluntad mediante bandera opcional en la petición REST o mediante configuración default de Spring Boot.
2. Decisiones de Arquitectura y Principios de Diseño
2.1 Stack Tecnológico
- Lenguaje: Java 21 LTS (Uso intensivo de Virtual Threads y
StructuredTaskScope). - Framework: Spring Boot 3.x.
- Estilo Arquitectural: Arquitectura Hexagonal (Puertos y Adaptadores) / Clean Architecture.
- Motor de Base de Datos: PostgreSQL corporativo.
- Esquema de Base de Datos: Mismo esquema de facturación (no existe esquema aislado de addendas).
- Gestión de Migraciones: Liquibase mediante changelogs versionados.
- Caché: Caffeine (en memoria local) / Redis distribuido con invalidación reactiva por evento de publicación.
- Seguridad: OAuth2 Resource Server con validación stateless de tokens JWT.
2.2 Política de Datos Semilla
[!IMPORTANT] Datos Semilla Exclusivos para Pruebas: Las configuraciones semilla (las 7 cadenas comerciales del alcance inicial definidas en especificación de alcance inicial) son utilizadas únicamente para ambientes de prueba (QA, Testcontainers, pruebas unitarias y golden files) mediante contextos Liquibase (
context: test,qa). En ambientes productivos, ninguna addenda estará cableada ni precargada por scripts DML; todas las configuraciones se darán de alta mediante la API REST administrativa.
3. Modelo de Decisión y Ruteo de Flujos (Legacy vs Assembled)
El microservicio desacopla la fuente de datos mediante el patrón Strategy, soportando dos implementaciones:
LegacyOracleAddendaStrategy(Flujo OBI heredado).AssembledAddendaStrategy(Flujo concurrente Scatter-Gather).
3.1 Precedencia de Decisión
El ruteo hacia la estrategia correspondiente se determina mediante el siguiente flujo de decisión:
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_precedencia_decision.mmd.
- Prioridad 1 (Bandera en Petición): El cliente puede enviar el campo opcional
"legacy": true | false."legacy": true$\rightarrow$ Fuerza la ejecución por el servicio OBI heredado."legacy": false$\rightarrow$ Fuerza la ejecución por el flujo ensamblado moderno.
- Prioridad 2 (Configuración de Spring): Si la bandera no viene en la petición (
null), se adopta el valor configurado en el perfil activo de Spring (@Profile("assembled" | "legacy")) o en la propiedadaddenda.orchestration.modedelapplication.yml.
4. Arquitectura del Flujo Assembled (Scatter-Gather & Fail-Fast)
El flujo assembled consulta concurrentemente múltiples fuentes heterogéneas mediante servicios internos de Spring que actúan como conectores locales protegidos por Circuit Breaker (Resilience4j).
4.1 Conectores Spring Internos y Fuentes Externas
Los conectores no son microservicios externos; son Spring Services componentes del propio microservicio:
FacturaConnectorService(HeaderConnectorPort): Conexión vía JDBC haciaDB Billing.ClienteConnectorService(ClientConnectorPort): Conexión vía HTTP REST haciaCat Generales.PedidoConnectorService(ItemsConnectorPort): Conexión vía OJDBC haciaOracle EBS.RubrosConnectorService(TaxesConnectorPort): Conexión vía JDBC haciaAS400.
4.2 Topología de Ejecución con Concurrencia Estructurada
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
// 1. Scatter (Fan-Out) en Virtual Threads
Subtask<AddendaHeader> subHeader = scope.fork(() -> facturaConnector.fetchHeader(invoiceId));
Subtask<AddendaClient> subClient = scope.fork(() -> clienteConnector.fetchClient(invoiceId));
Subtask<AddendaItems> subItems = scope.fork(() -> pedidoConnector.fetchItems(invoiceId));
Subtask<AddendaTaxes> subTaxes = scope.fork(() -> rubrosConnector.fetchTaxes(invoiceId));
// 2. Coordinación y Deadline Global
scope.joinUntil(deadline);
// 3. Fail-Fast
scope.throwIfFailed(throwable -> new AddendaAssemblyException("Fallo en conector de addenda", throwable));
// 4. Gather (Fan-In)
return aggregator.aggregate(subHeader.get(), subClient.get(), subItems.get(), subTaxes.get());
}
4.3 Política Estricta de Fail-Fast
- Cancelación Inmediata: Si cualquiera de los 4 conectores lanza una excepción o excede su timeout local,
StructuredTaskScopeejecutashutdown(). - Interrupción de Hilos: Se emite de inmediato
Thread.interrupt()a las tareas hermanas que continúen activas. - Liberación de Recursos: No se esperan hilos lentos; los sockets I/O y conexiones JDBC se cierran de inmediato, eliminando fugas de memoria y tareas huérfanas (orphan tasks).
5. Motor de Generación de Addendas (Plantillas, Tokens, Campos Custom y Reglas)
Una vez resuelto el payload unificado (proveniente de Assembled o de Legacy), el motor interno procesa la addenda según los lineamientos de la historia especificación de alcance inicial.
5.1 Modelo de Datos Normalizado (PostgreSQL / Esquema Facturación)
El almacenamiento y gobierno del motor de addendas se gestiona dentro del esquema de facturación mediante un modelo relacional normalizado compuesto por tres componentes esenciales:
- Catálogo de Plantillas (
cat_addenda_plantillas): Almacena las plantillas maestras en XML (encabezado y detalle) por cadena, cliente, tipo de comprobante y versión de vigencia. - Catálogo Global de Tokens (
cat_addenda_tokens): Diccionario canónico de placeholders disponibles, clasificados obligatoriamente por su tipo/origen (FACTURA,CLIENTE,PEDIDO,RUBROS_IMPUESTOS,SISTEMA_CFDI) con indicación explícita del conector asociado, sistema fuente y método de extracción ("de dónde y cómo"). - Catálogo de Campos/Tokens Custom por Plantilla (
cat_addenda_plantilla_custom_tokens): Tokens o campos adicionales definidos directamente sobre la plantilla para cubrir requerimientos específicos de clientes que demandan valores literales fijos o cálculos aritméticos dinámicos basados en tokens del catálogo global.
5.1.1 Diagrama Entidad-Relación (ERD)
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_erd_modelo_datos.mmd.
5.1.2 Especificación Detallada de Tablas
A. Tabla cat_addenda_plantillas (Catálogo de Plantillas de Addendas)
Registra la definición XML de las addendas por cliente/cadena, tipo de comprobante y vigencia:
| Campo | Tipo SQL | Nulable | Descripción |
|---|---|---|---|
id_plantilla | BIGSERIAL / BIGINT | No (PK) | Identificador único de la plantilla. |
cadena_codigo | VARCHAR(50) | No | Clave de la cadena o cliente (ej. TIENDAS_SORIANA, OXXO_CONSOLIDADA, LIVERPOOL). |
numero_cliente | VARCHAR(255) | Sí | Identificador(es) de cliente Alpura asociados (admite listas o comodín). |
rfc_receptor | VARCHAR(13) | Sí | RFC receptor asociado para ruteo por identidad fiscal. |
gln_receptor | VARCHAR(20) | Sí | Global Location Number (GLN) del cliente receptor. |
tipo_comprobante | VARCHAR(5) | No | I (Ingreso/Factura) o E (Egreso/Nota de Crédito). |
version | VARCHAR(20) | No | Etiqueta de versión (ej. 2026-11-01, v1.2). |
fecha_inicio_vigencia | TIMESTAMP WITH TIME ZONE | No | Inicio de vigor para comprobantes emitidos desde esta fecha. |
fecha_fin_vigencia | TIMESTAMP WITH TIME ZONE | Sí | Fin de vigor (NULL = vigente indefinidamente hasta nueva versión). |
estado | VARCHAR(20) | No | Estado de ciclo de vida: BORRADOR, PUBLICADA, RETIRADA. |
xml_plantilla_encabezado | TEXT | No | Plantilla XML completa de encabezado conteniendo placeholders $Token$ y el marcador <cfdi:DetalleAddenda/>. |
xml_plantilla_detalle | TEXT | No | Plantilla XML del nodo repetitivo de cada partida conteniendo $Detalle...$. |
xsd_schema | TEXT | Sí | Esquema XSD o URL para validación estructural del resultado final. |
descripcion | VARCHAR(500) | Sí | Justificación técnica y notas de cambio de la versión. |
dn_usuario_creador | VARCHAR(255) | No | Auditoría: Usuario creador. |
dd_fecha_creacion | TIMESTAMP | No | Auditoría: Fecha de creación. |
dn_usuario_modificador | VARCHAR(255) | No | Auditoría: Último usuario que modificó. |
dd_fecha_modificacion | TIMESTAMP | No | Auditoría: Fecha de última modificación. |
dn_activo | BOOLEAN | No | Auditoría: Borrado lógico (TRUE/FALSE). |
B. Tabla cat_addenda_tokens (Catálogo Global de Tokens y Mapeo de Origen)
Gobierna todos los tokens disponibles en la plataforma, tipificando su origen para que el motor sepa con exactitud de dónde y cómo obtener la información:
| Campo | Tipo SQL | Nulable | Descripción |
|---|---|---|---|
id_token | BIGSERIAL / BIGINT | No (PK) | Identificador único del token. |
clave_token | VARCHAR(100) | No (UK) | Nombre canónico delimitado por $ (ej. $EncabezadoserieComprobante$, $ClienteRFC$, $Detallecantidad$). |
nombre | VARCHAR(150) | No | Etiqueta funcional amigable para UI de administración. |
tipo_origen | VARCHAR(40) | No | Clasificación de Origen: FACTURA, CLIENTE, PEDIDO, RUBROS_IMPUESTOS, SISTEMA_CFDI. |
conector_asociado | VARCHAR(60) | No | Conector Spring responsable: FacturaConnectorService, ClienteConnectorService, PedidoConnectorService, RubrosConnectorService. |
sistema_fuente | VARCHAR(50) | No | Sistema base empresarial: DB Billing, Cat Generales, Oracle EBS, AS400, CFDI_BASE. |
campo_origen_path | VARCHAR(200) | No | Atributo o ruta en DTO/fuente (ej. serieComprobante, clienteId, sku, tasa, extraAttributes['GLN_SUCURSAL']). |
estrategia_extraccion | VARCHAR(40) | No | Método de extracción: DIRECT_DTO_FIELD, JSON_PATH, SQL_COLUMN, COMPUTED. |
alcance | VARCHAR(20) | No | Nivel de aplicación: ENCABEZADO o DETALLE. |
tipo_dato | VARCHAR(20) | No | Tipo semántico: STRING, NUMERIC, INTEGER, DATE, DATETIME, BOOLEAN. |
formato_default | VARCHAR(50) | Sí | Formato sugerido por defecto (ej. yyyy-MM-dd, 0.00). |
es_obligatorio | BOOLEAN | No | TRUE si el comprobante no puede emitirse sin este dato. Default: FALSE. |
valor_default | VARCHAR(255) | Sí | Valor de reemplazo si la fuente externa entrega nulo. |
descripcion | TEXT | Sí | Documentación detallada sobre el significado y obtención del dato. |
dn_usuario_creador | VARCHAR(255) | No | Auditoría: Usuario creador. |
dd_fecha_creacion | TIMESTAMP | No | Auditoría: Fecha de creación. |
dn_usuario_modificador | VARCHAR(255) | No | Auditoría: Usuario modificador. |
dd_fecha_modificacion | TIMESTAMP | No | Auditoría: Fecha de modificación. |
dn_activo | BOOLEAN | No | Auditoría: Borrado lógico (TRUE/FALSE). |
C. Tabla cat_addenda_plantilla_custom_tokens (Campos y Tokens Custom en Plantilla)
Permite asociar campos personalizados a una plantilla en particular, ya sea con valores literales fijos o con fórmulas matemáticas dinámicas:
| Campo | Tipo SQL | Nulable | Descripción |
|---|---|---|---|
id_custom_token | BIGSERIAL / BIGINT | No (PK) | Identificador único del token custom. |
id_plantilla | BIGINT | No (FK) | Clave foránea hacia cat_addenda_plantillas(id_plantilla). |
clave_token_custom | VARCHAR(100) | No | Placeholder asignado (ej. $CustomNumAcreedor$, $CustomFactorDescuento$, $DetalleCustomNeto$). |
alcance | VARCHAR(20) | No | Nivel del token: ENCABEZADO o DETALLE. |
tipo_valor | VARCHAR(20) | No | Naturaleza del campo: FIJO (literal estático) o CALCULADO (fórmula matemática). |
valor_fijo | TEXT | Sí | Texto constante asignado por el cliente cuando tipo_valor = 'FIJO' (ej. "ATZ 983527", "002"). |
expresion_calculo | TEXT | Sí | Expresión matemática cuando tipo_valor = 'CALCULADO'. Utiliza tokens del catálogo (ej. "$Detallecantidad$ * $DetalleprecioUnitario$"). |
tokens_dependientes | JSONB / TEXT | Sí | Arreglo JSON de tokens requeridos por la fórmula para validar dependencias. |
tipo_dato_resultado | VARCHAR(20) | No | Tipo resultante: NUMERIC, STRING, INTEGER, DATE. |
escala_decimales | INTEGER | No | Número de decimales para resultados numéricos (default: 2). |
tipo_redondeo | VARCHAR(20) | No | Algoritmo de redondeo: HALF_UP, HALF_EVEN, CEILING, FLOOR. Default: HALF_UP. |
orden_evaluacion | INTEGER | No | Secuencia de resolución (1, 2, 3...) para permitir cálculos en cascada. Default: 1. |
descripcion | VARCHAR(500) | Sí | Justificación de negocio para el requerimiento del cliente. |
dn_usuario_creador | VARCHAR(255) | No | Auditoría: Usuario creador. |
dd_fecha_creacion | TIMESTAMP | No | Auditoría: Fecha de creación. |
dn_usuario_modificador | VARCHAR(255) | No | Auditoría: Usuario modificador. |
dd_fecha_modificacion | TIMESTAMP | No | Auditoría: Fecha de modificación. |
dn_activo | BOOLEAN | No | Auditoría: Borrado lógico (TRUE/FALSE). |
5.2 Tipificación de Tokens y Mapeo de Origen ("De Dónde y Cómo")
Para garantizar que el orquestador y el motor conozcan de dónde y cómo obtener cada token sin acoplamientos rígidos en código duro, el catálogo cat_addenda_tokens clasifica cada dato según su fuente empresarial y conector interno:
Tipo de Origen (tipo_origen) | Conector Spring (conector_asociado) | Puerto Hexagonal | Sistema Fuente (sistema_fuente) | Datos Típicos Obtenidos |
|---|---|---|---|---|
FACTURA | FacturaConnectorService | IHeaderConnectorPort | DB Billing | Serie, folio, fecha comprobante, subtotal, total, moneda, tipo de cambio, condiciones de pago. |
CLIENTE | ClienteConnectorService | IClientConnectorPort | Cat Generales | ID de cliente, RFC receptor, razón social, GLN receptor, número de sucursal, domicilio fiscal, calle, CP. |
PEDIDO | PedidoConnectorService | IItemsConnectorPort | Oracle EBS | Número de orden de compra, fecha OC, número de línea/partida, SKU/código material, descripción, cantidad, unidad de medida (UOM), precio unitario, importe. |
RUBROS_IMPUESTOS | RubrosConnectorService | ITaxesConnectorPort | AS400 | Desglose de impuestos trasladados/retenidos: tipo (IVA, IEPS), base, tasa o cuota, importe de impuesto, retenciones. |
SISTEMA_CFDI | Interno / Timbrado | N/A | CFDI Base | UUID del comprobante fiscal, fecha/hora de timbrado SAT, sello digital, número de certificado emisor. |
5.2.1 Proceso de Extracción Guiado por Metadatos
- Inspección Previa de la Plantilla: Al cargarse la plantilla, el analizador léxico identifica todos los tokens presentes en el XML y en las fórmulas de los tokens custom.
- Determinación de Conectores Requeridos: Se consultan las definiciones en
cat_addenda_tokenspara los tokens identificados. Si una addenda solo requiere tokens deFACTURAyPEDIDO, el orquestador evita invocar fuentes innecesarias o prioriza la resolución. - Extracción Determinista de Propiedades: Al recibir los VOs (
AddendaHeaderVO,AddendaClientVO,AddendaItemsVO,AddendaTaxesVO), el componenteTokenOriginResolverconsultacampo_origen_pathyestrategia_extraccionpara poblar el mapa centralizado de variables:// Ejemplo conceptual del mapa resuelto en memoria:Map<String, Object> tokenContext = new HashMap<>();tokenContext.put("$EncabezadoserieComprobante$", headerVO.getSerieComprobante());tokenContext.put("$ClienteRFC$", clientVO.getRfcReceptor());tokenContext.put("$Detallecantidad$", itemVO.getCantidad());tokenContext.put("$DetalleprecioUnitario$", itemVO.getPrecioUnitario());
5.3 Motor de Reglas de Cálculo y Tokens Custom (Alineación HU-TEC-ADD-02)
Para dar estricto cumplimiento a los requerimientos de la historia de usuario técnica HU-TEC-ADD-02 y a la compatibilidad con el ecosistema de facturación Alpura (ref. docs/oldAddenda.md), el motor implementa un subsistema robusto de evaluación de cálculos que unifica las reglas de cálculo dinámicas (columna Excel Reglas calculo: [{"respuesta": "$Token$", "expresion": "..."}]) y los tokens custom de plantilla (cat_addenda_plantilla_custom_tokens con tipo_valor = 'CALCULADO').
5.3.1 Catálogo Exhaustivo de Reglas de Cálculo Soportadas
El motor soporta todas las variantes de fórmulas aritméticas y transformaciones matemáticas requeridas en el negocio:
| Categoría de Cálculo | Caso de Uso / Cadena en HU2 | Expresión de Ejemplo | Descripción y Manejo |
|---|---|---|---|
| Prorrateos y Porcentajes Globales | Tiendas Tres B (HU2 / CA5) | $ResultadosDescuentos$ = $Encabezadodescuentos$ / $Encabezadototal$ | Calcula el porcentaje de descuento global sobre el comprobante. Requiere división segura con escala decimal configurable. |
| Conversión de Factores UOM (Unidad de Medida) | Clientes CJA / Factor (ref. oldAddenda.md) | $DetalleprecioUnitarioCaja$ = $DetalleprecioUnitario$ * $DetallefactorConversion$$Detallecantidad$ = $Detallecantidad$ / $DetallefactorConversion$ | Homologación automática cuando unidadMedida == 'CJA', recalculando precio por caja y cantidad de cajas según el catálogo de conversión. |
| Importes Netos y Bases Imponibles por Partida | General / Soriana / Sánchez (HU2 / CA16) | $DetalleCustomNeto$ = ($Detalleimporte$ - $DetalleDescuento$) / $Detallecantidad$$DetalleCustomImporteNeto$ = $Detalleimporte$ + $DetalleimpuestoIVA$ | Deducción de descuentos de línea o suma de impuestos para obtener importes netos unitarios o totales de partida. |
| Cálculo Dinámico de Impuestos | Tiendas Garcés / Tres B (HU2) | $DetalleMontoIvaCalculado$ = $Detalleimporte$ * ($DetalleTasaIVA$ / 100)$DetalleTotalImpuestos$ = $DetallemontoIva$ + $DetallemontoIeps$ | Aplicación de alícuotas porcentuales o sumatoria de traslados/retenciones desglosados. |
| Totales Agregados de Comprobante | Totales EDI / AMC 7.1 (ref. oldAddenda.md) | $EncabezadoTotalSegmentos$ = (apostrofesHeader - 2) + (apostrofesDetail * cantDetalles)$EncabezadoSumaCantidadTotal$ = SUM($Detallecantidad$)$EncabezadoNumLineas$ = COUNT(detalles) | Conteo de segmentos EDI/apóstrofes, sumatoria acumulada de piezas/cajas y conteo de partidas del comprobante. |
| Cálculos en Cascada / Dependientes | Cadenas con fórmulas compuestas | Paso 1 (orden 1): $DetalleNeto$ = $Detalleimporte$ - $DetalleDescuento$Paso 2 (orden 2): $DetalleIvaNeto$ = $DetalleNeto$ * 0.16Paso 3 (orden 3): $DetalleTotalLinea$ = $DetalleNeto$ + $DetalleIvaNeto$ | Secuenciación determinista mediante orden_evaluacion, inyectando resultados parciales en el contexto para tokens subsiguientes. |
5.3.2 Operadores Matemáticos, Funciones y Sintaxis Soportada
- Operadores aritméticos estándar: Suma (
+), Resta (-), Multiplicación (*), División (/), Módulo (%). - Precedencia y agrupación: Paréntesis anidados
( )para alterar el orden algebraico de las operaciones. - Funciones matemáticas acotadas:
abs(x)(valor absoluto),round(x, d)(redondeo a $d$ decimales),min(a, b),max(a, b),ceil(x),floor(x). - Identificadores de tokens: Los tokens en las expresiones utilizan la sintaxis canónica delimitada por signos de dólar (ej.
$Encabezadodescuentos$,$Detallecantidad$), resolviéndose dinámicamente contra el contexto de tokens del comprobante.
5.3.3 Control de Precisión Financiera y Redondeo (BigDecimal)
Para evitar errores de punto flotante binario (IEEE 754 de Double/Float), el motor procesa todas las evaluaciones monetarias utilizando java.math.BigDecimal y java.math.MathContext:
- Escala de decimales (
escala_decimales): Configurable por token o regla (default:2). Admite precisión extendida (ej.4a6decimales) para precios unitarios de productos lácteos a granel. - Modo de redondeo (
tipo_redondeo):HALF_UP(Estándar fiscal SAT y regla predeterminada de negocio Alpura).HALF_EVEN(Redondeo bancario / contable).CEILING/FLOOR(Para ajustes específicos de cuotas de transporte o bultos).
5.3.4 Resiliencia y Reglas de Seguridad en la Evaluación
- Protección ante División entre Cero (Zero-Division Protection):
- Si en una expresión como
$Encabezadodescuentos$ / $Encabezadototal$el divisor$Encabezadototal$es0,0.00o nulo, el evaluador no propagaArithmeticException; en su lugar, asigna de forma segura el valor de fallback configurado (predeterminado:0.00) y registra un evento informativo en las advertencias del payload (advertencias).
- Si en una expresión como
- Coerción Segura de Nulos y Cadenas No Numéricas (Safe Null Coercion):
- Si un token referenciado en la expresión matemática no fue provisto o viene como cadena vacía (
""), se normaliza automáticamente aBigDecimal.ZERO(o aBigDecimal.ONEsi actúa como factor multiplicador neutro). - Los valores numéricos con comas de miles (ej.
"1,250.50") se limpian y normalizan automáticamente antes del cálculo.
- Si un token referenciado en la expresión matemática no fue provisto o viene como cadena vacía (
- Entorno Seguro de Evaluación (Sandboxed Evaluation):
- Para evitar inyección de código arbitrario o explotación de vulnerabilidades RCE, la evaluación se ejecuta mediante un motor estrictamente acotado:
- SpEL Seguro:
org.springframework.expression.spel.support.SimpleEvaluationContextconfigurado exclusivamente para lectura de propiedades y evaluación matemática, bloqueando acceso ajava.lang.Runtime,java.lang.System, reflexión o carga de clases. - Evaluador Aritmético Dedicado: Integración con analizador matemático puro tipo
exp4j(net.objecthunter.exp4j.ExpressionBuilder) o parser SpEL matemático, garantizando que solo se procesen expresiones algebraicas válidas.
- SpEL Seguro:
- Para evitar inyección de código arbitrario o explotación de vulnerabilidades RCE, la evaluación se ejecuta mediante un motor estrictamente acotado:
5.4 Fases del Procesamiento Integral de la Plantilla
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_fases_procesamiento.mmd.
- Recuperación y Caché: Búsqueda en
cat_addenda_plantillasde la versión publicada vigente a la fecha de emisión del comprobante (gestionada en caché local Caffeine / distribuida Redis). - Extracción de Tokens de Origen: Resolución de los tokens estándar a través de los DTOs devueltos por los conectores de Spring (
FacturaConnectorService,ClienteConnectorService,PedidoConnectorService,RubrosConnectorService) según las definiciones decat_addenda_tokens. - Resolución de Tokens Custom Fijos: Inyección de valores literales constantes definidos en la plantilla (
tipo_valor = 'FIJO'). - Evaluación de Reglas de Cálculo y Tokens Custom Calculados: Ejecución secuencial de expresiones aritméticas sobre tokens del catálogo en orden ascendente de
orden_evaluacion, aplicando precisiónBigDecimal, control de redondeo y protección contra división entre cero. - Evaluación de Reglas de Transformación Condicional: Operaciones
=,<>,=r(con token destino) y<>rpara homologaciones de unidades de medida (UOM) o mapeos condicionales. - Resolución de Modificadores de Formato: Aplicación de modificadores de longitud fija (
{Size_N}) con relleno configurable y formateadores de fecha ({yyMMdd}). - Poblado del Contexto Thymeleaf: Construcción de
org.thymeleaf.context.Contextcon todas las variables del comprobante, mapa plano de tokens, variables custom y utilitarios#mathy#dates. - Renderizado de Detalle y Encabezado con Thymeleaf: Procesamiento de las partidas de detalle y la cabecera mediante el motor
TemplateMode.XMLde Thymeleaf. - Saneamiento y Validación XML: Escape automático de caracteres especiales (
&,<,>,",'), verificación de XML bien formado y validación opcional contra XSD.
5.5 Arquitectura del Motor de Renderizado XML con Thymeleaf (Thymeleaf XML Engine)
El microservicio utiliza Thymeleaf 3.x (spring-boot-starter-thymeleaf) como su motor central de procesamiento de plantillas XML. Esta decisión arquitectónica sustituye los reemplazos frágiles por expresiones regulares de texto por un motor de plantillas XML maduro, robusto, altamente optimizado y consciente de la estructura del documento.
5.5.1 Ventajas Técnicas de Thymeleaf en Modo XML
- Escape Seguro de Caracteres Especiales: Manejo automático de entidades XML (
&,<,>,",'). Evita que razones sociales con ampersands (ej."SANCHEZ & ASOCIADOS S.A.") o descripciones con caracteres reservados corrompan el árbol XML final. - Preservación Estricta de Namespaces: Garantiza la integridad de los prefijos y esquemas fiscales SAT (
xmlns:cfdi="http://www.sat.gob.mx/cfd/4") y comerciales (xmlns:oxxo,xmlns:detallista, etc.). - Potencia de Expresiones y Formateo: Integración nativa con Spring Expression Language (SpEL) y objetos de utilidad de contexto (
#numbers.formatDecimal(...),#temporals.format(...), etc.). - Caché en Memoria de Plantillas Compiladas: Thymeleaf compila los árboles de plantillas a estructuras en memoria optimizadas, eliminando la sobrecarga de re-parseo en comprobantes de alta frecuencia.
5.5.2 Configuración del Motor Thymeleaf (ThymeleafConfig)
@Configuration
public class ThymeleafAddendaConfig {
@Bean(name = "addendaXmlTemplateEngine")
public TemplateEngine addendaXmlTemplateEngine() {
TemplateEngine engine = new TemplateEngine();
// Resolver de plantillas en memoria desde cadenas String persistidas en BD
StringTemplateResolver templateResolver = new StringTemplateResolver();
templateResolver.setTemplateMode(TemplateMode.XML);
templateResolver.setCacheable(true);
templateResolver.setCacheTTLMs(3600000L); // 1 hora de TTL para plantillas compiladas
engine.setTemplateResolver(templateResolver);
return engine;
}
}
5.5.3 Estructura del Contexto de Datos (org.thymeleaf.context.Context)
Antes de la invocación de Thymeleaf, el servicio ThymeleafContextBuilder construye el contexto de datos exponiendo tanto estructuras de objetos jerárquicas como el mapa canónico de tokens planos:
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_contexto_thymeleaf.mmd.
tokens(Mapa plano de tokens canónicos): Permite acceder a cualquier token del catálogo mediante su clave estándar (ej.${tokens['$EncabezadoserieComprobante$']}o${tokens['$Detallecantidad$']}).customTokens(Mapa de tokens custom): Contiene los valores fijos y los resultados de fórmulas calculadas (ej.${customTokens['$CustomNumAcreedor$']}).detalles(Colección de partidas): Lista de líneas de factura disponibles para iteración repetitiva.#math(Utilería financiera Alpura): Provee funciones como#math.format(valor, decimales)y operaciones aritméticas de redondeo.
5.5.4 Estrategia de Renderizado Dual (Compatibilidad Total y Modernización)
Para mantener 100% de retrocompatibilidad con las plantillas semilla y legadas del Excel (que utilizan $Token$ y <cfdi:DetalleAddenda/>), y al mismo tiempo permitir el uso de plantillas modernas Thymeleaf XML (th:each, th:text, [(${...})]), el motor soporta dos modalidades de renderizado:
Modalidad 1: Plantillas Tradicionales Alpura ($Token$ con Marcador <cfdi:DetalleAddenda/>)
- Fase Detalle: Por cada partida en
payload.getDetalle(), se pobla un contexto local con los tokens de detalle ($Detalle...$) y tokens de encabezado heredados. La plantillaxml_plantilla_detallese procesa mediante Thymeleaf; los fragmentos XML resultantes se concatenan preservando el orden de línea recibido. - Inyección en Marcador: El bloque consolidado de detalles sustituye el marcador
<cfdi:DetalleAddenda/>en la plantilla de encabezado. - Fase Encabezado: Se pre-procesan los tokens del encabezado (
$Encabezado...$) y tokens custom en la plantilla resultante, evaluándola a través del motoraddendaXmlTemplateEngineenTemplateMode.XML. Thymeleaf aplica el escape final de entidades y valida que el documento resultante sea XML bien formado.
Modalidad 2: Plantillas Nativas Thymeleaf XML (th:each, th:attr, th:if)
Las plantillas dadas de alta con sintaxis Thymeleaf nativa se renderizan en una sola pasada:
<cfdi:Addenda xmlns:cfdi="http://www.sat.gob.mx/cfd/4">
<oxxo:AddendaOXXO xmlns:oxxo="http://www.oxxo.com/addenda"
th:attr="version=${plantillaVersion}">
<oxxo:Remision th:attr="folio=${tokens['$EncabezadoserieComprobante$'] + '-' + tokens['$EncabezadofolioComprobante$']},
proveedor=${customTokens['$CustomNumProveedor$']}"/>
<oxxo:Detalle th:each="item : ${detalles}"
th:attr="numLinea=${item.numLinea},
codigo=${item.sku},
cantidad=${item.cantidad},
precio=${item.precioUnitario},
importe=${item.importe}"/>
</oxxo:AddendaOXXO>
</cfdi:Addenda>
5.5.5 Garantías de Calidad y Rendimiento
- Idempotencia: Idéntico payload de comprobante y versión de plantilla producen siempre el mismo XML canónico (hash SHA-256 verificado en bitácora).
- Rendimiento: Tiempos de renderizado en percentil 95 inferiores a 50 ms para comprobantes de hasta 200 partidas con plantillas compiladas en caché.
- Aislamiento de Errores: Errores de parseo o tokens obligatorios no resueltos devuelven un error controlado
422 Unprocessable Entitycon detalle RFC 7807 sin emitir XML incompleto o corrupto.
5.6 Modelo de Resolución Dinámica: Relación de Plantillas con Clientes y Facturas (Matching Multidimensional en Runtime)
Una duda arquitectónica recurrente consiste en cómo se vincula una plantilla de addenda en cat_addenda_plantillas con un cliente específico o con una factura determinada, dado que no existe una clave foránea (FK) física directa entre la tabla de plantillas y las tablas transaccionales de clientes (facturacion_receptores / clientes corporativos) o comprobantes (facturacion_comprobantes).
Esta sección detalla el fundamento del desacoplamiento, las cuatro dimensiones de resolución en tiempo de ejecución, el flujo de orquestación en el código y la consulta JPQL canónica de búsqueda.
5.6.1 Desacoplamiento de Plantillas frente a Clientes y Facturas
En la arquitectura de facturación de Alpura, las plantillas modelan el contrato técnico XML impuesto por una Cadena Comercial (ej. OXXO, Soriana, Walmart, Tiendas 3B, Liverpool), no la transacción particular de un cliente o comprobante.
El desacoplamiento deliberado mediante la ausencia de Foreign Keys directas responde a tres principios fundamentales:
- Relación 1 a N entre Cadena Comercial y Clientes Fiscales:
- Una misma cadena comercial (ej.
SORIANA) puede agrupar decenas de razones sociales, filiales, subsidiarias o RFCs receptores distintos (ej. Tiendas Soriana S.A. de C.V., Hipermart S.A. de C.V., Centros Comerciales Soriana S.A. de C.V.), así como cientos de centros de distribución (CEDIS). - Asignar un
plantilla_idfijo por cliente obligaría a duplicar o actualizar masivamente registros ante cualquier cambio de versión de la addenda.
- Una misma cadena comercial (ej.
- Inmutabilidad Fiscal del Comprobante vs. Evolución de Formatos:
- La factura emitida es un documento fiscal legally inmutable.
- Si una cadena comercial publica una nueva especificación de addenda (ej. actualización de versión de
1.0a2.0a partir del 1 de enero), las facturas emitidas previamente deben poder reconsultarse o regenerar su addenda con la versión que estuvo vigente en su fecha de emisión original, sin alterar las facturas nuevas.
- Gobierno Centralizado sin Afectación al Núcleo de Facturación:
- Permite que los administradores de addendas creen, prueben y publiquen nuevas plantillas en
cat_addenda_plantillassin requerir migraciones DDL ni DML sobre las tablas del core transaccional de facturación.
- Permite que los administradores de addendas creen, prueben y publiquen nuevas plantillas en
5.6.2 Criterio de Resolución Multidimensional (Las 4 Dimensiones de Matching)
Cuando se solicita la generación de una addenda, el sistema resuelve la plantilla aplicable mediante una tupla de cuatro dimensiones evaluadas estrictamente en tiempo de ejecución (runtime dynamic resolution):
| Dimensión | Campo en cat_addenda_plantillas | Origen en el Comprobante / Petición | Descripción y Justificación |
|---|---|---|---|
| 1. Cadena Comercial | cadena_codigo (id_cadena) | AddendaGenerationRequestVO.cadenao Receptor fiscal asociado | Identifica la cadena comercial destinataria (ej. 'OXXO', 'SORIANA', 'WALMART'). Resuelto a partir del código de cliente o provisto en la petición. |
| 2. Tipo de Comprobante | tipo_comprobante | FacturacionComprobanteDO.tipoComprobanteo AddendaGenerationRequestVO.tipoComprobante | Tipo fiscal SAT del CFDI ('I' = Ingreso / Factura, 'E' = Egreso / Nota de Crédito, 'T' = Traslado, 'P' = Recepción de Pagos). Una misma cadena suele exigir estructuras XML totalmente distintas para facturas que para notas de crédito. |
| 3. Vigencia Histórica Temporal | fecha_inicio_vigenciafecha_fin_vigencia | FacturacionComprobanteDO.fechaEmision(Fecha fiscal de emisión) | Determina la versión activa evaluando:p.fecha_inicio_vigencia <= :fechaEmisionAND (p.fecha_fin_vigencia IS NULL OR p.fecha_fin_vigencia >= :fechaEmision).Garantiza reproducibilidad histórica de addendas emitidas en fechas pasadas. |
| 4. Estado Operativo | estadodn_activo | Control de ciclo de vida del catálogo | Filtra exclusivamente plantillas en estado 'PUBLICADA' y con bandera dn_activo = true. Las plantillas en 'BORRADOR' u 'OBSOLETA' quedan excluidas del flujo productivo. |
5.6.3 Diagrama de Flujo del Matching Multidimensional
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_matching_multidimensional.mmd.
5.6.4 Flujo de Ejecución en Código y Diagrama de Secuencia
El proceso de orquestación en el microservicio se ejecuta de forma síncrona a través de las capas de Web, Fachada, Orquestador, Repositorios de Facturación y Motor de Addendas:
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_secuencia_orquestacion.mmd.
Puntos de interacción clave en el código:
- Controlador Web:
AddendaGenerationController.generarAddenda(...)recibe el payload JSON validando el rolADDENDA_GENERAR. - Capa Fachada:
AddendaGenerationFacadeImpl.generarAddenda(...)valida parámetros mínimos requeridos y delega en el orquestador bajo contexto transaccional@Transactional. - Orquestador Principal:
AddendaOrchestrationServiceImpl.procesarAddenda(...)resuelve la estrategia medianteIAddendaStrategyResolvery dispara la agregación de datos y renderizado. - Agregado de Facturación Optimizado:
IFacturacionComprobanteRepository.findAggregateByIdentifier(...)consolida en un únicoSELECTconLEFT JOINla cabecera, remisión, receptor, emisor e impuestos del comprobante fiscal. - Servicio de Configuración de Plantillas:
PlantillaConfigurationServiceImpl.findVigente(...)invoca al repositorio con la terna(cadena, tipoComprobante, fechaEmision). - Motor de Renderizado:
AddendaEngineServiceImpl.generarAddenda(...)fusiona el contexto de tokens y evalúa las expresiones XML con Thymeleaf.
5.6.5 Consulta JPQL Canónica (findVigente) y Estrategia de Caché de Dos Niveles
La consulta que materializa la resolución dinámica en Spring Data JPA reside en IPlantillaAddendaRepository.java:
@Query("SELECT p FROM PlantillaAddendaDO p WHERE p.active = true " +
"AND p.cadenaCodigo = :cadena " +
"AND p.tipoComprobante = :tipoComprobante " +
"AND p.estado = 'PUBLICADA' " +
"AND p.fechaInicioVigencia <= :fechaEmision " +
"AND (p.fechaFinVigencia IS NULL OR p.fechaFinVigencia >= :fechaEmision) " +
"ORDER BY p.fechaInicioVigencia DESC")
List<PlantillaAddendaDO> findVigente(@Param("cadena") String cadena,
@Param("tipoComprobante") String tipoComprobante,
@Param("fechaEmision") LocalDateTime fechaEmision);
Aspectos clave de la consulta:
p.active = true: Excluye registros marcados con borrado lógico (soft delete).p.estado = 'PUBLICADA': Garantiza que únicamente plantillas aprobadas por el flujo administrativo entren en producción.p.fechaInicioVigencia <= :fechaEmision: Asegura que la plantilla ya hubiese iniciado su vigencia legal al momento de emitir la factura.p.fechaFinVigencia IS NULL OR p.fechaFinVigencia >= :fechaEmision: Admite vigencia indefinida (NULL) o restringe a facturas emitidas antes de la expiración.ORDER BY p.fechaInicioVigencia DESC: En caso de existir solapamiento de fechas por configuración administrativa, prioriza de forma determinista la versión con inicio de vigencia más reciente (list.get(0)).
Estrategia de Caché:
- Caché L1 (Local Caffeine): Las plantillas resueltas se almacenan en memoria del pod con una clave canónica
cadena:tipoComprobante:YYYY-MM-DDy TTL configurable (1 hora). - Invalidación Reactiva: La publicación de una nueva plantilla o el cambio a estado
OBSOLETAmediantePlantillaConfigController.publicarPlantilla(...)oPlantillaConfigurationServiceImpl.publicarPlantilla(...)emite una invalidación de caché (@CacheEvict(value = "plantillasVigentes", allEntries = true)) para garantizar consistencia inmediata en el cluster.
5.7 Flujo de Creación de Plantillas, Configuración de Tokens y Motor Exhaustivo de Reglas
Esta sección documenta de forma exhaustiva el ciclo de vida administrativo para la incorporación de nuevas adendas en la plataforma, la parametrización de tokens y el funcionamiento interno del Motor de Reglas, el cual permite resolver dinámicamente transformaciones de valor, cálculos aritméticos financieros y formateo estructural sin requerir recompilación ni despliegue de código.
[!NOTE] El diagrama oficial independiente se encuentra en diagrama_motor_reglas.mmd.
5.7.1 Ciclo de Vida End-to-End: Creación y Gobierno de Plantillas
El proceso administrativo de configuración de una addenda sigue un flujo estricto de cinco etapas que garantiza la integridad estructural del XML y la consistencia en el cluster de producción:
-
Etapa 1: Alta de la Plantilla Base en Estado
BORRADOR- Endpoint:
POST /api/v1/configuraciones/plantillas. - Se registran los metadatos obligatorios:
cadenaCodigo(ej.'WALMART'),tipoComprobante('I'o'E'),version(ej.'v1.0.0'),fechaInicioVigenciay estado inicial sugerido'BORRADOR'. - Se proveen las estructuras XML canónicas divididas en dos segmentos:
xmlPlantillaEncabezado: Estructura raíz de la addenda con namespaces y el marcador obligatorio<cfdi:DetalleAddenda/>donde se inyectarán las partidas (o directivasth:each).xmlPlantillaDetalle: Esqueleto de la partida unitaria que se repetirá por cada ítem facturado.
- Validación Sintáctica XML DOM: Antes de persistir,
PlantillaConfigurationServiceImpl._validateXmlStructure(...)envuelve los fragmentos y los valida conDocumentBuilderFactoryendurecido (XMLConstants.FEATURE_SECURE_PROCESSING = true). Si el XML no está bien formado, la petición es rechazada con error422 Unprocessable Entity(PLANTILLA_INVALID_XML). - Restricción de Unicidad de Versión: Se verifica en base de datos que no exista otra versión activa con la misma terna
(cadena_codigo, tipo_comprobante, version). Si existe, se rechaza con error409 Conflict(PLANTILLA_DUPLICATE_VERSION).
- Endpoint:
-
Etapa 2: Mapeo y Parametrización de Tokens
- Se identifican los tokens requeridos en los esqueletos XML:
- Tokens Canónicos Globales (
cat_addenda_tokens): Extraídos automáticamente de la factura por el conector correspondiente (ej.$EncabezadofolioComprobante$,$ClienteRFC$,$Detallecantidad$,$DetalleprecioUnitario$). - Tokens Custom Específicos (
cat_addenda_plantilla_custom_tokens): Datos particulares requeridos por la cadena comercial que no pertenecen al estándar de facturación. Se registran víaPOST /api/v1/configuraciones/plantillas/{id}/custom-tokens.
- Tokens Canónicos Globales (
- Se identifican los tokens requeridos en los esqueletos XML:
-
Etapa 3: Parametrización del Motor de Reglas
- Se registran las reglas de negocio asociadas a la plantilla:
- Asignación de valores constantes (
tipo_valor = 'FIJO'). - Fórmulas matemáticas dinámicas (
tipo_valor = 'CALCULADO'). - Mapeos y transformaciones condicionales (
cat_addenda_reglas_transformacion).
- Asignación de valores constantes (
- Se registran las reglas de negocio asociadas a la plantilla:
-
Etapa 4: Simulación y Previsualización en Borrador
- Endpoint:
POST /api/v1/addendas/previsualizar. - Permite someter un comprobante real o sintético contra la plantilla en estado
BORRADOR. El orquestador ejecuta el motor completo, renderiza el XML, genera un hash de integridad SHA-256 y mide la latencia (duracionMs) sin afectar el tráfico productivo.
- Endpoint:
-
Etapa 5: Publicación Formal e Invalidación Reactiva de Caché
- Endpoint:
POST /api/v1/configuraciones/plantillas/{id}/publicar. - Actualiza el estado a
'PUBLICADA'y emite una invalidación de caché L1/L2 (@CacheEvict(value = "plantillasVigentes", allEntries = true)). A partir de este milisegundo, cualquier factura emitida es procesada con la nueva plantilla en todo el cluster.
- Endpoint:
5.7.2 Arquitectura del Motor de Reglas (Rules Engine Architecture)
El motor de reglas de addendas opera mediante un pipeline de tres subsistemas desacoplados que resuelven secuencialmente las dependencias de datos:
| Subsistema | Responsabilidad | Momento de Ejecución | Entidad / Configuración |
|---|---|---|---|
| 1. Reglas de Cálculo Aritmético | Evaluación de expresiones algebraicas, prorrateos y conversiones de UOM con precisión BigDecimal. | Previo al formateo textual, en orden ascendente de evaluación. | cat_addenda_plantilla_custom_tokens (tipo_valor = 'CALCULADO') |
| 2. Reglas de Transformación Condicional | Homologación de códigos, evaluación de operadores =, <>, =r, <>r y mapeos de listas de valores. | Posterior al cálculo numérico y antes de inyectar al contexto Thymeleaf. | cat_addenda_reglas_transformacion |
| 3. Modificadores de Formato | Ajustes de longitud fija {Size_N}, relleno (padding) y formateo de fechas {yyMMdd}. | Durante la interpolación y renderizado final de Thymeleaf. | Directivas en placeholders XML ($Token{Modificador}$) |
5.7.3 Subsistema de Reglas de Transformación Condicional (Reglas de Valor)
Las reglas de transformación permiten alterar el valor de un token en función de condiciones lógicas sobre el comprobante o sobre otros tokens.
Estructura de Definición de Regla
Cada regla en cat_addenda_reglas_transformacion define:
token_origen: Token evaluado en la condición (ej.$TipoComprobante$,$EncabezadoLocType$).operador: Operación lógica de comparación (=,<>,!=,=r,<>r).valor_condicion: Valor literal o lista separada por comas contra la cual se compara.nuevo_valor: Valor resultante si la condición es verdadera (puede ser un literal o un identificador de token).token_destino: Token sobre el cual se escribe el resultado (por defecto el mismotoken_origeno uno específico).orden_evaluacion: Secuenciador para aplicar transformaciones encadenadas.
Catálogo Exhaustivo de Operadores Condicionales
-
Operador
=(Igualdad Literal y Mapeo en Listas):- Comportamiento: Compara si el valor actual del token coincide exactamente con
valor_condicion. Sivalor_condicioncontiene comas (ej."58743,58750,58754,58755"), opera como pertenencia a conjunto (IN). - Caso Real (Soriana / Tiendas Específicas): Si el número de tienda coincide con una lista de CEDIS centralizados, asignar el código de proveedor maestro:
- Condición:
$EncabezadoreceptorNumeroSucursal$ = "58743,58750,58754". - Acción:
nuevo_valor = "PROV_CEDIS_CENTRAL".
- Condición:
- Caso Real (OXXO / Clase de Documento): Mapeo de tipo de comprobante SAT a código interno OXXO:
- Regla 1:
$TipoComprobante$ = "I"$\rightarrow$claseDoc = "1"(Factura). - Regla 2:
$TipoComprobante$ = "E"$\rightarrow$claseDoc = "3"(Nota de Crédito).
- Regla 1:
- Comportamiento: Compara si el valor actual del token coincide exactamente con
-
Operador
<>o!=(Desigualdad / Exclusión):- Comportamiento: La regla se dispara únicamente si el valor actual del token es distinto al valor de condición.
- Caso Real (OXXO / Proveedor Foráneo):
- Condición:
$EncabezadoLocType$ <> "B". - Acción:
nuevo_valor = "NACIONAL".
- Condición:
-
Operador
=r(Igualdad con Redirección a Token Destino):- Comportamiento: Evalúa igualdad (
==). Si se cumple, el nuevo valor no es un literal estático, sino que se extrae en tiempo de ejecución del token referenciado entoken_destinoo ennuevo_valor(usando sintaxis$TokenReferenciado$). - Caso Real (OXXO Consolidada - HU2): Para locales tipo
'B', el código de proveedor del XML debe tomarse del número de sucursal del receptor:- Condición:
$EncabezadoLocType$ = "B". - Operador:
=r. - Destino:
$EncabezadoreceptorNumeroSucursal$. - Efecto: El token
$CustomTipoProv$toma dinámicamente el valor almacenado en$EncabezadoreceptorNumeroSucursal$.
- Condición:
- Comportamiento: Evalúa igualdad (
-
Operador
<>r(Desigualdad con Redirección a Token Destino):- Comportamiento: Evalúa desigualdad (
!=). Si el valor no coincide con la condición, asigna el valor proveniente de otro token. - Caso Real (Soriana Remisión Alterna): Si el número de pedido de remisión está ausente o no es estándar, redirige al folio interno de factura:
- Condición:
$EncabezadonumPedido$ <> ""$\rightarrow$=r $EncabezadonumPedido$, caso contrario<>r $EncabezadofolioComprobante$.
- Condición:
- Comportamiento: Evalúa desigualdad (
5.7.4 Subsistema de Reglas de Cálculo Aritmético (Fórmulas Matemáticas y Tokens Calculados)
El subsistema de cálculo ejecuta fórmulas matemáticas configuradas en cat_addenda_plantilla_custom_tokens bajo las siguientes directrices técnicas:
1. Secuenciación y Cálculos en Cascada (nu_orden_evaluacion)
Cuando un cálculo depende del resultado de una fórmula previa, la precedencia se garantiza mediante nu_orden_evaluacion ASC:
- Paso 1 (
orden = 1): Importe neto de la partida restando descuentos de línea: $$$DetalleImporteNeto$ = $Detalleimporte$ - $DetalleDescuento$$$ - Paso 2 (
orden = 2): Cálculo del IVA proporcional sobre el importe neto obtenido en el Paso 1: $$$DetalleIvaNeto$ = $DetalleImporteNeto$ \times 0.16$$ - Paso 3 (
orden = 3): Total consolidado de partida sumando el resultado del Paso 1 y Paso 2: $$$DetalleTotalPartida$ = $DetalleImporteNeto$ + $DetalleIvaNeto$$$
Cada resultado intermedio se publica inmediatamente en el mapa de variables en memoria, estando disponible para los pasos posteriores de forma determinista.
2. Aritmética Financiera con BigDecimal y MathContext
Para neutralizar discrepancias de redondeo y cumplir con los lineamientos del SAT:
- Escala Configurable (
nu_escala_decimales): Define el número exacto de posiciones fraccionarias (ej.2para importes finales,4o6para precios unitarios de leche y derivados). - Modos de Redondeo Soportados (
ds_tipo_redondeo):HALF_UP: Redondeo estándar (si el decimal siguiente es $\ge 5$, incrementa). Predeterminado en el sistema.HALF_EVEN: Redondeo bancario o de Gauss (reduce el sesgo estadístico en sumatorias masivas).CEILING/FLOOR: Ajustes para cálculo de fletes y unidades enteras de transporte.
3. Resiliencia Operativa en Tiempo de Ejecución
- Protección ante División entre Cero (Zero-Division Protection): Si en expresiones como
$Encabezadodescuentos$ / $Encabezadototal$el divisor$Encabezadototal$es0o nulo, el motor captura la condición, asigna el valor predeterminado seguro0.00y registra un evento informativo de advertencia sin interrumpir el timbrado. - Coerción Automática de Nulos (Safe Null Coercion): Tokens nulos o vacíos se normalizan automáticamente a
BigDecimal.ZERO(oBigDecimal.ONEsi operan como factor multiplicador neutro). - Entorno de Ejecución Seguro (Sandboxed Evaluation): La evaluación SpEL se ejecuta en un
SimpleEvaluationContextestrictamente acotado a lectura de propiedades y operaciones matemáticas, impidiendo llamadas a reflexión, carga de clases o ejecución de comandos en el sistema operativo.
5.7.5 Subsistema de Modificadores de Longitud y Formato (Token Formatters)
Los modificadores permiten formatear el texto resultante en la plantilla sin alterar el valor numérico en el modelo de datos:
| Modificador | Sintaxis en Plantilla | Entrada de Ejemplo | Salida Renderizada | Caso de Negocio |
|---|---|---|---|---|
| Longitud Fija con Ceros (Zero Padding) | $DetalleSKU{Size_14_0}$ | "75010205" | "00000075010205" | Códigos EAN-13/GTIN-14 en adendas de autoservicio (Walmart/Soriana). |
| Longitud Fija con Espacios (Space Padding) | $EncabezadoSerie{Size_10_S}$ | "FAC" | "FAC " | Formatos legados EDIFACT / AMC 7.1 con columnas de ancho fijo. |
| Truncamiento de Cadena | $ClienteRazonSocial{Max_30}$ | "LECHE INDUSTRIALIZADA CONASUPO S.A." | "LECHE INDUSTRIALIZADA CONASUPO" | Restricción de longitud máxima de nodo impuesta por XSD de la cadena. |
| Formateo de Fecha Corta | $FechaEmision{yyMMdd}$ | "2026-11-10T14:30:00" | "261110" | Identificadores de remisión compactos (OXXO/Liverpool). |
| Formateo de Fecha SAT | $FechaEmision{yyyy-MM-dd}$ | "2026-11-10T14:30:00" | "2026-11-10" | Fechas estándar en atributos comerciales. |
| Transformación a Mayúsculas | $DetalleDescripcion{UPPER}$ | "Crema Alpura 200ml" | "CREMA ALPURA 200ML" | Homologación contra catálogo de artículos de la cadena. |
5.7.6 Matriz de Aplicabilidad en Cadenas Comerciales de Alpura
La siguiente matriz ilustra la combinación de reglas aplicadas a las principales cadenas comerciales gestionadas por Alpura:
| Cadena Comercial | Necesidad Técnica / Comercial | Regla Aplicada | Implementación en el Motor |
|---|---|---|---|
| Tiendas Soriana | Concatenación de token en atributo (Articulos$DetalleNumLinea$) y mapeo de CEDIS centrales. | Regla condicional = sobre lista de sucursales y regla =r para número de remisión alternativo. | Evaluador de listas IN ("58743,58750...") y reemplazo dinámico de tokenDestino. |
| Cadena OXXO Consolidada | Diferenciación de tipo de documento (claseDoc) y asignación condicional de proveedor para locales tipo 'B'. | Reglas de valor = (I $\rightarrow$ 1, E $\rightarrow$ 3) y regla condicional =r sobre $EncabezadoLocType$. | Redirección en runtime al token $EncabezadoreceptorNumeroSucursal$. |
| Tiendas 3B | Porcentaje de descuento global prorrateado sobre el valor total de la factura. | Regla de cálculo dinámico: $DescuentoGlobal$ = $Encabezadodescuentos$ / $Encabezadototal$. | Aritmética BigDecimal con escala decimal de 4 posiciones, redondeo HALF_UP y protección ante división por cero. |
| Corporación Sánchez | Homologación de unidades de venta cuando el producto se factura en cajas (CJA). | Regla de conversión UOM: recalcula cantidad y precio dividiendo o multiplicando por el factor de empaque. | Tokens calculados: $DetalleprecioUnitarioCaja$ = $DetalleprecioUnitario$ * $DetallefactorConversion$. |
| Walmart México | Conteo total de partidas y segmentos EDI, e inyección de GTIN a 14 dígitos. | Regla de conteo agregado $EncabezadoNumLineas$ = COUNT(detalles) y modificador {Size_14_0}. | Función de agregación sobre lista de ítems e interpolador con padding de ceros a la izquierda. |
6. Diagramas de Arquitectura del Sistema
Todos los diagramas oficiales de arquitectura del microservicio se encuentran formalmente versionados como archivos independientes en formato Mermaid (.mmd) dentro del directorio docs/, compartiendo una paleta corporativa y estilos visuales estandarizados:
- Diagrama de Topología General: arquitectura_diagrama.mmd
- Ilustra la topología integral del ecosistema de facturación, la bifurcación Legacy vs. Assembled y los conectores hacia fuentes externas.
- Diagrama de Componentes: diagrama_componentes.mmd
- Detalla la separación de capas: API REST, Application Services, Conectores internos de Spring, Repositorios JPA y Fuentes externas.
- Diagrama de Flujo General: diagrama_flujo.mmd
- Detalla la toma de decisiones por bandera
legacy/ Spring Profile, la bifurcación Legacy vs. Assembled, concurrencia Scatter-Gather, Fail-Fast y salida sin timbrado.
- Detalla la toma de decisiones por bandera
- Diagrama de Secuencia General: diagrama_secuencia.mmd
- Ilustra el flujo síncrono HTTP, invocaciones paralelas con Virtual Threads (
StructuredTaskScope), agregación Gather y respuesta 200 OK.
- Ilustra el flujo síncrono HTTP, invocaciones paralelas con Virtual Threads (
- Diagrama de Precedencia de Decisión: diagrama_precedencia_decision.mmd
- Modela el árbol determinista de precedencia de ruteo para alternar entre el flujo Legacy (OBI) y Assembled (Scatter-Gather).
- Diagrama Entidad-Relación (ERD): diagrama_erd_modelo_datos.mmd
- Modela el esquema relacional en PostgreSQL: catálogos de plantillas, tokens globales, tokens custom por plantilla y reglas de transformación.
- Diagrama de Fases del Procesamiento: diagrama_fases_procesamiento.mmd
- Modela las 13 fases secuenciales del motor Thymeleaf XML, desde la recepción del comprobante hasta la entrega del nodo
<cfdi:Addenda>.
- Modela las 13 fases secuenciales del motor Thymeleaf XML, desde la recepción del comprobante hasta la entrega del nodo
- Diagrama de Contexto Thymeleaf: diagrama_contexto_thymeleaf.mmd
- Diagrama de clases que especifica la estructura canónica de datos inyectada en
org.thymeleaf.context.Context(DTOs, mapas planos y utilerías).
- Diagrama de clases que especifica la estructura canónica de datos inyectada en
- Diagrama de Matching Multidimensional: diagrama_matching_multidimensional.mmd
- Modela la resolución dinámica de plantillas en tiempo de ejecución evaluando cadena, tipo comprobante, vigencia temporal y estado.
- Diagrama de Secuencia de Orquestación en Runtime (Generar Addenda): diagrama_secuencia_orquestacion.mmd
- Detalla la traza síncrona en código entre Controladores, Fachada, Orquestador, Repositorios de Facturación y Motor Thymeleaf (
POST /api/v1/addendas/generar).
- Detalla la traza síncrona en código entre Controladores, Fachada, Orquestador, Repositorios de Facturación y Motor Thymeleaf (
- Diagrama de Secuencia de Previsualización (Borrador): diagrama_secuencia_previsualizar.mmd
- Detalla la simulación administrativa de addendas con plantillas en estado borrador y cálculo de hash de integridad (
POST /api/v1/addendas/previsualizar).
- Detalla la simulación administrativa de addendas con plantillas en estado borrador y cálculo de hash de integridad (
- Diagrama de Secuencia de Consulta de Plantillas: diagrama_secuencia_plantillas_consulta.mmd
- Modela la búsqueda paginada y filtrada (
GET /api/v1/configuraciones/plantillas) y la consulta detallada por ID (GET /{id}).
- Modela la búsqueda paginada y filtrada (
- Diagrama de Secuencia de Creación de Plantilla: diagrama_secuencia_plantillas_creacion.mmd
- Modela el alta de plantillas con validación DOM de XML bien formado, unicidad de versión por cadena/tipo y persistencia de custom tokens (
POST /api/v1/configuraciones/plantillas).
- Modela el alta de plantillas con validación DOM de XML bien formado, unicidad de versión por cadena/tipo y persistencia de custom tokens (
- Diagrama de Secuencia de Modificación y Baja Lógica de Plantillas: diagrama_secuencia_plantillas_modificacion_baja.mmd
- Ilustra la actualización con revalidación de unicidad (
PUT /{id}) y la baja lógica (soft delete) en cascada sobre plantilla y tokens (DELETE /{id}).
- Ilustra la actualización con revalidación de unicidad (
- Diagrama de Secuencia de Publicación de Plantilla: diagrama_secuencia_publicar_plantilla.mmd
- Modela la transición a estado
PUBLICADA, auditoría e invalidación reactiva de la caché distribuida/local L1 (POST /{id}/publicar).
- Modela la transición a estado
- Diagrama de Secuencia de Tokens Custom: diagrama_secuencia_custom_tokens.mmd
- Modela el ciclo de vida de tokens fijos y calculados: listado ordenado, alta y baja lógica (
GET,POST,DELETE /{id}/custom-tokens).
- Modela el ciclo de vida de tokens fijos y calculados: listado ordenado, alta y baja lógica (
- Diagrama de Arquitectura y Evaluación del Motor de Reglas: diagrama_motor_reglas.mmd
- Detalla el pipeline secuencial de 3 subsistemas del motor: fórmulas de cálculo
BigDecimal, transformaciones condicionales (=,<>,=r,<>r) y formateadores de longitud/fecha.
- Detalla el pipeline secuencial de 3 subsistemas del motor: fórmulas de cálculo
7. Especificación de Endpoints (API REST)
| Método | Endpoint | Rol de Seguridad | Descripción | Diagrama de Secuencia Asociado |
|---|---|---|---|---|
POST | /api/v1/addendas/generar | ADDENDA_GENERAR | Genera el XML de la addenda a partir del JSON de comprobante. Acepta bandera opcional "legacy": boolean. | diagrama_secuencia_orquestacion.mmd / diagrama_secuencia.mmd |
POST | /api/v1/addendas/previsualizar | ADDENDA_ADMIN | Permite renderizar usando una versión en borrador antes de su publicación. | diagrama_secuencia_previsualizar.mmd |
GET | /api/v1/configuraciones/plantillas | ADDENDA_ADMIN | Consulta el catálogo de plantillas XML registradas (por cadena, tipo comprobante y vigencia). | diagrama_secuencia_plantillas_consulta.mmd |
GET | /api/v1/configuraciones/plantillas/{id} | ADDENDA_ADMIN | Obtiene el detalle completo de una plantilla por ID (encabezado, detalle y XSD). | diagrama_secuencia_plantillas_consulta.mmd |
POST | /api/v1/configuraciones/plantillas | ADDENDA_ADMIN | Alta de una nueva plantilla (XML de encabezado, XML de detalle, vigencias, etc.). | diagrama_secuencia_plantillas_creacion.mmd |
PUT | /api/v1/configuraciones/plantillas/{id} | ADDENDA_ADMIN | Actualización de versión o contenido de plantilla existente. | diagrama_secuencia_plantillas_modificacion_baja.mmd |
DELETE | /api/v1/configuraciones/plantillas/{id} | ADDENDA_ADMIN | Baja lógica (soft delete) de plantilla y tokens custom asociados. | diagrama_secuencia_plantillas_modificacion_baja.mmd |
POST | /api/v1/configuraciones/plantillas/{id}/publicar | ADDENDA_ADMIN | Publica formalmente una versión invalidando la caché distribuida/local. | diagrama_secuencia_publicar_plantilla.mmd |
GET | /api/v1/configuraciones/plantillas/{id}/custom-tokens | ADDENDA_ADMIN | Consulta los campos/tokens custom asociados a una plantilla (fijos y calculados). | diagrama_secuencia_custom_tokens.mmd |
POST | /api/v1/configuraciones/plantillas/{id}/custom-tokens | ADDENDA_ADMIN | Registra un campo/token custom en la plantilla (tipo_valor: FIJO con valor estático o CALCULADO con fórmula matemática sobre tokens del catálogo). | diagrama_secuencia_custom_tokens.mmd |
DELETE | /api/v1/configuraciones/plantillas/{id}/custom-tokens/{tokenId} | ADDENDA_ADMIN | Elimina o desactiva un campo/token custom de la plantilla. | diagrama_secuencia_custom_tokens.mmd |
GET | /api/v1/tokens | ADDENDA_ADMIN | Catálogo global de tokens disponibles. Soporta filtro query `?tipoOrigen=FACTURA | CLIENTE |
POST | /api/v1/tokens | ADDENDA_ADMIN | Alta de un token canónico en el catálogo con definición de conector, sistema fuente, path de extracción y tipo de dato. | N/A (Catálogo global) |
7.1 Ejemplo de Solicitud con Bandera legacy
{
"cadena": "TIENDAS_SORIANA",
"tipoComprobante": "I",
"fechaEmision": "2026-11-03T18:00:00-06:00",
"legacy": false,
"encabezado": {
"serieComprobante": "FA",
"folioComprobante": "987654",
"numProveedor": "12345",
"numOrdenCompra": "4500099999",
"subtotal": "25000.00",
"total": "29000.00"
},
"detalle": [
{
"numLinea": 1,
"SKU": "7501020512345",
"cantidad": "100",
"unidadMedida": "CAJA",
"precioUnitario": "250.00",
"importe": "25000.00"
}
]
}
7.2 Catálogo Canónico de Excepciones y Códigos de Error (Matriz de Errores Alpura)
El microservicio implementa una política uniforme de manejo de errores basada en el estándar corporativo de Alpura (AlpuraException), normalizada mediante el interceptor AOP @JsonResponseInterceptor e interceptores de Spring Web (BaseController), traduciendo los fallos de negocio en respuestas estructuradas con códigos HTTP canónicos:
| Código | Constante ServiceErrorCodeEnum | Excepción Java | HTTP Status | Dominio / Capa | Descripción Funcional | Condición Disparadora | Acción Correctiva / Recuperación |
|---|---|---|---|---|---|---|---|
0 | UNKNOWN_ERROR | AlpuraException | 500 Internal Server Error | Sistema / Core | Error no controlado o imprevisto. | Excepción no capturada en tiempo de ejecución o falla de infraestructura. | Consultar traza y telemetría con correlationId. |
1 | REQUIRED_FIELD | AlpuraException / MethodArgumentNotValidException | 400 Bad Request | Web / DTO | Campo obligatorio ausente en el payload JSON. | Atributo anotado con @NotNull, @NotBlank o @NotEmpty viene nulo o vacío (BaseNoBlankGroup). | Suministrar todos los campos mandatorios en el cuerpo de la petición. |
2 | EXCEEDS_MAX_LENGTH | AlpuraException / ValidationException | 400 Bad Request | Web / DTO | Cadena de texto excede la longitud máxima. | Campo excede la restricción de caracteres permitida (ej. @Size(max = N)). | Ajustar o truncar la longitud del texto provisto. |
404 | NO_RESULTS | AlpuraException | 404 Not Found | Persistencia / Catálogos | Consulta sin registros coincidentes. | Búsqueda por criterios o identificador no arrojó resultados activos. | Verificar los parámetros o identificadores enviados. |
500 | ADDENDA_PROCESSING_ERROR | AlpuraException | 500 Internal Server Error | Motor de Addendas | Error interno en la generación del XML. | Falla de compilación de plantilla Thymeleaf o error inesperado en motor de reglas. | Inspeccionar sintaxis de plantilla y bitácora de eventos. |
1001 | ADDENDA_CADENA_REQUIRED | AlpuraException | 400 Bad Request | Generación / Previsualización | Código de cadena comercial no especificado. | requestVO.getCadena() == null o requestVO.getCadena().isBlank(). | Indicar la cadena comercial destinataria (ej. "SORIANA", "OXXO"). |
1002 | ADDENDA_REQUEST_EMPTY | AlpuraException | 400 Bad Request | Generación / Previsualización | Payload de solicitud nulo o vacío. | requestVO == null o requestVO.getParameters() == null. | Enviar un objeto JSON de comprobante válido. |
2001 | PLANTILLA_NOT_FOUND | AlpuraException | 404 Not Found / 422 Unprocessable Entity | Plantillas / Generación | Plantilla inexistente o sin vigencia. | No existe plantilla activa con el ID indicado, o no hay versión 'PUBLICADA' vigente para la fecha de emisión. | Crear y publicar la plantilla requerida para la cadena y rango de fechas. |
2002 | PLANTILLA_DUPLICATE_VERSION | AlpuraException | 409 Conflict | Plantillas | Conflicto de versión de plantilla. | Ya existe un registro activo con la misma terna (cadenaCodigo, tipoComprobante, version). | Incrementar la versión (ej. "v1.0.1", "2026-12") antes de guardar. |
2003 | PLANTILLA_INVALID_XML | AlpuraException | 422 Unprocessable Entity | Plantillas / Motor XML | XML mal formado en encabezado o detalle. | Falla en validación sintáctica DOM (DocumentBuilderFactory, etiquetas mal cerradas o no balanceadas). | Corregir la sintaxis XML de los esqueletos asegurando que sea XML bien formado. |
2004 | CUSTOM_TOKEN_NOT_FOUND | AlpuraException | 404 Not Found | Tokens Custom | Token custom no encontrado en la plantilla. | No existe registro activo con id_custom_token vinculado al id_plantilla. | Verificar el ID del token y su pertenencia a la plantilla indicada. |
2005 | PLANTILLA_REQUIRED_FIELD | AlpuraException | 400 Bad Request | Plantillas / Tokens Custom | Parámetro obligatorio nulo en configuración. | Falta cadenaCodigo, tipoComprobante, version, fechaInicioVigencia, xmlPlantillaEncabezado, xmlPlantillaDetalle, claveTokenCustom o tipoValor. | Completar los campos requeridos en el DTO de configuración. |
3001 | CATALOG_SERVICE_ERROR | AlpuraException | 502 Bad Gateway / 503 Service Unavailable | Conectores / Catálogos | Error al consumir catálogos externos. | Timeout o falla de comunicación HTTP/JDBC con sistemas de catálogos maestros. | Reintentar la operación o verificar la disponibilidad del sistema fuente. |
504 | ADDENDA_TIMEOUT_FAIL_FAST | AddendaAssemblyException | 504 Gateway Timeout | Orquestador Assembled | Timeout en orquestación concurrente. | Una o más fuentes (Factura, Cliente, Pedido, Rubros) superaron el deadline global de 1500 ms en StructuredTaskScope. | Optimizar la respuesta de las fuentes externas o revisar la red. |
7.3 Mapeo y Tratamiento de Excepciones por Flujo Funcional
A continuación se detalla la matriz de excepciones que pueden producirse en cada uno de los flujos del microservicio, indicando la capa donde se intercepta, el código HTTP resultante y el comportamiento del sistema:
7.3.1 Flujo 1: Generación Productiva de Addenda (POST /api/v1/addendas/generar)
- Validación de Solicitud (Capa Web / Fachada):
1002 - ADDENDA_REQUEST_EMPTY(400 Bad Request): El cuerpo de la petición viene vacío oparameterses nulo.1001 - ADDENDA_CADENA_REQUIRED(400 Bad Request): El atributocadenano fue enviado o viene en blanco.1 - REQUIRED_FIELD(400 Bad Request): Faltan campos fiscales indispensables cuando se omite elinvoiceId.
- Orquestación y Conectores de Datos (Scatter-Gather en Virtual Threads):
504 - ADDENDA_TIMEOUT_FAIL_FAST(504 Gateway Timeout): La política Fail-Fast se activa al vencer el deadline global (1500 ms), cancelando de inmediato las tareas restantes.3001 - CATALOG_SERVICE_ERROR(502/503 Service Unavailable): Falla al resolver catálogos generales o equivalencias de cliente.
- Resolución Dinámica de Plantilla Vigente (Matching Multidimensional):
2001 - PLANTILLA_NOT_FOUND(422 Unprocessable Entity): No existe ninguna plantilla en estado'PUBLICADA'ydn_activo = trueque cubra la terna(cadena, tipoComprobante, fechaEmision).
- Motor Thymeleaf XML y Reglas de Negocio:
500 - ADDENDA_PROCESSING_ERROR(500 Internal Server Error): Error irrecuperable en renderizado o parseo de plantilla.
7.3.2 Flujo 2: Previsualización de Addenda en Borrador (POST /api/v1/addendas/previsualizar)
- Validación de Solicitud:
1002 - ADDENDA_REQUEST_EMPTY(400 Bad Request): Solicitud vacía.1001 - ADDENDA_CADENA_REQUIRED(400 Bad Request): Falta el identificador de cadena comercial.
- Resolución de Plantilla:
2001 - PLANTILLA_NOT_FOUND(422 Unprocessable Entity): No se localiza ninguna versión en borrador ni publicada para la cadena comercial indicada.
- Motor de Addendas:
500 - ADDENDA_PROCESSING_ERROR(500 Internal Server Error): Expresión SpEL o XML inválido en la versión en borrador.
7.3.3 Flujo 3: Búsqueda y Detalle de Plantillas (GET /api/v1/configuraciones/plantillas y GET /{id})
- Consulta Paginada (
GET /):- Si los filtros no arrojan coincidencias, el servicio no lanza excepción: retorna
200 OKcondata: [],totalRows: 0ypage: 0.
- Si los filtros no arrojan coincidencias, el servicio no lanza excepción: retorna
- Detalle por ID (
GET /{id}):2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): Si el parámetroides nulo o inválido.2001 - PLANTILLA_NOT_FOUND(404 Not Found): No existe plantilla con el ID suministrado o se encuentra condn_activo = false.
7.3.4 Flujo 4: Creación de Plantilla (POST /api/v1/configuraciones/plantillas)
- Validación Sintáctica de DTO:
1 - REQUIRED_FIELD(400 Bad Request): Error de validación JSR-380 (@Validated(BaseNoBlankGroup.class)).2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): Ausencia decadenaCodigo,tipoComprobante,version,fechaInicioVigencia,xmlPlantillaEncabezadooxmlPlantillaDetalle.
- Validación Sintáctica XML DOM:
2003 - PLANTILLA_INVALID_XML(422 Unprocessable Entity): Fallo en el parseador DOM (SAXParseException, etiquetas mal cerradas, XML corrupto).
- Control de Unicidad:
2002 - PLANTILLA_DUPLICATE_VERSION(409 Conflict): Ya existe una versión activa para la misma cadena y tipo de comprobante.
7.3.5 Flujo 5: Actualización de Plantilla (PUT /api/v1/configuraciones/plantillas/{id})
- Validación y Existencia:
2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): FaltaidPlantillao payload nulo.2001 - PLANTILLA_NOT_FOUND(404 Not Found): La plantilla a actualizar no existe o fue eliminada lógicamente.
- Control de Conflictos:
2002 - PLANTILLA_DUPLICATE_VERSION(409 Conflict): Si la actualización modificaversion,cadenaCodigootipoComprobantey colisiona con otra plantilla activa.
- Validación XML:
2003 - PLANTILLA_INVALID_XML(422 Unprocessable Entity): Si el XML modificado es sintácticamente inválido.
7.3.6 Flujo 6: Baja Lógica de Plantilla (DELETE /api/v1/configuraciones/plantillas/{id})
- Validación y Existencia:
2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): Parámetroidausente.2001 - PLANTILLA_NOT_FOUND(404 Not Found): No existe la plantilla a desactivar.
7.3.7 Flujo 7: Publicación Formal de Plantilla (POST /api/v1/configuraciones/plantillas/{id}/publicar)
- Validación y Existencia:
2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): Parámetroidnulo.2001 - PLANTILLA_NOT_FOUND(404 Not Found): La plantilla indicada no existe en el catálogo.
7.3.8 Flujo 8: Gestión de Tokens Custom (GET, POST, DELETE /{id}/custom-tokens)
- Listar Tokens (
GET):2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request):idde plantilla nulo.2001 - PLANTILLA_NOT_FOUND(404 Not Found): La plantilla padre no existe o está inactiva.
- Alta de Token Custom (
POST):1 - REQUIRED_FIELD(400 Bad Request): Error de validación en DTO.2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request): FaltaclaveTokenCustomotipoValor.2001 - PLANTILLA_NOT_FOUND(404 Not Found): La plantilla padre no existe.
- Baja Lógica de Token Custom (
DELETE):2005 - PLANTILLA_REQUIRED_FIELD(400 Bad Request):idPlantillaotokenIdnulo.2001 - PLANTILLA_NOT_FOUND(404 Not Found): Plantilla padre inexistente.2004 - CUSTOM_TOKEN_NOT_FOUND(404 Not Found): El token no existe o no pertenece a la plantilla especificada.
7.3.9 Flujo 9: Motor de Reglas en Runtime (Cálculos, Transformaciones y Formateo)
- División entre Cero: No arroja excepción al cliente; el evaluador asigna de forma segura el valor de fallback
0.00y emite una advertencia en el payload. - Token Faltante en Expresión: Se normaliza de forma segura a
BigDecimal.ZEROoBigDecimal.ONE. - Fórmula con Error de Sintaxis: Se intercepta como
500 - ADDENDA_PROCESSING_ERRORcon mensaje descriptivo de la expresión errónea.
7.4 Estructura Canónica de Error JSON (RFC 7807 + Envelope Alpura)
Ante cualquier excepción interceptada, el servicio responde con la estructura estándar corporativa:
{
"header": {
"code": 404,
"message": "La plantilla solicitada no fue encontrada o se encuentra inactiva",
"detail": "Error de negocio al resolver recurso"
},
"success": false,
"data": null,
"errors": [
{
"code": 2001,
"message": "La plantilla solicitada no fue encontrada o se encuentra inactiva",
"field": "idPlantilla"
}
],
"newToken": null,
"hash": null
}
8. Estrategia de Resiliencia y Observabilidad
- Circuit Breakers (Resilience4j):
- Configurados de forma individual para cada conector interno.
- Si el servicio externo (ej. AS400 o Cat Generales) no responde, el circuito se abre evitando saturación de conexiones.
- Timeouts Escalonados:
- Timeouts individuales por conector: 300ms a 1000ms.
- Deadline global en orquestador
StructuredTaskScope: 1500ms.
- Métricas y Trazabilidad:
- Métricas en Micrometer:
addenda.generation.duration,addenda.connector.latency,addenda.flow.strategy.used. - Trazas distribuidas con OpenTelemetry propagando
correlationIdentre hilos virtuales y llamadas HTTP/JDBC. - Bitácora en base de datos para auditoría y reprocesos.
- Métricas en Micrometer: