REST-справочник

Все маршруты gateway. Ошибки возвращаются единым JSON: { "errorCode": "…", "message": "…", "errors"?: [{ "path", "rule", "message" }], "details"?: … }.

Сводка маршрутов

Метод	Путь	Назначение	Успех
GET	/healthz	процесс жив	200
GET	/readyz	готовность: база, планировщик, валидатор	200 / 503
GET	/status	версия, коммит, время старта	200
GET	/metrics	метрики Prometheus	200
GET	/api/docs, /api/openapi.json	Swagger UI и OpenAPI	200
GET	/api/fleet	справочник моделей БВС	200
GET	/api/payloads	справочник нагрузок	200
GET	/api/scenarios	список: демо-сценарии и пользовательские	200
POST	/api/scenarios	сохранить сценарий	201
GET	/api/scenarios/{id}	документ сценария	200
PATCH	/api/scenarios/{id}	переименовать пользовательский сценарий	200
DELETE	/api/scenarios/{id}	удалить пользовательский сценарий и его расчёты	204
GET	/api/scenarios/{id}/plans	история расчётов сценария	200
POST	/api/plans	поставить расчёт в очередь	202
GET	/api/plans/{id}	статус или готовый план	200
GET	/api/plans/{id}/events	поток прогресса (SSE)	200
GET	/api/plans/{id}/export/{fmt}	выгрузка kml, geojson, plan, waypoints	200
POST	/api/plans/{id}/stop	остановить и взять лучший план	202
POST	/api/plans/{id}/replan	пересчёт после выбытия бортов	202
POST	/api/validate	отчёт валидатора по паре «сценарий + план»	200
GET	/api/weather/forecast	прогноз ветра в точке (если включён на стенде)	200
GET	/api/assistant/status	состояние чат-ассистента	200
POST	/api/assistant/recommend	подбор вариантов перебором	200
POST	/api/assistant/chat	диалог с ассистентом (SSE)	200

Служебные

GET /healthz → {"status":"ok"}. GET /readyz проверяет базу и доступность планировщика и валидатора; при недоступности — 503. GET /status — имя сервиса, версия, коммит сборки, время старта. GET /metrics — текст Prometheus, включая число заданий по статусам.

Справочники

GET /api/fleet — модели БВС: тип (multirotor, fixed_wing), скорости, запас хода, потолок и минимальная высота, предел ветра, радиус разворота, совместимые нагрузки. GET /api/payloads — нагрузки: тип съёмки, параметры камеры (матрица, фокусное расстояние, размер кадра), типовые перекрытия.

Сценарии

GET /api/scenarios

Список: демо-сценарии s01–s13 и сохранённые пользовательские, с названием, источником и признаком «только чтение» для демо.

POST /api/scenarios

Тело — документ сценария (см. Работа с файлами). Повторное сохранение с тем же scenario_id создаёт новую версию. Параметр ?geoscan_data=true помечает сценарий как построенный из данных организаторов.

Код	Когда
201	сохранён
422	SCHEMA_VALIDATION_FAILED — документ не прошёл JSON Schema; в errors[] путь поля и правило
409	SCENARIO_READONLY — попытка перезаписать демо-сценарий

GET /api/scenarios/{id}/plans

История расчётов сценария: plan_id, status, created_at, finished_at, criterion, makespan_s, scenario_changed (сценарий менялся после расчёта).

Расчёт

POST /api/plans

Поле тела	Смысл
scenario или scenario_id	сценарий целиком или идентификатор сохранённого / демо-сценария
objective	makespan (по умолчанию), total_flight_time, pareto
time_limit_s (или solver.time_limit_s)	лимит времени расчёта, от 1 до 1800 с; по умолчанию 300 с
seed (или solver.seed)	зерно генератора
separation	разведение бортов: none (по умолчанию), time, altitude

Заголовок Idempotency-Key (рекомендуется): повтор того же запроса возвращает тот же planId с заголовком Idempotency-Replayed: true, другое тело с тем же ключом — 409.

Ответ 202:

{ "planId": "3f0c…", "status": "queued" }

и заголовок Location: /api/plans/{planId}.

Код	Когда
202	задание в очереди
400	SCHEMA_VALIDATION_FAILED — тело или сценарий не прошли проверку, лимит вне 1…1800 с
404	SCENARIO_NOT_FOUND
409	IDEMPOTENCY_KEY_CONFLICT
429	QUEUE_FULL — в очереди 20 заданий; заголовок Retry-After: 30

GET /api/plans/{id}

Пока идёт расчёт — status (queued или running) и progress. После завершения:

{
  "planId": "3f0c…",
  "status": "completed",
  "metrics": {
    "makespan_s": 787.95, "total_flight_time_s": 2310.4, "total_distance_m": 0,
    "uav_used": 3, "sorties": 3, "coverage_fraction": 1.0,
    "objective": "makespan", "solver": { "status": "feasible", "solve_time_s": 0.7 }
  },
  "plan": { "schema_version": 1, "scenario_id": "s03-multi-sites", "missions": [ … ], "…": "…" }
}

При ошибке — status: "failed" и error с кодом: GSD_UNREACHABLE (требуемый GSD недостижим ни одним бортом), SCHEMA_VALIDATION_FAILED, UPSTREAM_TIMEOUT, SOLVER_INTERRUPTED, CANCELLED и др.

GET /api/plans/{id}/events

Поток Server-Sent Events. Каждый кадр — id: <номер> и data: {JSON} с полями planId, stage, progress (0…1), objective_value, elapsed_s, message, ts. Поток закрывается после стадии completed или failed; расчёт продолжается и без подписчика. Для переподключения передайте Last-Event-ID.

GET /api/plans/{id}/export/{fmt}

fmt: kml, geojson, plan (QGroundControl), waypoints. Параметр ?uav=<id> — выгрузка одного борта. Ответ — файл (Content-Disposition: attachment).

Код	Когда
409	PLAN_NOT_READY — расчёт ещё не завершён
400	EXPORT_FORMAT_UNSUPPORTED
404	PLAN_NOT_FOUND, UAV_NOT_IN_PLAN

POST /api/plans/{id}/stop

Остановить расчёт и взять лучший найденный план. Если задание ещё в очереди — оно завершается без плана («Расчёт остановлен оператором: план ещё не найден»). Если идёт расчёт — ответ {"status":"running","stopRequested":true}, а план приходит с предупреждением STOPPED_BY_OPERATOR. Для завершённого расчёта — 409. Подробности — Правила расчёта.

POST /api/plans/{id}/replan

Пересчёт готового плана без выбывших бортов:

{ "exclude_uav_ids": ["gemini-02"] }

Ответ 202 с новым planId. Если без исключённых бортов парк пуст — 400; родительский план не готов — 409.

Проверка плана

POST /api/validate

Тело — { "scenario": {…}, "plan": {…} }. Ответ 200 — { "report": {…} } с вердиктом admitted, пересчитанными метриками и 39 проверками (см. Проверки валидатора). Так можно проверить план, рассчитанный вне Аэрозвено, если он записан в формате JSON-плана. Время ответа валидатора ограничено 30 с.

Прогноз ветра

GET /api/weather/forecast?lat=55.76&lon=37.62&height_m=120&time=2026-09-20T06:00:00Z — скорость и направление ветра из Open-Meteo на заданной высоте. На стендах без доступа в интернет источник выключен.

Коды ошибок

Код	HTTP	Смысл
SCHEMA_VALIDATION_FAILED	400 / 422	документ не соответствует схеме
SCHEMA_VERSION_UNSUPPORTED	400	неизвестная версия схемы
PAYLOAD_TOO_LARGE	413	тело больше 25 МБ
SCENARIO_NOT_FOUND, PLAN_NOT_FOUND, UAV_NOT_IN_PLAN	404	нет такого объекта
SCENARIO_READONLY	409	демо-сценарий нельзя перезаписать
PLAN_NOT_READY	409	расчёт не завершён
IDEMPOTENCY_KEY_CONFLICT	409	тот же ключ, другое тело
GSD_UNREACHABLE, PAYLOAD_INCOMPATIBLE	422	нерешаемый вход: GSD недостижим, нет совместимой нагрузки
QUEUE_FULL	429	очередь заполнена
UPSTREAM_UNAVAILABLE	503	планировщик, валидатор или языковая модель недоступны
UPSTREAM_TIMEOUT	504	внутренний сервис не ответил вовремя
SOLVER_INTERRUPTED, CANCELLED, PLAN_FAILED, INTERNAL	— / 500	расчёт прерван, отменён или упал