# Архитектура

## 1. Модульная декомпозиция (D-005)

- `industry.melioration.field`
  - key entity: `field_water_balance`
- `industry.melioration.irrigation_machine`
  - key entity: `machine_irrigation_event`
- `industry.melioration.irrigation_drip`
  - key entity: `drip_irrigation_event`
- `industry.melioration.soil_moisture`
  - key entity: `soil_moisture_snapshot`
- `industry.melioration.weather`
  - key entity: `weather_observation`

Принцип D-002 соблюдается: один модуль — одна ключевая сущность, с допустимым обогащением через агрегаты.

## 2. Ключевые сущности

- `field` — поле/участок.
- `field_zone` — зона поля.
- `irrigation_campaign` — период полива.
- `water_source` — источник воды (`machine`, `drip_subsurface`, `rain`).
- `field_water_balance` — агрегированный водный баланс по полю/зоне.
- `soil_moisture_snapshot` — факт влажности почвы.
- `weather_observation` — факт метеопараметров.

Детализированная модель атрибутов и инвариантов вынесена в [data-model.md](data-model.md).

## 3. Поток данных и обогащение

1. `irrigation_machine` публикует события полива (объем/время/зона).
2. `irrigation_drip` публикует события капельного/внутрипочвенного полива.
3. `weather` публикует осадки и погодные параметры:
   - локальная станция как primary (D-008);
   - внешний сервис как fallback и для anomaly-check.
4. `soil_moisture` публикует снимки влажности по глубинам/зонам.
5. `field` агрегирует данные по источникам и строит `field_water_balance`:
   - сколько воды получено;
   - когда получено;
   - из какого источника получено.

## 4. Контур источников воды

Нормализованный источник для водного баланса:

- `machine` — широкозахватные дождевальные машины;
- `drip_subsurface` — капельное/внутрипочвенное орошение;
- `rain` — атмосферные осадки.

Для каждого источника хранить:

- `source_id`
- `source_type`
- `event_time`
- `volume_mm` (primary)
- `volume_m3` (derived from `volume_mm` и площади поля/зоны)
- `confidence`
- `origin` (`sensor`, `controller`, `external_weather_api`)

Правило D-008 для `rain`:

- `primary_reading` — значение локальной станции;
- `fallback_reading` — значение внешнего сервиса (используется при gap/timeout локального источника);
- `anomaly_flag` — признак значимого расхождения источников.

## 5. Интеграция с ядром

- API-подход: общий контракт `/api/v1/<resource>/list|scheme`.
- Модули подключаются через общий module manager.
- Права и сессии через общую auth/permission модель.
- Тревоги: D-004 (`status` + отраслевой alarm-bus).

## 6. Минимальные API-группы для MVP

- `/api/v1/melioration-field/*`
- `/api/v1/melioration-alerts/*`
- `/api/v1/melioration-irrigation-machine/*`
- `/api/v1/melioration-irrigation-drip/*`
- `/api/v1/melioration-soil-moisture/*`
- `/api/v1/melioration-weather/*`
- `/api/v1/melioration-control-mode/*`

Для каждой группы обязателен `list/scheme` контракт.

Для интеграционных контуров MVP дополнительно поддерживаются:
- `POST /api/v1/melioration-irrigation-machine/commands/ingest`
- `POST /api/v1/melioration-irrigation-drip/commands/ingest`
- `POST /api/v1/melioration-soil-moisture/commands/ingest`
- `POST /api/v1/melioration-weather/commands/ingest`
- `POST /api/v1/melioration-weather/commands/telemetry` (health/fallback policy D-008)

`/api/v1/melioration-alerts/list` рассчитывает и возвращает тревоги:
- `water_deficit` (дефицит влаги),
- `overwatering` (переувлажнение),
по агрегату `field_water_balance` + последнему `soil_moisture_snapshot`.

## 6.1. Режим управления поливом (D-009)

- `A` (`advisory-only`): система выдает рекомендации, запуск полива выполняет оператор.
- `B` (`semi-auto`, default MVP): система формирует действия, оператор подтверждает запуск.
- `C` (`full-auto`): система запускает сценарии автоматически по правилам.

Правила переключения:

- режим хранится в конфигурации площадки/хозяйства и может быть переопределен для поля;
- каждое переключение требует аудита (`who/when/from/to/reason`);
- для режима `C` обязательны валидные правила, актуальная телеметрия и корректное состояние источников.

Правило отказобезопасности:

- при потере критичных данных (`weather`, `soil`, `irrigation telemetry`) система выполняет деградацию `C -> B` (или `A` по policy) и формирует событие в alarm/status контуры.
- endpoint `POST /api/v1/melioration-weather/commands/telemetry` поддерживает `fallback_mode` и возвращает `auto_degraded=true`, если деградация была применена автоматически.

## 7. KPI и операционные метрики

- фактический водный баланс по полю/зоне (сутки/неделя/цикл);
- доля воды по источникам (`machine`, `drip_subsurface`, `rain`);
- расхождение «план полива vs факт»;
- отклонения влажности почвы от целевого диапазона;
- прогноз дефицита влаги с учетом прогноза погоды.
- тревоги дефицита/переувлажнения с severity/priority для alarm-контура.

## 8. Риски и меры

- Риск: конфликты единиц измерения из разных источников.
  - Мера: dual-модель D-007 (`mm` primary + `m3` derived) и единая формула пересчета через площадь.
- Риск: рассинхрон времени между контроллерами и weather API.
  - Мера: обязательный `event_time_utc` и окно дедупликации.
- Риск: двойной учет осадков и искусственного полива.
  - Мера: source-tagging и reconciliation правила в `field` модуле.
- Риск: расхождение осадков между локальной станцией и внешним сервисом.
  - Мера: D-008 policy (station primary, service fallback, anomaly control).