Skip to main content

📲 Flujo de consulta de Catálogo (Origen) con fallback silencioso a base local

Este documento describe el flujo end-to-end de la pantalla móvil que consulta el Servicio de Catálogos Generales (respaldado en ALP_CAT.ALP_FND_FLEX_VALUES) con política offline first / fallback silencioso: si no hay conectividad o el REST falla, la app no muestra error y lee el catálogo desde la base local del dispositivo.

🎯 Objetivo​

Cargar el catálogo ORIGEN en la UI móvil garantizando disponibilidad aun sin red, minimizando latencia y consumo de datos mediante doble caché:

  1. Caché cliente en memoria (sesión/pantalla).
  2. Caché local persistente (DB móvil).
  3. Caché del servicio (opcional: Redis/memoria) para reducir lecturas a BD Oracle.

👥 Participantes​

  • Usuario (U): interactúa con la pantalla “Buscar”.
  • App Móvil (M): UI + lógica de caché cliente y acceso a LocalDB.
  • API Gateway (G): front door, valida token con Keycloak (KC).
  • Keycloak (KC): autenticación/autorización (OIDC).
  • Catálogos Service (C): expone GET /catalogs.
  • Catálogos Repository (R): acceso a Oracle.
  • Oracle (D): ALP_CAT.ALP_FND_FLEX_VALUES.
  • LocalDB (L): base de datos del dispositivo (SQLite, Room, CoreData, etc.).

🧭 Flujo (paso a paso)​

  1. Apertura de pantalla

    • U abre “Buscar” y la UI debe poblar el dropdown Origen.

  2. Caché en memoria (cliente)

    • M consulta su caché en memoria.
      • HIT → Renderiza inmediatamente. (Fin flujo)
      • MISS → Continúa al paso 3.

  3. Verificación de conectividad

    • M verifica si hay red disponible y/o estado previo de reachability.
      • Offline → Ir a Paso 6 (LocalDB).
      • Online → Continúa al paso 4.

  4. Consulta remota (vía Gateway)

    • M → G: GET /catalogs?set=ORIGEN&lang=es-MX&enabled=Y con Bearer token.
    • G → KC: Valida token OIDC.
      • OK → G reenvía a C.
      • KO → (opcional) renovar token/PKCE; si falla → Paso 6 (LocalDB).

  5. Servicio de catálogos (caché de servicio y DB)

    • C revisa caché del servicio con clave ORIGEN|es-MX.
      • HIT → C retorna DTO al Gateway → M.
      • MISS → C → R → D: SELECT ... FROM ALP_FND_FLEX_VALUES WHERE ENABLED_FLAG='Y' AND ventana de vigencia
        • R mapea a DTO y retorna a C.
        • C guarda en caché (TTL configurado) y responde al Gateway → M.
    • M renderiza con datos remotos y realiza upsert en LocalDB para disponibilidad offline.

    Si durante 4/5/timeout hay error REST, la UI NO notifica; salta a Paso 6 (LocalDB).

  6. Consulta LocalDB (fallback silencioso)

    • M consulta LocalDB por set=ORIGEN.
    • Si hay datos locales → Renderiza sin notificar error.
    • Si NO hay datos locales → (opción de UX: mostrar “sin datos locales disponibles” y botón Reintentar que re-ejecuta desde Paso 3).

🧱 Regla de negocio y políticas​

  • Silencio ante falla remota: usuarios no ven errores de red; la app muestra datos locales si existen.
  • Actualización LocalDB: tras éxito remoto, persistir copia local (upsert) para offline.
  • Criterios de vigencia: filtrar por:
    • ENABLED_FLAG = 'Y'
    • START_DATE_ACTIVE <= SYSDATE o nulo
    • END_DATE_ACTIVE >= SYSDATE o nulo
  • Orden UX estable: ORDER BY ATTRIBUTE_SORT_ORDER NULLS LAST, FLEX_VALUE.

📡 Contrato de API (sugerido)​

Endpoint
GET /catalogs

Query Params

  • set (req): conjunto lógico del catálogo, p.ej. ORIGEN.
  • lang (opt): es-MX (reserva para i18n).
  • enabled (opt): Y|N, default Y.

Respuesta 200

[
  {"code":"ORIG-001","label":"Planta X","valueId":12345},
  {"code":"ORIG-002","label":"Centro Y","valueId":12346}
]