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

## 1. Отраслевая декомпозиция модулей

Рекомендуемый состав модулей:

- `industry.poultry.climate`
- `industry.poultry.flock`
- `industry.poultry.feedwater`
- `industry.poultry.production`
- `industry.poultry.alarms`

Принцип D-002:

- модульный набор включается выборочно по площадке;
- каждый модуль имеет одну ключевую сущность;
- обогащение других модулей допускается через агрегаты.

## 2. Сущности отрасли

- `house` — птичник.
- `batch` — партия/цикл выращивания.
- `age_phase` — стадия по возрасту.
- `climate_profile` — профиль уставок микроклимата.
- `feed_program` — программа кормления.
- `water_profile` — профиль водопотребления.
- `production_kpi` — отраслевые KPI (бройлер/несушка).
- `alarm_rule` / `alarm_event` — правила и события тревог.

Детальный core-модельный срез (`house`, `batch`, `age_phase`, `climate_profile`) вынесен в [data-model-core.md](data-model-core.md).
Операционный срез (`feed_program`, `water_profile`, `production_kpi`) вынесен в [data-model-operations.md](data-model-operations.md).
Тревожный срез (`alarm_rule`, `alarm_event`) вынесен в [data-model-alarms.md](data-model-alarms.md).

### 2.1. Key entity по модулям

- `industry.poultry.climate` -> `climate_profile`
- `industry.poultry.flock` -> `batch`
- `industry.poultry.feedwater` -> `feed_program`
- `industry.poultry.production` -> `production_kpi`
- `industry.poultry.alarms` -> `alarm_event`

## 3. Поток управления

1. По `batch` и `age_phase` выбирается активный `climate_profile`.
2. Профиль формирует setpoints для температуры/влажности/вентиляции.
3. Контроллерный контур принимает уставки и публикует telemetry.
4. `industry.poultry.alarms` сравнивает telemetry с нормами и создает события.
5. KPI-контуры обновляют техпроцессную аналитику и задачи оператору.

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

### 4.1. Общие контракты

- все данные через общий API-style (`/api/v1/<resource>/list|scheme`);
- все модули регистрируются в общем module manager;
- для каждого poultry-модуля в каталоге зафиксированы `database.migrations` и `database.tables`;
- auth/permissions берутся из общего контура.

### 4.2. Расширение без ломки ядра

- poultry-модули добавляют новые ресурсы, не меняя существующие core-endpoint-ы;
- отраслевые поля выносятся в namespace ресурсов poultry;
- общие модули (`status`, `tasks`, `charts`) получают poultry-представления через filter/context.

## 5. Контуры мониторинга и тревог

Принятое D-004:

- используется общий `status` + отдельный `industry.poultry.alarms` bus;
- критические poultry-события дублируются в `status` агрегированным событием;
- детальный разбор причин, маршрутизация и история эскалаций остаются в poultry-контуре.

### 5.1. Критические сигналы

- высокая/низкая температура;
- потеря/недостаточность вентиляции;
- выход влажности за допуски;
- пожар/авария питания;
- отклонения по водопотреблению и корму.

### 5.2. Политика эскалации

- `P1` — немедленная эскалация (operator + engineer);
- `P2` — операторский SLA-контур;
- `P3` — аналитический контур и плановые коррекции.

### 5.3. Синхронизация с `status`

- каждое критическое событие poultry содержит `correlation_id`;
- в `status` публикуется унифицированная запись с тем же `correlation_id`;
- карточка `status` ссылается на детализацию в `industry.poultry.alarms`.

## 6. Подтипы профилей

- `poultry.broiler`: акцент на темп роста, FCR, сохранность.
- `poultry.layer`: акцент на яйценоскость, массу/качество яйца, световые программы.

## 6.1. Нормативные профили poultry (D-003)

- Профили poultry хранятся как конфигурации и не вшиваются в код.
- Поддерживаются перенос и тиражирование между хозяйствами через `YAML`.
- Для каждого профиля ведется версия и журнал изменений.
- Откат к предыдущей версии обязателен для climate/feedwater/production нормативов.
- Структура версии (`version_id`, `state`, `change_note`, `rollback_of`) вынесена в [data-model-versioning.md](data-model-versioning.md).

## 7. Требования к API для poultry-MVP

Минимальные endpoint-группы:

- `/api/v1/poultry-climate/*`
- `/api/v1/poultry-flock/*`
- `/api/v1/poultry-feedwater/*`
- `/api/v1/poultry-production/*`
- `/api/v1/poultry-alarms/*`

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

См. детализацию:
- `norms-kpi.md` — нормативы и обязательные KPI.
- `mvp-api.md` — MVP API-контракт и команды.