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/).
This commit is contained in:
Zimin A.N.
@@ -0,0 +1,138 @@
|
||||
# Bundle справочников cuod (anchor v1)
|
||||
|
||||
ЦУОД (Центр обработки данных дистанционного зондирования Земли) — anchor
|
||||
customer Ordinis v1. Bundle `cuod-bundle:1.2.1` содержит 40 справочников.
|
||||
|
||||
## Полный список
|
||||
|
||||
| Имя | Scope | Записей (typical) | Назначение |
|
||||
|---|---|---|---|
|
||||
| `spacecraft` | PUBLIC | 4-30 | Каталог КА (космические аппараты) |
|
||||
| `satellite_type` | PUBLIC | 5-15 | Классификация типов КА |
|
||||
| `spacecraft_status` | PUBLIC | 5-10 | Статусы КА (planned, in-orbit, active, decommissioned) |
|
||||
| `mission` | PUBLIC | 9-20 | Программы (Ресурс-П, Канопус, Sentinel...) |
|
||||
| `ground_station` | PUBLIC | 3-10 | Наземные пункты приёма |
|
||||
| `antenna` | PUBLIC | 5-30 | Антенны на ground stations |
|
||||
| `instrument` | PUBLIC | 10-50 | Бортовые сенсоры (Геотон, MODIS, C-SAR...) |
|
||||
| `sensor_type` | PUBLIC | 5-15 | Типы сенсоров (optical, SAR, LIDAR, hyperspectral) |
|
||||
| `data_format` | PUBLIC | 8-15 | GeoTIFF, NITF, SAFE, COG, JPEG2000, HDF5 |
|
||||
| `processing_level` | PUBLIC | 8 | L0-L4 уровни обработки |
|
||||
| `orbit_type` | PUBLIC | 5-10 | LEO, MEO, GEO, SSO, polar |
|
||||
| `coverage_pattern` | PUBLIC | 5-15 | global, regional, targeted, swath |
|
||||
| `revisit_period` | PUBLIC | 10-20 | Категории revisit time |
|
||||
| `band_definition` | PUBLIC | 50-200 | Спектральные band definitions |
|
||||
| `radiometric_resolution` | PUBLIC | 5-15 | bit depth (8, 12, 16-bit) |
|
||||
| `swath_width` | PUBLIC | 10-20 | Категории ширины полосы |
|
||||
| `temporal_resolution` | PUBLIC | 10-20 | Категории временного разрешения |
|
||||
| `spatial_resolution` | PUBLIC | 15-30 | Категории пространственного разрешения |
|
||||
| `aoi_type` | PUBLIC | 5-10 | Типы AOI (regions, footprint, custom polygon) |
|
||||
| `acquisition_mode` | PUBLIC | 5-15 | Modes (push-broom, whisk-broom, frame, SAR strip) |
|
||||
| `pointing_capability` | PUBLIC | 5-10 | Off-nadir capabilities (nadir-only, ±15°, ±45°) |
|
||||
| `polarisation_mode` | PUBLIC | 5-10 | SAR polarisation (HH, HV, VH, VV, dual) |
|
||||
| `antenna_type` | PUBLIC | 10-20 | Антенны: parabolic, phased-array, helical |
|
||||
| `tracking_mode` | PUBLIC | 5-10 | Tracking algorithms |
|
||||
| `data_product_type` | PUBLIC | 15-30 | Конечные продукты (orthorectified, mosaic, classified) |
|
||||
| `coordinate_system` | PUBLIC | 20-50 | Проекции (WGS84, GK-Pulkovo, UTM-zones, MGRS) |
|
||||
| `agency` | PUBLIC | 10-20 | Космические агентства (Roscosmos, NASA, ESA, JAXA) |
|
||||
| `orbit_inclination` | PUBLIC | 10 | Категории наклонения |
|
||||
| `quality_indicator` | INTERNAL | 10-20 | Индикаторы качества (cloud cover, snow cover, off-nadir) |
|
||||
| `tasking_priority` | INTERNAL | 5-10 | Приоритеты заказов |
|
||||
| `pricing_tier` | INTERNAL | 5-15 | Тарифы (по resolution / coverage) |
|
||||
| `customer_segment` | INTERNAL | 10-20 | Сегменты заказчиков |
|
||||
| `delivery_format` | INTERNAL | 10-20 | Формы поставки (FTP, S3, USB, physical media) |
|
||||
| `processing_chain_type` | INTERNAL | 10-20 | Цепочки обработки |
|
||||
| `archive_tier` | INTERNAL | 5 | Tiers хранения (hot/warm/cold) |
|
||||
| `retention_policy` | RESTRICTED | 5-10 | Сроки хранения по типам данных |
|
||||
| `access_classification` | RESTRICTED | 5-10 | Уровни секретности |
|
||||
| `export_control` | RESTRICTED | 5-15 | Экспортные ограничения |
|
||||
| `licensing_terms` | RESTRICTED | 10-20 | Лицензионные условия |
|
||||
| `data_sharing_agreement` | RESTRICTED | 5-10 | Соглашения об обмене |
|
||||
|
||||
(Точное число записей варьируется — bundle ships seed data, операторы
|
||||
добавляют свои.)
|
||||
|
||||
## Cross-references (FK графа)
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
SC[spacecraft]
|
||||
ST[satellite_type]
|
||||
SS[spacecraft_status]
|
||||
M[mission]
|
||||
I[instrument]
|
||||
DF[data_format]
|
||||
PL[processing_level]
|
||||
SE[sensor_type]
|
||||
OT[orbit_type]
|
||||
AG[agency]
|
||||
|
||||
SC --satelliteTypeCode--> ST
|
||||
SC --statusCode--> SS
|
||||
SC --orbitTypeCode--> OT
|
||||
SC --agencyCode--> AG
|
||||
M --spacecraftCodes--> SC
|
||||
I --spacecraftCodes--> SC
|
||||
I --sensorTypeCode--> SE
|
||||
I --supportedFormatCodes--> DF
|
||||
I --supportedLevelCodes--> PL
|
||||
```
|
||||
|
||||
(Это subset, для full графа см. отдельные schemas в коде:
|
||||
`ordinis-cuod-bundle/src/main/resources/cuod/schemas/`.)
|
||||
|
||||
## Типичные сценарии
|
||||
|
||||
### Сценарий: список всех КА с их типами
|
||||
|
||||
1. `GET /api/v1/spacecraft/records?lang=ru` — все КА
|
||||
2. `GET /api/v1/satellite_type/records?lang=ru` — все типы (parallel)
|
||||
3. Memory join: `spacecraft.data.satelliteTypeCode === satellite_type.businessKey`
|
||||
|
||||
### Сценарий: cascading select для UI
|
||||
|
||||
```ts
|
||||
// User выбрал "instrument: MSI-Sentinel-2"
|
||||
const instrument = await get('/api/v1/instrument/records/MSI-S2?lang=ru')
|
||||
|
||||
// Показать только supported formats
|
||||
const allFormats = await get('/api/v1/data_format/records?lang=ru')
|
||||
const allowed = allFormats.filter(f =>
|
||||
instrument.data.supportedFormatCodes.includes(f.businessKey))
|
||||
|
||||
// allowed: SAFE, GEOTIFF, COG, JPEG2000
|
||||
```
|
||||
|
||||
### Сценарий: snapshot для legal compliance
|
||||
|
||||
При создании imaging order — snapshot всех использованных справочников
|
||||
в свою БД. См. [Caching → Snapshot at order time](caching.md#snapshot-at-order-time).
|
||||
|
||||
## Performance considerations
|
||||
|
||||
- Полный bundle (все 40 справочников × средние 15 записей × ~1KB JSON =
|
||||
~600KB total). Cold load на startup — допустимо.
|
||||
- После cold load — кэш на 5 мин TTL, рефреш по событиям через webhook /
|
||||
Kafka.
|
||||
- Spatial фильтры (`?bbox=`) — только на словари с geometry полями
|
||||
(`spacecraft.aoi`, `mission.coverage_area`). Использует PostGIS GiST
|
||||
index.
|
||||
|
||||
## Bundle versioning policy
|
||||
|
||||
| Изменение | Bump |
|
||||
|---|---|
|
||||
| Add field в schema (optional) | Patch (1.2.1 → 1.2.2) |
|
||||
| Add справочник | Minor (1.2.x → 1.3.0) |
|
||||
| Make required field из optional | Minor (consumers compatible если default sane) |
|
||||
| Remove field / справочник | Major (1.x.x → 2.0.0) |
|
||||
| Change field type | Major |
|
||||
| Add x-references | Minor (но requires re-validation existing data) |
|
||||
|
||||
Major changes coordinated с consumers через `nsi.dictionary.changed` events
|
||||
+ admin announcement.
|
||||
|
||||
## Дальше
|
||||
|
||||
- [Read endpoints](read-endpoints.md) — как читать
|
||||
- [Cross-references](x-references.md) — детали FK
|
||||
- [Caching](caching.md) — стратегии кэша для bundle scale
|
||||
Reference in New Issue
Block a user