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/).
2.8 KiB
2.8 KiB
Ordinis НСИ ЦУОД ОДХ
Документация для разработчиков, интеграторов и операторов.
Anchor v1 — production LIVE на cluster.142 (с 2026-05-07). Альтум consumers подключены, blue/green cutover завершён.
Что внутри
{% list tabs %}
-
Я интегрирую свой сервис
Начни с обзора API и авторизации.
Дальше:
- Read-side endpoints — как читать справочники
- События (Kafka outbox) — топики
ordinis.cuod.events.* - Webhooks — push-уведомления вместо polling
- Кэширование — TTL / push / snapshot стратегии
-
Я строю UI / клиент
- Cross-references — FK между справочниками
- Bitemporal —
validFrom/validTo+ история - Bundle cuod — список 40 справочников ЦУОД
- Best practices — частые ошибки
-
Я — оператор / on-call
{% endlist %}
Среды
| Среда | URL | Auth | Назначение |
|---|---|---|---|
| prod | https://ordinis.k8s.264.nstart.cloud/ |
JWT обязателен | Альтум real users |
| staging | https://ordinis.k8s.265.nstart.cloud/ |
optional (legacy mode) | Dev environment |
| local | http://localhost:8080 |
off | docker-compose dev |
Поддержка
- Issues / bug reports:
git.nstart.cloud:2-6/2-6-4/terravault/ordinis - Эскалация:
zimin.an@nstart.space - Запросы новых ролей / scope в Keycloak: тот же email.
Версионирование
API стабилизирован под v1 — breaking changes только через major bump (v2). См.
Best practices для рекомендаций по
обработке появления новых полей в v1 (forward compatibility).
Bundle справочников ЦУОД versioned отдельно (cuod-bundle:1.2.1). Изменение
schemas — minor bump, добавление словарей — minor bump, удаление — major bump
(никогда без уведомления consumers через nsi.dictionary.changed event).