mdm-ordinis/docs/integration/api/caching.md

Стратегии кэширования

Ordinis оптимизирован под редкие записи и частые чтения. Кэшируй у себя, не делай round-trip на каждый GET.

Три рекомендуемых стратегии:

A. Простой TTL (рекомендуется для v1)

Самый простой подход — TTL 5 мин на per-(dictionary, lang) ключ.

TanStack Query (React)

useQuery({
  queryKey: ['ordinis', 'spacecraft', lang],
  queryFn: () =>
    fetch(`/api/reference/spacecraft?lang=${lang}`, {
      headers: { Authorization: `Bearer ${token}` }
    }).then(r => r.json()),
  staleTime: 5 * 60_000,
  gcTime: 30 * 60_000,
  retry: 3,
})

Server-side кэш (Caffeine + Spring)

@Cacheable(value = "ordinis-records", key = "#dictionary + ':' + #lang")
public List<Record> fetchRecords(String dictionary, String lang) {
  return ordinisClient.list(dictionary, lang);
}

// application.yml
spring:
  cache:
    caffeine:
      spec: maximumSize=10000,expireAfterWrite=5m

Pro: просто, работает out of the box. Con: до 5 мин stale данных. При закрытии записи consumer покажет её ещё 5 мин.

B. Webhook / Kafka push (рекомендуется для prod)

Realtime invalidation через push-уведомления.

Kafka

Подпишись на ordinis.cuod.events.public (см. События), для каждого пришедшего event — invalidate соответствующий cache key:

def on_event(event):
    dict_name = event['dictionary']
    business_key = event['businessKey']
    redis.delete(f"ordinis:{dict_name}:list")  # invalidate list
    redis.delete(f"ordinis:{dict_name}:byKey:{business_key}")

Webhook

Тот же pattern но на HTTP push (см. Webhooks):

app.post('/webhooks/ordinis', (req, res) => {
  if (!verifyHmac(req)) return res.status(403).send()

  for (const event of req.body.events) {
    cache.delete(`ordinis:${event.dictionary}:list`)
    cache.delete(`ordinis:${event.dictionary}:byKey:${event.businessKey}`)
  }
  res.status(202).send()
})

Pro: < 1s invalidation latency. Con: требует Kafka/HTTPS infrastructure + handle duplicates (at-least-once).

C. Snapshot at order time

Для аудит-кейсов когда нужен «как было на момент заказа» (legal compliance).

Pattern

CREATE TABLE imaging_order (
  id              UUID PRIMARY KEY,
  spacecraft_business_key  VARCHAR(256),
  instrument_business_key  VARCHAR(256),
  reference_snapshot       JSONB,      -- копии записей, не FK
  created_at      TIMESTAMPTZ DEFAULT NOW()
);

При создании заказа:

spacecraft_data = ordinis.get(f"/spacecraft/records/{key}")
instrument_data = ordinis.get(f"/instrument/records/{key}")

db.execute(
  "INSERT INTO imaging_order(id, spacecraft_business_key, instrument_business_key, reference_snapshot) "
  "VALUES (%s, %s, %s, %s)",
  (order_id, spacecraft_key, instrument_key, json.dumps({
    'spacecraft': spacecraft_data,
    'instrument': instrument_data,
  }))
)

Pro: гарантированная история, не зависит от Ordinis availability / retention. Если Ordinis retroactively изменит запись — твоя копия не сдвинется.

Con: дубликат данных, увеличение твоей БД. Для Альтум typical scale (~100k orders/year × ~1KB snapshot = 100MB/year) — не проблема.

Альтернатива: bitemporal query

Можно не делать копию, а позже запрашивать ?at=<order.created_at>:

GET /api/v1/spacecraft/records/RESURS-P-3?at=2025-06-15T10:00:00Z

См. Bitemporal. Pro: меньше storage. Con: depends on Ordinis availability + retention. Альтум выбрала snapshot для legal compliance.

Hybrid: TTL + push invalidation

Лучший из двух — TTL 1 час (long enough чтобы сократить request rate) + event-driven invalidation (для realtime updates):

# Получаем event → invalidate
def on_event(event):
    cache.delete(f"ordinis:{event['dictionary']}:list")

# При cache miss — refetch с TTL 1h
def get_records(dictionary, lang):
    cached = cache.get(f"ordinis:{dictionary}:list:{lang}")
    if cached:
        return cached
    fresh = ordinis_client.list(dictionary, lang)
    cache.setex(f"ordinis:{dictionary}:list:{lang}", 3600, fresh)
    return fresh

Cache key patterns

Что кэшируем	Ключ
List of dictionaries	ordinis:dictionaries:{scope}
List of records per dict	ordinis:{dict}:list:{lang}
Single record	ordinis:{dict}:byKey:{businessKey}:{lang}
History of record	ordinis:{dict}:history:{businessKey} (rare, TTL=24h)

Включай lang в key — иначе разные locales перетирают друг друга.

Invalidation на cascade close (v2 roadmap)

В будущем при cascade close источника emit'ятся events для всех referencing records. Consumer должен слушать events и invalidate их тоже:

def on_event(event):
    cache.delete(f"ordinis:{event['dictionary']}:byKey:{event['businessKey']}")

    # NEW v2: cascade source — заодно invalidate dependents
    if event.get('cascadeSource'):
        # Источник тоже нужно invalidate (мы видим только закрытие dependent)
        src = event['cascadeSource']
        cache.delete(f"ordinis:{src['dictionary']}:byKey:{src['businessKey']}")

См. design doc dict-relationships-v2 (внутренний artifact).

Stale cache на 5xx / timeout

Если Ordinis недоступен — отдавай старые данные с warn'ом, не падай каскадно:

def get_records_safe(dictionary, lang):
    try:
        return get_records(dictionary, lang)
    except (TimeoutError, HTTPError) as e:
        log.warning(f"Ordinis unavailable, using stale cache: {e}")
        stale = cache.get(f"ordinis:{dictionary}:list:{lang}", ignore_ttl=True)
        if stale:
            return stale
        raise

Метрика <consumer>_ordinis_stale_serves_total для мониторинга.

Дальше

• Best practices — общие рекомендации
• Bundle cuod — что именно нужно кэшировать