Files

T

Zimin A.N. d5268b9395 docs: Diplodoc setup + полное руководство интеграции по API

Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.

Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors

Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями

Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references

Build:
  cd docs && pnpm install && pnpm build
  → ./_dist (20 HTML files, 7.1M)
  pnpm serve  # → http://localhost:8088

CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).

Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).

2026-05-07 23:19:02 +03:00

3.1 KiB

Raw Blame History

Интеграция по API — обзор

Этот раздел описывает как backend-сервисы (Альтум, геопортал, BI и т.д.) читают и пишут справочники Ordinis НСИ ЦУОД.

Owner: Ordinis team — zimin.an@nstart.space.

С чего начать

Получи Keycloak service account — нужен для всех API вызовов.
Прочитай read-side endpoints — как получить данные.
Выбери стратегию обновления — TTL, webhooks, либо Kafka events.

Что Ordinis даёт

Bitemporal CRUD для справочников — validFrom / validTo + revision history через Hibernate Envers.
Multi-locale — каждое поле может иметь {ru-RU, en-US, ...} варианты. Flatten через ?lang= параметр.
Cross-dictionary FK через x-references schema extension. Server-side валидация на CRUD + orphan scanner periodic.
Geometry support — PostGIS для bbox/polygon фильтров (spacecraft.aoi, mission.coverage_area).
Audit log — все изменения через /api/v1/admin/audit (UI: /audit).
Outbox + Kafka — at-least-once delivery всех изменений в 3 топика.
Webhooks — push-уведомления HTTP к зарегистрированным URLs (для consumers без Kafka access).
Bulk operations — multi-select close + CSV export.

Что Ordinis НЕ делает

Не хранит "снимок на момент заказа" — для этого consumer должен сделать snapshot rough copy в свою БД (см. Caching → Snapshot strategy).
Не enforce'ит FK на уровне DB — это NoSQL-style references поверх JSONB. Cascade rules в roadmap (см. design dict-relationships-v2).
Не обеспечивает realtime sync — TTL = 5 мин минимум либо event-driven invalidation.

Версионирование

API — /api/v1/... стабилен. Breaking changes только через major (v2).
Bundle (cuod-bundle) — semver. Minor bump при schema изменении, major при удалении справочника. См. Bundle cuod.

Глоссарий

Термин	Значение
Dictionary	Справочник (например `spacecraft`, `satellite_type`).
Record	Запись в справочнике с уникальным `businessKey`.
businessKey	Стабильный идентификатор (string). Не меняется при update.
Bundle	Maven module с schemas + seed data. ЦУОД bundle = 40 справочников.
Scope	Уровень доступа: `PUBLIC` / `INTERNAL` / `RESTRICTED`.
Bitemporal	Запись имеет `validFrom`/`validTo` + revision history (transaction time).
x-references	JSON Schema extension для cross-dictionary FK.

3.1 KiB Raw Blame History Unescape Escape