Справочники

Пулы адресов и VLAN, списки доступа, адресная база, реквизиты, валюта, статусы, единицы измерения и периоды — плюс краткие обзоры ключевых сущностей биллинга.

7. Справочники

Что на что опирается

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

flowchart TD
    ADDR["Адреса
(дом, улица, район)"]
    STATUS["Статусы
подключения"]
    ATTR["Дополнительные
поля клиента"]
    UTYPE["Типы услуг"]
    RANGE["Линейки услуг"]
    POOL["Пулы адресов"]

    CARD["Карточка клиента"]
    TAR["Тарифы и услуги"]
    NET["Оборудование
и доступ"]
    SORM["Выгрузки СОРМ"]

    ADDR --> CARD
    ADDR --> NET
    STATUS --> CARD
    ATTR --> CARD
    ATTR --> SORM
    UTYPE --> TAR
    RANGE --> TAR
    POOL --> NET
    CARD --> SORM
    TAR --> SORM

Раздел меню «Справочники» — все нормативно-справочные данные системы: пулы IP, ACL, адреса, валюты, статусы и т.д.

7.1. Пулы IP и VLAN

Подменю с двумя справочниками: пулы IP-адресов для выдачи через RADIUS и пулы VLAN для разметки портов на коммутаторах.

Пулы IP — назначение и роль

IP-пул — это диапазон IP-адресов [start_ip…end_ip], из которого FreeRADIUS выдаёт клиенту Framed-IP-Address при PPPoE/IPoE-авторизации. Хранится в таблице ip_pull, редактируется на /admin/dictionary/IpPull/.

Зачем нужен IP-пул

Пул решает две задачи:

1. Автоматическая выдача IP клиенту. При авторизации FreeRADIUS вызывает allocate_ip_from_pool() (см. billing/services/ip_allocation.py), который находит первый свободный IP в диапазоне пула, помечает его в Users.IP и возвращает в RADIUS-ответе как Framed-IP-Address. Без пула — пришлось бы вручную проставлять IP каждому клиенту в карточке.
2. Сегментация сети. Разным NAS можно привязать разные пулы → разные подсети для разных регионов / типов услуг (PPPoE-клиенты vs Hotspot, белые IP vs NAT).

4 роли пула на NAS

Один и тот же NAS может ссылаться на 4 разных пула, каждый со своим назначением:

Какой пул использует FreeRADIUS — определяется по статусу клиента (tarif, has_white_ip, hotspot-флаг). На странице /admin/dictionary/IpPull/ в колонке «Привязка к NAS» видно, какие роли выполняет пул на каждом NAS.

Chain-цепочки (NEXT_PULL_ID)

Поле ip_pull.NEXT_PULL_ID позволяет связать пулы в цепочку резервирования: когда основной пул исчерпан, аллокатор автоматически переходит к следующему. Пример (рабочий сервер, 2026-05):

Защита от циклов: _expand_next_pull_chain() ограничивает глубину 10 шагами и держит set уже посещённых ID. UI отображает chain-цепочку бейджем 🔗 с tooltip-разбивкой JOY-1 (510/510) → JOY-2 (14/510) → JOY-3 (0/510).

Когда нужно создавать новый пул

• Новый NAS в новом регионе — отдельный пул для отделения трафика;
• Новый платный сервис «белый IP» — отдельный WHITE_PULL_ID;
• Расширение исчерпанной подсети — добавить пул и связать через NEXT_PULL_ID (без перенастройки NAS);
• Гостевой Wi-Fi — отдельный HOTSPOT_PULL_ID с ограниченной скоростью.

Что делать со старыми пулами

1. Тестовые пулы (имя содержит «test», «tmp», «proba») — удаляются через UI кнопкой 🗑, если у пула 0 пользователей и 0 NAS-привязок;
2. Декомиссированные пулы — поставить enabled=false вместо удаления, если есть исторические Users с IP из этого пула. Это сохранит историческую целостность;
3. Не трогать пулы, упомянутые в любом из 4 полей nas.*_PULL_ID или в NEXT_PULL_ID другого пула — это сразу разрушит chain-цепочку.

Пулы IP-адресов

URL: /admin/dictionary/IpPull/

Пул IP-адресов — это диапазон от start_ip до end_ip, из которого FreeRADIUS выдаёт Framed-IP-Address при авторизации клиента. Один пул привязан к одному или нескольким NAS-устройствам через 4 разных поля (см. роли). Список загружается AJAX, статистика занятости считается раз в минуту с кешем.

Возможности списка

• KPI-сводка сверху: общее количество пулов, активных, опасных (≥75 %), исчерпанных, суммарное использование.
• Сегменты Все / Активные / Опасные / Исчерпанные — фильтр по состоянию.
• Чипы-фильтры по ролям NAS: main / nat / white / hotspot — показывает пулы, используемые соответствующим способом.
• Колонки «Свободно» / «% занято» с прогресс-баром: зелёный <75 %, оранжевый 75–90 %, красный ≥90 %, бейдж «ИСЧЕРПАН» при 0 свободных.
• Σ-блок «🔗 Σ N/M ×K» для пулов в цепочке — суммарная занятость всех пулов цепочки JOY-1 → JOY-2 → JOY-3 с разбивкой в tooltip. Без этого блока админ видит «JOY-1 = 100 % занято» и думает «всё пропало», на самом деле есть запас в JOY-2/3.
• Привязка к NAS — цветные бейджи ролей (main / nat / white / hotspot), tooltip раскрывает все привязки одного NAS.
• Бейдж «🔗 → #N» в колонке «Название» — ссылка на следующий пул в цепочке (клик открывает его модалку).
• Сортировка сохраняется в localStorage — после CRUD страница перерисовывается с тем же sort и фильтрами.
• «Авто-шлюз» — кнопка-помощник: для пулов без шлюза подставляет первый IP диапазона (по конвенции start_ip - 1 или start_ip).

Добавление пула

Кнопка «+ Новый IP-пул» в правом верхнем углу открывает модалку:

Обязательные поля:

• Название (name, до 256 символов) — отображается в селектах и в колонке списка. Пример: SmIT-main, JOY-1, HOTSPOT-FAG. Рекомендуется префикс по NAS или роли.
• Начальный IP (start_ip) — первый адрес диапазона.
• Конечный IP (end_ip) — последний адрес. Сервер проверяет что start ≤ end, иначе вернёт 400.

Опциональные поля:

• Маска (netmask) — справочное значение, клиенту через RADIUS не назначается. Используется только для cfg-генерации NAS (rtsh cfg make) и SORM-отчётов. По умолчанию — 255.255.255.0 (/24).
• Шлюз (gateway) — справочное, отображается в cfg-шаблонах. По умолчанию — пусто (можно автозаполнить кнопкой «Авто-шлюз» в toolbar).
• Следующий пул (next_pull_id) — Select из активных пулов того же оператора. Когда основной исчерпан, allocate_ip_from_pools переходит в этот пул автоматически (см. цепочки). Защита от циклов: max_depth=10.
• Активность (enabled, default = true) — выключенный пул не выдаёт IP, но остаётся в БД. Используется при выводе пула из эксплуатации без удаления.
• Комментарий (comment) — свободный текст. Удобно фиксировать VLAN-номер, оператора или причину создания.

Что происходит после сохранения:

1. Запись в БД (ip_pull): новый pull_id генерируется автоинкрементом.
2. Audit-запись в AuditOperations (table_name='IP_PULL', object_id=pull_id).
3. Кеш статистики (ip_pool_stats_v3) инвалидируется — следующая загрузка списка пересчитывает использование.
4. Пул автоматически становится доступным в Select-полях NAS (Pull / NAT-pull / White-pull / Hotspot-pull) и в RADIUS_USERAUTH при авторизации.

Редактирование пула

Клик по строке (или иконке карандаша справа) открывает ту же модалку с предзаполненными полями:

Все поля редактируются. Изменение start_ip / end_ip у используемого пула — опасная операция: если новый диапазон не покрывает уже выданные адреса, клиенты со «старыми» IP не попадут в пул при следующей авторизации (allocate_ip_from_pools не считает их занятыми, может выдать дубль). Прежде чем сужать диапазон — проверьте через find_ip_duplicates --pool_id=N.

Удаление через кнопку «Удалить» внутри модалки. Защита: пул нельзя удалить, если на него ссылается хоть один NAS (через любое из 4 полей pull_id / nat_pull_id / white_pull_id / hotspot_pull_id) или другой пул через next_pull_id. Сервер вернёт ошибку «Пул используется в N NAS / M пулах. Сначала уберите ссылки.»

Роли пула на NAS (4 поля)

Один NAS может ссылаться на пул через 4 разных поля, что определяет как IP из этого пула используется:

В списке пулов рядом с именем NAS показываются бейджи ролей для каждого NAS, использующего этот пул. Это помогает быстро понять «куда подключён пул» без перехода на страницу NAS.

Цепочки пулов (next_pull)

Когда клиентов больше, чем размер одного /24-пула (254 адреса), используется цепочка: основной пул ссылается на резервный через next_pull_id. Алгоритм allocate_ip_from_pools() в billing/services/ip_allocation.py:

1. Проверяет основной пул (NAS.pull_id).
2. Если он исчерпан — переходит в next_pull.
3. Из next_pull снова в его next_pull, и т.д.
4. Защита от циклов: max_depth=10 + seen-set по pull_id.
5. Если все пулы цепочки исчерпаны — fallback на глобальный FALLBACK_IP_POOL_ID (если задан в VpnConst), затем reclaim из offline-клиентов, затем Telegram-алерт.

Пример (рабочий сервер, 2026-05): JOY-1 → JOY-2 → JOY-3, каждый по 510 адресов. Σ-блок в UI показывает «🔗 Σ 1006 / 1530 ×3» — итого занято 1006 из 1530, цепочка из 3 пулов.

Visual: на пуле, у которого задан next_pull_id, в колонке «Название» появляется бейдж «🔗 → #N». Клик открывает модалку следующего пула.

Пулы VLAN — назначение и роль

Пул VLAN — это диапазон номеров VLAN [start_vlan…end_vlan], закреплённых за конкретным оператором связи или сегментом сети. Хранится в vlan_pull, редактируется на /admin/dictionary/VlanPull/.

Зачем нужен пул VLAN

Пул VLAN решает две задачи:

1. Сегментация L2-сети. Каждой точке подключения (CONNECTION_POINTS) можно присвоить отдельный VLAN из пула — изолировать трафик клиентов друг от друга на коммутаторах. Биллинг подсказывает свободный VLAN из пула при создании точки.
2. Учёт использования номеров VLAN. На корпоративных сетях (или нескольких операторов в одной инфраструктуре) выделение VLAN строгое: например, оператор А получил 100–200, оператор Б — 201–300. Пул не даёт случайно занять чужой номер.

Где это поле используется

Когда нужно создавать пул VLAN

• Если вы единственный оператор в сети — обычно достаточно одного пула на 1–4094 (или часто на 100–4000, чтобы оставить системные номера). Технически можно вообще обойтись без VLAN-пулов и выставлять номера руками.
• Если делите инфраструктуру с другими операторами — отдельный пул для каждого, чтобы UI не давал случайно занять чужой VLAN.
• Сегментация по типам услуг — например, 100–199 для PPPoE, 200–299 для IPoE, 300–399 для гостевого Wi-Fi.

Что делать со старыми пулами

• Тестовые пулы с 0 точек подключения — удаляются через UI кнопкой 🗑.
• Декомиссированные пулы — лучше выключить (enabled=false), а не удалять, если есть точки подключения с VLAN из этого пула. После миграции точек на новый пул — удалить.
• Защита удаления: UI блокирует удаление пула, у которого counter «Использовано» > 0. Чтобы удалить — сначала переведите все точки подключения на другие пулы.

Пулы VLAN

URL: /admin/dictionary/VlanPull/

Пул VLAN — диапазон номеров VLAN, выделенных оператору связи. Используется при настройке точек подключения (одна точка = одна VLAN из пула) и в шаблонах конфигурации коммутаторов.

Возможности списка

• Список с поиском по названию и оператору.
• Колонка «Использовано» — счётчик точек подключения, занявших VLAN из пула.
• Бейдж активности (enabled) — Bootstrap-switch прямо в строке.
• Скрытие «оператора», если у системы единственный оператор: колонка убирается через .vp-op-col-hidden, чтобы не путать админа.

Добавление и редактирование

Кнопка «+ Новый VLAN-пул» открывает модалку:

Поля:

• Название (name) — отображается в селектах и списке.
• Начальный VLAN (start_vlan, 1–4094) — первый номер диапазона.
• Конечный VLAN (end_vlan, 1–4094) — последний номер. Сервер проверяет start ≤ end и непересечение с другими активными пулами того же оператора.
• Оператор (operator_id) — Select из клиентов в папке Операторы (9002). Для одно-операторских систем поле скрыто.
• Активность (enabled) — выключенный пул не назначается на новые точки подключения.
• Комментарий — свободный текст.

На скриншоте edit-режим: модалка идентична add, но с заполненными значениями + кнопкой «Удалить» снизу слева.

Защита удаления: VLAN-пул нельзя удалить, если он использован хотя бы в одной точке подключения. Сервер вернёт ошибку «Пул используется в N точках. Удаление запрещено для сохранения связей.»

Мониторинг и алерты

Beat-задача ip-pool-monitor (раз в час) обходит все enabled IP-пулы:

• Считает использование через get_pool_stats(pool) — для пулов в цепочке возвращает chain-aware Σ.
• Если % занятости ≥ IP_POOL_DANGER_THRESHOLD_PCT (90 % default) → пул помечается как опасный.
• Если ≥1 пул в опасной зоне ИЛИ исчерпан → отправка одной нотификации в Telegram-чат админов (дедуп ip_pool_monitor:alert:{date}).

На дашборде /admin/welcome/ — компактный виджет «IP-пулы» с топ-3 опасными и сводкой использования.

7.2. Контроль доступа (ACL)

Подменю с двумя справочниками для управления сетевыми правилами доступа.

Подраздел «ACL группы»

Именованные списки правил для firewall: «Домашние пользователи», «Корпоративные», «VIP», «Социальный тариф» и т.п. Каждой группе соответствует набор правил — разрешения и запреты по портам, протоколам и адресам. Группа назначается клиенту в его карточке (на вкладке «Точки подключения») и попадает в RADIUS-ответ как Filter-Id.

Подраздел «Списки разрешённых сайтов»

Белые списки доменов для клиентов в финансовой блокировке (captive portal): сайт оператора, страница оплаты, личный кабинет. Когда клиент в долге, NAS ограничивает его трафик до этих доменов — чтобы он мог пополнить счёт, но не мог пользоваться интернетом для развлечений.

7.3. Все адреса

Подменю с тремя справочниками для адресной системы оператора.

Адреса (Homes) — назначение и роль

Адрес (Homes) — запись в иерархическом справочнике Россия → регион → город → район → улица → дом. Хранится в таблице homes как самоссылочное дерево (через parent_id), редактируется на /admin/dictionary/Homes/.

Зачем нужен справочник адресов

Справочник homes решает четыре задачи:

1. Привязка клиента к физическому адресу. Поле Abonents.HOME_ID → конкретный дом. Используется для печатных форм договоров, счетов, СОРМ-выгрузок (поле ABONENT_ADDR).
2. Привязка оборудования к месту установки. Поле switch.HOME_ID и nas.HOME_ID — где установлена железка. Это техдокументация для выезжающих инженеров.
3. Точки подключения. CONNECTION_POINTS.HOME_ID — на каком доме точка подключения находится. Один дом может иметь много точек (квартиры, офисы).
4. Геокодинг и карта. Поля lat/lon хранят координаты дома (геокодируются через DaData). Используются на карте клиентов /admin/abonents/map/ — кружки с цветом по статусу клиента.

Где используется адрес

Дерево и геокодинг

Адреса организованы как самоссылочное дерево:

• Корень — обычно «Россия» (одна запись с parent_id=NULL);
• Уровни: регион (Волгоградская обл.) → город (Волгоград) → район (Кировский) → улица (Ленина) → дом (15);
• Геокоординаты заполняются для домов через команду manage.py geocode_homes_dadata. На рабочий сервер 2026-05: 4045/4261 (94.93%) адресов имеют lat/lon;
• Использование на карте: для отображения клиента на карте нужен заполненный lat/lon у его дома. Если координат нет — клиент в маркер не попадёт.

Подробнее про карту см. «Карта клиентов».

Что делать с адресами без жителей

В аудите БД часто видны адреса без привязанных клиентов и Users (на рабочем сервере 2026-05: 992 шт). Это не мусор, а адресная база региона — список потенциальных адресов для подключения.

• Не удалять автоматически. Адресная база заполнялась заранее (DaData импорт), пустые адреса ждут подключения новых клиентов;
• Удалять только конкретные ошибки — дубли, неверные индексы, переименованные улицы. Удаление через UI кнопкой 🗑;
• Защита FK: на homes ссылаются NO ACTION поля из abonents, users, switch, nas, CONNECTION_POINTS, EQUIPMENT, netmap_node, video_object, video_project, а также сам homes через PARENT_ID. UI заблокирует удаление, если есть хоть одна привязка — в том числе когда у адреса есть вложенные адреса.

Подраздел «Адреса»

Иерархия Россия → регион → город → район → улица → дом. Хранится как дерево с unicode-сравнением, дома содержат геокоординаты (lat/lon), индекс, дату начала обслуживания.

Возможности списка:

• Все 4000+ адресов загружаются одним AJAX-запросом, фильтрация и сортировка — на клиенте.
• Фильтры: Город, Район (выпадающий список), дата подключения дома.
• Сортировка по любому столбцу.
• CSV-экспорт отфильтрованных строк.
• Геокодирование через DaData (поле «Адрес» с автокомплитом, лат/лон сохраняются автоматически).

Подраздел «Точки подключения»

Физическое место подключения клиента: коммутатор + порт + VLAN. Один дом может содержать несколько точек (если в подъезде несколько коммутаторов или несколько провайдерских узлов). Используется для DHCP Option 82, RADIUS-фильтра и СОРМ-выгрузки.

Подраздел «Типы адресных единиц»

Словарь сокращений: ул, пер, наб, пр, пл, бульв, проезд, тупик, шоссе, поселение, мкрн и т.д. Используется для нормализации и парсинга полных адресов, передачи в DaData и в форматирование адреса для печатных документов.

7.4. Реквизиты

Шаблоны атрибутов для физлиц и юрлиц. Физлицо: паспорт серия/номер, дата выдачи, кем выдан, адрес регистрации, СНИЛС. Юрлицо: ИНН, КПП, ОГРН, юридический/физический/почтовый адрес, расчётный счёт, банк, БИК, корреспондентский счёт, в лице, директор.

Атрибуты автоматически создаются у клиента при создании в зависимости от типа (физлицо / юрлицо). Заполняются во вкладке «Реквизиты» карточки клиента. Для юрлиц также собираются на вкладке СОРМ.

7.5. Валюты

Список валют биллинга. По умолчанию — рубль (₽). Для мультивалютных схем можно добавить USD/EUR с курсами.

7.6. Выходные дни

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

Статусы клиентов — назначение и роль

Статус клиента — состояние его подключения: «Активный», «Заблокирован», «На паузе», «Тестовый период», «Должник», «Корпоративный VIP». Хранится через FK Abonents.status_id → таблицу STATUS. Управляется в /admin/dictionary/Status/.

Зачем нужны статусы

Статусы решают четыре задачи:

1. Визуальная индикация — цветной бейдж рядом с именем клиента в списке. Оператор видит «должник», «новый», «активный» одним взглядом;
2. Автоматизация смены — при определённых событиях (баланс ушёл в минус, истёк тестовый период) Целери-задача меняет статус автоматически;
3. Триггер для сообщений — при смене статуса автоматически шлётся email/SMS/push/Telegram-сообщение из StatusMsgTemplate;
4. Изменение поведения сети — каждому статусу можно привязать StatusRadiusParam — RADIUS-атрибуты для NAS (например Filter-Id := block у статуса «Заблокирован»).

Поля и связанные модели

Дополнительные модели:

• StatusFollow — иерархия переходов (parent → child). Например: после статуса «Заблокирован за долг» через 30 дней автоматически переход в «Удалённый»;
• StatusMsgTemplate — шаблоны email/SMS/push для смены на этот статус;
• StatusRadiusParam — RADIUS-атрибуты, которые отдаются NAS при этом статусе.

4 категории событий аудита

В AUDIT_OPERATIONS поле op_type_category разделяет события на 4 группы:

В UI вкладки «Аудит» карточки клиента можно фильтровать по категории — получаешь только статусные смены или только финансовые операции.

Связь с шаблонами сообщений

Когда статус меняется, через post-save сигнал биллинг проходит по StatusMsgTemplate для нового статуса и отправляет:

• Email с шаблоном-текстом (плейсхолдеры: {{ abonent.name }}, {{ balance }});
• SMS через настроенный шлюз (SmitSMSGateway / SMSAero);
• Push на мобильное приложение (через FCM, если устройство зарегистрировано);
• Telegram через SMITSupport_bot, если у клиента привязан Telegram ID;
• Уведомление в ЛК — через MsgStack, клиент видит при следующем входе.

Управление шаблонами — в модалке статуса (вкладка «Шаблоны»). Каждый канал включается / выключается отдельно.

Связь с RADIUS

При авторизации клиента FreeRADIUS читает его текущий статус и применяет связанные с ним атрибуты:

• Статус «Активный» — отдаются нормальные параметры из тарифа (Mikrotik-Rate-Limit и т.д.);
• Статус «Заблокирован» — может вернуться Filter-Id := block (фильтр на NAS, ограничивающий трафик до captive-portal);
• Статус «Перерыв на лето» — отдельный Pool-Name с медленной скоростью.

Это альтернатива полной блокировке — клиент остаётся подключён, но с ограничениями. Гибче чем boolean enabled=false.

7.7. Управление статусами

Подменю с двумя справочниками для управления пользовательскими статусами клиентов.

Подраздел «Статусы»

Пользовательские статусы клиента: «Тестовый период», «Должник», «Перерыв на лето», «Корпоративный», «VIP» и т.п. Каждый статус имеет цвет (показывается как бейдж рядом с именем клиента в списке) и шаблон сообщения, которое отправляется автоматически при назначении статуса.

В модалке статуса есть вкладки для шаблонов сообщений по каналам (Email / SMS / Push / Telegram) и RADIUS-параметров (если статус должен влиять на скорость или ACL клиента в авторизации).

Подраздел «Настройка статусов»

Правила автоматической смены статуса по событиям: платёж выше N руб → статус «Активный»; задержка платежа > N дней → статус «Должник»; истечение договора → статус «Архив». Правила применяются Celery-задачей раз в час.

7.8. Типы отчётов

Категории SQL-отчётов для разделения по ролям сотрудников: Техсервис, Руководство, Бухгалтерия, ЦОК, Телефония, Техподдержка, ЦУС. Каждый тип имеет цвет и иконку.

Управляется из этого справочника или прямо из Библиотеки отчётов кнопкой «Типы».

7.9. Единицы измерения

Словарь единиц измерения для услуг: МБ, ГБ, минуты, штуки. Используется в названиях услуг и в детализации расхода.

7.10. Периоды

Биллинговые периоды (обычно «месяц с 1-го по последний день»). Период определяет дату списания абонплаты, формирование отчётов, закрытие периода.