Skip to main content

Documento de Diseño de Alto Nivel (HLD)

Microservicio Generador de Addendas XML (msa-facturacion-generador-addendas)​

AtributoDetalle
ProyectoNueva Facturación Electrónica Alpura
Componentemsa-facturacion-generador-addendas
Versión del Documento1.0.0
FechaNoviembre 2026
EstadoAprobado para Construcción
ReferenciasDiccionario 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​

  1. Desacoplamiento del Monolito: Permitir la transición gradual desde el flujo heredado (Legacy / OBI) hacia un flujo de consulta distribuido y paralelo (Assembled).
  2. Concurrencia de Alto Rendimiento: Implementar el patrón Scatter-Gather con Structured Concurrency (Java 21) y política estricta de Fail-Fast.
  3. 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.
  4. 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.

  1. 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.
  2. 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 propiedad addenda.orchestration.mode del application.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 hacia DB Billing.
  • ClienteConnectorService (ClientConnectorPort): Conexión vía HTTP REST hacia Cat Generales.
  • PedidoConnectorService (ItemsConnectorPort): Conexión vía OJDBC hacia Oracle EBS.
  • RubrosConnectorService (TaxesConnectorPort): Conexión vía JDBC hacia AS400.

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, StructuredTaskScope ejecuta shutdown().
  • 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:

  1. 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.
  2. 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").
  3. 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:

CampoTipo SQLNulableDescripción
id_plantillaBIGSERIAL / BIGINTNo (PK)Identificador único de la plantilla.
cadena_codigoVARCHAR(50)NoClave de la cadena o cliente (ej. TIENDAS_SORIANA, OXXO_CONSOLIDADA, LIVERPOOL).
numero_clienteVARCHAR(255)SíIdentificador(es) de cliente Alpura asociados (admite listas o comodín).
rfc_receptorVARCHAR(13)SíRFC receptor asociado para ruteo por identidad fiscal.
gln_receptorVARCHAR(20)SíGlobal Location Number (GLN) del cliente receptor.
tipo_comprobanteVARCHAR(5)NoI (Ingreso/Factura) o E (Egreso/Nota de Crédito).
versionVARCHAR(20)NoEtiqueta de versión (ej. 2026-11-01, v1.2).
fecha_inicio_vigenciaTIMESTAMP WITH TIME ZONENoInicio de vigor para comprobantes emitidos desde esta fecha.
fecha_fin_vigenciaTIMESTAMP WITH TIME ZONESíFin de vigor (NULL = vigente indefinidamente hasta nueva versión).
estadoVARCHAR(20)NoEstado de ciclo de vida: BORRADOR, PUBLICADA, RETIRADA.
xml_plantilla_encabezadoTEXTNoPlantilla XML completa de encabezado conteniendo placeholders $Token$ y el marcador <cfdi:DetalleAddenda/>.
xml_plantilla_detalleTEXTNoPlantilla XML del nodo repetitivo de cada partida conteniendo $Detalle...$.
xsd_schemaTEXTSíEsquema XSD o URL para validación estructural del resultado final.
descripcionVARCHAR(500)SíJustificación técnica y notas de cambio de la versión.
dn_usuario_creadorVARCHAR(255)NoAuditoría: Usuario creador.
dd_fecha_creacionTIMESTAMPNoAuditoría: Fecha de creación.
dn_usuario_modificadorVARCHAR(255)NoAuditoría: Último usuario que modificó.
dd_fecha_modificacionTIMESTAMPNoAuditoría: Fecha de última modificación.
dn_activoBOOLEANNoAuditorí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:

CampoTipo SQLNulableDescripción
id_tokenBIGSERIAL / BIGINTNo (PK)Identificador único del token.
clave_tokenVARCHAR(100)No (UK)Nombre canónico delimitado por $ (ej. $EncabezadoserieComprobante$, $ClienteRFC$, $Detallecantidad$).
nombreVARCHAR(150)NoEtiqueta funcional amigable para UI de administración.
tipo_origenVARCHAR(40)NoClasificación de Origen: FACTURA, CLIENTE, PEDIDO, RUBROS_IMPUESTOS, SISTEMA_CFDI.
conector_asociadoVARCHAR(60)NoConector Spring responsable: FacturaConnectorService, ClienteConnectorService, PedidoConnectorService, RubrosConnectorService.
sistema_fuenteVARCHAR(50)NoSistema base empresarial: DB Billing, Cat Generales, Oracle EBS, AS400, CFDI_BASE.
campo_origen_pathVARCHAR(200)NoAtributo o ruta en DTO/fuente (ej. serieComprobante, clienteId, sku, tasa, extraAttributes['GLN_SUCURSAL']).
estrategia_extraccionVARCHAR(40)NoMétodo de extracción: DIRECT_DTO_FIELD, JSON_PATH, SQL_COLUMN, COMPUTED.
alcanceVARCHAR(20)NoNivel de aplicación: ENCABEZADO o DETALLE.
tipo_datoVARCHAR(20)NoTipo semántico: STRING, NUMERIC, INTEGER, DATE, DATETIME, BOOLEAN.
formato_defaultVARCHAR(50)SíFormato sugerido por defecto (ej. yyyy-MM-dd, 0.00).
es_obligatorioBOOLEANNoTRUE si el comprobante no puede emitirse sin este dato. Default: FALSE.
valor_defaultVARCHAR(255)SíValor de reemplazo si la fuente externa entrega nulo.
descripcionTEXTSíDocumentación detallada sobre el significado y obtención del dato.
dn_usuario_creadorVARCHAR(255)NoAuditoría: Usuario creador.
dd_fecha_creacionTIMESTAMPNoAuditoría: Fecha de creación.
dn_usuario_modificadorVARCHAR(255)NoAuditoría: Usuario modificador.
dd_fecha_modificacionTIMESTAMPNoAuditoría: Fecha de modificación.
dn_activoBOOLEANNoAuditorí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:

CampoTipo SQLNulableDescripción
id_custom_tokenBIGSERIAL / BIGINTNo (PK)Identificador único del token custom.
id_plantillaBIGINTNo (FK)Clave foránea hacia cat_addenda_plantillas(id_plantilla).
clave_token_customVARCHAR(100)NoPlaceholder asignado (ej. $CustomNumAcreedor$, $CustomFactorDescuento$, $DetalleCustomNeto$).
alcanceVARCHAR(20)NoNivel del token: ENCABEZADO o DETALLE.
tipo_valorVARCHAR(20)NoNaturaleza del campo: FIJO (literal estático) o CALCULADO (fórmula matemática).
valor_fijoTEXTSíTexto constante asignado por el cliente cuando tipo_valor = 'FIJO' (ej. "ATZ 983527", "002").
expresion_calculoTEXTSíExpresión matemática cuando tipo_valor = 'CALCULADO'. Utiliza tokens del catálogo (ej. "$Detallecantidad$ * $DetalleprecioUnitario$").
tokens_dependientesJSONB / TEXTSíArreglo JSON de tokens requeridos por la fórmula para validar dependencias.
tipo_dato_resultadoVARCHAR(20)NoTipo resultante: NUMERIC, STRING, INTEGER, DATE.
escala_decimalesINTEGERNoNúmero de decimales para resultados numéricos (default: 2).
tipo_redondeoVARCHAR(20)NoAlgoritmo de redondeo: HALF_UP, HALF_EVEN, CEILING, FLOOR. Default: HALF_UP.
orden_evaluacionINTEGERNoSecuencia de resolución (1, 2, 3...) para permitir cálculos en cascada. Default: 1.
descripcionVARCHAR(500)SíJustificación de negocio para el requerimiento del cliente.
dn_usuario_creadorVARCHAR(255)NoAuditoría: Usuario creador.
dd_fecha_creacionTIMESTAMPNoAuditoría: Fecha de creación.
dn_usuario_modificadorVARCHAR(255)NoAuditoría: Usuario modificador.
dd_fecha_modificacionTIMESTAMPNoAuditoría: Fecha de modificación.
dn_activoBOOLEANNoAuditorí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 HexagonalSistema Fuente (sistema_fuente)Datos Típicos Obtenidos
FACTURAFacturaConnectorServiceIHeaderConnectorPortDB BillingSerie, folio, fecha comprobante, subtotal, total, moneda, tipo de cambio, condiciones de pago.
CLIENTEClienteConnectorServiceIClientConnectorPortCat GeneralesID de cliente, RFC receptor, razón social, GLN receptor, número de sucursal, domicilio fiscal, calle, CP.
PEDIDOPedidoConnectorServiceIItemsConnectorPortOracle EBSNú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_IMPUESTOSRubrosConnectorServiceITaxesConnectorPortAS400Desglose de impuestos trasladados/retenidos: tipo (IVA, IEPS), base, tasa o cuota, importe de impuesto, retenciones.
SISTEMA_CFDIInterno / TimbradoN/ACFDI BaseUUID 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​

  1. 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.
  2. Determinación de Conectores Requeridos: Se consultan las definiciones en cat_addenda_tokens para los tokens identificados. Si una addenda solo requiere tokens de FACTURA y PEDIDO, el orquestador evita invocar fuentes innecesarias o prioriza la resolución.
  3. Extracción Determinista de Propiedades: Al recibir los VOs (AddendaHeaderVO, AddendaClientVO, AddendaItemsVO, AddendaTaxesVO), el componente TokenOriginResolver consulta campo_origen_path y estrategia_extraccion para 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álculoCaso de Uso / Cadena en HU2Expresión de EjemploDescripción y Manejo
Prorrateos y Porcentajes GlobalesTiendas 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 PartidaGeneral / 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 ImpuestosTiendas 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 ComprobanteTotales 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 / DependientesCadenas con fórmulas compuestasPaso 1 (orden 1): $DetalleNeto$ = $Detalleimporte$ - $DetalleDescuento$
Paso 2 (orden 2): $DetalleIvaNeto$ = $DetalleNeto$ * 0.16
Paso 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. 4 a 6 decimales) 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​

  1. Protección ante División entre Cero (Zero-Division Protection):
    • Si en una expresión como $Encabezadodescuentos$ / $Encabezadototal$ el divisor $Encabezadototal$ es 0, 0.00 o nulo, el evaluador no propaga ArithmeticException; 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).
  2. 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 a BigDecimal.ZERO (o a BigDecimal.ONE si 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.
  3. 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.SimpleEvaluationContext configurado exclusivamente para lectura de propiedades y evaluación matemática, bloqueando acceso a java.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.

5.4 Fases del Procesamiento Integral de la Plantilla​

[!NOTE] El diagrama oficial independiente se encuentra en diagrama_fases_procesamiento.mmd.

  1. Recuperación y Caché: Búsqueda en cat_addenda_plantillas de la versión publicada vigente a la fecha de emisión del comprobante (gestionada en caché local Caffeine / distribuida Redis).
  2. 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 de cat_addenda_tokens.
  3. Resolución de Tokens Custom Fijos: Inyección de valores literales constantes definidos en la plantilla (tipo_valor = 'FIJO').
  4. 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ón BigDecimal, control de redondeo y protección contra división entre cero.
  5. Evaluación de Reglas de Transformación Condicional: Operaciones =, <>, =r (con token destino) y <>r para homologaciones de unidades de medida (UOM) o mapeos condicionales.
  6. Resolución de Modificadores de Formato: Aplicación de modificadores de longitud fija ({Size_N}) con relleno configurable y formateadores de fecha ({yyMMdd}).
  7. Poblado del Contexto Thymeleaf: Construcción de org.thymeleaf.context.Context con todas las variables del comprobante, mapa plano de tokens, variables custom y utilitarios #math y #dates.
  8. Renderizado de Detalle y Encabezado con Thymeleaf: Procesamiento de las partidas de detalle y la cabecera mediante el motor TemplateMode.XML de Thymeleaf.
  9. 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​

  1. Escape Seguro de Caracteres Especiales: Manejo automático de entidades XML (&amp;, &lt;, &gt;, &quot;, &apos;). Evita que razones sociales con ampersands (ej. "SANCHEZ & ASOCIADOS S.A.") o descripciones con caracteres reservados corrompan el árbol XML final.
  2. 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.).
  3. Potencia de Expresiones y Formateo: Integración nativa con Spring Expression Language (SpEL) y objetos de utilidad de contexto (#numbers.formatDecimal(...), #temporals.format(...), etc.).
  4. 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/>)​
  1. 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 plantilla xml_plantilla_detalle se procesa mediante Thymeleaf; los fragmentos XML resultantes se concatenan preservando el orden de línea recibido.
  2. Inyección en Marcador: El bloque consolidado de detalles sustituye el marcador <cfdi:DetalleAddenda/> en la plantilla de encabezado.
  3. Fase Encabezado: Se pre-procesan los tokens del encabezado ($Encabezado...$) y tokens custom en la plantilla resultante, evaluándola a través del motor addendaXmlTemplateEngine en TemplateMode.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 Entity con 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:

  1. 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_id fijo por cliente obligaría a duplicar o actualizar masivamente registros ante cualquier cambio de versión de la addenda.
  2. 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.0 a 2.0 a 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.
  3. 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_plantillas sin requerir migraciones DDL ni DML sobre las tablas del core transaccional de facturación.

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ónCampo en cat_addenda_plantillasOrigen en el Comprobante / PeticiónDescripción y Justificación
1. Cadena Comercialcadena_codigo (id_cadena)AddendaGenerationRequestVO.cadena
o 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 Comprobantetipo_comprobanteFacturacionComprobanteDO.tipoComprobante
o 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 Temporalfecha_inicio_vigencia
fecha_fin_vigencia
FacturacionComprobanteDO.fechaEmision
(Fecha fiscal de emisión)
Determina la versión activa evaluando:
p.fecha_inicio_vigencia <= :fechaEmision
AND (p.fecha_fin_vigencia IS NULL OR p.fecha_fin_vigencia >= :fechaEmision).
Garantiza reproducibilidad histórica de addendas emitidas en fechas pasadas.
4. Estado Operativoestado
dn_activo
Control de ciclo de vida del catálogoFiltra 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:

  1. Controlador Web: AddendaGenerationController.generarAddenda(...) recibe el payload JSON validando el rol ADDENDA_GENERAR.
  2. Capa Fachada: AddendaGenerationFacadeImpl.generarAddenda(...) valida parámetros mínimos requeridos y delega en el orquestador bajo contexto transaccional @Transactional.
  3. Orquestador Principal: AddendaOrchestrationServiceImpl.procesarAddenda(...) resuelve la estrategia mediante IAddendaStrategyResolver y dispara la agregación de datos y renderizado.
  4. Agregado de Facturación Optimizado: IFacturacionComprobanteRepository.findAggregateByIdentifier(...) consolida en un único SELECT con LEFT JOIN la cabecera, remisión, receptor, emisor e impuestos del comprobante fiscal.
  5. Servicio de Configuración de Plantillas: PlantillaConfigurationServiceImpl.findVigente(...) invoca al repositorio con la terna (cadena, tipoComprobante, fechaEmision).
  6. 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-DD y TTL configurable (1 hora).
  • Invalidación Reactiva: La publicación de una nueva plantilla o el cambio a estado OBSOLETA mediante PlantillaConfigController.publicarPlantilla(...) o PlantillaConfigurationServiceImpl.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:

  1. 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'), fechaInicioVigencia y 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 directivas th: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 con DocumentBuilderFactory endurecido (XMLConstants.FEATURE_SECURE_PROCESSING = true). Si el XML no está bien formado, la petición es rechazada con error 422 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 error 409 Conflict (PLANTILLA_DUPLICATE_VERSION).
  2. 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ía POST /api/v1/configuraciones/plantillas/{id}/custom-tokens.
  3. 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).
  4. 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.
  5. 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.

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:

SubsistemaResponsabilidadMomento de EjecuciónEntidad / Configuración
1. Reglas de Cálculo AritméticoEvaluació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 CondicionalHomologació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 FormatoAjustes 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 mismo token_origen o uno específico).
  • orden_evaluacion: Secuenciador para aplicar transformaciones encadenadas.
Catálogo Exhaustivo de Operadores Condicionales​
  1. Operador = (Igualdad Literal y Mapeo en Listas):

    • Comportamiento: Compara si el valor actual del token coincide exactamente con valor_condicion. Si valor_condicion contiene 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".
    • 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).
  2. 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".
  3. 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 en token_destino o en nuevo_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$.
  4. 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$.

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. 2 para importes finales, 4 o 6 para 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$ es 0 o nulo, el motor captura la condición, asigna el valor predeterminado seguro 0.00 y 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 (o BigDecimal.ONE si operan como factor multiplicador neutro).
  • Entorno de Ejecución Seguro (Sandboxed Evaluation): La evaluación SpEL se ejecuta en un SimpleEvaluationContext estrictamente 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:

ModificadorSintaxis en PlantillaEntrada de EjemploSalida RenderizadaCaso 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 ComercialNecesidad Técnica / ComercialRegla AplicadaImplementación en el Motor
Tiendas SorianaConcatenació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 ConsolidadaDiferenciació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 3BPorcentaje 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ánchezHomologació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éxicoConteo 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:

  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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).
  1. 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.
  1. 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>.
  1. 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).
  1. 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.
  1. 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).
  1. 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).
  1. 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}).
  1. 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).
  1. 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}).
  1. 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).
  1. 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).
  1. 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.

7. Especificación de Endpoints (API REST)​

MétodoEndpointRol de SeguridadDescripciónDiagrama de Secuencia Asociado
POST/api/v1/addendas/generarADDENDA_GENERARGenera 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/previsualizarADDENDA_ADMINPermite renderizar usando una versión en borrador antes de su publicación.diagrama_secuencia_previsualizar.mmd
GET/api/v1/configuraciones/plantillasADDENDA_ADMINConsulta 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_ADMINObtiene el detalle completo de una plantilla por ID (encabezado, detalle y XSD).diagrama_secuencia_plantillas_consulta.mmd
POST/api/v1/configuraciones/plantillasADDENDA_ADMINAlta de una nueva plantilla (XML de encabezado, XML de detalle, vigencias, etc.).diagrama_secuencia_plantillas_creacion.mmd
PUT/api/v1/configuraciones/plantillas/{id}ADDENDA_ADMINActualización de versión o contenido de plantilla existente.diagrama_secuencia_plantillas_modificacion_baja.mmd
DELETE/api/v1/configuraciones/plantillas/{id}ADDENDA_ADMINBaja lógica (soft delete) de plantilla y tokens custom asociados.diagrama_secuencia_plantillas_modificacion_baja.mmd
POST/api/v1/configuraciones/plantillas/{id}/publicarADDENDA_ADMINPublica formalmente una versión invalidando la caché distribuida/local.diagrama_secuencia_publicar_plantilla.mmd
GET/api/v1/configuraciones/plantillas/{id}/custom-tokensADDENDA_ADMINConsulta los campos/tokens custom asociados a una plantilla (fijos y calculados).diagrama_secuencia_custom_tokens.mmd
POST/api/v1/configuraciones/plantillas/{id}/custom-tokensADDENDA_ADMINRegistra 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_ADMINElimina o desactiva un campo/token custom de la plantilla.diagrama_secuencia_custom_tokens.mmd
GET/api/v1/tokensADDENDA_ADMINCatálogo global de tokens disponibles. Soporta filtro query `?tipoOrigen=FACTURACLIENTE
POST/api/v1/tokensADDENDA_ADMINAlta 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ódigoConstante ServiceErrorCodeEnumExcepción JavaHTTP StatusDominio / CapaDescripción FuncionalCondición DisparadoraAcción Correctiva / Recuperación
0UNKNOWN_ERRORAlpuraException500 Internal Server ErrorSistema / CoreError no controlado o imprevisto.Excepción no capturada en tiempo de ejecución o falla de infraestructura.Consultar traza y telemetría con correlationId.
1REQUIRED_FIELDAlpuraException / MethodArgumentNotValidException400 Bad RequestWeb / DTOCampo 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.
2EXCEEDS_MAX_LENGTHAlpuraException / ValidationException400 Bad RequestWeb / DTOCadena 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.
404NO_RESULTSAlpuraException404 Not FoundPersistencia / CatálogosConsulta sin registros coincidentes.Búsqueda por criterios o identificador no arrojó resultados activos.Verificar los parámetros o identificadores enviados.
500ADDENDA_PROCESSING_ERRORAlpuraException500 Internal Server ErrorMotor de AddendasError 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.
1001ADDENDA_CADENA_REQUIREDAlpuraException400 Bad RequestGeneración / PrevisualizaciónCódigo de cadena comercial no especificado.requestVO.getCadena() == null o requestVO.getCadena().isBlank().Indicar la cadena comercial destinataria (ej. "SORIANA", "OXXO").
1002ADDENDA_REQUEST_EMPTYAlpuraException400 Bad RequestGeneración / PrevisualizaciónPayload de solicitud nulo o vacío.requestVO == null o requestVO.getParameters() == null.Enviar un objeto JSON de comprobante válido.
2001PLANTILLA_NOT_FOUNDAlpuraException404 Not Found / 422 Unprocessable EntityPlantillas / GeneraciónPlantilla 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.
2002PLANTILLA_DUPLICATE_VERSIONAlpuraException409 ConflictPlantillasConflicto 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.
2003PLANTILLA_INVALID_XMLAlpuraException422 Unprocessable EntityPlantillas / Motor XMLXML 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.
2004CUSTOM_TOKEN_NOT_FOUNDAlpuraException404 Not FoundTokens CustomToken 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.
2005PLANTILLA_REQUIRED_FIELDAlpuraException400 Bad RequestPlantillas / Tokens CustomPará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.
3001CATALOG_SERVICE_ERRORAlpuraException502 Bad Gateway / 503 Service UnavailableConectores / CatálogosError 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.
504ADDENDA_TIMEOUT_FAIL_FASTAddendaAssemblyException504 Gateway TimeoutOrquestador AssembledTimeout 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 o parameters es nulo.
    • 1001 - ADDENDA_CADENA_REQUIRED (400 Bad Request): El atributo cadena no fue enviado o viene en blanco.
    • 1 - REQUIRED_FIELD (400 Bad Request): Faltan campos fiscales indispensables cuando se omite el invoiceId.
  • 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' y dn_activo = true que 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 OK con data: [], totalRows: 0 y page: 0.
  • Detalle por ID (GET /{id}):
    • 2005 - PLANTILLA_REQUIRED_FIELD (400 Bad Request): Si el parámetro id es nulo o inválido.
    • 2001 - PLANTILLA_NOT_FOUND (404 Not Found): No existe plantilla con el ID suministrado o se encuentra con dn_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 de cadenaCodigo, tipoComprobante, version, fechaInicioVigencia, xmlPlantillaEncabezado o xmlPlantillaDetalle.
  • 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): Falta idPlantilla o 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 modifica version, cadenaCodigo o tipoComprobante y 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ámetro id ausente.
    • 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ámetro id nulo.
    • 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): id de 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): Falta claveTokenCustom o tipoValor.
    • 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): idPlantilla o tokenId nulo.
    • 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.00 y emite una advertencia en el payload.
  • Token Faltante en Expresión: Se normaliza de forma segura a BigDecimal.ZERO o BigDecimal.ONE.
  • Fórmula con Error de Sintaxis: Se intercepta como 500 - ADDENDA_PROCESSING_ERROR con 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​

  1. 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.
  2. Timeouts Escalonados:
    • Timeouts individuales por conector: 300ms a 1000ms.
    • Deadline global en orquestador StructuredTaskScope: 1500ms.
  3. Métricas y Trazabilidad:
    • Métricas en Micrometer: addenda.generation.duration, addenda.connector.latency, addenda.flow.strategy.used.
    • Trazas distribuidas con OpenTelemetry propagando correlationId entre hilos virtuales y llamadas HTTP/JDBC.
    • Bitácora en base de datos para auditoría y reprocesos.