TEC-001 — Caché Distribuido con Redis
Implementación de la mejora TEC-001 (Caché Distribuido), dentro de 6.1 Rendimiento y Escalabilidad. El módulo pasa de un caché local a cada instancia a un caché distribuido compartido por todas, con el estado de sesión incluido y degradación automática a memoria.
📋 Alcance
| RF | Entregable |
|---|---|
| RF-TEC-001-01 | Redis como caché distribuido de las consultas frecuentes (reportes, consumo y KPIs) |
| RF-TEC-001-02 | Estado de sesión distribuido: sesiones activas y blacklist de tokens invalidados |
| RF-TEC-001-03 | Invalidación del caché al cambiar los datos subyacentes |
| RF-TEC-001-04 | TTL configurable por tipo de consulta mediante variables de entorno |
⚙️ Arquitectura
CacheService conserva su interfaz pública (get, set, getOrSet, del, delByPrefix,
clear) y pasa a ser una fachada sobre un backend intercambiable:
- Redis (
redis4.7) cuando está habilitado y conecta. Serializa en JSON, usaSCAN—nuncaKEYS— para invalidar por prefijo y antepone un prefijo global (ccf:) a todas las claves. - Memoria (el
Mapcon TTL anterior) cuando Redis está deshabilitado, no conecta o falla en caliente. Una caída de Redis no tumba la aplicación: cada operación degrada al respaldo y deja un aviso en el log.
Ningún dominio cambió su forma de cachear: siguen inyectando CacheService.
🔐 Sesiones distribuidas (RF-02)
SessionStoreService reemplaza el Map en memoria de AuthService por dos claves en el caché
compartido: sesion:activa:{idUsuario} y sesion:invalidada:{idUsuario} (TTL = vigencia del JWT).
El JWT sigue siendo stateless; lo que ahora se comparte entre instancias es el estado de sesión.
Se añade GET /api/auths/sessions (Administrador) para listar las sesiones activas.
♻️ Invalidación al escribir (RF-03)
Un interceptor global (CacheInvalidationInterceptor) y el decorador @InvalidaCache('reportes:')
invalidan el caché después de que una escritura tiene éxito en los controladores de
movimientos, solicitudes, productos, lotes/series, categorías, oficinas y presentaciones. Una
petición fallida no borra el caché.
⏱️ TTL por tipo de consulta (RF-04)
| Tipo | Variable | Defecto |
|---|---|---|
| reportes | CACHE_TTL_REPORTES | 60 s |
| consumo | CACHE_TTL_CONSUMO | 60 s |
| kpis | CACHE_TTL_KPIS | 60 s |
| próximos a vencer | CACHE_TTL_PROXIMOS_VENCER | 60 s |
| sesión | CACHE_TTL_SESION | 24 h |
| general | CACHE_TTL_SECONDS | 60 s |
🔍 Observabilidad
GET /api/cache/estado (Administrador) informa el backend activo, su disponibilidad, el prefijo y
la tabla de TTL vigente. POST /api/cache/invalidar permite invalidar el caché de reportes a mano.
✅ Verificación
- 368 pruebas en 38 suites, 0 fallos;
tscy ESLint limpios. - Pruebas nuevas para constantes/TTL, backend en memoria, backend Redis (cliente simulado), fachada, sesiones, interceptor y una prueba de integración de DI que arranca el módulo sin Redis y confirma la degradación a memoria.
- La prueba de integración destapó un bug real: cerrar un cliente Redis que nunca conectó lanzaba
ClientClosedError; corregido comprobandoisOpenantes de cerrar.
Limitación: con Redis caído, cada instancia invalida solo su propio respaldo en memoria (comportamiento equivalente al anterior).
