Caché y Rendimiento (Nivel 1)

Caché y Rendimiento (Nivel 1)

Sin cambios de contrato API

Esta optimización es transparente: los endpoints, parámetros y formatos de respuesta son idénticos. Ningún cliente necesita modificar código para usarla.

Contexto

Las búsquedas de catálogo (productos y clientes) son las operaciones más frecuentes en un POS: el buscador search-as-you-type dispara una petición por tecla. El backend ahora las sirve desde una capa de caché en memoria y usa índices pg_trgm para acelerar las búsquedas parciales (ILIKE '%termino%').

Qué se logró

Mejora	Efecto
Índices GIN pg_trgm en productos.nombre, productos.codigo, clientes.nombre	Búsqueda parcial sin full-scan
Caché de respuestas TTL 10s	Búsquedas repetidas sin tocar BD ni re-serializar
Caché de permisos RBAC TTL 30s	Una query menos por request
Invalidación automática en escrituras	POST/PUT/DELETE y cambios de stock refrescan la caché al instante

Endpoints con caché

Productos (GET /api/productos/, /search, /search/nombre, /search/codigo, /categoria/:id)

Clientes (GET /api/clientes/, /search/nombre, /search/dni)

Comportamiento observable

Situación	Comportamiento
Búsqueda repetida en pocos segundos	Se sirve desde caché (más rápida, misma respuesta)
Crear/actualizar/eliminar un producto o cliente	La caché se invalida → la siguiente búsqueda ve el dato nuevo
Hacer una venta / anular / revertir stock	La caché de productos se invalida al instante
Cambiar permisos de un rol	El efecto puede tardar hasta 30s en aplicarse
Cambio de datos por fuera de la API (BD directa)	La búsqueda puede mostrar el valor previo hasta 10s
Varias réplicas del API	Cada instancia tiene su propia caché (se consolida con Redis en el Nivel 2)

Stock en búsquedas

El stock mostrado en búsquedas puede quedar hasta 10s desactualizado en pantalla. La validación de stock al vender siempre lee la BD directamente (nunca caché), así que no hay riesgo de vender sin stock.

Configuración

Valores configurables en neopos-api.properties o .env del backend:

cache.ttl_search=10   # segundos de TTL para búsquedas de catálogo
cache.ttl_rbac=30     # segundos de TTL para validación de permisos

Recomendaciones para clientes

• No guardar catálogos completos en memoria propia del lado cliente durante períodos largos si se necesita stock actualizado; las búsquedas del backend ahora son baratas.
• Si el cliente hace debounce de búsquedas (~200-300ms entre teclas), el impacto en BD se reduce aún más.
• No hay headers, parámetros ni campos nuevos que consumir.

Despliegue

Los índices pg_trgm se crean automáticamente al iniciar el API. En catálogos grandes, el primer arranque puede tomar unos segundos más.

docker compose up -d --build

Siguientes niveles

• Nivel 2 — Redis: caché distribuida y rate limiter compartido (necesario con varias réplicas del API).
• Nivel 3 — Arquitectura: snapshot del catálogo por tenant y métricas de hit-ratio.