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

## 1. Архитектурная модель

`ioot-pro-cabinet` реализует каркас **Master Cloud Layer** для платформы Green Robot/IOOT PRO и ориентирован на конфигурационный, backend-driven UI.

### 1.1. Логические уровни (по базовой модели green-robot)

1. **Field Device Layer (IOOT PRO устройства)**  
   AT32/ESP32 блоки с обменом PDO/SDO, преобразованием и transport-частью.

2. **Local Controller Layer (локальный контроллер объекта)**  
   Локальный исполнительный/супервизорный контур с CANopen, local broker и локальными сервисами.

3. **Tenant Cloud Layer (контур клиента)**  
   Облако клиента: приём телеметрии, агрегирование данных, команды, конфигурации, обновления, PostgreSQL.

4. **Master Cloud Layer (контур управления парком)**  
   Многоклиентский уровень: подписки, политикеы, глобальные аналитические и синхронные механизмы.

5. **Client Applications Layer (клиентские UI)**  
   Веб-интерфейс с карточным модульным shell и адаптивным (mobile-first) подходом.

## 1.2. Что сейчас реализовано в коде

- **Master Cloud Layer (каркас):**
  - `backend-go/internal/api` — HTTP роутинг и базовые endpointы.
  - `backend-go/internal/api/plugins/<module>/plugin.go` — plugin-style обработчики backend для каждого модуля.
  - `backend-go/internal/modules` — модульный реестр (metadata + зависимости + install state).
  - `backend-go/internal/modules/catalog/<module>/definition.go` — описание каждого backend-модуля в своей директории.
  - `backend-go/internal/app` — загрузка конфигурации (`yaml` + env).
  - `backend-go/cmd/server/main.go` — точка запуска API сервера.
- **Client Applications Layer (каркас):**
  - `frontend-vue/src/App.vue` — shell приложения и базовые карточки.
  - `frontend-vue/src/modules/<module>/manifest.js` — описание frontend-модуля в своей директории.
  - `frontend-vue/src/modules/registry.js` — сборка frontend-реестра модулей и порядка карточек.
  - `frontend-vue/src/styles.css` — единый UI-стиль.
- **Инфраструктурный каркас:**
  - `docker-compose.yml` — PostgreSQL + NanoMQ + backend.
  - `scripts/dev.sh`, `scripts/docker.sh`.

## 1.3. Каркас данных и сервисов (желаемая логика)

1. Конфигурационный/контекстный старт
   - backend-driven catalog (`modules/scheme`) определяет доступные модули.
   - UI выбирает `module_view`, `display_module`, `show_filters`.

2. Модульная логика backend
   - API ресурсы формируют схему (`GET /api/v1/<resource>/scheme`) и данные (`GET /api/v1/<resource>/list`).

3. Реактивная выдача и управление
   - live-потоки через WebSocket/MQTT для статусов и событий.

4. Master-level интеграции
   - ограниченный обмен служебными данными tenant<->master;
   - отдельные контуры подписок/политик/обновлений.

## 1.4. Коммуникационный слой

- **HTTP REST** — синхронные операции и конфигурирование.
- **WebSocket/MQTT** — телеметрия, статусы и события.
- **Swagger/OpenAPI** — источник истины по контрактам.
- **Контекстные заголовки** для маршрутизации и трассировки:
  - `X-Route-Path`
  - `X-Route-Module`
  - `X-Route-Filter`
  - `X-Client-Version`
  - `X-Client-Build-Time`

## 1.5. Разделение стеков (синхронизировано с green-robot)

- Backend: **Go**
- Database: **PostgreSQL**
- Message broker: **NanoMQ** (в составе docker-compose)
- Frontend: **Vue 3** (в текущем проекте; в базовой green-robot-архитектуре указан Vue 2+TypeScript как целевой стек)

## 1.6. Scope текущего этапа

- Закрыт каркас уровней и контрактов API.
- Введен модульный runtime-реестр (`backend-go/internal/modules`) с install/uninstall.
- Каждый модуль описывает оба контура:
  - `frontend` (dashboard block/component),
  - `backend` (набор API routes),
  - `database` (миграции и таблицы),
  - `permissions` (role/resource/actions).
- Production runtime использует shared persistence/migration layer (`postgres|sqlite`) для `modules/auth/site-policy/status`, а `modules_state_path` остается только legacy import path для совместимости с прежними JSON sidecar-файлами.
- UI-состав дашборда синхронизируется с установленными модулями.
- Введены read-only контуры модели БД и прав:
  - `GET /api/v1/modules/database/list`
  - `GET /api/v1/modules/permissions/list`
- Не реализованы пока:
  - production-grade domain services (`tenant-master sync`, `analytics`, `policy updates` как отдельные сервисы);
  - PWA/offline и специализированные отраслевые сценарии.

- Реализован security-контур JWT + RBAC:
  - JWT (HMAC-SHA256) принимается через HttpOnly cookie и `Authorization: Bearer`;
  - middleware применяет role/scope гварды для master/tenant endpoint-групп;
  - tenant scope принудительно применяется для `industry-*`, `melioration-*`, `poultry-*`, `swine-*`;
  - для tenant scope включена boundary-проверка `tenant_id` / `target_tenant_id` в query и JSON body.
  - добавлена вычисляемая permission matrix (`/api/v1/auth/permissions/scheme|list`) для UI/API операций.
  - добавлен security-log (`/api/v1/auth/security-log/scheme|list`) для событий auth/action (`allow|deny`).

- Реализован operability/release-ready контур:
  - публичные probes `/health`, `/live`, `/ready`;
  - диагностический runtime snapshot по shared persistence, migrations, зависимостям и состоянию модулей;
  - локальный quality gate (`ci-local`, smoke, release-checklist);
  - deployment package, production runbook и release gate.

## 1.7. Отраслевые контуры

- Добавлен отдельный документационный каркас `docs/industries` для изолированных отраслевых пакетов.
- Каждый отраслевой пакет использует общие контракты ядра, но имеет собственные:
  - архитектуру;
  - backlog задач;
  - KPI/alarms профили;
  - интеграционные адаптеры оборудования.
- Первый пакет: `docs/industries/poultry` (на базе источников `../poultry-module`).
- В runtime добавлен `industry dispatcher` с режимами:
  - `cloud-multi` — поддержка выбора отрасли;
  - `edge-single` — фиксированная отрасль на инсталляцию.
- Для `poultry` frontend использует единый workspace:
  - `cloud/tenant` — overview dashboard с KPI summary и переходом в submodule details;
  - `edge-single` — fullscreen cards-dashboard для 10" HMI с теми же KPI и быстрым переходом в submodule details;
  - при отсутствии явного route/module-контекста `edge-single` открывает poultry workspace как primary fullscreen-экран.
- Добавлен endpoint `GET /api/v1/app/context` для bootstrap-контекста (deployment mode, active industry, feature flags, user scope).
- `app/context` возвращает runtime policy snapshot (`permissions.ui/api`, `capabilities`, `guards`) и используется как source-of-truth для UI/API guard-слоя (`tenant/master`, `role`, `feature_flags`), включая capability-флаги `sidebar_menu` и `sidebar_menu_update`.
- `modules/scheme` дополнен `catalog_enrichment` и используется shell-runtime для связки `Sidebar -> Content -> Infobar`.
- Shell поддерживает отдельный UI-access ресурс `ui.sidebar.menu`: доступ к burger-меню и его редактированию определяется role-based UI policy, а выход вынесен в topbar и остается доступным вне burger-контура.
- Порядок модулей синхронизируется между dashboard и burger-меню через общий drag-and-drop layout persistence; быстрые fullscreen-кнопки рядом с burger формируются из закрепленных модулей sidebar.
- Пользовательские shell-настройки (`theme`, `dashboard_layout`, `quick_module_ids`) сохраняются через backend `auth/ui-preferences` с изоляцией по `tenant/site/industry` и shared persistence layer; локальный `localStorage` используется только как fallback-кеш в degraded/offline режиме.
- Shell profile вынесен в отдельный versioned runtime-контур `auth/shell-profile`: доступны `list`, `export`, `import`, `rollback` для снапшотов `theme/layout/quick modules/ui-access` по ключу `tenant/site/industry`, backend source-of-truth хранится в shared SQL persistence.
- Для pilot-контура подготовлены preset-артефакты `cloud-multi` и `edge-single`; shell acceptance smoke выделен в отдельный сценарий и включен в release/smoke pipeline reference runtime.
- В reference runtime теперь присутствуют pilot process-артефакты: bootstrap-package (`scripts/pilot-bootstrap.py`), evidence bundle (`scripts/pilot-evidence-bundle.py`), rollback/restore drill (`scripts/pilot-rollback-drill.py`) и единый sign-off bundle (`scripts/pilot-signoff.py`), использующие существующие API `app/context`, `modules/list`, `modules/site-policy/*`, `auth/shell-profile/*`, `auth/security-log/*`.
- Для pilot-артефактов введен внешний retention storage (`scripts/pilot-artifact-retention.py`) с `archive-root`, `index.json` и `record.json`.
- Для pilot observability добавлен нормализованный summary endpoint `GET /api/v1/operability/pilot-summary` и alerting CLI `scripts/pilot-observability-check.py`.
- Для перехода `pilot -> production` добавлен формальный gate `scripts/pilot-promotion-check.py`, а для multi-site эксплуатации — `scripts/fleet-rollout-registry.py`, `scripts/incident-handover-package.py` и `scripts/package-immutability-check.py`.
- Клиент `status/stream` работает в resilient-режиме: WebSocket reconnect/backoff и fallback на HTTP polling при разрыве realtime-канала.
- Для отрасли `melioration` реализованы API-контуры:
  - `scheme|list` для `field/irrigation-machine/irrigation-drip/soil-moisture/weather/control-mode`;
  - ingest-маршруты `machine/drip/soil/weather` и `weather/telemetry`.
- `melioration-field` рассчитывает агрегированный водный баланс по источникам и времени (`mm` primary, `m3` derived) с D-008 policy (`station primary`, `service fallback`).
- Добавлен `profile-service` для отраслевых нормативов (`/api/v1/industry-profiles/*`): YAML import/export, versioning и rollback профилей между хозяйствами.
- Добавлен отраслевой `industry alarm-bus` (`/api/v1/industry-alarms/*`) и bridge в `status` для критичных/высоких тревог с передачей `correlation_id`.
- В отраслевых API формализованы ключи изоляции `tenant_id / industry_code / site_id` для фильтрации и трассировки данных.
- В `modules/permissions` добавлены отраслевые границы обновления прав по `industry_code` (policy conflict при попытке update вне выбранной отрасли).
- Добавлен `modules/site-policy` контур частичной активации модулей на уровне `site` с фильтрацией выдачи модулей/прав/DB-модели по `site_id`; policy сохраняется в shared SQL persistence, а не в transient runtime store.