Архитектура

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

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.

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).

Содержание