Jobs Quartz¶

El backend corre tareas de fondo con Quartz (spring-boot-starter-quartz, RAMJobStore por default). No hay crons hardcodeados: cada job se da de alta como una fila en la tabla Tareas y se agenda en el arranque. Esto reemplaza al scheduling Seam-async del legacy (TaskMainController con @Startup/@Observer + StdSchedulerFactory por tarea). El detalle del diseño está en SPEC-011; acá está la referencia operativa. Para entender qué hace cada job en el ciclo fiscal, mirá El ciclo de facturación.

Cómo se cargan los jobs¶

flowchart LR
  A["Arranque<br/>ApplicationReadyEvent"] --> B["TareaScheduler<br/>lee tabla Tareas"]
  B --> C["por cada Tarea:<br/>resolveJobClass + cron"]
  C --> D["scheduler.scheduleJob<br/>JobDetail + CronTrigger"]
  D --> E["REGISTRY id→Tarea<br/>(para CommonJob)"]
  E --> F["¿hay TokenManagerJob?<br/>triggerJob YA (warm-up TA)"]

El componente central es TareaScheduler (action/quartz/TareaScheduler.java):

1. En @EventListener(ApplicationReadyEvent.class) recorre TareaList.instance().getResultList() (todas las filas de Tareas).
2. Por cada Tarea resuelve la clase del job desde jobProcessor (nombre simple → se le antepone el paquete com.tipre.tifacturaonlinemanager.action.job.; o FQCN si trae punto), valida que implemente org.quartz.Job y arma un JobDetail + CronTrigger con el cron de programacion.
3. Guarda la Tarea en un REGISTRY estático (id → Tarea) para que CommonJob la recupere en cada ejecución (el id viaja como description del JobDetail).
4. Warm-up del TA: si entre las tareas agendadas hay un TokenManagerJob, lo dispara ya mismo (scheduler.triggerJob, en un worker de Quartz) sin esperar al primer cron — así el TA de WSAA está listo apenas arranca el servicio y el POS no pega contra un TA frío. Si el disparo falla, se loguea un WARN y el job igual reintenta por su cron.

La entidad Tarea¶

model/tarea/Tarea.java, mapeada a la tabla Tareas:

El JobFactory (QuartzConfig)¶

config/QuartzConfig.java instala un AutowiringSpringBeanJobFactory vía SchedulerFactoryBeanCustomizer. Así, cuando Quartz instancia un job, sus dependencias (@Autowired) se resuelven contra el contexto de Spring. Por eso cada job es una clase fina que delega la lógica a un @Service.

Los jobs¶

Cada job extiende CommonJob e implementa org.quartz.Job. El patrón es siempre el mismo: startExecute (lock + bitácora), try { servicio.hacerAlgo() } catch (Throwable) { registrarError } finally { finallyDo }. La lógica de negocio vive en el @Service, no en el job.

Alta de un job nuevo¶

Insertás una fila en Tareas. Ejemplo (del propio NotaCreditoReconciliacionJob):

INSERT INTO Tareas (Id, Descripcion, Programacion, JobProcessor)
VALUES ('NC_RECONCILIACION', 'Reconciliacion NC CAE-CAEA',
        '0 30 2 * * ?', 'NotaCreditoReconciliacionJob');

Programacion es cron de Quartz: seg min hora díaMes mes díaSemana [año]. El alta se toma en el próximo arranque (el scheduler lee Tareas en ApplicationReadyEvent).

Locking de ejecución (ThreadSafety)¶

Antes de cada corrida, CommonJob.startExecute toma el lock de ThreadSafety.setExecuting(tarea); finallyDo lo libera con setAvailable(tarea). Es un mapa estático (Map<Tarea,String>) con acceso totalmente sincronizado sobre el propio mapa: si la Tarea ya está en el mapa, setExecuting devuelve false y el job no corre (se loguea MULTIPLE EJECUCION). Esto garantiza un solo proceso por Tarea a la vez (INVARIANTE §5.13), aun si un cron dispara mientras la corrida anterior sigue viva.

Limpieza del scope EVENT al fin de cada job¶

Al final de cada ejecución, CommonJob.finallyDo llama a SeamEventScope.clear() (commit e7b5ebf, plan 006). Es el equivalente, para los jobs, de lo que SeamEventScopeFilter hace por cada request HTTP: vaciar el scope EVENT del shim seam-compat.

Por qué hace falta: los *Home/*List (EnteFacturadorHome, EnteFacturadorList, etc.) son beans de scope EVENT, guardados en un ThreadLocal por hilo. Quartz corre los jobs en un pool de worker threads de larga vida: sin esta limpieza, cuando un worker reusa el hilo para la corrida siguiente se encuentra los *Home/*List de la corrida anterior — con su filtro/id/entidad managed adentro. Eso es fuga de estado entre ejecuciones, y toca el money-path (la reconciliación de NC y la notificación CAEA leen EnteFacturadorList.instance() desde dentro de un job). El detalle del mecanismo está en La capa de compatibilidad Seam.

El clear() va en un finally propio, después de la escritura de bitácora (para que JobEjecucionRegistro.registrar(...) todavía vea el scope vivo) y blindado para que un fallo de la bitácora no se lo saltee. Como está centralizado en CommonJob.finallyDo, todo job que extienda CommonJob y lo llame en su finally (el patrón establecido) hereda la limpieza sin cambios por job.

Auditoría de ejecuciones (JobEjecucion)¶

Cada corrida deja una fila en la tabla JobEjecucion (entidad model/job/JobEjecucion.java), que graba CommonJob.finallyDo vía JobEjecucionRegistro:

El cockpit muestra la última ejecución por job: JobEjecucionRegistro.ultimasPorTarea() (una fila por tareaId) más el próximo disparo del trigger Quartz (TareaScheduler.nextFireTime). Eso es lo que arma CockpitJobs para GET /api/cockpit/jobs. Ver Cockpit.

Por dónde seguir¶

• Cockpit — la grilla /jobs que visualiza estas ejecuciones.
• El ciclo de facturación — CAE, CAEA y por qué hace falta cada job.
• Configuración y perfiles — propiedades como nc.reconciliacion.ventana-dias.
• Setup del entorno — para ver los jobs agendarse al arrancar en local.