gRPC и схемы¶

Внутренние контракты между gateway, планировщиком и валидатором. Снаружи они недоступны: внешние клиенты работают через REST. Контракты нужны тем, кто встраивает планировщик или валидатор в свой контур напрямую.

Общие правила¶

Protobuf-пакеты geoscan.planner.v1, geoscan.validator.v1, общие типы — common.proto.
Документы сценария и плана передаются как JSON в байтовых полях (scenario_json, plan_json) — те же документы, что в REST.
Единицы кодируются суффиксом имени поля (_m, _s, _ms, _deg, _frac …).
Сервисный ключ — метаданные x-service-api-key; идентификатор запроса — x-request-id.
Максимальный размер сообщения — 64 МиБ.

PlannerService¶

service PlannerService {
  rpc Plan(PlanRequest) returns (stream PlanEvent);
  rpc StopPlan(StopPlanRequest) returns (StopPlanResponse);
  rpc ExportPlan(ExportPlanRequest) returns (ExportPlanResponse);
}

Сообщение	Поля
`PlanRequest`	`scenario_json`, `criterion`, `time_limit_s`, `seed`, `parent_plan_json`, `replan_at_time_s`, `replan_failed_uav_ids`, `separation` (`none`, `time`, `altitude`)
`PlanEvent`	одно из: `PlanProgress progress` или `PlanResult result`
`PlanProgress`	`stage`, `progress_frac`, `objective_value`, `best_objective_value`, `elapsed_s`, `message`
`PlanResult`	`plan_json`, `solver_status`, `solve_time_s`, `metrics`, `violations`, `unassigned`, `warnings`
`ExportPlanRequest`	`plan_json`, `format` (`GEOJSON`, `KML`, `PLAN`, `WAYPOINTS`), `uav_id`, `scenario_json` (для слоёв сценария)

Ошибки планировщика: INVALID_ARGUMENT — сценарий не прошёл проверку (в REST — 400), FAILED_PRECONDITION — нерешаемый вход, например недостижимый GSD (422), DEADLINE_EXCEEDED — вышел срок (504), UNAVAILABLE — сервис недоступен (503).

ValidatorService¶

service ValidatorService {
  rpc Validate(ValidateRequest) returns (ValidateResponse);
}

Сообщение	Поля
`ValidateRequest`	`scenario_json`, `plan_json` (можно передать одним `plan_json` вида `{"scenario": …, "plan": …}`)
`ValidateResponse`	`metrics`, `violations` (только жёсткие), `warnings`, `unassigned`, `admitted`, `report_json` — полный отчёт

Общие типы¶

Тип	Значения
`SolverStatus`	`optimal`, `feasible`, `infeasible`, `timeout`
`ExportFormat`	`GEOJSON`, `KML`, `PLAN`, `WAYPOINTS`
`ViolationKind`	`NFZ`, `AIRSPACE`, `ENDURANCE`, `WIND`, `PAYLOAD`, `ALTITUDE`, `TURNAROUND`
`UnassignedReason`	`no_compatible_payload`, `endurance_exceeded`, `outside_allowed_airspace`, `inside_no_fly_zone`, `wind_above_limit`, `time_window_missed`, `solver_time_limit`

JSON Schema¶

Файл	Что описывает
`scenario.schema.json`	документ сценария; поля — в Работе с файлами
`plan.schema.json`	документ плана; поля — в Работе с файлами
`units.json`	допустимые суффиксы единиц

Обе схемы — JSON Schema 2020-12 со строгим набором полей (additionalProperties: false): лишнее поле — ошибка.

erDiagram
  SCENARIO ||--|{ LAUNCH_SITE : launch_sites
  SCENARIO ||--o{ LANDING_SITE : landing_sites
  SCENARIO ||--|{ UAV : fleet
  SCENARIO ||--|{ SURVEY_TASK : tasks
  SCENARIO ||--|| AIRSPACE : airspace
  AIRSPACE ||--o{ ZONE : no_fly
  SCENARIO ||--|| WIND : weather
  SCENARIO ||--|| OBJECTIVE : objective
  SCENARIO ||--|| SOLVER : solver
  PLAN ||--|{ MISSION : missions
  MISSION ||--|{ SORTIE : sorties
  SORTIE ||--|{ PHASE : phases
  PLAN ||--o{ UNASSIGNED : unassigned
  PLAN ||--o{ WARNING : warnings
  PLAN ||--o{ DECISION : decisions

Командная строка¶

Планировщик и валидатор запускаются и без сервера:

cd src/backend
uv run python -m planner run --scenario scenarios/s03-multi-sites.json \
  --objective makespan --out /tmp/plan.json
uv run python -m planner export --plan /tmp/plan.json \
  --scenario scenarios/s03-multi-sites.json --fmt kml --out /tmp/plan.kml
uv run python -m validator check --scenario scenarios/s03-multi-sites.json \
  --plan /tmp/plan.json --json