# API

Документ фиксирует целевой MVP backend API для swine-модулей в формате `scheme|list` + ingest/commands.

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

- Префикс: `/api/v1`
- Envelope: `item/list + meta.request_id/meta.timestamp`
- Изоляция: `tenant_id`, `industry_code=swine`, `site_id`, `house_id` (или `barn_id`)
- Пагинация list: `limit`, `offset`

## 2. Модули и endpoint-ы

### 2.1. Swine Climate

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

List-фильтры:
- `q`, `house_id`, `batch_id`, `age_phase_id`, `subtype`, `state`, `current_age_days`, `age_mode`

### 2.2. Swine Feeding

- `GET /api/v1/swine-feeding/scheme`
- `GET /api/v1/swine-feeding/list`
- `POST /api/v1/swine-feeding/commands/ingest`

List-фильтры:
- `q`, `house_id`, `batch_id`, `group_id`, `phase_id`, `status`

### 2.3. Swine Water

- `GET /api/v1/swine-water/scheme`
- `GET /api/v1/swine-water/list`
- `POST /api/v1/swine-water/commands/ingest`

List-фильтры:
- `q`, `house_id`, `batch_id`, `line_id`, `status`

### 2.4. Swine Production

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

List/KPI-фильтры:
- `q`, `house_id`, `batch_id`, `metric_date`, `window_days`, `subtype`

### 2.5. Swine Biosecurity

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

List-фильтры:
- `q`, `site_id`, `zone_id`, `event_code`, `severity`, `status`

## 3. Ingest-контуры (целевой baseline)

### 3.1. Climate telemetry contour

- Источники:
  - контроллер микроклимата (`swine-bigfarmnet-climatepro-v1`)
  - sensor gateway fallback
- Поток:
  1. `POST /swine-climate/telemetry` (controller primary)
  2. `POST /swine-climate/sensors/ingest` (fallback/secondary)
  3. диагностические флаги и bridge критических событий в `status`

### 3.2. Feed/Water counters contour

- Источники:
  - feed/water gateway
  - ручной fallback input
- Поток:
  1. `POST /swine-feeding/ingest`
  2. `POST /swine-water/ingest`
  3. расчет `deviation_pct` и `status=ok|warn|alarm`

### 3.3. Production & biosecurity contour

- Источники:
  - production batch snapshots
  - biosecurity external service
- Поток:
  1. `POST /swine-production/ingest`
  2. `POST /swine-biosecurity/ingest`
  3. агрегаты KPI (`GET /swine-production/kpi`) и тревоги P1/P2

## 4. Примеры payload

### 4.1. `POST /api/v1/swine-climate/commands/telemetry`

```json
{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "house_id": "barn-02",
    "batch_id": "batch-swine-2026-03",
    "temp_c": 24.8,
    "humidity_percent": 67.1,
    "co2_ppm": 2100,
    "nh3_ppm": 8.2,
    "timestamp": "2026-03-06T00:10:00Z"
  }
}
```

### 4.2. `POST /api/v1/swine-water/commands/ingest`

```json
{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "house_id": "barn-02",
    "batch_id": "batch-swine-2026-03",
    "water_l_per_head_day": 6.4,
    "pressure_kpa": 180,
    "source": "swine-feedwater-gateway-v1",
    "timestamp": "2026-03-06T00:15:00Z"
  }
}
```

### 4.3. `POST /api/v1/swine-biosecurity/commands/ingest`

```json
{
  "item": {
    "tenant_id": "tenant-a",
    "site_id": "site-a",
    "zone_id": "zone-quarantine-1",
    "event_code": "ppe_violation",
    "severity": "high",
    "comment": "door opened without sanitization",
    "timestamp": "2026-03-06T00:17:00Z"
  }
}
```