# Регламент · Что заводить в 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 разумно захотеть читать это?» Нет → не НСИ.

---

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

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

Если **≥ 7 yes** — заводи. Если меньше — обсудите с Ordinis team, возможно паттерн не НСИ.

---

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

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

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

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

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

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

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

---

## Conventions для schema

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

- **`businessKey`** должен быть human-readable стабильный идентификатор. Не UUID — `GS_MOSCOW_A1` лучше чем `b284f74e-60c8-…`.
- **Required fields** — минимум что нужно для валидности. Не объявляй required то, что может быть пустым в legacy data.
- **`x-localized: true`** на текстовых полях, которые должны переводиться (`name`, `displayName`, `description`).
- **`x-references: target_dict.field`** для FK — Ordinis валидирует и строит граф.
- **`x-section`** — группировка полей в UI editor'е (`Основное`, `Геометрия`, `Метаданные`).
- **`enum`** для closed lists вместо свободной строки (тип КА, статус миссии).
- **`format: date-time`** для timestamps (Ordinis парсит как ISO-8601).

---

## 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, не НСИ.

---

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

- Slack `#ordinis`
- zimin.an@nstart.space
- Office-hours: четверг 15:00 МСК (ad-hoc на DM)

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

— Ordinis team · v1.0 · 2026-05