🔮 BI Magic Resources

Русский | English

Набор инструментов для разработки и сопровождения проектов на базе платформы Luxms BI. Позволяет создавать кастомные визуализации, стилизовать интерфейс, хранить и редактировать конфигурации дэшлетов, дэшбордов и кубов.

Код и ресурсы проекта хранятся в Git с историей версий, что упрощает параллельную разработку и координацию работы команды. С помощью встроенных скриптов можно запускать проект локально, проверять изменения и синхронизировать ресурсы с удалёнными BI-серверами.

Выбирайте базовую ветку в соответствии с версией вашего BI-сервера:

Ветка	Версия Luxms BI	Версия React
`master`	v12	19.0.0
`master-v11`	v11	18.2.0

⚡ Быстрый старт

1. Подготовьте окружение

Понадобятся Git, Node.js, Yarn и доступ к BI-серверу с правами на нужные ресурсы. Склонируйте репозиторий и установите зависимости:

git clone --branch master git@github.com:luxms/bi-magic-resources.git
cd bi-magic-resources
yarn install

Для BI версии 11 замените --branch master на --branch master-v11.

2. Настройте конфиг

В config.json замените адрес сервера и ds_my_project на схему вашего проекта:

{
  "server": "https://bi.example.com",
  "port": 3003,
  "include": "^ds_my_project$",
  "resources": true,
  "dashboards": false,
  "cubes": false
}

По умолчанию локально обрабатываются только ресурсы. Для работы с конфигурациями дэшбордов и дэшлетов включите dashboards; для кубов — cubes. Подробную информацию обо всех ключах смотрите в разделе «Конфигурация».

3. Настройте доступ

Создайте в корне файл authConfig.json и укажите логин и пароль для входа в систему:

{
  "username": "<логин>",
  "password": "<пароль>"
}

Доступны также другие способы входа. Подробнее в разделе «Авторизация».

4. Загрузите ресурсы и запустите проект

yarn pull --no-remove
yarn start

Откройте http://localhost:3003, редактируйте файлы в src и проверяйте результат в браузере.

🪄 Команды

Команда	Описание
`yarn start`	Запустить сервер локальной разработки
`yarn _pull`	Синхронизировать BI-сервер с `dist`, не меняя `src`
`yarn pull`	Выполнить `_pull` и восстановить исходники в `src`
`yarn build`	Собрать исходники из `src` в папку `dist`
`yarn _push`	Синхронизировать `dist` с BI-сервером без сборки
`yarn push`	Собрать проект и синхронизировать `dist` с BI-сервером
`yarn test`	Запустить тесты
`yarn create-topic`	Создать конфигурацию темы локально
`yarn create-dashboard`	Создать конфигурацию дэшборда локально
`yarn create-dashlet`	Создать конфигурацию дэшлета локально

Команды создания конфигураций получают идентификаторы с BI-сервера, поэтому требуют авторизации и доступа к выбранной схеме.

Схема показывает путь файлов при сборке и синхронизации: от исходников в src через готовые ресурсы в dist до BI-сервера и обратно.

flowchart LR
  SRC["src<br/>Редактируемые исходники"]
  DIST["dist<br/>Готовые файлы для сервера"]
  BI["Luxms BI<br/>Ресурсы на сервере"]
  SRC -->|"push: сборка"| DIST
  DIST -->|"push: отправка"| BI
  BI -->|"pull: загрузка"| DIST
  DIST -->|"pull: восстановление"| SRC

📋 Рабочий процесс

Ниже описан базовый сценарий работы с проектом — от обновления до проверки изменений и публикации на сервере:

При необходимости обновите код и ресурсы. Выполните git pull --rebase, чтобы получить актуальное состояние репозитория, и yarn pull, чтобы загрузить ресурсы с сервера.
Запустите окружение и внесите изменения. Выполните yarn start, редактируйте исходники в src и проверяйте результат в браузере.

Перед правками в интерфейсе проверьте ключи resources, dashboards и cubes в config.json: для включённых блоков изменения обрабатываются локально, для отключённых — отправляются на сервер. Независимые правки одних и тех же ресурсов локально и на сервере могут привести к конфликту при следующем yarn pull. После изменения конфига перезапустите dev-сервер.
Проверьте изменения тестами. Рекомендуется писать тесты для новой логики и изменений поведения. Перед отправкой результата запустите тесты проекта командой yarn test.

Тесты визуализаций размещайте в tests/: эта папка исключена из сборки и не отправляется на BI-сервер. Настройка и запуск описаны в документации по тестам.
Сохраните историю в Git. Добавьте нужные файлы (git add), создайте коммит (git commit) и отправьте его в удалённый репозиторий (git push).
Отправьте ресурсы на сервер. Выполните yarn push: команда сначала запускает сборку, затем синхронизирует результат с сервером. Перед подтверждением проверьте список CREATE, OVERWRITE, REMOVE.

Синхронизация и конфликты

Для управления синхронизацией используйте флаги:

Флаг	Назначение
`--no-remove`	Сохраняет на целевой стороне файлы, отсутствующие в источнике: `yarn pull --no-remove` или `yarn push --no-remove`
`--include` и `--exclude`	Ограничивают набор схем, участвующих в синхронизации
`--force`	Пропускает подтверждение при `pull` и `push`

Если yarn pull сообщает Restore conflicts, согласуйте локальные и серверные изменения вручную перед повторной загрузкой. Восстановление останавливается до записи в src; сам dist к этому моменту уже может быть обновлён. Автоматическое слияние конфликтующих исходников не выполняется.

Подробнее о ключах, фильтрах и флагах — в разделе «Конфигурация».

Форматы исходников

Код визуализаций может содержать JavaScript, JSX, TypeScript и TSX; стили — CSS, SCSS и Sass
Конфиги тем, дэшбордов, дэшлетов и кубов поддерживают JSON, JSON5 и YAML. Новые конфиги используют JSON5 с расширением .json; на сервер отправляется обычный JSON
Обычные ресурсы вне каталогов конфигов сохраняют имена и содержимое, даже если имеют расширение .json, .json5, .yaml или .yml
Исходный код восстанавливается из sourcesContent в sourcemap. Если карта неполная или исходников в ней нет, ресурс остаётся готовым JS/map; комментарии из серверного JSON и исходное YAML-оформление восстановить нельзя
Файл .bi-build.json, создаваемый внутри схемы при восстановлении, хранится в Git вместе с исходниками и определяет точки входа сборки

Сборка и dev-сервер нормализуют переводы строк текстовых ресурсов UTF-8 в LF, включая исходный текст в .map. При синхронизации различия только в CRLF/LF не вызывают перезапись. Исходники при сборке не перезаписываются.

Подробности преобразований, сохранения форматов и конфликтов — в описании работы с исходниками и серверными файлами.

🗂️ Структура проекта

Пример после загрузки ресурсов и сборки:

src/                     Исходники, которые редактируются и хранятся в Git
  ds_my_project/         Ресурсы выбранной схемы
    topic.1/             Конфиги темы, дэшбордов и дэшлетов
    .cubes/              Конфиги кубов и измерений
    .bi-build.json       Точки входа и состав восстановленных бандлов
dist/                    Результат сборки или загрузки с сервера; исключён из Git
.bi-sync/                Состояние восстановления и локальные метаданные; исключены из Git
bi-internal/             Объявления типов API Luxms BI
scripts/                 Сборка, dev-сервер и синхронизация
tests/                   Тесты визуализаций проекта
doc/                     Подробная документация
config.json              Настройки проекта
authConfig.json          Локальные данные для входа; исключены из Git

⚙️ Конфигурация

Параметры выбираются в следующем порядке, от большего приоритета к меньшему:

Аргументы командной строки
Переменные окружения BI_*; .env в корне заполняет только отсутствующие переменные
config.json для настроек проекта и authConfig.json для настроек авторизации
Значения по умолчанию
Ввод в терминале, если обязательный параметр не найден

Настройки проекта

Поле в `config.json`	По умолчанию	Назначение
`server`	Запрашивается	Адрес BI-сервера
`port`	`3003`	Порт dev-сервера
`include`	`^ds_\w+$`	Регулярное выражение для включения схем
`exclude`	Пустая строка	Регулярное выражение для исключения схем
`resources`	`true`	Ресурсы, включая код, стили и файлы
`dashboards`	`false`	Темы, дэшборды и дэшлеты
`cubes`	`false`	Кубы и измерения
`noRemove`	`false`	Синхронизация без удаления отсутствующих файлов
`force`	`false`	Синхронизация без запроса подтверждения
`noLogin`	`false`	Запуск dev-сервера без предварительного входа для разработки окна авторизации

В CLI имена записываются через дефис, а в переменных окружения — прописными буквами с префиксом BI_:

yarn start --port=8080
yarn pull --include='^ds_my_project$' --no-remove

Пример .env:

BI_SERVER=https://bi.example.com
BI_PORT=3003
BI_INCLUDE=^ds_my_project$
BI_USERNAME=<логин>
BI_PASSWORD=<пароль>

🔐 Авторизация

Выбирается первый настроенный способ авторизации в следующем порядке:

Браузерная сессия
Kerberos
JWT
Логин и пароль

Способ	Где задать	Переменные окружения
Браузерная сессия	`session` в `authConfig.json`	`BI_SESSION`
Kerberos / SSO	`kerberos` в `config.json`, например `HTTP@sso.example.com`	`BI_KERBEROS`
JWT	`jwt` в `authConfig.json`	`BI_JWT`
Логин и пароль	`username`, `password` в `authConfig.json`	`BI_USERNAME`, `BI_PASSWORD`

Права на чтение и изменение выбранных сущностей нужны независимо от способа входа. Создание JWT и необходимые эндпоинты описаны в инструкции по токенам.

Для нескольких проектов authConfig.json может содержать настройки по именам Git-веток:

{
  "feature/my-project": {
    "username": "<логин>",
    "password": "<пароль>"
  },
  "feature/another-project": {
    "jwt": "<токен>"
  }
}

Браузерная сессия БЛИЦ

После входа в BI через БЛИЦ возьмите значение cookie LuxmsBI-User-Session и добавьте его в локальный authConfig.json:

{
  "session": "<значение-cookie>",
  "insecureSessionTls": false
}

Укажите в config.json HTTPS-адрес самого BI-сервера и запустите yarn start. Сессия проверяется через /api/auth/check, используется прокси и командами pull/push. В этом режиме dev-сервер слушает только 127.0.0.1; запуск не завершает браузерную сессию.

Когда сессия истечёт, обновите cookie и перезапустите команду. Для BI-сервера с недоверенным сертификатом существует явная опция insecureSessionTls: true (BI_INSECURE_SESSION_TLS=true): она отключает проверку сертификата при проверке сессии и синхронизации. Значение по умолчанию — false; dev-прокси отдельно использует secure: false.

Name		Name	Last commit message	Last commit date
.yarn/releases		.yarn/releases
bi-internal		bi-internal
doc		doc
scripts		scripts
src		src
tests		tests
.babelrc		.babelrc
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.yarnrc.yml		.yarnrc.yml
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
config.json		config.json
package.json		package.json
tsconfig.json		tsconfig.json
webpack.config.js		webpack.config.js
yarn.lock		yarn.lock

Navigation Menu

Repository navigation

About

Repository files navigation

🔮 BI Magic Resources

Содержание

⚡ Быстрый старт

1. Подготовьте окружение

2. Настройте конфиг

3. Настройте доступ

4. Загрузите ресурсы и запустите проект

🪄 Команды

📋 Рабочий процесс

Синхронизация и конфликты

Форматы исходников

🗂️ Структура проекта

⚙️ Конфигурация

Настройки проекта

🔐 Авторизация

Браузерная сессия БЛИЦ

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🔮 BI Magic Resources

Содержание

⚡ Быстрый старт

1. Подготовьте окружение

2. Настройте конфиг

3. Настройте доступ

4. Загрузите ресурсы и запустите проект

🪄 Команды

📋 Рабочий процесс

Синхронизация и конфликты

Форматы исходников

🗂️ Структура проекта

⚙️ Конфигурация

Настройки проекта

🔐 Авторизация

Браузерная сессия БЛИЦ

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages