Zimin A.N.
d5268b9395
Новая документация-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/).
55 lines
3.1 KiB
Markdown
55 lines
3.1 KiB
Markdown
# Интеграция по API — обзор
|
||
|
||
Этот раздел описывает как backend-сервисы (Альтум, геопортал, BI и т.д.)
|
||
читают и пишут справочники Ordinis НСИ ЦУОД.
|
||
|
||
**Owner:** Ordinis team — `zimin.an@nstart.space`.
|
||
|
||
## С чего начать
|
||
|
||
1. [Получи Keycloak service account](auth.md) — нужен для всех API вызовов.
|
||
2. [Прочитай read-side endpoints](read-endpoints.md) — как получить данные.
|
||
3. [Выбери стратегию обновления](caching.md) — 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](caching.md#snapshot-at-order-time)).
|
||
- Не 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](bundle-cuod.md).
|
||
|
||
## Глоссарий
|
||
|
||
| Термин | Значение |
|
||
|---|---|
|
||
| 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. |
|