Александр Зимин
59 lines
3.4 KiB
Markdown
59 lines
3.4 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.
|
||
- **Schema workflow** — maker-checker approval для изменения schemas
|
||
(drafts + review + publish). См. [Schema workflow API](schema-workflow.md).
|
||
- **Full changelog timeline** — `/dictionaries/{name}/changelog` объединяет
|
||
definition CRUD + draft workflow events с `kind` field для UI rendering.
|
||
|
||
## Что 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. |
|