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

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

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.

Содержание