diff --git a/docs/integration/dictionary-criteria.html b/docs/integration/dictionary-criteria.html new file mode 100644 index 0000000..e9b14ef --- /dev/null +++ b/docs/integration/dictionary-criteria.html @@ -0,0 +1,588 @@ + + + + + +Регламент · Что заводить в Ordinis НСИ + + + +
+ +
+

Регламент · Ordinis MDM · v1.0

+

Что заводить в Ordinis НСИ

+

+ Decision framework для владельцев данных: какие справочники стоит выносить в централизованную НСИ Ordinis MDM, а какие держать локально в своём сервисе. +

+
+ TL;DR: НСИ — для shared reference data со slow change rate. Если данные нужны только одному сервису, меняются 100 раз в секунду или это транзакции — это не НСИ. +
+
+ +

Что стоит заводить в НСИ

+

Справочник — кандидат, если он удовлетворяет минимум 3 из 5 критериев ниже.

+ +
+

1. Shared между ≥ 2 потребителями

+

Данные читают/используют как минимум два разных сервиса (или будут в обозримом roadmap).

+

Примеры: Космические аппараты (планировщик миссий + геопортал + биллинг), наземные станции (планировщик + телеметрия + Альтум), классы разрешения (геопортал + ML pipeline).

+
Если данные нужны только одному сервису — храни локально. Не плоди интеграционные точки на пустом месте.
+
+ +
+

2. Slow change rate (часы → недели, а не секунды)

+

Изменяется редко — раз в неделю / месяц / квартал. Не транзакционные данные.

+ + + + + + + + + +
Частота измененийЭто НСИ?
Раз в год — справочник стран✓ да
Раз в квартал — справочник миссий ДЗЗ✓ да
Раз в неделю — справочник антенн (новые станции)✓ да
Раз в час — текущая температура спутника✗ нет (телеметрия)
100×/сек — статус заявки на съёмку✗ нет (state machine)
+
+ +
+

3. Нужна validity-window (validFrom / validTo)

+

Данные актуальны на определённый период. Закрытие/замена записи через bitemporal versioning, не через DELETE.

+

Примеры: Тарифы (действуют с 01.01.2026), орбитальные параметры (TLE на конкретную epoch), составы flight crew (период).

+
Если данные «текущее состояние и забыли» — может быть просто config или KV store.
+
+ +
+

4. Требуется audit-trail (compliance / governance)

+

Нужно знать кто, когда, почему изменил запись — для compliance, forensics, отката.

+

Все справочники в Ordinis по умолчанию имеют Hibernate Envers audit log с full history.

+

Примеры: Регуляторные классификации, security clearances, тарифные планы (для финансового audit'а).

+
+ +
+

5. Есть схема (structured, validated)

+

Данные имеют стабильную JSON-Schema с required-полями и валидацией. Не «свободный мешок ключей».

+
Если структура каждую неделю меняется и нет SLA на стабильность — может быть это ещё не НСИ, а Notion-like wiki.
+
+ + +

Что не стоит заводить в НСИ

+ +
+

A. Транзакционные данные

+

Заявки, заказы, события, измерения, журналы. Это transactional store (PostgreSQL/Kafka topic application'а), не НСИ.

+

растёт линейно со временем работы системы

+
+ +
+

B. Высокочастотные мутации

+

> 100 updates/sec — не лезет в audit, забивает Kafka outbox. Для счётчиков и telemetry — Redis / time-series DB / Prometheus.

+
+ +
+

C. Производные / вычисляемые данные

+

Если значение вычисляется из других данных — храни источник, не результат. Кэш производных — в Redis с invalidation.

+

«активные миссии за месяц» — это query, не справочник

+
+ +
+

D. PII / sensitive без access control

+

Персональные данные физлиц, payment data, security secrets. Ordinis сейчас поддерживает scope (PUBLIC / INTERNAL / RESTRICTED), но per-record ACL пока в roadmap (Q4 2026).

+

Для PII — выделенный сервис с шифрованием и compliance audit, не общий НСИ.

+
+ +
+

E. Большие BLOB'ы

+

Изображения, PDF, сырые телеметрические дампы. → MinIO/S3 + ссылка в справочнике, но не контент в data.

+
+ +
+

F. Данные, нужные только одному сервису

+

Если справочник никогда не покинет границу сервиса X — это его внутренний config. Не выноси наружу.

+

boundary test — «может ли потребитель Y разумно захотеть читать это?». Нет → не НСИ

+
+ + +

Чек-лист перед созданием справочника

+ +
+

10 вопросов · ответь "да" / "нет"

+
    +
  1. Минимум один реальный потребитель кроме создателя? (named system)
    2. +
  2. Согласованная schema (фиксированный набор полей)?
    3. +
  3. Change rate < 10/мин в среднем?
    4. +
  4. Validity windows имеют смысл (или достаточно "current state")?
    5. +
  5. Audit-trail нужен для compliance / forensics?
    6. +
  6. Owner назначен? Reviewer pool назначен (для approval-required dicts)?
    7. +
  7. Bundle подобран? (cuod / geo / comms / delivery — см. existing)
    8. +
  8. Локализация — нужна? Какие locale supported?
    9. +
  9. Scope: PUBLIC / INTERNAL / RESTRICTED?
    10. +
  10. Onboarding plan — кто и когда мигрирует существующие consumers?
    11. +
+
+ ≥ 7 yes — заводи. Если меньше — обсуди с Ordinis team, возможно паттерн не НСИ. +
+
+ + +

Процесс создания справочника

+ +

Простой случай (PUBLIC scope, owner = создающий)

+
+
Owner открывает /dictionaries admin UI → Создать
+
Заполняет name, displayName, schema (через UI builder или импорт JSON)
+
Тестит в staging (ordinis.k8s.265.nstart.cloud)
+
После validation — publish; данные иммутабельно зашиваются в Kafka outbox
+
Сообщение в #ordinis Slack — потребители подхватывают через /dictionaries listing
+
+ +

Approval-required (для критичных)

+
+
Owner создаёт schema draft (не публикует сразу)
+
Reviewer pool получает email уведомление
+
Reviewer открывает /reviews → diff → approve/reject
+
После approval — auto-publish через workflow
+
+ +

Onboarding существующих данных (миграция)

+
+
Owner экспортирует существующий справочник из source-системы в CSV/JSON
+
Создаёт schema в Ordinis (UI builder)
+
Bulk import API (Q4 2026) или manual seed через bundle YAML
+
Запускает параллельное чтение — consumers читают и из source, и из Ordinis, сверяют diff
+
После недели зелёного diff — переключают consumers на Ordinis exclusive
+
Декомиссия source: справочник удаляется в source, остаётся в Ordinis
+
+ + +

Conventions для schema

+

Чтобы интеграторам было проще читать твой справочник:

+ + + +

Anti-patterns (видели на практике)

+
+

Справочник = state machine состояний заявки. application_status: NEW/APPROVED/REJECTED — это enum в схеме заявки, а не отдельный справочник.

+

Справочник под per-user preferences. Предпочтения юзера X — это его profile в auth-сервисе.

+

Справочник вместо feature flag. Если читается на каждом запросе для decisions — config service (Spring Cloud Config + LaunchDarkly-like).

+

«Логирование» через справочник. Лог событий — Kafka topic + Loki, не НСИ.

+

Справочник, чтобы передать данные между двумя своими микросервисами. Используй внутреннюю DB / message broker, не НСИ.

+
+ + +

Когда сомневаешься — спроси

+
+ Контакты Ordinis team + +

Лучше 30 минут на консультацию, чем месяц на отрыв справочника обратно в local store.

+
+ + +
+ Ordinis MDM · v1.0 · 2026-05 · NStart +
+ +
+ +