API и протоколы

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. Связанные документы#

Содержание