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-рассылку.
2026-05-20 17:10:03 +03:00
parent aa93879a72
commit 5b96f98fb8
2 changed files with 290 additions and 0 deletions
@@ -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