mdm-ordinis

ivan-igorevich/mdm-ordinis

Fork 0

Commit Graph

Author	SHA1	Message	Date
Zimin A.N.	d5268b9395	docs: Diplodoc setup + полное руководство интеграции по API Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).	2026-05-07 23:19:02 +03:00
Zimin A.N.	2fc9b451e4	fix(cuod+docs): Resurs-P/Канопус/Метеор/Электро/Арктика в seed + правильный read-api путь Альтум-команда обнаружила что /api/v1/dictionaries/{name}/records даёт 500 и spacecraft_codes ссылаются на несуществующий "RESURS-P-3". Оба бага мои: 1. Read-api живёт на /api/v1/{name}/records (БЕЗ /dictionaries/ префикса). /dictionaries/* — это admin-write контроллер, у него GET-list нет. Fix: docs/integration/altum-imaging-order.md + docs/tech/api-integration.md обновлены с правильными URL'ами + примером ответа из live staging. 2. spacecraft seed имел только 4 КА (Terra, Sentinel-1A/2A, Кондор-ФКА), а mission.spacecraft_codes ссылался на пустые/RESURS-P-3 — каскад в "Заказ съёмки" не работал бы. Fix: добавлено 10 российских КА (Ресурс-П 1-4, Канопус-В 1+5, Метеор-М 2+2-2, Электро-Л 2, Арктика-М 1) с COSPAR designators как businessKey. 3. mission.records.json + instrument.records.json: spacecraft_codes теперь ссылается на реально существующие COSPAR-ключи. Каскад работает: instrument MSU-MR → spacecraft [2014-037A, 2019-038A] → Метеор-М № 2 / 2-2. После redeploy и идемпотентного пересева: spacecraft 14 (было 4, +10 РФ) mission 9 (existing 9, references фиксированы) instrument 11 (было 10, +МСУ-ГСМ Арктики)	2026-05-04 18:27:36 +03:00
Zimin A.N.	930df5b888	feat(api): Swagger UI + docs/integration для Альтума и других consumer'ов Springdoc-openapi генерирует OpenAPI 3 spec из аннотаций контроллеров — интеграторам не нужно поддерживать markdown-ТЗ синхронно с кодом. - /swagger-ui.html (UI), /v3/api-docs (JSON), /v3/api-docs.yaml. - OpenApiConfig: title/description/contact/servers (staging+prod+local), bearerAuth security scheme (Keycloak JWT). - SecurityConfig: permitAll на swagger paths. Документация: - docs/integration/altum-imaging-order.md — ТЗ интеграции «Заказ съёмки». Согласованы: m2m service account через Keycloak, BFF в altum-backend (FastAPI), 4 справочника со схемами, cascading select через instrument.supported_*_codes, snapshot strategy для аудита. - docs/tech/api-integration.md — общий гайд для интеграторов: auth flow, endpoints, кэш-стратегии, bitemporal модель, current dictionaries, cross-refs, best practices. Скрипты codegen openapi-generator-cli работают off /v3/api-docs.	2026-05-04 15:45:09 +03:00

Author

SHA1

Message

Date

Zimin A.N.

d5268b9395

docs: Diplodoc setup + полное руководство интеграции по API

Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.

Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors

Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями

Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references

Build:
  cd docs && pnpm install && pnpm build
  → ./_dist (20 HTML files, 7.1M)
  pnpm serve  # → http://localhost:8088

CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).

Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).

2026-05-07 23:19:02 +03:00

Zimin A.N.

2fc9b451e4

fix(cuod+docs): Resurs-P/Канопус/Метеор/Электро/Арктика в seed + правильный read-api путь

Альтум-команда обнаружила что /api/v1/dictionaries/{name}/records даёт 500
и spacecraft_codes ссылаются на несуществующий "RESURS-P-3". Оба бага мои:

1. Read-api живёт на /api/v1/{name}/records (БЕЗ /dictionaries/ префикса).
   /dictionaries/* — это admin-write контроллер, у него GET-list нет.
   Fix: docs/integration/altum-imaging-order.md + docs/tech/api-integration.md
   обновлены с правильными URL'ами + примером ответа из live staging.

2. spacecraft seed имел только 4 КА (Terra, Sentinel-1A/2A, Кондор-ФКА),
   а mission.spacecraft_codes ссылался на пустые/RESURS-P-3 — каскад в
   "Заказ съёмки" не работал бы.
   Fix: добавлено 10 российских КА (Ресурс-П 1-4, Канопус-В 1+5, Метеор-М 2+2-2,
   Электро-Л 2, Арктика-М 1) с COSPAR designators как businessKey.

3. mission.records.json + instrument.records.json: spacecraft_codes теперь
   ссылается на реально существующие COSPAR-ключи. Каскад работает:
   instrument MSU-MR → spacecraft [2014-037A, 2019-038A] → Метеор-М № 2 / 2-2.

После redeploy и идемпотентного пересева:
  spacecraft   14 (было 4, +10 РФ)
  mission       9 (existing 9, references фиксированы)
  instrument   11 (было 10, +МСУ-ГСМ Арктики)

2026-05-04 18:27:36 +03:00

Zimin A.N.

930df5b888

feat(api): Swagger UI + docs/integration для Альтума и других consumer'ов

Springdoc-openapi генерирует OpenAPI 3 spec из аннотаций контроллеров —
интеграторам не нужно поддерживать markdown-ТЗ синхронно с кодом.

- /swagger-ui.html (UI), /v3/api-docs (JSON), /v3/api-docs.yaml.
- OpenApiConfig: title/description/contact/servers (staging+prod+local),
  bearerAuth security scheme (Keycloak JWT).
- SecurityConfig: permitAll на swagger paths.

Документация:
- docs/integration/altum-imaging-order.md — ТЗ интеграции «Заказ съёмки».
  Согласованы: m2m service account через Keycloak, BFF в altum-backend
  (FastAPI), 4 справочника со схемами, cascading select через
  instrument.supported_*_codes, snapshot strategy для аудита.
- docs/tech/api-integration.md — общий гайд для интеграторов: auth flow,
  endpoints, кэш-стратегии, bitemporal модель, current dictionaries,
  cross-refs, best practices.

Скрипты codegen openapi-generator-cli работают off /v3/api-docs.

2026-05-04 15:45:09 +03:00

3 Commits