docs(integration): регламент НСИ + текст рассылки для интеграторов
* dictionary-criteria.md — decision framework "что заводить в НСИ":
- 5 положительных критериев (shared, slow change, validity windows,
audit-trail, structured schema) с min-3-из-5 threshold
- 6 anti-patterns (transactional, high-freq mutations, derived data,
PII без ACL, BLOBs, single-consumer данные)
- 10-пунктный чек-лист (≥7 yes → заводи, < — обсуди)
- Процесс создания (simple + approval-required + миграция)
- Schema conventions (businessKey, x-localized, x-references etc)
- Anti-patterns с примерами из практики
* email-announcement.md — текст рассылки команде:
- URLs (prod/staging/Swagger/docs)
- Что внутри Ordinis (37 dicts, REST API, локализация, audit, workflow)
- С чего начать (Quick Start, Cheat Sheet, Postman, presentation)
- 60-second smoke командой
- Roadmap Q3
- Plain-text вариант для систем без markdown
Both files готовы к публикации: regulation идёт в integrator docs (link
из email), letter — в Mattermost / email-рассылку.
This commit is contained in:
Zimin A.N.
@@ -0,0 +1,176 @@
|
|||||||
|
# Регламент · Что заводить в 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
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
# Письмо рассылки · НСИ Ordinis MDM доступна для интеграции
|
||||||
|
|
||||||
|
**Тема:** Ordinis MDM — централизованная НСИ ДЗЗ доступна для интеграции
|
||||||
|
|
||||||
|
**Кому:** development-leads@, integration-team@, data-owners@, product@nstart.space
|
||||||
|
**От:** zimin.an@nstart.space (Ordinis team)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Коллеги, добрый день.
|
||||||
|
|
||||||
|
Запустили **Ordinis MDM** — централизованный сервис нормативно-справочной информации (НСИ) для проектов ДЗЗ. Это **единый source of truth** для справочников, к которому теперь могут подключаться все потребители вместо ведения собственных копий.
|
||||||
|
|
||||||
|
## Где это живёт
|
||||||
|
|
||||||
|
| Среда | URL | Назначение |
|
||||||
|
|---|---|---|
|
||||||
|
| **Production** | https://ordinis.nstart.cloud | Боевые справочники, public LE-cert |
|
||||||
|
| **Staging** | https://ordinis.k8s.265.nstart.cloud | Тесты интеграции, Swagger UI здесь |
|
||||||
|
| Admin UI | (тот же домен) | Просмотр / редактирование (auth required) |
|
||||||
|
| OpenAPI spec | `$BASE/v3/api-docs` (staging) | Для генерации clients |
|
||||||
|
| Integrator docs | `$BASE/docs` (staging) | Полная документация |
|
||||||
|
|
||||||
|
## Что внутри
|
||||||
|
|
||||||
|
- **37 справочников** на проде (космические аппараты, наземные станции, антенны, миссии, спектральные каналы, классы разрешения, и т.д.) — все на сегодня в `PUBLIC` scope
|
||||||
|
- **REST API** с full bitemporal queries (`?at=<timestamp>`)
|
||||||
|
- **Локализация** через `Accept-Language` header (ru-RU / en-US / zh-CN)
|
||||||
|
- **Audit + history** — каждое изменение versioned (Hibernate Envers)
|
||||||
|
- **Workflow approvals** — maker-checker для чувствительных справочников
|
||||||
|
- **Kafka events** + **webhooks** — push-уведомления потребителям
|
||||||
|
- **Smart search** — full-text по всем справочникам
|
||||||
|
|
||||||
|
## С чего начать интегратору
|
||||||
|
|
||||||
|
1. **Quick Start (15 минут):** https://git.nstart.cloud/2-6/2-6-4/terravault/ordinis/-/blob/main/docs/integration/api-quickstart.md
|
||||||
|
2. **Cheat Sheet** (одностраничник): https://git.nstart.cloud/2-6/2-6-4/terravault/ordinis/-/blob/main/docs/integration/api-cheatsheet.md (он же зеркалится как **Приложение A** в Quick Start)
|
||||||
|
3. **Postman collection** (27 рабочих запросов + 10-шаговый demo flow): см. `docs/integration/postman/` в репо или попросите у Ordinis team
|
||||||
|
4. **Live presentation API Demo** (14 слайдов): попросите у меня PowerPoint, проведём walkthrough
|
||||||
|
|
||||||
|
## Smoke 60 секунд
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ORDINIS=https://ordinis.nstart.cloud
|
||||||
|
|
||||||
|
curl -s $ORDINIS/api/v1/version | jq
|
||||||
|
curl -s $ORDINIS/api/v1/dictionaries | jq 'length' # 37
|
||||||
|
curl -s "$ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC" | jq '.[0]'
|
||||||
|
curl -sH "Accept-Language: en-US" \
|
||||||
|
"$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC" \
|
||||||
|
| jq '.data.operator' # "NASA"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Что должно лечь в Ordinis (и что не должно)
|
||||||
|
|
||||||
|
См. **регламент** `docs/integration/dictionary-criteria.md` — короткий decision framework для владельцев данных: какие данные стоит выносить в централизованную НСИ, а какие держать локально в своём сервисе. Прежде чем заводить новый справочник или мигрировать существующий — пройдитесь по чек-листу.
|
||||||
|
|
||||||
|
## Roadmap Q3
|
||||||
|
|
||||||
|
- Geo bundle (орбиты, AOI templates, terrain layers)
|
||||||
|
- AI Schema Assist v2 — per-field LLM suggest
|
||||||
|
- Multi-tenant ACL + bulk import API
|
||||||
|
|
||||||
|
## Поддержка и обратная связь
|
||||||
|
|
||||||
|
- **Slack/Mattermost:** `#ordinis` (если нет — постучитесь, добавлю)
|
||||||
|
- **Issue tracker:** GitLab project `2-6/2-6-4/terravault/ordinis`
|
||||||
|
- **Прямой контакт:** zimin.an@nstart.space
|
||||||
|
|
||||||
|
Подключайтесь — чем больше потребителей, тем быстрее НСИ закрывает реальные потребности. Готов лично провести 30-минутный demo любой команде.
|
||||||
|
|
||||||
|
С уважением,
|
||||||
|
Команда Ordinis
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Plain-text (для систем без markdown)
|
||||||
|
|
||||||
|
> Тема: Ordinis MDM — централизованная НСИ ДЗЗ доступна для интеграции
|
||||||
|
>
|
||||||
|
> Коллеги, добрый день.
|
||||||
|
>
|
||||||
|
> Запустили Ordinis MDM — централизованный сервис НСИ для проектов ДЗЗ.
|
||||||
|
> Это единый source of truth для справочников, к которому теперь могут
|
||||||
|
> подключаться все потребители вместо ведения собственных копий.
|
||||||
|
>
|
||||||
|
> URLs:
|
||||||
|
> - Production: https://ordinis.nstart.cloud
|
||||||
|
> - Staging (Swagger UI): https://ordinis.k8s.265.nstart.cloud
|
||||||
|
> - OpenAPI: $BASE/v3/api-docs (только staging)
|
||||||
|
> - Integrator docs: $BASE/docs (staging)
|
||||||
|
>
|
||||||
|
> Что внутри:
|
||||||
|
> - 37 справочников на проде (КА, наземные станции, миссии, антенны, ...)
|
||||||
|
> - REST API с time-travel (?at=<timestamp>)
|
||||||
|
> - Локализация через Accept-Language header
|
||||||
|
> - Audit + history (каждое изменение versioned)
|
||||||
|
> - Workflow approvals (maker-checker)
|
||||||
|
> - Kafka events + webhooks
|
||||||
|
> - Smart search
|
||||||
|
>
|
||||||
|
> С чего начать:
|
||||||
|
> 1. Quick Start: docs/integration/api-quickstart.md
|
||||||
|
> 2. Cheat Sheet: docs/integration/api-cheatsheet.md
|
||||||
|
> 3. Postman: docs/integration/postman/ (или у Ordinis team)
|
||||||
|
>
|
||||||
|
> Регламент "что заводить в НСИ" — docs/integration/dictionary-criteria.md.
|
||||||
|
> Пройдите чек-лист прежде чем создавать новый справочник.
|
||||||
|
>
|
||||||
|
> Slack: #ordinis · GitLab: 2-6/2-6-4/terravault/ordinis · zimin.an@nstart.space
|
||||||
|
>
|
||||||
|
> Готов провести 30-минутный demo для любой команды.
|
||||||
|
>
|
||||||
|
> — Ordinis team
|
||||||
Reference in New Issue
Block a user