Arquitectura del sistema¶

Esta página explica cómo está armado TiFacturaOnlineNext y, sobre todo, por qué. Para los datos exactos —versiones, dependencias, rutas de endpoints— andá a Backend TiFacturaOnlineNext. Acá te cuento la forma del sistema y la lógica detrás de las decisiones, que en este proyecto está dominada por una sola fuerza: fue un legacy Seam/JBoss que se migró a Spring Boot sin reescribir el negocio. Si entendés eso, entendés casi todo lo demás.

Una foto de 10.000 metros¶

TiFacturaOnlineNext es un monolito Spring Boot: un único proceso (com.tipre.tifacturaonlinemanager.Application, anotado @SpringBootApplication + @EnableScheduling) que arranca un Tomcat embebido, conecta a SQL Server, publica endpoints SOAP y REST, y agenda jobs Quartz. No hay microservicios, no hay colas, no hay broker: la complejidad no está en la topología, está en el diálogo fiscal con AFIP y en preservar el comportamiento del legacy.

graph TD
    POS["POS / sistema de ventas"]
    OPS["Cockpit UI<br/>(operador)"]

    subgraph App["TiFacturaOnlineNext (un proceso Spring Boot 4)"]
        direction TB
        subgraph Edge["Capa de borde (adaptadores)"]
            SOAP["SOAP · CXF<br/>TrxWS · CaeaWS · TiFacturaOnlineManagerWS"]
            REST["REST · Spring MVC<br/>/caeaWS · /fecaeaSolicitar · /api/cockpit"]
            QZ["Quartz<br/>(tabla Tareas)"]
        end
        subgraph Biz["Lógica de negocio (lift &amp; shift)"]
            SVC["Services de facturación<br/>FacturacionService · CaeaGestion · ..."]
            CLI["Cliente AFIP<br/>WSAA · WSFE · firma CMS"]
        end
        subgraph Compat["seam-compat (paquete org.jboss.seam.*)"]
            HOME["EntityHome / EntityQuery / Controller"]
            COMP["Component · ScopeType · @Name / @Scope"]
        end
        SOAP --> SVC
        REST --> SVC
        QZ --> SVC
        SVC --> CLI
        SVC --> HOME
        HOME --> COMP
    end

    DB[("SQL Server<br/>esquema lo administra el cliente")]
    AFIP["AFIP / ARCA<br/>WSAA + WSFEv1"]

    POS -->|SOAP + REST| Edge
    OPS -->|REST| REST
    SVC -->|JPA / Hibernate 7| DB
    CLI -.->|SOAP firmado · red externa| AFIP

Por qué hay un paquete org.jboss.seam en el repo¶

Esta es la decisión arquitectónica que más sorprende al entrar. El código de negocio legacy usa la API de Seam: anotaciones @Name, @Scope, accesores estáticos Component.getInstance(...), clases base EntityHome / EntityQuery. Reescribir todos esos import org.jboss.seam.* sería cambiar código de negocio — exactamente lo que la regla de oro prohíbe.

La solución fue construir un shim: reimplementar el subconjunto de Seam que la app usa, manteniendo los mismos nombres de paquete y clase, pero por dentro delegando en Spring. El código legacy compila y corre sin que se le toque una línea.

graph LR
    LEGACY["Código de negocio<br/>com.tipre.tifacturaonlinemanager.*<br/>(usa import org.jboss.seam.*)"]
    COMPAT["seam-compat<br/>org.jboss.seam.*<br/>(reimplementación)"]
    SPRING["Spring<br/>ApplicationContext · Scopes · Tx"]

    LEGACY -->|"compila contra<br/>el mismo paquete"| COMPAT
    COMPAT -->|"delega en"| SPRING

Algunos puentes concretos, verificables en el repo de código:

El detalle profundo de esta capa está en La capa seam-compat. Lo importante a nivel arquitectura: seam-compat es la pieza que hace posible no reescribir. Crece por demanda; el código de negocio no se toca.

La capa de borde: tres superficies, un núcleo¶

El sistema expone tres formas de entrar, y todas terminan en el mismo núcleo de negocio.

SOAP — el contrato congelado (Apache CXF)¶

Tres endpoints SOAP 1.2, publicados con CXF en modo contract-first: TrxWS, CaeaWS y TiFacturaOnlineManagerWS. La decisión clave —visible en config/CxfSoapConfig.java— es que cada endpoint se publica con setWsdlLocation("wsdl/X.wsdl"), sirviendo el WSDL EXACTO del baseline de producción, no el que CXF regeneraría. Es la vía más segura para el diff de WSDL bloqueante que exige el proyecto.

graph TD
    BASE["WSDL baseline de producción<br/>src/main/resources/wsdl/*.wsdl"]
    GEN["cxf-codegen-plugin (wsdl2java)<br/>genera el SEI + DTOs JAXB"]
    EP["Endpoints CXF<br/>TrxWsEndpoint · CaeaWsEndpoint · TfomWsEndpoint"]
    SERVED["WSDL servido en runtime<br/>setWsdlLocation(classpath wsdl)"]

    BASE --> GEN --> EP
    BASE --> SERVED
    EP --> SERVED

Detalle no obvio, documentado en el propio CxfSoapConfig.java: el handler JAX-WS legacy (WSServerLogHandler) no se porta, porque su logging estaba muerto/comentado en el legacy y su única función viva —montar el contexto Seam— ya la cubre SeamEventScopeFilter. Replicar el legacy fielmente acá significa no logear el cuerpo SOAP, igual que producción.

REST — Spring MVC¶

Reemplaza al RESTEasy/JAX-RS del legacy con controladores Spring MVC. Las rutas verificadas:

El detalle en API REST.

Quartz — los jobs que viven en la base¶

El scheduling no está hardcodeado: las tareas se leen de la tabla Tareas en SQL Server. Al arrancar, action/quartz/TareaScheduler.java lee la tabla, y por cada fila hace Class.forName(...) para resolver la clase del job y la agenda con su expresión cron. Esto reproduce el modelo del legacy, donde el cron vivía en la base de datos.

graph TD
    START["Arranque de la app"] --> READ["TareaScheduler lee tabla Tareas"]
    READ --> LOOP["Por cada Tarea:<br/>Class.forName(jobProcessor)"]
    LOOP --> SCHED["Agenda JobDetail + CronTrigger<br/>con Tarea.programacion (cron)"]
    SCHED --> RUN["El job corre"]
    RUN --> LOCK["CommonJob: toma lock ThreadSafety<br/>(1 ejecución por Tarea)"]
    LOCK --> BITA["Persiste bitácora en JobEjecucion<br/>(inicio · fin · resultado · error)"]

Los jobs principales (en action/job/):

El locking lo provee model/tarea/ThreadSafety.java: garantiza una sola ejecución por Tarea a la vez. Más en Jobs Quartz.

El núcleo de negocio y el borde con AFIP¶

Por dentro de la capa de borde, los services orquestan la facturación y delegan el diálogo fiscal en el cliente AFIP (action/ws/client/). Ese borde es el más complejo del sistema y el único que sale a la red externa. El flujo, simplificado:

graph TD
    REQ["Pedido de comprobante"] --> TOK{"¿Token WSAA<br/>vigente?"}
    TOK -->|"sí (cache / DB)"| SIGN
    TOK -->|"no"| LOGIN["WSAA LoginCMS<br/>firma CMS (BouncyCastle, SHA1, encapsulado)"]
    LOGIN --> SIGN["Arma el pedido WSFEv1"]
    SIGN --> CALL["FECAESolicitar a AFIP"]
    CALL --> OK{"¿AFIP autorizó?"}
    OK -->|"sí"| CAE["Persiste CAE en la Trx<br/>(cae · caeFchVto · caeBarCode)"]
    OK -->|"AFIP caído / error"| CAEA["Fallback: emite con CAEA<br/>e informa en diferido (job)"]

El token WSAA se obtiene con una estrategia de capas (memoria → DB → login nuevo) persistiendo token/sign/expirationTime en la entidad EnteFacturador, de modo que sobrevive a reinicios. La firma es CMS SHA1 encapsulado con provider BouncyCastle "BC" — una invariante sagrada: la salida firmada tiene que ser válida para AFIP. Todo el detalle en Cliente AFIP y el flujo CAE/CAEA completo en El ciclo de facturación.

El Cockpit: operar sin tocar la base¶

Sobre el mismo proceso vive un panel de operación (paquete cockpit/), expuesto bajo /api/cockpit. No es parte del contrato con el POS: es para que un operador vea la salud del sistema —métricas de emisión, estado de AFIP, jobs agendados, últimas transacciones, comprobantes pendientes y errores— y administre la tabla SucPosPV (la relación sucursal+POS → puntos de venta AFIP). El ABM admin está protegido por un secreto de header (X-Cockpit-Secret). Más en Cockpit.

Persistencia: el esquema no es nuestro¶

Un principio que atraviesa toda la arquitectura: la app nunca genera ni altera DDL. El esquema SQL Server lo administra el cliente (hbm2ddl=none). Las entidades JPA (model/) mapean tablas existentes con nombres literales en PascalCase (Trx, Caeas, EntesFacturadores, TiposComprobante, Tareas). Por eso los "enums AFIP" del dominio (TipoComprobante, TipoDocumento, etc.) en realidad no son enums de Java: son entidades JPA que mapean tablas de catálogo (@Table(name = "TiposComprobante")). Esto es fácil de malinterpretar.

Lo que no podés romper¶

La arquitectura está al servicio de una restricción: comportamiento observable idéntico al legacy. Tres barreras lo hacen cumplir.

Por dónde seguir¶

• Migración Seam/JBoss → Spring Boot — la estrategia completa, fase por fase.
• La capa seam-compat — cómo funciona el shim por dentro.
• Invariantes sagradas — lo que no se toca.
• Glosario del dominio — todo el vocabulario AFIP y técnico.
• Backend TiFacturaOnlineNext — los datos exactos de stack y build.