API

API#

Документ фиксирует реализованный baseline MVP API для poultry-модулей.

1. Общие правила#

  • Префикс: /api/v1.

  • Формат: list/scheme + команды.

  • Envelope: item/list + meta.request_id/meta.timestamp.

  • Изоляция: tenant_id, industry_code=poultry, site_id, house_id (где применимо).

2. Группы endpoint-ов#

2.1. Poultry Climate#

  • 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

Минимальные фильтры list:

  • tenant_id, site_id, house_id, batch_id, age_phase, limit, offset.

Adapter-правила:

  • setpoint должен возвращать статус диспетчеризации в климат-контроллер;

  • telemetry принимает telemetry-контур (temp/rh/co2/nh3/ventilation) и возвращает оценку отклонений по активному профилю.

  • sensors/ingest принимает адаптерные показания датчиков среды (T/RH/pressure/gas) и нормализует их в общий telemetry payload.

2.2. Poultry Flock#

  • GET /api/v1/poultry-flock/scheme

  • GET /api/v1/poultry-flock/list

Примечание:

  • batch lifecycle команды для poultry-flock не входят в текущий runtime baseline и не публикуются в OpenAPI до отдельной реализации.

2.3. Poultry Feedwater#

  • GET /api/v1/poultry-feedwater/scheme

  • GET /api/v1/poultry-feedwater/list

  • POST /api/v1/poultry-feedwater/commands/ingest

2.4. Poultry Production#

  • GET /api/v1/poultry-production/scheme

  • GET /api/v1/poultry-production/list

  • POST /api/v1/poultry-production/commands/ingest

2.5. Poultry Alarms#

  • GET /api/v1/poultry-alarms/scheme

  • GET /api/v1/poultry-alarms/list

  • POST /api/v1/poultry-alarms/commands/publish

  • POST /api/v1/poultry-alarms/commands/ack

Обязательные поля alarm-события:

  • alarm_code, severity, priority, tenant_id, industry_code, site_id, house_id, correlation_id, timestamp.

3. Профили нормативов poultry#

  • GET /api/v1/poultry-profiles/scheme

  • GET /api/v1/poultry-profiles/list

  • POST /api/v1/poultry-profiles/commands/export-yaml

  • POST /api/v1/poultry-profiles/commands/import-yaml

  • POST /api/v1/poultry-profiles/commands/publish

  • POST /api/v1/poultry-profiles/commands/rollback

Правила:

  • версии draft/published/archived;

  • rollback как новый publish с rollback_of;

  • совместимость импорта по industry_code=poultry и equipment_profile.

4. Bridge в общий status#

Для severity=critical|high:

  • poultry alarm-bus публикует событие в status;

  • в обеих системах одинаковый correlation_id;

  • status хранит агрегат, poultry-контур хранит детали и эскалацию.

5. Минимальные схемы payload#

5.1. Пример POST /api/v1/poultry-climate/commands/setpoint#

{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "house_id": "house-1",
    "batch_id": "batch-2026-03",
    "age_phase": "broiler_day_8_14",
    "temperature_target_c": 29.0,
    "humidity_target_pct": 60,
    "ventilation_mode": "minimum",
    "reason": "phase_switch"
  }
}

5.2. Пример POST /api/v1/poultry-climate/commands/telemetry#

{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "house_id": "house-1",
    "batch_id": "batch-2026-03",
    "age_phase_id": "broiler-day-8-14",
    "source": "ctrl-climatepro",
    "temp_c": 34.7,
    "humidity_percent": 69.0,
    "co2_ppm": 2810,
    "nh3_ppm": 17.0,
    "ventilation_percent": 14.0
  }
}

5.3. Пример POST /api/v1/poultry-climate/sensors/commands/ingest#

{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "house_id": "house-1",
    "batch_id": "batch-2026-03",
    "source": "sensor-gateway-1",
    "readings": [
      { "sensor_type": "temperature_c", "device_id": "tmp-01", "value": 33.9, "unit": "C" },
      { "sensor_type": "humidity_percent", "device_id": "rh-01", "value": 67.1, "unit": "%" },
      { "sensor_type": "pressure_pa", "device_id": "prs-01", "value": 41, "unit": "Pa" },
      { "sensor_type": "co2_ppm", "device_id": "co2-01", "value": 2480, "unit": "ppm" },
      { "sensor_type": "nh3_ppm", "device_id": "nh3-01", "value": 11.4, "unit": "ppm" }
    ]
  }
}

5.4. Пример POST /api/v1/poultry-alarms/commands/publish#

{
  "item": {
    "tenant_id": "tenant-a",
    "industry_code": "poultry",
    "site_id": "site-a",
    "house_id": "house-1",
    "alarm_code": "poultry_temp_high",
    "severity": "critical",
    "priority": "P1",
    "title": "Температура выше порога",
    "message": "House-1: temp=34.1C > 33C",
    "correlation_id": "corr-20260305-001",
    "timestamp": "2026-03-05T13:20:00Z"
  }
}

6. План реализации (связка с tasks)#

  1. Реализовать scheme|list для 5 poultry-модулей.

  2. Добавить команды управления (setpoint, ack, batch lifecycle).

  3. Подключить профильный контур poultry-profiles/* с YAML/versioning/rollback.

  4. Добавить poultry alarm-bus и bridge в status.

  5. Зафиксировать contract tests по envelope/meta/error и correlation_id.

Содержание