# 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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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`.