# Open-source Studio

Dashboard Studio предоставляет опцию с открытым исходным кодом (лицензия MPL-2.0) для технических команд, которым требуется настройка фронтенда за пределами стандартной конфигурации. Модифицируйте пользовательский интерфейс, интегрируйте с существующими приложениями или внедряйте собственные дизайн-системы, сохраняя при этом полные аналитические возможности.

### Сценарии использования

Обычные сценарии, когда подход с открытым исходным кодом может быть полезен:

* Пользовательский брендинг и интеграция дизайн-системы
* Специализированные отраслевые UI-рабочие процессы
* Встраиваемая аналитика в проприетарные приложения
* White-label реализации для партнёров

### Требования

| Компонент              | Требование                                                        |
| ---------------------- | ----------------------------------------------------------------- |
| **Доступ к IoT Query** | Активный экземпляр с действительными учетными данными базы данных |
| **Аутентификация**     | JWT-токен от Navixy Authentication Gateway                        |
| **Среда разработки**   | Node.js 18+, npm, Git                                             |
| **Технические навыки** | React, TypeScript, PostgreSQL, современная веб‑разработка         |

{% hint style="info" %}
См. [App Connect](https://app.gitbook.com/s/6dtcPLayxXVB2qaaiuIL/user-api/backend-api/resources/commons/user/applications/app-connect) в нашей документации для разработчиков для деталей реализации аутентификации.
{% endhint %}

## Компоненты с открытым исходным кодом

Реализация Dashboard Studio с открытым исходным кодом состоит из трёх основных компонентов:

### Репозиторий на GitHub

**Расположение:** <https://github.com/SquareGPS/navixy-iot-query-dashboard>

Репозиторий содержит полный React‑фронтенд, Node.js‑бэкенд-сервисы, файлы конфигурации и подробную документацию. Клонируйте репозиторий для локальной разработки или чтобы изучить архитектуру перед внедрением.

### npm‑пакет

Оптимизированное распространение для интеграции в JavaScript‑проекты. Пакет повторяет кодовую базу на GitHub с обычным рабочим процессом установки через npm. См. репозиторий [README](https://github.com/SquareGPS/navixy-iot-query-dashboard?tab=readme-ov-file#navixy-iot-query-dashboard) для инструкций по установке и версионированию.

### Шлюз аутентификации

Генерация JWT‑токена через Navixy authentication gateway. Бэкенд прозрачно обрабатывает управление сессиями. См., [App Connect](https://app.gitbook.com/s/6dtcPLayxXVB2qaaiuIL/user-api/backend-api/resources/commons/user/applications/app-connect) в нашей документации для разработчиков для деталей реализации.

## Начало работы

**Шаги настройки:**

1. Изучите репозиторий [README](https://github.com/SquareGPS/navixy-iot-query-dashboard)
2. Убедитесь, что у вас есть активный доступ к IoT Query&#x20;
3. Установите Node.js 18+ и npm
4. Следуйте [Quick Start guide](https://github.com/SquareGPS/navixy-iot-query-dashboard) для локального развертывания
5. Изучите [документацию по архитектуре](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/ARCHITECTURE.md) перед кастомизацией

### Документация в репозитории

Репозиторий включает подробные руководства по работе с кодовой базой:

| Документ                                                                                                      | Содержание                                                                 |
| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [**ARCHITECTURE.md**](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/ARCHITECTURE.md) | Проектирование системы, структура компонентов, поток данных                |
| [**DEVELOPMENT.md**](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/DEVELOPMENT.md)   | Локальная настройка, стандарты кодирования, тестирование, рабочие процессы |
| [**API.md**](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/API.md)                   | Бэкенд‑эндпоинты, форматы запросов/ответов, аутентификация                 |
| [**DEPLOYMENT.md**](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/DEPLOYMENT.md)     | Хостинг в продакшене для различных окружений                               |

Все файлы документации находятся в папке [`/docs`](https://github.com/SquareGPS/navixy-iot-query-dashboard/tree/main/docs) репозитория. В кодовой базе повсеместно используется TypeScript для типобезопасности и ясных интерфейсов компонентов.

### Варианты кастомизации

Реализация с открытым исходным кодом предоставляет полный доступ к фронтенду для модификаций:

{% columns %}
{% column %}
**UI и дизайн**

* Библиотека компонентов (цвета, типографика, отступы, UI‑паттерны)
* Интеграция пользовательской дизайн‑системы
* Изменения тем

**Редактор дашбордов**

* Пользовательские алгоритмы расположения
* Альтернативные методы расположения панелей
* Упрощённые рабочие процессы для конкретных групп пользователей
  {% endcolumn %}

{% column %}
**Визуализации**

* Заменяйте существующие компонентные графики на собственные
* Добавляйте новые типы визуализаций
* Изменяйте поведение отрисовки графиков

**Интеграция**

* Реализация единого входа (SSO)
* Общая навигация с существующими приложениями
* Встраиваемые представления аналитики
  {% endcolumn %}
  {% endcolumns %}

Изучите [`ARCHITECTURE.md`](https://github.com/SquareGPS/navixy-iot-query-dashboard/blob/main/docs/ARCHITECTURE.md) файл в репозитории перед существенными изменениями, чтобы понять взаимосвязи компонентов и необходимые изменения.

### Паритет функций со стандартной версией

Открытая реализация Dashboard Studio поддерживает полный паритет функций с версией, размещённой Navixy:

| Функция                                               | С открытым исходным кодом | Стандартная |
| ----------------------------------------------------- | ------------------------- | ----------- |
| Редактор дашбордов (перетаскивание, панели, строки)   | ✓                         | ✓           |
| Выполнение SQL (безопасность, тайм‑ауты, кэширование) | ✓                         | ✓           |
| Визуализации (столбчатые, круговые, таблица, stat)    | ✓                         | ✓           |
| Организация меню (разделы, изменение порядка)         | ✓                         | ✓           |
| Обновления и новые функции                            | ✓                         | ✓           |

Репозиторий регулярно получает обновления, согласованные с выпусками размещённой версии. Новые типы визуализаций, возможности редактора и улучшения производительности появляются одновременно в обеих моделях развертывания.

### Модель поддержки и сопровождения

| Ответственность                  | Ваша команда | Navixy |
| -------------------------------- | ------------ | ------ |
| Обновления ядра Dashboard Studio |              | ✓      |
| Патчи безопасности               |              | ✓      |
| Совместимость с IoT Query API    |              | ✓      |
| Обновления документации          |              | ✓      |
| Поддержка пользовательского кода | ✓            |        |
| Инфраструктура развертывания     | ✓            |        |
| Синхронизация с апстримом        | ✓            |        |
| Тестирование после обновлений    | ✓            |        |

Отслеживайте репозиторий на предмет релизов, содержащих исправления ошибок, патчи безопасности и новые функции. Тестируйте свои кастомизации после обновлений перед развертыванием в продакшен.

{% hint style="info" %}

### Поддержка и помощь

Для технической поддержки и помощи по IoT Query свяжитесь с нашей службой поддержки по адресу <iotquery@navixy.com>.
{% endhint %}