mdm-ordinis/docs/integration/api/bundle-cuod.md

# 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. Полный граф можно получить через `GET /dictionaries` +
inspection schemas через `GET /dictionaries/{name}` — каждый возвращает
JSON Schema с x-references маркерами.)

## Типичные сценарии

### Сценарий: список всех КА с их типами

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