Cockpit (panel de operación)¶

El Cockpit es la cara operativa del backend: un conjunto de endpoints REST de monitoreo y de operación, más una interfaz web que los consume para responder, de un vistazo, ¿está vivo el enlace con AFIP?, ¿cuánto se está emitiendo y con qué tasa de éxito? y ¿qué quedó pendiente de resolver?. Para el por qué del ciclo CAE/CAEA que estas métricas reflejan, mirá El ciclo de facturación; acá están los datos exactos.

La UI es una SPA estática (src/main/resources/static/cockpit.html, ~1180 líneas, con el micro-framework reactivo Arrow.js — sin build, sin React/Thymeleaf), servida directamente por Spring. Hace polling a /api/cockpit/* cada ~5 s. WebConfig la mapea a tres rutas que cambian el modo desde la misma página:

Además del modo de la ruta, el runner se gatea por configuración del server: la SPA consulta GET /api/cockpit/config al arrancar y, si runnerEnabled=false (perfil prod, fail-closed), oculta el bloque del runner aunque la ruta sea de test. Ver Configuración y perfiles.

La interfaz¶

La UI v2 muestra toda la operación en una sola página, filtrable por comercio (multi-ente). Vista general, con datos reales del ambiente de prueba:

La fila birds-eye resume la salud de cada comercio de un vistazo: la sucursal con sus POS y su KPI, el gateway en el medio y, a la derecha, el estado del enlace con ARCA/AFIP (online/offline y vigencia del token de acceso):

El ABM de comercios se desbloquea con el secret (X-Cockpit-Secret) y permite dar de alta/baja EnteFacturador, cargar su certificado y administrar sus puntos de venta:

En modo test, el runner de escenarios ejecuta operaciones contra AFIP homologación (obtener token, dummy, consultar último comprobante, emitir un CAE de prueba, etc.) y muestra el XML SOAP del tráfico:

Todo cuelga del paquete com.tipre.tifacturaonlinemanager.cockpit. Hay tres bloques bien diferenciados:

1. Monitoreo — CockpitController¶

@RestController en /api/cockpit. Pensado para polling cada pocos segundos. Combina dos fuentes de verdad:

• Métricas en memoria (CockpitMetrics): contadores OK/error por operación AFIP, vivos, thread-safe, que se pierden al reiniciar. Es monitoreo operativo, no auditoría.
• Datos de la DB (CockpitPendientes, CockpitPorPos, CockpitAfipStatus, etc.): backlog, stats por POS y estado del TA.

Endpoints¶

Métricas en memoria (CockpitMetrics)¶

Las operaciones que se cuentan están en el enum CockpitMetrics.Op:

Cada OpStat expone ok, error, total y successRate (0..100; 100 si no hubo intentos). El buffer de errores recientes está acotado a 50 entradas (recentErrors, más reciente primero). Los clientes AFIP (WSAA/WSFE) alimentan estos contadores al ejecutar cada operación; además, recordError persiste el error vía TrxErrorRegistro para que la grilla /errores lo vea aunque el contador en memoria se haya reseteado.

Estado AFIP (CockpitAfipStatus)¶

/afip-status arma tres bloques:

• online — ping FEDummy a WSFE (no requiere TA). Cacheado 60 s (DUMMY_TTL_MS) para no martillar a AFIP. Reporta appserver/dbserver/authserver y checkedAt. Agrega estado (online | verificando | caido) y fallosConsecutivos con debounce (ver abajo).
• ta — si el EnteFacturador habilitado tiene token, cuándo expira (expira), si está vigente y minutosRestantes.
• facturador — cuit y razonSocial del primer EnteFacturador habilitado.

Los dos ABM del cockpit (PVs y comercios) son config fiscal sensible: un PV mal cargado factura contra el punto de venta equivocado; un cert mal seteado firma con la identidad equivocada. Por eso, además de la autenticación user/pass de cockpit-auth (sección 5), suman un segundo candado: el header X-Cockpit-Secret, centralizado en el componente compartido CockpitAdminGuard (requireSecret(...)), inyectado en ambos controllers (una sola fuente de verdad del candado).

• El secret se configura por la env var COCKPIT_ADMIN_SECRET (property cockpit.admin-secret).
• El front lo manda en el header X-Cockpit-Secret en cada request del ABM.
• Comparación en tiempo constante (MessageDigest.isEqual) para no filtrar el secret por timing.
• Fail-closed: si no hay secret configurado, todo el ABM responde 503 (deshabilitado). Si el secret no coincide, 401.

3. ABM de SucPosPV — CockpitAdminController¶

SucPosPV es el mapeo sucursal + POS físico → punto de venta CAE (y opcionalmente CAEA) de AFIP, con su comercio dueño (idEnteFacturador). Va detrás de cockpit-auth + el secret de la sección 2.

Endpoints¶

El cuerpo de alta/edición es {suc, pos, pvcae, pvcaea, idEnteFacturador} donde pvcaea es opcional (nullable) — un POS puede facturar solo CAE — e idEnteFacturador es obligatorio en alta (en edición, null = no cambia el dueño).

Las ResponseStatusException se traducen a JSON {status, message} mediante un @ExceptionHandler propio, porque con la cadena de filtros de Security el resolver por defecto las dejaría salir como 500.

4. ABM de comercios — EnteFacturadorAdminController¶

CRUD de EnteFacturador (tabla EntesFacturadores): el comercio dueño de los PVs, con su CUIT, razón social, flag habilitado (el mismo que lee la resolución de ente en emisión), su certificado .p12 por comercio y los campos de PDF del comprobante (getPdf). Vive bajo /api/cockpit/comercios, detrás de cockpit-auth + el mismo secret X-Cockpit-Secret (sección 2). Reemplaza por UI lo que antes se administraba a mano en SQL. No toca emisión, money-path ni WSDL — es administración pura.

Campos de PDF del comprobante (getPdf)¶

El ABM administra los dos campos que configuran el PDF por comercio: backGroundFacturaPath (path de filesystem al PDF template del comprobante) y layout (copias: 1=ORIGINAL, 2=+DUPLICADO, 0=sin PDF). EnteFacturadorForm los expone y el service valida layout a 0..2 antes de persistir (rechaza con AbmComercioException); null/vacío = no tocar el valor actual (permite editar sin re-tipear). Ver Email y PDF.

El cert es write-only (la password nunca sale)¶

La protección es por whitelist, no blacklist: las respuestas del ABM nunca serializan la entidad EnteFacturador, solo el DTO de lectura EnteFacturadorView, que no tiene campo certP12Password (ni getter). Que el campo no exista en el DTO ⇒ Jackson no puede emitirlo bajo ninguna config futura.

• EnteFacturadorView (lectura) publica: id, razonSocial, cuit, habilitado, certP12Path, certP12Alias, certConfigurado. certConfigurado es un booleano derivado (certP12Password != null && !blank) que deja al front mostrar "Cert: configurado / sin configurar" sin revelar la clave.
• EnteFacturadorForm (escritura) sí incluye certP12Password. Semántica de set: null/vacío → no toca el valor actual en DB; string no vacío → lo reemplaza. Así se puede editar razón social o el path sin re-tipear la clave.
• El service tiene prohibido loguear la entidad (su toString() arrastra token/sign) y el valor de la password en cualquier nivel.

Recarga de cert (evict del TA en 2 niveles)¶

POST /api/cockpit/comercios/{id}/cert/reload invalida el TA cacheado del comercio para que la próxima emisión re-logueé con el cert recién guardado, sin reiniciar la app. El evict limpia dos niveles (vía EnteFacturadorTokenProvider.evict):

• L1 (memoria): la entrada por CUIT del WsaaTokenCache.
• L2 (DB): nulea token/sign/expirationTime de la fila del EnteFacturador.

Limpiar solo L1 dejaría el TA viejo VIGENTE en L2 (DB), y la próxima emisión seguiría firmando con el cert viejo — por eso se limpian ambos. Requiere cert configurado (path + password): si no, responde 422. El re-login es lazy (ocurre en la próxima emisión real), no inmediato. La respuesta avisa: "Cert recargado. El TA nuevo se emitirá en la próxima emisión (puede requerir esperar a que expire el TA anterior en AFIP)."

Verificación de PVs contra AFIP (F5)¶

GET /api/cockpit/comercios/{id}/pvs-afip compara los puntos de venta configurados localmente para el comercio contra los que AFIP reporta por FEParamGetPtosVenta (vía PtoVentaConsultaService). Es solo lectura (no toca money-path). Devuelve PvsAfipComparacion (solo números de PV, sin datos sensibles):

Si AFIP falla (timeout, sin TA, cert inválido) responde 502 (AfipException).

Endpoints¶

5. Autenticación del cockpit — cockpit-auth (SecurityConfig)¶

El cockpit ya no está abierto. SecurityConfig (com.tipre.tifacturaonlinemanager.config) define un SecurityFilterChain que protege el cockpit y deja abiertos los endpoints de facturación.

Qué está protegido y qué no¶

Los matchers van de más específico a más general: los de cockpit primero, después los permitAll del SOAP/WS y el anyRequest. (Sin listar /cockpit-test, /cockpit-prod y /cockpit.html explícitos, esos caían al anyRequest().permitAll() y quedaban SIN auth — por eso están enumerados.)

Mecanismo, user store y credenciales¶

• HTTP Basic (httpBasic) para la API/runner/scripts/tests de integración + form login (formLogin) para el browser. Ambos sobre el mismo filter chain.
• User store: InMemoryUserDetailsManager con un único usuario, rol COCKPIT, password codificada con BCrypt. No usa la tabla Usuarios legacy.
• Credenciales por entorno: cockpit.auth.user / cockpit.auth.password (env COCKPIT_USER / COCKPIT_PASS). En dev, defaults admin / changeme (application-dev.yml). No hay credenciales hardcodeadas en el código.
• Aviso de arranque: si las credenciales están vacías o son las de dev por defecto, SecurityConfig loguea un WARN ("usando credenciales por defecto de dev… configurá COCKPIT_USER/COCKPIT_PASS antes de exponer en producción").

CSRF¶

CSRF queda deshabilitado para todo lo máquina-a-máquina (ignoringRequestMatchers): /api/** (API del cockpit), /TiFacturaOnlineManagerWS/** y /ws/** (SOAP del POS) y /fecaeaSolicitar (REST del notificador DINO). Esos clientes son máquinas y no mandan token CSRF — con CSRF activo recibirían 403 y se rompería la emisión. CSRF sigue activo solo para el form login del cockpit (browser).

6. Test runner — CockpitTestRunnerService / CockpitTestRunnerController¶

@RestController en /api/cockpit/test. Son acciones de validación técnica contra AFIP homologación. Cada método mide durationMs, captura excepciones y devuelve siempre {ok, durationMs, error, …campos} — nunca tira la excepción al cliente. Además el controller envuelve cada llamada en withTraffic(...), que captura el XML SOAP request/response hacia ARCA y lo agrega en la clave traffic: [{dir, action, xml}] para inspeccionarlo desde el panel.

Endpoints¶

Los endpoints que emiten o consultan contra AFIP aceptan, además de sus params propios, la pareja opcional enteId + idModo para elegir por qué identificador se resuelve el comercio (ver "Identificación del comercio" abajo).

En la UI del runner¶

El escenario "Obtener CAE" ofrece un selector de Protocolo POS que decide a qué endpoint pega el front: V2 · NextGen (/test/cae, default) o V1 · clásico (/test/cae-v1). El panel de resultado muestra el protocolo usado (V1 · fecaeSolicitar / V2 · fecaeSolicitar (nroTicketPos)) — ambos por la misma operación SOAP fecaeSolicitar, distinguidos por nroTicketPos.

En los escenarios que piden tipo de comprobante (Último comprobante y Consultar comprobante), el tipo dejó de ser un campo libre: ahora es un listbox restringido a los tipos permitidos [1, 3, 6, 8, 11, 13] (Facturas y Notas de Crédito A/B/C; sin Notas de Débito).

Manejo de errores (CockpitExceptionHandler)¶

Los endpoints del cockpit son nuevos: no forman parte del contrato legacy SPEC-009 (que replica el DefaultExceptionHandler global con 500 + headers exception-class/exception-message + stacktrace en el body — ver API REST). Para no filtrar estructura interna, un @RestControllerAdvice scopeado al paquete com.tipre.tifacturaonlinemanager.cockpit (@Order(HIGHEST_PRECEDENCE)) los maneja distinto:

• ResponseStatusException (status intencionales: 403 runner off, 401/503 del ABM, etc.) → ese mismo status con body {ok:false, error:<reason>}.
• Cualquier otra excepción → 500 con {ok:false, error:"Error interno del cockpit"}; el detalle completo (con stacktrace) queda solo en el log del server, nunca en la respuesta.

Como está scopeado por basePackages, no toca los controllers de negocio (web.*) ni el SOAP; y los @ExceptionHandler propios de cada controller (p.ej. el {status, message} del ABM) siguen teniendo prioridad. El hardening de errores de mapeo (404/405, que se lanzan antes de resolver el controller) vive aparte en MappingErrorHardeningHandler — ver API REST.

Para emitir un CAE de prueba paso a paso, mirá la guía de tareas.

Por dónde seguir¶

• Jobs Quartz — la grilla /jobs del cockpit muestra estos jobs.
• API REST — el resto de la superficie REST del backend.
• El ciclo de facturación — qué significan CAE, CAEA y los estados que el cockpit reporta.
• Setup del entorno — para levantar el backend y pegarle al cockpit en local.