diff --git a/docs/integration/dictionary-criteria.md b/docs/integration/dictionary-criteria.md new file mode 100644 index 0000000..097f573 --- /dev/null +++ b/docs/integration/dictionary-criteria.md @@ -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 diff --git a/docs/integration/email-announcement.md b/docs/integration/email-announcement.md new file mode 100644 index 0000000..2edb434 --- /dev/null +++ b/docs/integration/email-announcement.md @@ -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=`) +- **Локализация** через `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=) +> - Локализация через 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