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 графа)

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

// 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.

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 — как читать
• Cross-references — детали FK
• Caching — стратегии кэша для bundle scale