О плагине

Плагин предназначен для мониторинга и управления OLT-устройствами (Optical Line Terminal) и ONU абонентов. Выполняет Telnet-опрос OLT-оборудования, хранит данные в локальной БД BGERP и интегрируется с BGBilling для маппинга MAC→абонент.

Возможности:

  • Встроенный Telnet-опрос OLT-устройств (BdCom, GateRay, CData) с автоопределением vendor

  • Отображение данных ONU на вкладке процесса и вкладке договора BGBilling

  • Страница управления OLT — CRUD, массовый/выборочный опрос, просмотр портов/ONU

  • Импорт OLT из биллинга и автоматический маппинг MAC→абонент

  • Фильтрация OLT по биллингу, статусу, вендору + текстовый поиск (MAC/договор/ФИО/адрес)

  • Цветовая подсветка проблемных RX-сигналов (пересвет, средний, плохой)

  • Перезагрузка ONU с cooldown-защитой (5 мин)

  • Активация/замена ONU — обновление MAC-адреса в биллинге

  • Автоматическое создание записок в процессе при выполнении действий

  • Опрос по расписанию (scheduler task) с защитой от зависания статуса UPDATING

  • Вкладка «Массовая авария» — выбор затронутых OLT/портов на карточке аварийного процесса (см. Вкладка «Массовая авария»)

Оборудование

Vendor Класс Описание

BDCOM

BdComDevice

BdCom GP3600-08B и аналоги

GATERAY

GateRayDevice

GateRay EPON до 2020

GATERAY2020

GateRay2020Device

GateRay EPON 2020+

CDATA

CDataDevice

CData EPON

CDATA_GPON

CDataGponDevice

CData GPON

CDATA_FD1608

CDataFD1608Device

CData FD1608S-B1

CDATA_FD1208

CDataFD1208Device

CData FD1208S-B1

Настройка

BGBilling

Плагин поддерживает два варианта бэкенда на стороне биллинга:

  1. Единый сервис ru.rock.getolt.GetOltService (рекомендуется для новых инсталляций) — все методы в одном dynservice-классе.

  2. Три legacy-webhook-а ru.webHooks.InetMac / ru.webHooks.InetMacList / ru.webHooks.OltList — обратная совместимость со старыми биллингами.

Переключение между режимами выполняется флагом getolt:webhook.unified в конфигурации плагина (см. Плагин).

Единый сервис (webhook.unified=1)

В каталоге динамического кода dyn создать подкаталоги ru/rock/getolt и поместить в самый нижний файл сервиса.

Динамический сервис должен быть указан в конфигурации биллинга:

dynservice:ru.rock.getolt.GetOltServiceInterface=ru.rock.getolt.GetOltService

Дополнительная настройка для случая, когда MAC в конфигурации сервиса вместо стандартного поля:

# ключ доп. параметра сервиса с MAC ONU
server.rock.getolt.mac.config.key=onu_mac_param

Если в дереве устройств биллинга (inet_device_tree_N) OLT лежат вперемешку с другими сетевыми устройствами (коммутаторами, маршрутизаторами), можно явно ограничить выборку GetOltList() по типу устройства — CSV-список deviceTypeId из inv_device_N:

# типы устройств, которые сервис считает OLT (через запятую)
server.rock.getolt.device.type.ids=14
# несколько типов:
# server.rock.getolt.device.type.ids=14,25,30

Если параметр не задан, фильтр по типу не применяется — в список попадают все записи, у которых заполнен host в inet_device_tree_N или в связанном inv_device_N. Декомиссированные устройства (inv_device.dateTo IS NOT NULL) в любом случае исключаются.

Legacy-режим (webhook.unified=0, по умолчанию)

В dyn/ должны быть зарегистрированы три отдельных класса:

dynservice:ru.webHooks.InetMac.InetMacInterface=ru.webHooks.InetMac.InetMac
dynservice:ru.webHooks.InetMacList.GetInetMacListInterface=ru.webHooks.InetMacList.GetInetMacList
dynservice:ru.webHooks.OltList.GetOltListInterface=ru.webHooks.OltList.GetOltList

Используется, если биллинг уже имеет эти webhook-и от предыдущих версий интеграции.

Плагин

Создать включающую плагин конфигурацию, в которую добавить:

# Параметр процесса "Оператор" (param_list)
getolt:operator.paramId=68
getolt:operator.default=РТЦ

# Маппинг значений параметра на операторов
getolt:operator.mapping.1=Омиплат
getolt:operator.mapping.2=Омикрон
getolt:operator.mapping.3=Рокет
getolt:operator.mapping.4=РТЦ
getolt:operator.mapping.5=Флеш

# Маппинг billingId → имя оператора (для ссылок на договоры)
getolt:operator.billing.omicron=ЮТК
getolt:operator.billing.rocket=Рокет

# общие логин с паролем для обращения к сервису биллинга (auto-discovery режим)
getolt:webhook.user=YOUR_WEBHOOK_USER
getolt:webhook.password=YOUR_WEBHOOK_PASSWORD

# опционально отдельные логин с паролем
# getolt:inetmac.rocket.user=special_user
# getolt:inetmac.rocket.password=special_pass

# выбор бэкенда на стороне биллинга:
#   0 (по умолчанию) — три legacy-webhook-а (ru.webHooks.InetMac / InetMacList / OltList)
#   1                — единый сервис ru.rock.getolt.GetOltService (см. раздел "BGBilling")
# getolt:webhook.unified=0
#
# опционально — переключение per-billing (перекрывает общий флаг)
# getolt:inetmac.rocket.unified=1

# === External GetOLT API (для вкладки «Массовая авария») ===
# Базовый URL standalone-сервиса GetOLT v2 (включая /api/v1/external),
# X-API-Key передаётся в заголовке.
getolt:api.url=https://olt.example.com/api/v1/external
getolt:api.key=getolt_xxxxxxxxxxxxxxxxxxxx
getolt:api.timeout=5000

# === «Массовая авария» (ТЗ #11) ===
# id text/blob-параметра процесса для JSON-снимка выбора OLT/портов.
# Рекомендуется тип blob — text-VARCHAR(255) маловат для >5-6 OLT.
getolt:incident.selectionParamId=297
# (опц.) id text/list-параметра «Город» для фильтра списка OLT.
getolt:incident.cityParamId=84
# Активация на конкретном типе процесса — в его configMap (см. <<setup-incident-show-tab>>):
#   getolt:incident.showTab=1

URL для обращений к биллингам получается из конфигурации плагина BGBilling. Path webhook-ов подставляется автоматически в зависимости от webhook.unified: legacy — /ru.webHooks.InetMac/InetMacInterface (+ два соседних класса для списков), unified — /json/ru.rock.getolt/GetOltServiceInterface (все методы в одном endpoint; префикс /json/ обязателен для JSON-RPC, иначе биллинг отдаёт 415).

Настройка порогов сигнала

Пороги сигнала настраиваются в конфигурации следующим образом:

# RX пороги (dBm)
getolt:signal.rx.overexposed=-15
getolt:signal.rx.good=-25
getolt:signal.rx.medium=-27

# TX пороги (dBm)
getolt:signal.tx.overexposed=5
getolt:signal.tx.good=0.5
getolt:signal.tx.medium=-1

Логика: значение выше overexposed — засвет, от overexposed до good — норма, от good до medium — средний, ниже medium — плохой.

Определение оператора

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

  1. Параметр процесса "Оператор" (param_list)

    • ID параметра: getolt:operator.paramId

    • Маппинг значений: getolt:operator.mapping.{valueId}

  2. Billing ID из contract link

    • Формат link: contract:{billingId}

    • Маппинг: getolt:operator.billing.{billingId}

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

    • getolt:operator.default

Планировщик

В эту же конфигурацию добавляется задача планировщика, опрашивающая устройства:

scheduler.task.oltPoll.class=OltPollingTask
scheduler.task.oltPoll.hours=*
scheduler.task.oltPoll.minutes=0,30
scheduler.task.oltPoll.batchSize=10
scheduler.task.oltPoll.staleMinutes=60

Вкладка процесса

В конфигурации типа процесса добавить:

getolt:processShowTab=1

Вкладка «Массовая авария» на типе процесса

В конфигурации аварийного типа процесса (например «Массовая авария (Общий тип)», «Расширение каналов» и т.д.) добавить:

getolt:incident.showTab=1

После этого в карточке процессов этого типа появится отдельная вкладка «Массовая авария» (см. Вкладка «Массовая авария»). На остальных типах вкладки нет.

Безопасность

Валидация MAC

  • Проверка формата: XX:XX:XX:XX:XX:XX

  • Нормализация различных форматов (дефисы, точки, пробелы, без разделителей)

  • Защита от кириллических символов (А, В, С, Е похожи на латинские)

  • Преобразование в верхний регистр

Маскировка паролей

TelnetSession поддерживает sensitiveMode — при setSensitiveMode(true) перед отправкой пароля все данные маскируются в логах (*).

Rate Limiting

  • Перезагрузка ONU: cooldown 5 минут (localStorage на фронтенде)

  • Scheduler: AtomicBoolean предотвращает параллельный запуск опроса

Отладка

Логирование

# Telnet-опрос
grep "OltPollingService\|OltPollingTask" log/bgerp.log

# Действия пользователя
grep "GetOltAction\|OltManageAction" log/bgerp.log

# Billing webhooks
grep "InetMacApiClient" log/bgerp.log

Типичные проблемы

Проблема Причина Решение

Вкладка процесса не появляется

Плагин не включён или нет прав

Проверить getolt:enable=1, processShowTab=1 и право getolt:null

"Нет привязанных договоров"

У процесса нет contract link

Привязать договор к процессу

"ONU не найдена"

OLT не опрошен или маппинг не выполнен

Запустить опрос OLT + маппинг на странице управления

OLT завис в UPDATING

Ошибка при опросе (перезапуск сервера сбросит)

Перезапустить BGERP или подождать следующий цикл scheduler

500 при фильтрах OLT

Отсутствует синоним :unspecified в action.xml

Проверить manage:null,manage:unspecified в action.xml

Пустой vendor после импорта

Vendor определяется отдельным циклом

Подождать следующий цикл scheduler или запустить опрос вручную

Кнопка перезагрузки заблокирована

Cooldown 5 мин после предыдущей перезагрузки

Подождать 5 минут или очистить localStorage

Проверка конфигурации

-- Проверить, что плагин включён
SELECT * FROM config_global WHERE config LIKE '%getolt:enable%';

-- Проверить настройки типа процесса
SELECT id, title, config FROM process_type
WHERE config LIKE '%getolt:processShowTab%';

-- Проверить права
SELECT pp.permset_id, pt.title, pp.action
FROM user_permset_permission pp
JOIN user_permset_title pt ON pp.permset_id = pt.id
WHERE pp.action LIKE '%getolt%';

-- Проверить OLT в БД
SELECT id, ip, vendor, billing, status, last_update FROM getolt_olt ORDER BY ip;

-- Количество ONU
SELECT o.ip, COUNT(onu.id) AS onu_count
FROM getolt_olt o LEFT JOIN getolt_olt_onu onu ON o.id = onu.olt_id
GROUP BY o.id ORDER BY o.ip;

Использование

Вкладка GetOLT (процесс)

process tab overview

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

  1. Плагин включён (getolt:enable=1)

  2. Тип процесса имеет настройку getolt:processShowTab=1

  3. У пользователя есть право getolt:null

  4. К процессу привязан договор (contract link)

Вкладка GetOLT (договор BGBilling)

Вкладка появляется на карточке договора BGBilling при:

  1. Плагин включён (getolt:enable=1)

  2. У пользователя есть право getolt:contractOnu

Данные ONU ищутся напрямую по operator + contractId/numDogovor — без привязки к процессу.

Карточка ONU

onu card full

Карточка отображает:

  • Заголовок: MAC-адрес, статус (ONLINE/OFFLINE), время последнего обновления

  • Кнопки: Обновить порт, Перезагрузить ONU (при наличии прав)

  • Данные:

    • OLT IP

    • Порт / ONU ID

    • Сигнал RX/TX (с цветовой индикацией качества)

    • Дистанция (м)

    • Температура (°C)

    • Напряжение (V)

    • MAC за ONU (список)

    • Соседи по порту (таблица)

Соседи по порту

port neighbors table

Таблица соседей отображает все ONU на том же порту OLT. Текущая ONU абонента выделена жёлтым цветом. Качество сигнала (RX) подсвечивается цветом.

Индикация качества сигнала

Подсвечиваются только проблемные значения RX. Нормальный сигнал — без подсветки. TX и температура не подсвечиваются. Значения порогов по-умолчанию, могут быть изменены в конфигурации.

RX

Качество RX диапазон Цвет

Засвет (overexposed)

> -15 dBm

Голубой (#17a2b8)

Хороший (good)

-15 до -25 dBm

(без подсветки)

Средний (medium)

-25 до -27 dBm

Оранжевый (#e6a000)

Плохой (poor)

< -27 dBm

Красный (#dc3545)

TX

Качество TX диапазон

Засвет (overexposed)

> 5 dBm

Хороший (good)

0.5 до 5 dBm

Средний (medium)

-1 до 0.5 dBm

Плохой (poor)

< -1 dBm

Управление OLT

Страница доступна через меню "OLT" (право manage:null).

Функции:

  • Таблица OLT — IP, vendor, billing, порты, ONU (active/total), статус, last update

  • Фильтры — биллинг, статус, vendor (combo-check) + текстовый поиск

  • CRUD — создание, редактирование, удаление OLT

  • Опрос — ручной опрос одного OLT или массовый (чекбоксы + кнопка "Обновить все/N")

  • Порты/ONU — expandable rows с детальной информацией

  • Импорт — загрузка списка OLT из биллинга

  • Маппинг — ручной запуск сопоставления MAC→абонент

Форма активации ONU

При наличии права activateOnu отображается форма:

  • Поле ввода MAC: автоформатирование, валидация, защита от кириллицы

  • Кнопка "Активировать": отправляет запрос на обновление MAC в биллинге

Если у договора несколько интернет-услуг, появляется модальное окно выбора услуги.

Cooldown перезагрузки

После успешной перезагрузки ONU кнопка блокируется на 5 минут. Состояние сохраняется в localStorage браузера.

Вкладка «Массовая авария»

Отдельная вкладка на карточке аварийных типов процессов. Аварийный диспетчер выбирает затронутые OLT и порты, указывает «все порты» или конкретные, видит сводку по затронутым ONU (всего/online + разбивка по сигналам good/medium/poor/overexposed) и сохраняет JSON-снимок выбора в параметр процесса.

Назначение

Главная цель функционала — машиночитаемый снимок «зоны действия аварии», который смогут использовать смежные системы для точечного информирования абонентов и ответа на их вопросы. В частности:

  • Голосовые боты (исходящие обзвоны / входящие линии техподдержки) — по номеру абонента/договору поднимают активные «Массовые аварии», на чьих OLT/портах находится его ONU, и в реальном времени отвечают:

    • какой тип аварии затрагивает абонента (тип процесса);

    • на каком OLT и порту зафиксировано отключение;

    • предполагаемые сроки устранения (берутся из параметров процесса);

    • текущий статус работ;

  • SMS / Push / Telegram-уведомления — рассылки только по затронутым ONU (исключаются абоненты не из аварии);

  • Отчётность по простоям — снимок служит источником данных для расчёта числа абонентов и времени восстановления связи на каждой аварии.

Условия отображения

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

  1. Плагин включён (getolt:enable=1).

  2. Тип процесса помечен в его конфигурации флагом getolt:incident.showTab=1.

  3. У пользователя есть право /user/plugin/getolt/massIncident:null.

  4. В конфигурации плагина задан id text/blob-параметра процесса: getolt:incident.selectionParamId=<paramId>.

Источник данных

Список OLT и счётчики ONU/сигналов берутся из External GetOLT API (GET /api/v1/external/olts/statistics) — единый запрос отдаёт все OLT с разбивкой ONU на каждом порту. URL и API-ключ задаются в getolt:api.url и getolt:api.key (см. Плагин).

Фильтрация по городу и оператору идёт по параметрам самого процесса:

  • Город — getolt:incident.cityParamId (text или list-параметр); суффикс «- {оператор}» автоматически отрезается.

  • Оператор — переиспользуется существующий getolt:operator.paramId
    маппинг getolt:operator.mapping.*.

Два режима UI

  1. Режим «Сводка» — открывается по умолчанию, если в параметре уже сохранён выбор. Показывает построчно затронутые OLT (IP, vendor, billing, затронутые порты, число online ONU) и итоговую строку «Всего: N OLT · M портов · Затронутых ONU: X online / Y всего». Кнопка «Изменить список затронутых» раскрывает редактор.

  2. Режим «Редактор» — открывается при пустом выборе или по кнопке. Список OLT с чекбоксами, для каждого выбранного OLT — радио «Все порты / Выбрать порты» с чекбоксами портов. Рядом с каждым портом видны бакеты сигнала (good/medium/poor/overexposed/noSignal).

Поиск OLT других локаций

Отдельная кнопка «+ Добавить OLT другой локации» открывает поле ввода с автоподсказками городов (после ≥3 символов, debounce 300 мс). Под каждым найденным городом — раскрывающийся список его OLT с чекбоксами:

  • Клик по тексту города — toggle разворачивания списка OLT.

  • Клик по чекбоксу города — отметить/снять отметку всех OLT этого города.

  • Клик «Добавить выбранные» — слияние с основным списком (без потери уже сделанного выбора, дубликаты по IP игнорируются).

Сохранение в параметре процесса

Кнопка «Сохранить» записывает в указанный incident.selectionParamId параметр компактный JSON:

[
  { "ip": "10.130.2.98" },
  { "ip": "10.130.0.229", "ports": [3, 5, 6] }
]

Отсутствие поля ports означает «все порты». Поля billing/vendor не сохраняются — подтягиваются из API при следующем открытии вкладки.

Тип параметра — blob. В text-параметре value имеет тип VARCHAR(255), этого недостаточно для >5–6 OLT с портами. Создавайте параметр типа blob (хранится в param_blob.value, без ограничения длины). Action автоматически определяет тип параметра и пишет в нужную таблицу.

При повторном открытии вкладки JS дозагружает OLT из других городов (если в выборе есть OLT не из «домашнего» города процесса) точечным запросом по IP — выбор полностью восстанавливается.

Записки в процессе

При выполнении действий плагин автоматически создаёт записки (MessageTypeNote):

Обновление порта

Обновлены данные порта OLT
OLT: 192.168.1.1
Порт: 3

Перезагрузка ONU

Выполнена перезагрузка ONU
Порт/ONU ID: 3/12
MAC: AA:BB:CC:DD:EE:FF

Активация/замена ONU

Активация/замена ONU
Договор: 123456
Старый MAC: AA:BB:CC:DD:EE:FF
Новый MAC: 11:22:33:44:55:66
Сессия: сброшена