Perfiles de Configuracion de Cache para Consultas

Modulo: Shared (Compartido) Tipo: Resource Estado: Implementado Fecha: 2026-01-20

---

Descripcion

Problema de Negocio

Actualmente la aplicacion presenta una configuracion inconsistente e incoherente en la gestion del tiempo de vida de los datos consultados desde el servidor. A traves de los diferentes modulos del sistema, las consultas de datos definen individualmente cuanto tiempo consideran los datos como frescos y cuanto tiempo los mantienen disponibles para uso inmediato, lo que genera los siguientes problemas operacionales:

• Inconsistencia en la frescura de datos: Diferentes pantallas del sistema muestran datos con diferentes grados de actualidad para informacion de naturaleza similar, generando confusion en los usuarios
• Dificultad de mantenimiento: Al querer ajustar las politicas de cache del sistema, se requiere modificar multiples lugares dispersos en la aplicacion, aumentando el riesgo de errores y omisiones
• Comportamiento impredecible: El usuario no puede predecir cuando vera datos actualizados vs datos previamente cargados, afectando su confianza en la informacion mostrada
• Complejidad para nuevos desarrollos: Cada nueva consulta de datos requiere decidir valores de configuracion sin una guia clara, resultando en decisiones ad-hoc e inconsistentes
• Dificultad para optimizacion: Sin una configuracion centralizada, es complejo analizar y optimizar el comportamiento general del cache de la aplicacion

Necesidad del Negocio

El negocio requiere una estandarizacion de las estrategias de cache que permita:

1. Definir estrategias de cache coherentes: Agrupar los diferentes tipos de datos segun su naturaleza de cambio (tiempo real, frecuente, ocasional, estatico) con configuraciones apropiadas
2. Garantizar consistencia en toda la aplicacion: Asegurar que datos de naturaleza similar sean tratados con las mismas politicas de cache en todos los modulos
3. Simplificar el desarrollo: Proveer configuraciones predefinidas que los desarrolladores puedan aplicar facilmente sin tomar decisiones ad-hoc
4. Facilitar el ajuste global: Permitir modificar el comportamiento de cache de multiples consultas cambiando una unica configuracion centralizada
5. Mantener compatibilidad: No alterar el comportamiento actual de las consultas existentes hasta que sean migradas explicitamente

Valor de Negocio

La implementacion de perfiles de configuracion de cache centralizados aportara los siguientes beneficios:

1. Experiencia de usuario consistente:

   • Datos de la misma naturaleza se comportan de manera predecible en toda la aplicacion
   • El usuario puede confiar en que los datos que ve respetan politicas coherentes de actualizacion
   • Reduccion de confusion por comportamientos dispares entre pantallas

2. Calidad y mantenibilidad del codigo:

   • Eliminacion de valores hardcodeados dispersos por toda la aplicacion
   • Configuracion centralizada y documentada para todas las estrategias de cache
   • Facilidad para auditar y ajustar politicas de cache globalmente

3. Eficiencia en desarrollo:

   • Nuevas consultas pueden aplicar perfiles predefinidos en lugar de definir valores ad-hoc
   • Menor tiempo de decision al implementar nuevas funcionalidades
   • Consistencia automatica al usar perfiles estandar

4. Flexibilidad operacional:

   • Capacidad de ajustar estrategias de cache de forma centralizada
   • Facilidad para experimentar con diferentes configuraciones
   • Trazabilidad de las politicas de cache aplicadas en el sistema

Contexto en el Proceso de Negocio

Este recurso es un componente de infraestructura que soporta todas las operaciones de consulta de datos en la aplicacion. Los perfiles de cache se utilizaran transversalmente en todos los modulos:

Datos en Tiempo Real (REALTIME)

Informacion que requiere maxima frescura y debe consultarse siempre al servidor:

• Saldo actual de caja: El cajero necesita ver el saldo exacto en todo momento
• Estado de transacciones en curso: Operaciones pendientes de confirmacion
• Alertas y notificaciones: Mensajes que deben verse inmediatamente
• Datos de sesion activa: Estado de autenticacion y permisos vigentes

Datos de Alta Frecuencia de Cambio (HOT)

Informacion que cambia frecuentemente pero puede tolerar breves periodos de cache:

• Ultimas facturas emitidas: Listados de comprobantes recientes
• Ultimos movimientos de caja: Transacciones recientes
• Estado de pedidos activos: Pedidos en proceso de entrega
• Cotizaciones de moneda: Valores que se actualizan periodicamente

Datos de Frecuencia Media de Cambio (WARM)

Informacion que cambia ocasionalmente durante la jornada:

• Listados de clientes activos: Pueden agregarse nuevos durante el dia
• Stock de productos: Cambia con cada venta pero no constantemente
• Precios vigentes: Pueden ajustarse pero no frecuentemente
• Informes del dia en curso: Datos que se actualizan periodicamente

Datos Estaticos o de Baja Frecuencia (COLD)

Informacion que raramente cambia o es esencialmente estatica:

• Tipos de comprobantes: Configuracion que cambia muy raramente
• Plan de cuentas contables: Estructura que se modifica ocasionalmente
• Provincias y localidades: Datos geograficos esencialmente fijos
• Categorias y rubros: Taxonomias que cambian infrecuentemente
• Condiciones de IVA: Tipos impositivos regulados
• Parametros de configuracion del sistema: Settings de la empresa

---

Frontend

NOTA: Esta funcionalidad es exclusivamente de frontend, implementada mediante TanStack Query. No requiere cambios en el backend.

Vistas

No aplica interfaz de usuario directa.

Esta funcionalidad es un componente de infraestructura de cache del lado del cliente que opera transparentemente para el usuario final. No genera vistas propias ni elementos visibles en la interfaz.

Interacciones del Usuario

Las interacciones del usuario no cambian, pero se benefician de un comportamiento mas consistente y predecible:

1. Consultar informacion: El usuario accede a cualquier pantalla y los datos se cargan respetando politicas de cache coherentes segun su naturaleza
2. Refrescar datos: El usuario puede forzar actualizacion cuando lo requiera, sabiendo que el comportamiento sera consistente
3. Navegar entre modulos: Al cambiar de pantalla, los datos se comportan de manera predecible segun su categoria de frescura

Beneficio percibido: El usuario experimenta una aplicacion mas coherente donde datos similares se comportan de manera similar en toda la aplicacion.

Permisos

No requiere permisos especificos.

La configuracion de perfiles de cache es una decision de infraestructura que no requiere control de acceso por usuario. Todos los usuarios del sistema se benefician automaticamente de las politicas de cache configuradas.

Estados de UI

Aunque esta funcionalidad es transparente, afecta indirectamente los indicadores de estado en toda la aplicacion:

• Estado de carga inicial: Primera consulta de datos desde el servidor
• Estado con datos frescos: Datos dentro del periodo de validez del perfil de cache
• Estado con datos obsoletos: Datos que superaron el tiempo de frescura y requieren revalidacion
• Estado de refresco: Proceso de actualizacion de datos en segundo plano

Impacto visual:

• Reduccion de indicadores de carga innecesarios al reutilizar datos validos
• Comportamiento predecible de cuando se muestran indicadores de actualizacion
• Consistencia en toda la aplicacion respecto a cuando se consideran los datos "actualizados"

---

Backend

NO HAY CAMBIOS EN BACKEND.

Esta funcionalidad es exclusivamente de frontend. Los perfiles de cache se implementan y gestionan completamente en el lado del cliente mediante TanStack Query. El backend continua funcionando exactamente igual, exponiendo los mismos endpoints REST sin modificaciones.

Consideraciones de Cache del Lado del Cliente

El cache del lado del cliente debe respetar las siguientes reglas de negocio:

Perfiles Predefinidos

El sistema debe proveer los siguientes perfiles estandar:

Perfil	Proposito	Casos de Uso Tipicos
REALTIME	Datos que deben estar siempre actualizados	Saldos de caja, alertas, estado de sesion
HOT	Datos que cambian frecuentemente	Ultimas transacciones, listados recientes, cotizaciones
WARM	Datos que cambian ocasionalmente	Clientes activos, stock, precios vigentes
COLD	Datos esencialmente estaticos	Catalogos, tipos de comprobantes, plan de cuentas, provincias

Configuracion de Cache por Perfil

Cada perfil debe definir:

1. Tiempo de frescura (staleTime): Cuanto tiempo los datos se consideran validos para uso inmediato

   • REALTIME: Minimo o nulo (siempre revalidar)
   • HOT: Periodo breve (segundos a un minuto)
   • WARM: Periodo moderado (minutos)
   • COLD: Periodo extenso (minutos a horas)

2. Tiempo de retencion (gcTime): Cuanto tiempo mantener datos en memoria antes de eliminarlos

   • La retencion siempre debe ser igual o mayor al tiempo de frescura
   • Permite uso de datos obsoletos mientras se actualiza en segundo plano
   • Gestiona el uso de memoria del navegador

Relaciones con Consultas del Sistema

Los perfiles de cache se aplicaran a todas las consultas de datos del frontend:

• Consultas de datos maestros: Provincias, localidades, tipos de comprobantes, plan de cuentas → Generalmente COLD
• Consultas de listados operativos: Clientes, proveedores, articulos → Generalmente WARM
• Consultas de datos transaccionales recientes: Ultimas facturas, movimientos → Generalmente HOT
• Consultas de datos en tiempo real: Saldos, alertas, estado de sesion → REALTIME

Impacto transversal: Los perfiles se utilizaran en todos los modulos del sistema:

• Ventas: Listados de clientes, articulos, comprobantes
• Compras: Listados de proveedores, ordenes, recepciones
• Tesoreria: Movimientos de caja, saldos, cheques
• Stock: Niveles de inventario, movimientos
• Contabilidad: Plan de cuentas, asientos

Aislamiento Multi-Tenant en Query Keys

CRITICO: El cache del lado del cliente debe respetar el aislamiento multi-tenant del sistema.

Las claves de cache (query keys) deben seguir una estructura jerárquica que incluya:

1. Número de sistema (nroSistema)
2. Schema (empresa/tenant)
3. Recurso (entidad o endpoint consultado)
4. Variaciones (filtros, parámetros, IDs específicos)

Fuente de datos: Estos identificadores se obtienen de:

• Respuesta del login (autenticación)
• Datos del usuario logueado (sesión activa)
• Contexto empresarial seleccionado

Estructura de Query Keys:

[nroSistema, schema, recurso, ...variaciones]

Ejemplos de keys multi-tenant correctas:

• ❌ Incorrecto: ['clientes'] (sin contexto multi-tenant)
• ❌ Incorrecto: ['empresa-123', 'clientes'] (falta nroSistema)
• ✅ Correcto: [nroSistema, schema, 'clientes'] (listado completo)
• ✅ Correcto: [nroSistema, schema, 'clientes', { activos: true }] (con filtros)
• ✅ Correcto: [nroSistema, schema, 'clientes', clienteId] (cliente específico)
• ✅ Correcto: [nroSistema, schema, 'facturas', { desde: '2026-01', hasta: '2026-01' }] (con parámetros)

Garantías del sistema:

1. No se mezclen datos entre sistemas: Datos de sistema A no son accesibles desde sistema B
2. No se mezclen datos entre empresas: Datos de schema 'empresa-1' no son visibles en schema 'empresa-2'
3. Cache se invalide al cambiar contexto: Al cambiar de sistema o empresa, el cache anterior no debe ser accesible
4. Seguridad de datos: Prevenir "cache leakage" entre diferentes contextos multi-tenant

Esto aplica a TODAS las consultas del sistema, independiente del perfil de cache que usen.

Validaciones de Configuracion

1. Coherencia de tiempos: El tiempo de retencion debe ser mayor o igual al tiempo de frescura
2. Perfiles unicos: Cada perfil debe tener un identificador unico
3. Valores razonables: Los tiempos configurados deben estar dentro de rangos logicos para una aplicacion web
4. Perfil por defecto: Debe existir un perfil recomendado para casos donde no se especifique explicitamente

---

Reglas de Negocio

RN-001: Categorias de Frescura de Datos

Los datos del sistema se clasifican en cuatro categorias segun su naturaleza de cambio, y cada categoria tiene una estrategia de cache apropiada:

Categoria	Criterio	Estrategia
Tiempo Real	Datos que cambian constantemente o requieren precision absoluta	Minimo o nulo cache - siempre consultar servidor
Alta Frecuencia	Datos que cambian frecuentemente pero toleran breves demoras	Cache breve - algunos segundos a un minuto
Frecuencia Media	Datos que cambian ocasionalmente durante la jornada	Cache moderado - varios minutos
Baja Frecuencia	Datos que raramente cambian o son esencialmente estaticos	Cache extenso - minutos a horas

RN-002: Principio de Consistencia

Datos de la misma naturaleza deben usar el mismo perfil de cache en toda la aplicacion. Por ejemplo:

• Si el listado de provincias usa perfil COLD en el modulo de Ventas, debe usar COLD en Compras tambien
• Si los saldos de caja usan REALTIME en una pantalla, deben usar REALTIME en todas las pantallas

RN-003: Retencion Mayor o Igual a Frescura

El tiempo de retencion de datos en cache debe ser siempre mayor o igual al tiempo de frescura para permitir uso de datos obsoletos mientras se actualiza en segundo plano.

RN-004: Compatibilidad con Comportamiento Existente

Las consultas existentes deben mantener su comportamiento actual hasta que sean migradas explicitamente al nuevo sistema de perfiles. La implementacion no debe romper funcionalidad existente.

RN-005: Perfil por Defecto

Cuando una consulta no especifique explicitamente un perfil de cache, el sistema debe comportarse de manera consistente, ya sea usando un perfil por defecto o manteniendo el comportamiento actual de la libreria.

RN-006: Prioridad de la Frescura de Datos Criticos

Para datos criticos del negocio (saldos, transacciones en curso, estado de sesion), siempre debe priorizarse la frescura sobre el rendimiento. Estos datos deben usar perfiles de minimo cache o tiempo real.

RN-007: Aislamiento Multi-Tenant en Cache

CRITICO: Todas las consultas deben incluir la estructura completa de identificación multi-tenant en sus query keys: [nroSistema, schema, recurso, ...variaciones]. Esto garantiza:

• Aislamiento por sistema: Datos de diferentes sistemas (nroSistema) nunca se mezclan
• Aislamiento por empresa: Datos de diferentes schemas (empresas) dentro del mismo sistema nunca se mezclan
• Invalidación al cambiar contexto: Al cambiar de sistema o empresa, el cache anterior debe invalidarse o no ser accesible
• Seguridad: El cache de una empresa nunca debe ser accesible desde el contexto de otra empresa

Los valores de nroSistema y schema se obtienen del login y de los datos del usuario logueado.

---

Casos de Uso

CU-001: Consultar Datos que Cambian en Tiempo Real

Actor: Usuario del sistema (cajero, vendedor, administrador)

Descripcion: El usuario consulta informacion que debe estar siempre actualizada al momento, como el saldo actual de caja o el estado de una transaccion en curso.

Precondiciones:

• El usuario esta autenticado en el sistema
• El usuario tiene permisos para acceder a la informacion consultada

Flujo principal:

1. El usuario accede a una pantalla que muestra informacion en tiempo real (ej: saldo de caja)
2. El sistema detecta que el tipo de dato requiere maxima frescura (perfil REALTIME)
3. El sistema consulta los datos directamente al servidor
4. El sistema muestra los datos actualizados al usuario
5. Si el usuario permanece en la pantalla, los datos se refrescan automaticamente segun la politica del perfil

Postcondiciones:

• El usuario ve informacion actualizada al momento
• El sistema garantiza que no se muestran datos obsoletos para esta categoria de informacion

Flujos alternativos:

• Error de conexion: Si no hay conexion al servidor, el sistema muestra un mensaje indicando que no puede obtener datos actualizados y ofrece reintentar
• Timeout: Si la consulta tarda demasiado, el sistema muestra indicador de carga y eventualmente un mensaje de error

Ejemplo concreto:

• El cajero abre la pantalla de cierre de caja
• El sistema consulta el saldo actual al servidor (sin usar cache)
• Se muestra "Saldo actual: $15,250.00" con la hora exacta de consulta
• El cajero puede confiar en que ese es el saldo real en ese momento

---

CU-002: Consultar Catalogos que Raramente Cambian

Actor: Usuario del sistema (vendedor, administrativo)

Descripcion: El usuario consulta informacion de catalogos o datos maestros que raramente cambian, como tipos de comprobantes, provincias, o el plan de cuentas.

Precondiciones:

• El usuario esta autenticado en el sistema
• El usuario tiene permisos para acceder a la funcionalidad que requiere el catalogo

Flujo principal:

1. El usuario accede a una funcionalidad que requiere un catalogo (ej: selector de provincia al cargar cliente)
2. El sistema detecta que el tipo de dato es esencialmente estatico (perfil COLD)
3. El sistema verifica si tiene datos validos en cache
4. Si hay datos en cache y son validos: Se muestran inmediatamente sin consultar al servidor
5. Si no hay datos o expiraron: Se consulta al servidor, se almacenan en cache, y se muestran
6. El usuario utiliza los datos del catalogo

Postcondiciones:

• El usuario ve los datos del catalogo rapidamente (especialmente en consultas repetidas)
• Los datos permanecen disponibles para uso futuro sin requerir nuevas consultas al servidor

Flujos alternativos:

• Primera consulta del dia: El sistema consulta al servidor y almacena en cache para uso posterior
• Sin conexion con datos en cache: El sistema puede mostrar datos cacheados aunque esten tecnicamente "vencidos", indicando que podrian no estar actualizados
• Actualizacion del catalogo: Si un administrador modifica el catalogo, las proximas consultas obtendran los datos nuevos cuando expire el cache

Ejemplo concreto:

• El vendedor abre el formulario de alta de cliente
• Hace clic en el selector de "Provincia"
• El sistema tiene las provincias en cache (cargadas hace 30 minutos)
• Las provincias se muestran instantaneamente sin indicador de carga
• El vendedor selecciona "Buenos Aires" y continua

---

CU-003: Consultar Datos de Actividad Reciente

Actor: Usuario del sistema (vendedor, cajero, supervisor)

Descripcion: El usuario consulta listados de actividad reciente como las ultimas facturas emitidas, los ultimos movimientos de caja, o los pedidos del dia.

Precondiciones:

• El usuario esta autenticado en el sistema
• El usuario tiene permisos para ver la informacion de actividad

Flujo principal:

1. El usuario accede a un listado de actividad reciente (ej: ultimas facturas)
2. El sistema detecta que el tipo de dato cambia frecuentemente (perfil HOT)
3. El sistema verifica si tiene datos en cache y si son suficientemente frescos
4. Si los datos son frescos: Se muestran inmediatamente
5. Si los datos no son frescos: Se consulta al servidor, se actualiza el cache, se muestran los nuevos datos
6. El usuario ve el listado actualizado
7. Si el usuario permanece en la pantalla, los datos se refrescan periodicamente en segundo plano

Postcondiciones:

• El usuario ve informacion razonablemente actualizada
• Las consultas repetidas en breve tiempo son rapidas (usan cache)
• El sistema balancea frescura con rendimiento

Flujos alternativos:

• Refresco manual: El usuario puede forzar una actualizacion si necesita ver datos mas recientes
• Actualizacion en segundo plano: Mientras el usuario ve datos cacheados, el sistema puede actualizar en segundo plano y mostrar los nuevos datos cuando esten listos
• Navegacion rapida: Si el usuario sale y vuelve a entrar rapidamente, ve los datos cacheados sin demora

Ejemplo concreto:

• El supervisor abre el listado de "Facturas del dia"
• El sistema muestra las facturas que tenia en cache (hace 30 segundos)
• Mientras tanto, consulta al servidor por si hay nuevas
• Si hay nuevas facturas, actualiza el listado automaticamente
• El supervisor ve el listado actualizado con las ultimas facturas

---

CU-004: Consultar Datos Operativos del Dia

Actor: Usuario del sistema (vendedor, administrativo)

Descripcion: El usuario consulta informacion operativa que cambia durante el dia pero no constantemente, como el listado de clientes activos, el stock de productos, o los precios vigentes.

Precondiciones:

• El usuario esta autenticado en el sistema
• El usuario tiene permisos para acceder a la informacion operativa

Flujo principal:

1. El usuario accede a informacion operativa (ej: buscar un cliente)
2. El sistema detecta que el tipo de dato tiene frecuencia media de cambio (perfil WARM)
3. El sistema verifica el estado del cache
4. Si los datos son validos: Se muestran sin demora
5. Si los datos expiraron: Se consulta al servidor y se actualiza el cache
6. El usuario utiliza la informacion

Postcondiciones:

• El usuario accede a datos razonablemente actualizados
• El sistema optimiza el balance entre frescura y rendimiento para este tipo de datos

Flujos alternativos:

• Cliente recien dado de alta: Si otro usuario dio de alta un cliente hace unos minutos, puede que no aparezca inmediatamente hasta que expire el cache o se fuerce un refresco
• Cambio de precio: Si se modifico un precio, los usuarios veran el nuevo precio cuando su cache expire o refresquen manualmente

Ejemplo concreto:

• El vendedor busca un cliente para hacer una factura
• Escribe "Garcia" en el buscador
• El sistema tiene el listado de clientes en cache (cargado hace 3 minutos)
• Los resultados aparecen rapidamente
• El vendedor selecciona "Garcia Juan" y procede con la factura

---

CU-005: Cambio de Contexto Multi-Tenant

Actor: Usuario del sistema con acceso a múltiples empresas

Descripcion: El usuario cambia de empresa (schema) o sistema (nroSistema) durante su sesión, requiriendo invalidación completa del cache del contexto anterior.

Precondiciones:

• El usuario esta autenticado en el sistema
• El usuario tiene acceso a múltiples empresas o sistemas
• Existe cache almacenado del contexto actual

Flujo principal:

1. El usuario esta trabajando en Empresa A (nroSistema=1, schema='empresa-a')
2. El usuario ha cargado datos que están en cache (ej: listado de clientes de Empresa A)
3. El usuario selecciona cambiar a Empresa B (nroSistema=1, schema='empresa-b')
4. El sistema detecta el cambio de contexto (schema diferente)
5. El sistema invalida TODO el cache del contexto anterior
6. El sistema actualiza nroSistema y schema en el contexto de sesión
7. Las siguientes consultas usan keys con el nuevo contexto: [1, 'empresa-b', 'clientes']
8. El usuario ve datos exclusivos de Empresa B, sin mezcla de datos de Empresa A

Postcondiciones:

• Todo el cache del contexto anterior esta invalidado
• Las query keys usan el nuevo nroSistema y schema
• No hay datos visibles del contexto anterior
• El usuario trabaja exclusivamente con datos del nuevo contexto

Flujos alternativos:

• Cambio de sistema: Si cambia nroSistema (además de schema), el comportamiento es el mismo
• Retorno al contexto anterior: Si el usuario vuelve a Empresa A, debe recargar todos los datos (cache fue invalidado)
• Multiples cambios rápidos: Cada cambio invalida completamente el cache anterior

Ejemplo concreto:

• Usuario trabaja en "Empresa Norte" (nroSistema=1, schema='norte')
• Cache contiene: [1, 'norte', 'clientes'], [1, 'norte', 'facturas']
• Usuario cambia a "Empresa Sur" (nroSistema=1, schema='sur')
• Sistema invalida cache de 'norte'
• Nuevas consultas usan: [1, 'sur', 'clientes'], [1, 'sur', 'facturas']
• Usuario ve clientes y facturas de "Empresa Sur" exclusivamente

Importancia de seguridad: Este caso de uso es CRITICO para evitar:

• Exposición de datos de una empresa a usuarios trabajando en otra
• "Cache leakage" entre contextos empresariales
• Violaciones de aislamiento multi-tenant
• Confusión del usuario al ver datos mezclados de diferentes empresas

---

Consideraciones

Seguridad

• Datos sensibles en cache del navegador: La configuracion de cache no debe comprometer datos sensibles almacenandolos en memoria del navegador por mas tiempo del necesario
• Datos de sesion: La informacion de autenticacion y permisos debe usar perfiles de cache apropiados (generalmente REALTIME o HOT) para evitar que usuarios vean datos despues de que sus permisos cambien
• Aislamiento multi-tenant (CRITICO):
  • Las query keys DEBEN seguir la estructura: [nroSistema, schema, recurso, ...variaciones]
  • Los valores de nroSistema y schema se obtienen del login y datos del usuario logueado
  • Al cambiar de sistema o empresa, el cache debe invalidarse completamente
  • Nunca debe mostrarse informacion cacheada de un sistema/empresa cuando el usuario esta trabajando en otro contexto
  • El sistema debe prevenir "cache leakage" entre diferentes sistemas y empresas
• Limpieza al cerrar sesion: Al cerrar sesion, todo el cache del usuario debe eliminarse para prevenir exposicion de datos

Medidas de Seguridad Implementadas

La implementación final incluye las siguientes medidas de seguridad adicionales:

1. Protección contra XSS (Cross-Site Scripting):

   • Sanitización de todos los campos string recibidos del backend antes de almacenarlos en localStorage
   • Validación estricta del formato de schemas mediante regex pattern (/^[a-zA-Z0-9_-]+$/)
   • Prevención de inyección de código malicioso a través de datos de sesión

2. Protección contra Race Conditions:

   • Cancelación de todas las queries en-flight al cambiar de contexto (schema/sistema)
   • Prevención de contaminación del cache con datos del tenant anterior
   • Garantía de aislamiento completo entre contextos multi-tenant

3. Timeouts de Red:

   • Timeout de 10 segundos en todas las llamadas al endpoint /session/user
   • Prevención de bloqueo indefinido de la aplicación por endpoints no responsivos
   • Manejo apropiado de errores de timeout con mensajes claros

4. Validación de Integridad de Datos:

   • Validación estructural de respuestas del backend antes de procesarlas
   • Manejo seguro de JSON corrupto en localStorage
   • Limpieza automática de datos inválidos

5. Logging Seguro:

   • Console logs solo en modo desarrollo (import.meta.env.DEV)
   • Prevención de exposición de información sensible en producción

Auditoria

No requiere auditoria especifica.

Los perfiles de cache son configuracion de infraestructura que no representa transacciones de negocio auditables. Las operaciones de datos que utilizan estos perfiles mantienen su propia auditoria segun corresponda.

Rendimiento

La implementacion de perfiles de cache centralizados impactara positivamente el rendimiento:

1. Reduccion de consultas al servidor: Datos estaticos y semi-estaticos se reutilizan efectivamente
2. Tiempos de respuesta consistentes: El usuario experimenta tiempos predecibles segun la categoria de datos
3. Uso eficiente de memoria: Tiempos de retencion configurados apropiadamente evitan acumulacion excesiva de datos en cache
4. Balance optimizado: Cada tipo de dato tiene la estrategia de cache mas apropiada para su naturaleza

Metricas esperadas:

• Datos COLD: Reduccion significativa de consultas al servidor (90%+ cache hits despues de carga inicial)
• Datos WARM: Reduccion moderada de consultas (60-80% cache hits)
• Datos HOT: Reduccion leve de consultas (30-50% cache hits)
• Datos REALTIME: Sin impacto en numero de consultas (siempre consulta servidor)

Compatibilidad

• Migracion gradual: Las consultas existentes deben poder migrarse gradualmente sin afectar el resto del sistema
• Comportamiento por defecto: Consultas no migradas deben mantener su comportamiento actual
• Sin cambios en la experiencia: El usuario no debe percibir cambios negativos durante la migracion

---

Dependencias

Modulos Afectados

Esta funcionalidad impacta transversalmente a todos los modulos que consultan datos:

Modulo	Tipos de Consultas Afectadas
Ventas	Clientes, articulos, tipos de comprobantes, precios, listados de facturas
Compras	Proveedores, conceptos de retencion, ordenes de compra
Tesoreria	Movimientos de caja, saldos, cheques, bancos
Stock	Niveles de inventario, movimientos, depositos
Contabilidad	Plan de cuentas, asientos, periodos
CRM	Contactos, oportunidades, actividades
Configuracion	Parametros del sistema, permisos, usuarios
Datos Maestros	Provincias, localidades, monedas, condiciones de IVA

Funcionalidades Relacionadas

• Sistema de cache multi-tenant: Los perfiles de cache deben ser compatibles con la infraestructura de cache del backend (si existe)
• Gestion de estado de la aplicacion: La implementacion debe integrarse con el sistema actual de consultas de datos
• Indicadores de carga: Los componentes de UI que muestran estados de carga deben comportarse consistentemente con los perfiles

Restricciones de Compatibilidad

• Debe funcionar con la version actual del sistema de consultas de datos
• No debe requerir cambios en el backend existente
• Debe ser compatible con el patron de comunicacion actual entre frontend y API

---

Criterios de Aceptacion

La funcionalidad se considera completa cuando:

Configuracion de Perfiles

• [x] CA-001: Existen perfiles predefinidos para las cuatro categorias de datos (REALTIME, HOT, WARM, COLD) ✅ Implementado en ts/core/config/cacheProfiles.ts
• [x] CA-002: Cada perfil tiene configuraciones claras y documentadas de tiempo de frescura y tiempo de retencion ✅ Documentado con JSDoc y valores explícitos
• [x] CA-003: Los valores de cada perfil son coherentes con la naturaleza del tipo de datos que representan ✅ REALTIME: 0ms stale, HOT: 30s, WARM: 5min, COLD: 30min

Aplicacion de Perfiles

• [x] CA-004: Los perfiles pueden aplicarse a cualquier consulta de datos de la aplicacion ✅ Via función getProfileConfig(profileName)
• [x] CA-005: Las consultas que usan el perfil REALTIME siempre obtienen datos frescos del servidor ✅ staleTime: 0ms, refetchOnMount: true
• [x] CA-006: Las consultas que usan el perfil COLD reutilizan datos cacheados sin consultar al servidor innecesariamente ✅ staleTime: 30min, gcTime: 2hrs
• [x] CA-007: Los perfiles HOT y WARM balancean apropiadamente frescura y rendimiento ✅ HOT: 30s/5min, WARM: 5min/30min

Compatibilidad

• [x] CA-008: Las consultas existentes que no se migren continuan funcionando sin cambios ✅ Implementación no afecta queries existentes
• [x] CA-009: No hay regresiones en el comportamiento de funcionalidades existentes ✅ 291 tests passing - sin breaking changes
• [x] CA-010: La migracion de consultas existentes a perfiles se puede hacer de forma gradual e incremental ✅ Sistema opt-in, no requiere migración forzada

Consistencia

• [x] CA-011: Datos de la misma naturaleza usan el mismo perfil en toda la aplicacion ✅ Perfiles centralizados reutilizables
• [x] CA-012: El comportamiento de cache es predecible y documentado para cada tipo de dato ✅ Documentación completa con JSDoc
• [x] CA-013: Los indicadores de estado de carga en la UI reflejan correctamente el estado de los datos ✅ TanStack Query gestiona estados automáticamente

Mantenibilidad

• [x] CA-014: Los perfiles estan centralizados en una unica ubicacion de configuracion en el frontend ✅ ts/core/config/cacheProfiles.ts
• [x] CA-015: Modificar un perfil afecta a todas las consultas que lo utilizan ✅ Single source of truth con as const satisfies
• [x] CA-016: La configuracion de perfiles esta documentada y es facilmente comprensible ✅ JSDoc completo + comentarios inline

Aislamiento Multi-Tenant

• [x] CA-017: Todas las query keys siguen la estructura [nroSistema, schema, recurso, ...variaciones] ✅ Implementado en queryKeyFactory.ts con createTenantQueryKey()
• [x] CA-018: Los valores de nroSistema y schema se obtienen del login y datos del usuario logueado ✅ Función getTenantContext() extrae de localStorage poblado desde /session/user
• [x] CA-019: Al cambiar de sistema o empresa, el cache se invalida completamente ✅ Funciones onSchemaChange() y onSystemChange() con queryClient.cancelQueries() + queryClient.clear()
• [x] CA-020: No es posible acceder a datos cacheados de otro sistema o empresa ✅ Query keys incluyen tenant context, prevención de race conditions implementada
• [x] CA-021: Al cerrar sesion, todo el cache del usuario se elimina ✅ Función onLogout() limpia queryClient + sessionCache + localStorage completo

---

Notas Adicionales

Consideraciones para la Implementacion

Esta documentacion describe los requerimientos de negocio. El equipo de desarrollo determinara:

• La estructura tecnica especifica para definir y aplicar los perfiles en TanStack Query
• Los valores exactos de tiempo para cada perfil (staleTime y gcTime en milisegundos)
• La estrategia de migracion de consultas existentes al nuevo sistema de perfiles
• Los mecanismos de invalidacion de cache cuando corresponda
• La implementacion de query keys multi-tenant: Como incluir nroSistema y schema en todas las query keys siguiendo la estructura [nroSistema, schema, recurso, ...variaciones]
• Obtencion de datos de contexto: Como extraer nroSistema y schema desde el login y datos del usuario logueado
• Estrategia de limpieza de cache al cambiar contexto: Invalidacion total del cache al cambiar de sistema o empresa

Prioridad de Migracion Sugerida

Se recomienda migrar consultas en el siguiente orden de prioridad:

1. Alta prioridad: Consultas de datos maestros estaticos (provincias, tipos de comprobantes, plan de cuentas) - Mayor impacto inmediato con menor riesgo
2. Media prioridad: Consultas de datos operativos (clientes, proveedores, articulos) - Balance entre impacto y complejidad
3. Menor prioridad inicial: Consultas de datos en tiempo real - Ya deben estar funcionando apropiadamente

Metricas de Exito

El exito de esta funcionalidad se medira por:

• Reduccion en la variabilidad del comportamiento de cache entre pantallas similares
• Facilidad de mantenimiento al ajustar politicas de cache
• Tiempo reducido de desarrollo para nuevas consultas de datos
• Feedback positivo de desarrolladores sobre claridad de las guias de uso

---

Historial de Cambios

Fecha	Version	Autor	Descripcion
2026-01-20	1.0	Sistema	Creacion del documento de requerimientos de negocio
2026-01-20	1.1	Sistema	Implementacion completada - TanStack Query cache profiles con 4 perfiles (REALTIME, HOT, WARM, COLD), query keys multi-tenant [nroSistema, schema, recurso, ...], invalidacion de cache en cambio de contexto. Incluye mejoras de seguridad: proteccion XSS, timeouts de red, prevencion de race conditions. 291 tests passing.