# API и протоколы

## Метаданные

- Документ ID: `REG-TECH-002`
- Версия: `0.1.1`
- Ответственный: `ООО "Аросса"`
- Статус: `Готово`

## 1. API-контур

- Протокольная модель: `REST API` на базе `Swagger/OpenAPI`.
- Префикс API: `/api/v1`.
- Политика версионирования: изменения внутри `v1` только обратно-совместимые; несовместимые правки только в новой major-ветке.
- Формат данных `list/scheme`:
  - `GET /api/v1/<resource>/list` — отбор + фильтры + пагинация.
  - `GET /api/v1/<resource>/scheme` — схема UI/backend.
  - `POST /api/v1/<resource>` — создание сущности/команды.
  - `GET /api/v1/<resource>/{id}` — чтение сущности.
  - `PATCH /api/v1/<resource>/{id}` — изменение.
  - `DELETE /api/v1/<resource>/{id}` — архивирование/удаление.

## 2. Протоколы обмена

- MQTT: телеметрия, события и команды, двусторонняя синхронизация между `local` и `tenant/master`.
- CANopen: `PDO/SDO` для полевого контура, включительно с интеграцией IOOT PRO.
- RS485 Modbus RTU: интеграции внешних узлов и привязанных датчиков.
- Обработка отказов:
  - для команд используется подтверждение и ретрай;
  - при потере связи выполняется локальная очередь и досинхронизация после возврата канала.

## 3. Полный runtime-реестр маршрутов

- Служба здоровья:
  - `GET /health`
  - `GET /api/v1/app/context` (`deployment_mode`, tenant/site, active industry, feature flags, `policy.permissions/capabilities/guards`)

- Модульный runtime:
  - `GET /api/v1/modules/scheme` (`display_module`, `show_filters`, `module_view`, `catalog_enrichment`)
  - `GET /api/v1/modules/list`
  - `GET /api/v1/modules/database/scheme`
  - `GET /api/v1/modules/database/list`
  - `GET /api/v1/modules/permissions/scheme`
  - `GET /api/v1/modules/permissions/list`
  - `POST /api/v1/modules/permissions/commands/update`
  - `GET /api/v1/auth/ui-access/list`
  - `POST /api/v1/auth/ui-access/commands/update`
  - `GET /api/v1/auth/ui-preferences/list`
  - `POST /api/v1/auth/ui-preferences/commands/update`
  - `GET /api/v1/auth/shell-profile/list`
  - `POST /api/v1/auth/shell-profile/commands/export`
  - `POST /api/v1/auth/shell-profile/commands/import`
  - `POST /api/v1/auth/shell-profile/commands/rollback`
  - `GET /api/v1/modules/access-audit/scheme`
  - `GET /api/v1/modules/access-audit/list`
  - `GET /api/v1/modules/site-policy/scheme`
  - `GET /api/v1/modules/site-policy/list`
  - `POST /api/v1/modules/site-policy/commands/set`
  - `POST /api/v1/modules/commands/install`
  - `POST /api/v1/modules/commands/uninstall`

- Супервизия и инциденты:
  - `GET /api/v1/status/list`
  - `GET /api/v1/status/stream` (WebSocket)
  - `GET /api/v1/alarms/scheme`
  - `GET /api/v1/alarms/list`
  - `POST /api/v1/alarms/commands/ack`
  - `GET /api/v1/tasks/scheme`
  - `GET /api/v1/tasks/list`
  - `POST /api/v1/tasks`
  - `GET /api/v1/tasks/{id}`
  - `POST /api/v1/tasks/commands/transition`
  - `GET /api/v1/audit/scheme`
  - `GET /api/v1/audit/list`
  - `POST /api/v1/audit/commands/log`
  - `GET /api/v1/devices/telemetry/scheme`
  - `GET /api/v1/devices/telemetry/list`
  - `GET /api/v1/devices/telemetry/kpi`

- Клиентская устойчивость runtime:
  - UI использует `app/context` как source-of-truth для role/scope/capability guards;
  - при недоступности `status/stream` клиент переключается на reconnect/backoff и fallback `status/list` polling.

- Tenant/master и governance:
  - `GET /api/v1/tenant-master/scheme`
  - `GET /api/v1/tenant-master/list`
  - `POST /api/v1/tenant-master/commands/publish`
  - `GET /api/v1/tenant-master-sync/scheme`
  - `GET /api/v1/tenant-master-sync/list`
  - `POST /api/v1/tenant-master-sync/commands/run`
  - `POST /api/v1/tenant-master-sync/commands/set-mode`
  - `GET /api/v1/subscriptions/scheme`
  - `GET /api/v1/subscriptions/list`
  - `POST /api/v1/subscriptions/commands/set-status`
  - `GET /api/v1/sla-profiles/scheme`
  - `GET /api/v1/sla-profiles/list`
  - `POST /api/v1/sla-profiles/commands/assign`
  - `GET /api/v1/version-policies/scheme`
  - `GET /api/v1/version-policies/list`
  - `POST /api/v1/version-policies/commands/set`
  - `POST /api/v1/version-policies/commands/check`
  - `GET /api/v1/analytics/metrics/scheme`
  - `GET /api/v1/analytics/metrics/list`
  - `GET /api/v1/analytics/summary`

- Аутентификация и безопасность:
  - `GET /api/v1/passkeys/scheme`
  - `GET /api/v1/passkeys/list`
  - `POST /api/v1/passkeys/commands/issue`
  - `POST /api/v1/passkeys/commands/revoke`
  - `POST /api/v1/auth/passkey/commands/start`
  - `POST /api/v1/auth/passkey/commands/complete`
  - `GET /api/v1/auth/passkey/status`
  - `GET /api/v1/auth/me`
  - `POST /api/v1/auth/commands/logout`
  - `GET /api/v1/auth/permissions/scheme`
  - `GET /api/v1/auth/permissions/list`
  - `GET /api/v1/auth/ui-access/list`
  - `POST /api/v1/auth/ui-access/commands/update`
  - `GET /api/v1/auth/ui-preferences/list`
  - `POST /api/v1/auth/ui-preferences/commands/update`
  - `GET /api/v1/auth/shell-profile/list`
  - `POST /api/v1/auth/shell-profile/commands/export`
  - `POST /api/v1/auth/shell-profile/commands/import`
  - `POST /api/v1/auth/shell-profile/commands/rollback`
  - `GET /api/v1/auth/security-log/scheme`
  - `GET /api/v1/auth/security-log/list`

- Профили и отраслевые каталоги:
  - `GET /api/v1/industry-profiles/scheme`
  - `GET /api/v1/industry-profiles/list`
  - `POST /api/v1/industry-profiles/commands/import`
  - `POST /api/v1/industry-profiles/commands/export`
  - `POST /api/v1/industry-profiles/commands/publish`
  - `POST /api/v1/industry-profiles/commands/rollback`
  - `POST /api/v1/poultry-profiles/commands/import-yaml`
  - `POST /api/v1/poultry-profiles/commands/export-yaml`
  - `POST /api/v1/poultry-profiles/commands/publish`
  - `POST /api/v1/poultry-profiles/commands/rollback`
  - `GET /api/v1/industry-alarms/scheme`
  - `GET /api/v1/industry-alarms/list`
  - `POST /api/v1/industry-alarms/commands/publish`

- Мелиорация:
  - `GET /api/v1/melioration-field/scheme`, `GET /api/v1/melioration-field/list`
  - `GET /api/v1/melioration-alerts/scheme`, `GET /api/v1/melioration-alerts/list`
  - `GET /api/v1/melioration-irrigation-machine/scheme`, `GET /api/v1/melioration-irrigation-machine/list`, `POST /api/v1/melioration-irrigation-machine/commands/ingest`
  - `GET /api/v1/melioration-irrigation-drip/scheme`, `GET /api/v1/melioration-irrigation-drip/list`, `POST /api/v1/melioration-irrigation-drip/commands/ingest`
  - `GET /api/v1/melioration-soil-moisture/scheme`, `GET /api/v1/melioration-soil-moisture/list`, `POST /api/v1/melioration-soil-moisture/commands/ingest`
  - `GET /api/v1/melioration-weather/scheme`, `GET /api/v1/melioration-weather/list`, `POST /api/v1/melioration-weather/commands/ingest`, `POST /api/v1/melioration-weather/commands/telemetry`
  - `GET /api/v1/melioration-control-mode/scheme`, `GET /api/v1/melioration-control-mode/list`, `POST /api/v1/melioration-control-mode/commands/set`, `POST /api/v1/melioration-control-mode/commands/degrade`

- Отраслевые модули птицеводства:
  - `GET /api/v1/poultry-climate/scheme`, `GET /api/v1/poultry-climate/list`, `POST /api/v1/poultry-climate/commands/setpoint`, `POST /api/v1/poultry-climate/commands/ack`, `POST /api/v1/poultry-climate/commands/telemetry`, `POST /api/v1/poultry-climate/sensors/commands/ingest`
  - `GET /api/v1/poultry-flock/scheme`, `GET /api/v1/poultry-flock/list`
  - `GET /api/v1/poultry-feedwater/scheme`, `GET /api/v1/poultry-feedwater/list`, `POST /api/v1/poultry-feedwater/commands/ingest`
  - `GET /api/v1/poultry-production/scheme`, `GET /api/v1/poultry-production/list`, `GET /api/v1/poultry-production/kpi`
  - `GET /api/v1/poultry-alarms/scheme`, `GET /api/v1/poultry-alarms/list`, `POST /api/v1/poultry-alarms/commands/evaluate`, `POST /api/v1/poultry-alarms/commands/publish`, `POST /api/v1/poultry-alarms/commands/ack`, `POST /api/v1/poultry-alarms/commands/escalate`

- Отраслевые модули свиноводства:
  - `GET /api/v1/swine-climate/scheme`, `GET /api/v1/swine-climate/list`, `POST /api/v1/swine-climate/commands/setpoint`, `POST /api/v1/swine-climate/commands/telemetry`, `POST /api/v1/swine-climate/sensors/commands/ingest`
  - `GET /api/v1/swine-feeding/scheme`, `GET /api/v1/swine-feeding/list`, `POST /api/v1/swine-feeding/commands/ingest`
  - `GET /api/v1/swine-water/scheme`, `GET /api/v1/swine-water/list`, `POST /api/v1/swine-water/commands/ingest`
  - `GET /api/v1/swine-production/scheme`, `GET /api/v1/swine-production/list`, `GET /api/v1/swine-production/kpi`, `POST /api/v1/swine-production/commands/ingest`
  - `GET /api/v1/swine-biosecurity/scheme`, `GET /api/v1/swine-biosecurity/list`, `POST /api/v1/swine-biosecurity/commands/ingest`, `POST /api/v1/swine-biosecurity/commands/ack`

- Беспилотные весы:
  - `GET /api/v1/weighbridge-session/scheme`, `GET /api/v1/weighbridge-session/list`, `GET /api/v1/weighbridge-session/offline-queue`
  - `POST /api/v1/weighbridge-session/commands/detect`, `POST /api/v1/weighbridge-session/commands/complete-phase`, `POST /api/v1/weighbridge-session/commands/interlock`, `POST /api/v1/weighbridge-session/commands/erp-sync`
  - `GET /api/v1/weighbridge-identity/scheme`, `GET /api/v1/weighbridge-identity/list`, `POST /api/v1/weighbridge-identity/commands/resolve`, `POST /api/v1/weighbridge-identity/commands/attach`
  - `GET /api/v1/weighbridge-media/scheme`, `GET /api/v1/weighbridge-media/list`, `POST /api/v1/weighbridge-media/commands/ingest`
  - `GET /api/v1/weighbridge-alarms/scheme`, `GET /api/v1/weighbridge-alarms/list`, `POST /api/v1/weighbridge-alarms/commands/publish`, `POST /api/v1/weighbridge-alarms/commands/ack`
  - lifecycle baseline: `completed|manual_review|rejected`, причем `rejected` не используется как silent fallback
  - duplicate detection обязан переиспользовать открытый `session_id`, а не создавать вторую карточку
  - media evidence хранится через `storage_ref`/`preview_ref`; `cargo_top(gross)` обязателен для automatic close
  - `offline-queue` удерживает session/media/alarm entities до подтвержденного sync

- Demo и пульт:
  - `GET /api/v1/pult/scheme`
  - `GET /api/v1/pult/state`
  - `POST /api/v1/pult/commands/dispatch`
  - `GET /api/v1/demo/scheme`
  - `GET /api/v1/demo/state`
  - `GET /api/v1/demo/stream` (WebSocket)
  - `POST /api/v1/demo/commands/start`
  - `POST /api/v1/demo/commands/stop`
  - `POST /api/v1/demo/commands/pulse`

- Generic resource API:
  - `GET /api/v1/tables/scheme`, `GET /api/v1/tables/list`, `POST /api/v1/tables`, `GET /api/v1/tables/{id}`, `PATCH /api/v1/tables/{id}`, `DELETE /api/v1/tables/{id}`
  - `GET /api/v1/forms/scheme`, `GET /api/v1/forms/list`, `POST /api/v1/forms`, `GET /api/v1/forms/{id}`, `PATCH /api/v1/forms/{id}`, `DELETE /api/v1/forms/{id}`

- Расширения runtime green-robot:
  - `GET /api/v1/accounts/scheme`
  - `GET /api/v1/accounts/list`
  - `GET /api/v1/accounts/{id}`
  - `POST /api/v1/accounts`
  - `PATCH /api/v1/accounts/{id}`
  - `POST /api/v1/accounts/{id}/block`
  - `POST /api/v1/accounts/{id}/unblock`
  - `GET /api/v1/roles/list`
  - `POST /api/v1/accounts/{id}/roles`
  - `DELETE /api/v1/accounts/{id}/roles/{role_id}`
  - `GET /api/v1/audit-events/list?scope=auth`

## 4. Обязательные query-параметры list-маршрутов

- Для всех `GET /api/v1/.../list` маршрутов из runtime-реестра обязательны query-параметры: `limit`, `offset`.
- Для `GET /api/v1/modules/site-policy/list` дополнительно обязателен `site_id`.
- Для `GET /api/v1/audit-events/list?scope=auth` дополнительно обязателен `scope=auth`.
- Дополнительные фильтры (`sort`, `order`, `q`, бизнес-поля ресурса) не отменяют обязательные параметры и задаются контрактом ресурса.

## 5. Интеграционные требования

- Точки интеграции между embedded и cloud-контуром должны иметь:
  - трассируемую метку `request_id`;
  - проверяемый scope (`local/tenant/master`);
  - понятную обратную совместимость ответов (`meta`/`error` envelope).

## 6. Связанные документы

- [CANopen Profiles](../../canopen-profiles)
- [Architecture](../../architecture)
- [Стиль API и контракт ответов](api-style)
- [Модель учетных записей и доступа](account-model)
- [API-контракты (v1)](../../backend_contracts)