Руководство по установке#

Модуль «Информационная панель руководителя. Мониторинг градостроительного потенциала территории» (далее – «Информационная панель руководителя») содержит набор интерактивных аналитических панелей (дашбордов) и карт, отражающих ключевые показатели жилищного строительства на основе данных Системы.

Приложение совместимо с любыми устройствами.

Подготовка к установке#

Поддерживается развёртывание программного решения в двух конфигурациях:

  • Только в защищённом окружении (закрытом контуре), тогда модуль устанавливается целиком в закрытом контуре. В данном случае необходимо обеспечить возможность пользователям из сети интернет получить доступ к информационной панели руководителя в соответствии с политикой информационной безопасности конкретного заказчика.

  • Часть программного решения в защищённом окружении (закрытом контуре), а часть в публичном окружении (открытом контуре). В данном случае необходимо обеспечить доступ из защищённого окружения в публичное для репликации данных (см. Диаграмму развёртывания).

Модуль поддерживает централизованный сбор метрик, трассировок и журналов по протоколу OpenTelemetry. При установке модуля рекомендуется убедиться в том, что сбор метрик приложения включен и работает корректно. Для мониторинга работы модуля создана информационная панель в Grafana.

Подготовка справочника муниципальных образований QuartzMunicipalities.json#

Для отображения фильтра и таблицы по муниципальным образованиям в интерфейсе системы, перед установкой необходимо подготовить справочник МО для каждого заказчика в формате .json.

Фильтр имеет иерархическую структуру:

  • для всех объектов МО, которые находятся в массиве Children в поле [Alias] необходимо указать псевдоним схемы проекта из таблицы «m_projects»;

  • для регионального проекта в поле [Value] обязательна формулировка "Региональные объекты (__Название региона__)".

Подготовка справочника учётных записей QuartzUsers.json#

Система авторизации в информационной панели руководителя никак не связана с авторизацией в Geometa, так как приложение разработано для эксплуатации в отрытом контуре, поэтому приложение имеет свой собственный список учётных записей. Этот список необходимо подготовить перед развёртыванием системы для каждого заказчика в формате .json.

Для добавления новых учётных записей необходимо внести их в файл QuartzUsers.json, а затем перезапустить Quartz на публичном сервере.

Установка#

Метаданные представлены двумя подсистемами:

  • Подсистема Информационная панель руководителя – устанавливается только на региональный проект. Содержит реестр для формирования комплексного отчёта в Минстрой, а также реестры для настройки расчёта градостроительного потенциала.

  • Подсистема Информационная панель руководителя (Проверка качества данных) – устанавливается на все проекты. Содержит реестры для проверки качества заполнения РС, РВ, ГПЗУ, ОЖФ, изменений в РС.

Чтобы установить модуль:

  1. Подключите в метаданные регионального проекта подсистему …\Подсистемы\Информационная панель руководителя.

  2. Подключите в метаданные всех проектов подсистему …\Подсистемы\Информационная панель руководителя (Проверка качества данных).

  3. Откройте метаданные проектов в Редакторе метаданных и проверьте на наличие ошибок.

  4. Обновите метаданные на проектах.

  5. Установите компонент БД Project.Quartz на все схемы проекта.

  6. Перенесите подготовленные файлы json:

    • При установке через Ansible положите ранее подготовленные файлы QuartzMunicipalities.json и QuartzUsers.json в папку files в директории ansible.

    • При установке через Jenkins перенесите содержимое файлов QuartzMunicipalities.json и QuartzUsers.json в соответствующие конфигурационные файлы.

  7. Убедитесь в наличии модуля Module.QuartzIntegration. Модули уже присутствуют, если вы получили пакет с дистрибутивами для проекта.

  8. Установите, если отсутствует, брокер сообщений RabbitMQ.

  9. Укажите следующие переменные в файле vars.yml.

Важно

Файл vars_default.yml редактировать не нужно. Он содержит дефолтные значения переменных.

Чтобы изменить значение переменной из vars_default.yml, добавьте (продублируйте) переменную в vars.yml и укажите нужное значение – при установке оно будет перезаписано.

При установке системы на разные сервера необходимо обеспечить одновременное подключение от хостовой машины до серверов открытого gvQUARTZ_DELEGATE_PUBLIC и закрытого контуров gvQUARTZ_DELEGATE_PRIVATE.

При установке системы на один сервер, переменным gvQUARTZ_DELEGATE_PRIVATE и gvQUARTZ_DELEGATE_PUBLIC необходимо задать одинаковое значение.

Название переменной

Значение по умолчанию

Описание переменной

vars.yml:

gvQUARTZ_DELEGATE_PRIVATE

app-1

Псевдоним сервера закрытого контура в Ansible

gvQUARTZ_DELEGATE_PUBLIC

app-2

Псевдоним сервера открытого контура в Ansible

gvQUARTZ_PUBLIC_INSTALL_DIR

/opt/QuartzPublic

Директория установки части приложения в открытом контуре

gvQUARTZ_PRIVATE_INSTALL_DIR

/opt/QuartzPrivate

Директория установки части приложения в закрытом контуре

gvQUARTZ_PUBLIC_IP

IP-адрес сервера открытого контура во внутренней сети заказчика

gvQUARTZ_DB_USER_LOGIN

postgres

Имя суперпользователя в БД Quartz в docker-контейнере

gvQUARTZ_DB_USER_PASS

postgres

Пароль суперпользователя в БД Quartz в docker-контейнере

gvQUARTZ_PUBLIC_ORIGIN

https://quartz-{{ gvNGINX_FQDN }}

Публичный URI, по которому пользователь будет заходить в систему

gvQUARTZ_REGION_PROJECT_ALIAS

testregion

Псевдоним региональной схемы

vars_default.yml:

gvQUARTZ_DB_PORT

5433

Порт для подключения к БД Quartz (внешней порт БД в docker-контейнере)

gvQUARTZ_WEBAPI_LAYERS_URL_SCHEMA

https://tile.openstreetmap.org/{z}/{x}/{y}.png

URI для получения подложки

gvQUARTZ_WEBAPI_LAYERS_URL_SATELLITE

https://server.arcgisonline.com/ArcGIS/rest/ services/World_Imagery/MapServer/tile/{z}/{y}/{x}

URI для получения спутниковой подложки

gvQUARTZ_PUBLIC_PORT

5256

Порт, по которому доступен UI. Изменить в случае конфликта с другими приложениями

gvQUARTZ_PUBLIC_API_PORT

5257

Порт, по которому доступен API. Изменить в случае конфликта с другими приложениями

gvQUARTZ_CRON_EXPRESSION

0 0 0 ? * *

Расписание, по которому будет происходить обновление данных в формате Cron. Инструмент для генерации выражений https://www.freeformatter.com/cron-expression-generator-quartz.html

gvQUARTZ_USE_CONSUL

false

Флаг использования централизованного хранилища конфигураций Consul

gvQUARTZ_DB_CONNECTION_STRING

Server={{ gvQUARTZ_PUBLIC_IP }};Port={{ gvQUARTZ_DB_PORT }};Database=quartz;User Id={{ gvQUARTZ_DB_USER_LOGIN }};Password={{ gvQUARTZ_DB_USER_PASS }};CommandTimeout=120;

Строка подключения до БД. Изменять в случае, если заказчик требует использовать уже существующий сервер СУБД

gvOTLP_LOGS_ENABLE

false

Параметр для управления логированием. Допустимые значения: false – логи записываются в файлы директории /var/log/gems; true – логи записываются в grafana

  1. Если используется БД в контейнере, то убедитесь, что на сервере открытого контура порт из переменной gvQUARTZ_DB_PORT не закрыт.

  2. Обновите приложение с помощью тега install_quartz.

Конфигурирование#

При установке системы через Ansible, если переменной gvQUARTZ_USE_CONSUL присвоено значение true, администратору становится доступна возможность ручного конфигурирования системы для конкретного заказчика через UI интерфейс Consul.

Конфигурирование позволяет:

  • Добавлять и редактировать SQL-скрипты агрегации данных, а также управлять последовательностью их выполнения.

  • Настраивать SQL-скрипты для получения данных для каждого элемента дашборда.

Конфигурирование сервиса агрегации данных#

Конфигурация сервиса агрегации позволяет настраивать SQL-скрипты, направленные на получение определенных данных из основного приложения.

Настройки сервиса агрегации данных находятся в централизованном хранилище Consul в разделе Quartz/ETL, где представлены две папки: Configuration и AggregationScripts.

Папка Configuration хранит файл PipelineConfiguration.json, который определяет задачи агрегации данных и их последовательность.

В файле представлен массив PipelineTasks, каждый элемент которого описывает задачу, которую будет выполнять сервис агрегации.

Элементы массива содержат следующие поля:

  • [Name] – имя задачи;

  • [Type] – тип задачи:

    • Aggregation – выполнение SQL-скриптов;

    • Transfer – перенос таблиц из БД Geometa в БД Информационной панели;

  • [Order] – порядковый номер задачи, который определяет последовательность её выполнения;

  • [Parameters] – объект параметров, который содержит переменные, используемые в SQL-скриптах. Например, переменная @RegionSchema будет заменена на значение, указанное в данном объекте.

Папка AggregationScripts хранит SQL-скрипты, которые выполняются приложением.

Скрипты организованы в папки, имена которых совпадают с названием задачи в файле PipelineConfiguration.json. Например, для задачи с именем «Init», скрипты будут расположены в папке Quartz/ETL/AggregationScripts/Init.

Конфигурирование основного сервиса#

Конфигурация основного сервиса позволяет добавлять новые дашборды в систему, а также редактировать уже имеющиеся. Если в компонент дашборда выводятся новые данные, то предварительно нужно написать SQL-скрипт для их расчёта и указать этот скрипт при конфигурировании сервиса агрегации данных.

Настройки основного сервиса находятся в разделе Quartz/WebAPI, который включает две основные папки: Configuration и InitConfiguration.

Папка Configuration содержит все необходимые SQL-запросы и другие файлы, которые используются для получения данных и настройки компонентов дашбордов. В этой папке хранятся SQL-файлы, которые система использует для выполнения запросов в базу данных и отображения соответствующих данных на дашбордах.

Папка InitConfiguration содержит важные файлы, необходимые для корректной работы системы:

  • QuartzMunicipalities.json и QuartzUsers.json – эти файлы определяются через Ansible или Jenkins до установки системы и включают информацию о муниципалитетах и пользователях соответственно.

Структура каждого дашборда описывается в отдельном json-файле. Порядок дашбордов задается путем добавления цифры в наименовании файла, например, 1_ComissioningPlan.json.

Пример структуры

Каждый дашборд в системе описывается как объект с набором полей, которые определяют его функциональность и внешний вид. Рассмотрим основные поля:

  • [Alias] – уникальный идентификатор дашборда;

  • [DisplayName] – название дашборда, отображаемое пользователю в интерфейсе;

  • [SvgIcon] – иконка в формате SVG, которая будет использоваться для визуального представления дашборда;

  • [GridLayoutDescription] – описание сетки, которая определяет количество столбцов и строк для размещения компонентов дашборда (поля ColumnsCount и RowsCount).

Компоненты дашборда:

  1. SwitcherComponents – элементы для переключения между различными представлениями дашборда (например, «Карта» или «Дашборд»):

    • [Alias] – уникальный идентификатор компонента;

    • [DisplayName] – название компонента;

    • [SwitcherElements] – элементы переключателя, которые могут быть выбраны пользователем (например, карта или дашборд):

      • [Alias] – уникальный идентификатор элемента переключения;

      • [DisplayName] – название, которое будет отображается в интерфейсе.

  2. FilterComponents – фильтры, которые позволяют пользователям управлять отображением данных:

    • [Alias] – уникальный идентификатор фильтра;

    • [DisplayName] – название фильтра, которое будет отображаться в интерфейсе;

    • [MultipleChoice] – возможность множественного выбора значений (true/false);

    • [Type] – тип фильтра (например, «CategoricalText» для выбора категорий или «DateRange» для выбора диапазонов дат);

    • [QueryContext] – описание контекста запроса, который определяет, как фильтр получает данные:

      • [Alias] – наименование SQL-скрипта в хранилище Consul;

      • [SeriesMetadataCollection] – метаданные серии:

        • [Alias] – наименование поля, полученного в результате выполнения скрипта;

        • [DisplayName] – название фильтра, которое будет отображаться на странице;

        • [DataType] – тип данных (доступные типы данных: Double, String, Date, DayOfMonth);

        • [Type] – тип серии (доступные типы серии: Labels, Values, Discriminator, ParentGroupValues, ChildGroupValues).

  3. VisualComponents – визуальные элементы дашборда, такие как индикаторы, графики и таблицы:

    • [Alias] – уникальный идентификатор визуального компонента;

    • [DisplayName] – название компонента;

    • [Type] – тип компонента, например:

      • [Indicator] – индикатор;

      • [BarChart] – столбчатая диаграмма;

      • [Map] – карта;

      • [LineChart] – линейный график;

      • [HalfDoughnut] – полукруговая диаграмма;

      • [Table] – таблица;

      • [GroupedTable] – таблица групп застройщиков;

      • [ColorLineIndicator] – цветной линейный индикатор;

      • [HeatMapTable] – тепловая карта;

    • [GridLayoutPosition] – позиция компонента в сетке дашборда, которая определяется координатами (X, Y) и размерами (ширина и высота);

    • [SwitcherElementAlias] – указывается алиас нужного SwitcherElements, на котором будет отображатся визуальный элемент;

    • [QueryContext] – контекст запроса, который отвечает за получение данных для отображения в компоненте:

      • [Alias] – наименование SQL-скрипта в хранилище Consul;

      • [SeriesMetadataCollection] – метаданные серии:

        • [Alias] – наименование поля, полученного в результате выполнения скрипта;

        • [DataType] – тип данных;

        • [Type] – тип серии;

        • [Measure] – единицы измерения;

      • [Variables] – секция заполнения фильтров:

        • [Name] – наименование фильтра;

        • [QuaryVariableType] – тип фильтра (доступные типы: TextArray, DateRange);

        • [FilterComponentAlias] – алиас фильтра;

      • [MapLayers] – слои карты:

        • [Alias] – алиас папки со скриптом в хранилище;

        • [QueryContext] – контекст запроса, который отвечает за получение данных для отображения в компоненте:

          • [MapLayerAlias] - алиас слоя карты;

          • [Alias] – наименование SQL скрипта;

          • [DataType] – тип данных;

          • [Variables] – настройка фильтров для слоя:

            • [Name] – наименование фильтра;

            • [QuaryVariableType] – тип фильтра;

            • [FilterComponentAlias] – алиас фильтра.

Поле [QueryContext] отвечает за определение данных, которые будут возвращены SQL-запросом для конкретных фильтров или визуальных компонентов.

Поле [Alias] используется для поиска соответствующего SQL-файла в папке Configuration.

Например, для дашборда с Alias «ComissioningOfMKD» существует визуальный компонент HousingComissionedAreaIndicator с типом LineChart и контекстом запроса RVAreaPeriod. Система будет ожидать, что SQL-файл, который содержит логику получения данных для этого компонента, будет находиться по следующему пути: Quartz/WebAPI/Configuration/ComissioningOfMKD/Charts/HousingComissionedAreaIndicator/RVAreaPeriod.sql.

По аналогии размещаются SQL-файлы для фильтров и слоев, соответственно:

  • Quartz/WebAPI/Configuration/ComissioningOfMKD/Filters/HousingComissionedCompanyGroupFilter/HousingComissionedCompanyGroupFilterData.sql;

  • Quartz/WebAPI/Configuration/ComissioningOfMKD/Maps/HousingComissionedMap/Layers/PolygonsOzf/PolygonsOzf.sql.

Файл MapConfig.json составляется с помощью сервиса Maputnik.

Импорт данных в каталог групп компаний#

  1. Сформируйте файл импорта со списком групп компаний, расположенный по пути X:\Разное\AD\Информационная панель руководителя (мониторинг градпотенциала)\company_group_loader\company_group_loader.exe.

Или возьмите готовый, расположенный по пути X:\Разное\AD\Информационная панель руководителя (мониторинг градпотенциала)\company_group_loader\CompanyGroups.

  1. Откройте приложение Импортер даных (Emerald) и загрузите новый шаблон импорта на региональную схему проекта: X:\Разное\AD\Информационная панель руководителя (мониторинг градпотенциала)\Шаблон импорта Emerald для групп компаний застройщиков.

  2. Проведите импорт данных файла со списком групп компаний.

  3. Проверьте, что загруженные данные появились в реестре.