Dashboards (BI)

Сервис бизнес-аналитики (BI) и интерактивных визуализаций данных: создание дашбордов организации и пространств, настраиваемая Grafana-подобная сетка (24 колонки) на базе angular-gridster2, изолированные iframe-виджеты с безопасным обменом данными через @leggnom/data-bridge, выполнение параметризованных запросов JSON QuerySpec к физическим таблицам Data Tables (и наборам данных Data Catalog), а также расширяемость через защищенные .usint пакеты виджетов.

Порты

Порт	Назначение
8113	HTTP REST (PM2 dev)
18113	Docker host

• БД: dashboards_db (PostgreSQL)
• Gateway: /proxy/dashboards/...

Архитектура и поток данных

1. Дашборды могут иметь область видимости org (общие для организации, space_id IS NULL, секция dashboards) или space (внутри пространства, space_id, секция space_dashboards).
2. Каждый дашборд содержит панели с координатами сетки {x, y, w, h}, источником данных (data_table или data_catalog), спецификацией запроса QuerySpec и визуальными параметрами visual.
3. Виджеты загружаются внутри песочницы <iframe> (sandbox allow-scripts allow-forms).
4. Вся коммуникация между хостом Angular и iframe виджета осуществляется через протокол @leggnom/data-bridge:
   • Хост отправляет событие init с конфигурацией visual, locale, theme и query.
   • Виджет отправляет событие query с возможным фильтром/оверлеем.
   • Хост запрашивает бэкенд POST /api/v1/panels/:id/query или POST /api/v1/query/preview.
   • Бэкенд валидирует параметры, выполняет безопасный параметризованный SQL к таблице Data Tables и возвращает нормализованный QueryResult.

JSON QuerySpec контракт

Запрос от виджета/панели описывается безопасной структурой без произвольного SQL:

{
  "select": [
    { "field": "category" },
    { "field": "amount", "agg": "sum", "as": "total" }
  ],
  "filters": [
    { "field": "status", "op": "eq", "value": "paid" }
  ],
  "filter_mode": "and",
  "group_by": ["category"],
  "order_by": [
    { "field": "total", "dir": "desc" }
  ],
  "limit": 1000,
  "offset": 0
}

Поддерживаемые операции

• Агрегации (agg): sum, avg, min, max, count, count_distinct.
• Операторы фильтрации (op): eq, ne, gt, gte, lt, lte, contains, in, is_null, is_not_null.

Формат ответа (QueryResult)

{
  "columns": [
    { "name": "category", "type": "string" },
    { "name": "total", "type": "number" }
  ],
  "rows": [
    ["Электроника", 125000],
    ["Мебель", 45000]
  ],
  "row_count": 2,
  "truncated": false
}

API

Метод	Путь	Описание
GET	/api/v1/dashboards	Список дашбордов (scope, space_id)
POST	/api/v1/dashboards	Создание дашборда
GET	/api/v1/dashboards/:id	Получение дашборда и его панелей
PATCH	/api/v1/dashboards/:id	Обновление дашборда
DELETE	/api/v1/dashboards/:id	Удаление дашборда
GET	/api/v1/dashboards/:id/panels	Список панелей дашборда
POST	/api/v1/dashboards/:id/panels	Создание панели
GET	/api/v1/panels/:id	Получение панели
PATCH	/api/v1/panels/:id	Обновление координат сетки/запроса/оформления панели
DELETE	/api/v1/panels/:id	Удаление панели
POST	/api/v1/panels/:id/query	Выполнение запроса панели с объединением фильтров
POST	/api/v1/query/preview	Предпросмотр выполнения запроса по источнику
GET	/api/v1/widgets	Список доступных виджетов
GET	/api/v1/widgets/:slug	Информация о виджете
GET	/api/v1/widgets/:slug/files/*filepath	Раздача статических файлов виджета
GET	/api/v1/widget-packs	Список установленных пакетов виджетов
POST	/api/v1/widget-packs/import	Импорт пакета виджетов (.usint или .zip)
DELETE	/api/v1/widget-packs/:id	Удаление пакета виджетов

Пакеты виджетов (.usint)

Пакеты виджетов упаковываются по стандарту USINT1 (AES-GCM шифрование с ключом INTEGRATION_PACK_KEY):

• Максимальный размер пакета: 32 MiB.
• В составе пакета: manifest.yaml (описание пакета, виджетов, схем visual_schema и подсказок query_hints) и каталоги виджетов со статическими файлами (index.html, скрипты, стили).
• CLI-утилита сервиса:

  # Запаковать директорию с виджетами в .usint
  ./bin/cli pack seal packs/pack-core-charts -o pack-core-charts.usint
  
  # Проверить содержимое запечатанного пакета
  ./bin/cli pack open pack-core-charts.usint

SDK разработчика виджетов

Для создания кастомных виджетов используется npm-библиотека @leggnom/unishift-widget (в репозитории libs/unishift-widget):

• Автоматически настраивает двусторонний мост через @leggnom/data-bridge.
• Предоставляет строгие TypeScript-типы для QuerySpec, QueryResult, VisualSchema.
• Включает готовый стартовый шаблон на Vite (templates/vite-widget).

Переменные окружения

Переменная	По умолчанию	Описание
PORT	8113	HTTP порт сервиса
DB_NAME	dashboards_db	Имя базы данных
INTEGRATION_PACK_KEY	-	Ключ шифрования AES-GCM для .usint пакетов
SPACES_SERVICE_URL	http://localhost:8092	URL сервиса Spaces для проверки доступа
DATA_TABLES_SERVICE_URL	http://localhost:8105	URL сервиса Data Tables для выполнения запросов
DATA_CATALOG_SERVICE_URL	http://localhost:8109	URL сервиса Data Catalog
ASSETS_DIR	./data/widgets	Директория распакованных статических файлов виджетов