Биллинг. Основные настройки биллинга

Раздел описывает все семь пунктов главного меню админки СмИТ Биллинг — от тарификации и оборудования до справочников и работы с абонентами. Структура страницы повторяет структуру меню.

1. Дашборд

Главная страница админки по адресу /admin/welcome/. Перестроена в build 539–558 после /critique-аудита: иерархия KPI с hero-метрикой, единый визуальный язык компактных карточек (.dash-tile), все блоки скрываются автоматически при отсутствии данных.

Виджет SORM в правой колонке показывает статус выгрузок:

• Имя конфига → ссылка на /admin/equipment/sorm_list/<id>/
• Vendor (СпецТехПитон / СигналТек / ...)
• FTP-хост и путь
• Время выгрузки
• Бейдж с числом отчётов
• Статус последней выгрузки: ✓ зелёный N/M файлов / ⚠ оранжевый partial / ✗ красный provаl / ⏳ синий running
• Дата + кол-во строк + значок облака (✅ если ftp_uploaded)
• Сводка за 7 дней (счётчики success/partial/failed)

«Горячие абоненты» + «Платежи: день × час» теперь в одном ряду:

Карта абонентов (была пустой до v966):

Шапка: 6 KPI-карточек

Верхний ряд — финансовый/операционный обзор. Hero-карточка «Должников» в 2× ширину с явным CTA «Все должники →» (build 539, единственный btn-primary на странице — даёт глазу первую точку фиксации). Остальные 5 KPI равноценные:

• 🔵 Всего — все абоненты + топ-3 подкатегории (SMIT / Все / EBS-импорт)
• 🟢 Активных + бейдж «Заблокированных»
• 🟢 Серверов доступа (NAS) с подзаголовком «Онлайн сейчас»
• 🟠 Должников (hero) — с CTA
• 🟡 Открытых заявок + «за 30 дней / всего»
• 🔵 Новых за месяц + «за 7 дней»

Все 6 градиентов унифицированы на linear-gradient(135deg, A, B) в одной палитре (раньше было 4 разных рецепта).

IP-пулы + EBS Синхронизация

Две компактные карточки в одну строку (build 540, ~110px высоты вместо 200+):

• IP-пулы — сводка used / total (%, N пулов) + статус-pill (✓ В норме / ⚠ ≥90%: N / 🚨 Опасно при наличии пула ≥99%) + топ-3 «опасных» с горизонтальными mini-bar (красный/оранжевый/жёлтый).
• EBS Синхронизация — 3 строки cron-расписаний:
  • Импорт: каждые 10 мин, последний запуск + длительность + last tx_id
  • Сверка: раз в час, скорректировано N балансов
  • Абоненты: ежедневно 04:00 МСК, последний запуск + ETA до следующего

Унифицированные бейджи .dash-pill с цветовым кодированием (is-ok/is-warn/is-danger/is-info). JS-обновление каждые 60 сек через /admin/dictionary/ip_pull_stats/ и /admin/ebs_sync_status/.

Свежие проблемы (alerts feed)

Build 550. Отображается только при наличии алертов. Источники:

• 🔴 NAS DOWN сейчас — последний event=down per NAS из NasStatusLog, с возрастом события
• 🔴/🟡 IP-пул ≥99% / 100% через get_pool_stats(pool)
• 🟡 EBS sync failed за 24ч (status=failed в EBS_SYNC_STATE)
• 🟡 Backup failed за 24ч

Каждая строка кликабельна → ведёт в соответствующий раздел. Левый красный бордер 3px, максимум 6 алертов. Видна всем, не только cash-группе.

Касса месяца

Build 543–548. Расчёт по календарному месяцу (с 1-го числа) из FinanceOperations:

• Начислено — сумма всех op_summa < 0
• Оплачено — сумма всех op_summa > 0 (зелёный) + Δ-pill «темп vs тот же день прошлого месяца» («+17,4% к апрелю») + hint «прошлый месяц к N-му: X ₽»
• Прогноз закрытия — линейная экстраполяция paid × days_in_month / day_of_month (синий) + Δ-pill «к плану» + hint «прошлый месяц закрыли: X ₽»
• Прогресс месяца — цветной progress-bar (зелёный ≥100% / синий 70–99% / оранжевый <70%) + «N/M дн.»

Сверху справа бейдж «✓ Сбор N%» (зелёный/синий/оранжевый по тем же порогам). Видна только для группы cash.

Платежи сегодня vs вчера

Build 549. 4 ячейки + sparkline по часам:

• Платежей (count, шт) + hint «вчера к HH:00 — N»
• Сумма ₽ (зелёный) + hint «вчера — X ₽»
• Средний чек ₽ (бирюзовый) + hint «вчера всего: M / X ₽»
• По часам — 24 столбика sparkline за сегодня. Текущий час голубой с glow, будущие часы серые, оси 0/6/12/18/24.

В шапке — Δ-pill «к вчера» (≥+5% зелёный, ≤−5% оранжевый, иначе ≈ синий).

Горячие абоненты + CRM сегодня

Build 551–554. Две карточки в одной строке: «Горячие абоненты» (col-lg-8) + «CRM сегодня» (col-lg-4).

Горячие абоненты 24ч — скоринг и интерпретация

Топ-5 абонентов, кому стоит уделить внимание прямо сейчас. Алгоритм в billing/views/auth.py::welcome.

Скоринг (суммируется):

• Разрывы сессий за 24 часа (≥3 завершённых сессий): 3–9 → 30 pts, 10–29 → 40 pts, ≥30 → 60 pts
• Открытые тикеты (status 1=Открыта, 2=В работе) с обращением за 24 часа: 1 шт → 10 pts, ≥2 → 25 pts
• «Оплатил, но заблокирован» (b_negbal=true + положительный платёж сегодня) → 50 pts — критично, абонент заплатил, но биллинг не разблокировал

В блок попадают абоненты со score ≥ 15, отсортированные по убыванию. Цвет строки: ≥50 — красный, ≥25 — оранжевый, <25 — синий.

Что значат коды разрыва (END_REASON в RADIUS_SESSIONS):

• Lost-Carrier — NAS перестал видеть клиента: PPP-keepalive не пришёл, физический линк упал, или MikroTik сам разорвал по idle-timeout. Самый частый код у проблемных клиентов.
• User-Request — клиент сам инициировал отключение (PPPoE-disconnect от устройства абонента). Часто маршрутизатор «дёргает» PPP при потере WAN или по таймеру.
• NAS-Request — NAS принял решение отключить (CoA Disconnect, смена тарифа, остановка сервиса биллингом).
• Synthetic (no Start): User-Request — искусственный Stop-пакет, созданный radius_accounting.py, потому что NAS прислал Stop без предшествующего Accounting-Start. Бывает после рестарта FreeRADIUS или потери Start-пакета (build 450, async-accounting).
• Stale: no Interim-Update — наш cleanup-таск убил «зомби»-сессию: Interim-Update не приходил >10 минут.

Корневые причины (паттерны):

1. Массовые Lost-Carrier каждые 4–10 минут (100+ разрывов за сутки) — обрыв физики: гнилой коннектор RJ-45, плохая обжимка, попадание воды в муфту, проблема PoE-инжектора, MAC-конфликт на порту коммутатора. Это не баг биллинга и не пароль (тот дал бы Access-Reject). Действие: выезд монтажника на точку.
2. Десятки User-Request с короткими сессиями (~2 минуты) — клиентский роутер сам разрывает PPP. Возможно: двойной PPPoE-клиент в прошивке, жёсткий idle-timeout в настройках, скрипт автоматического переподключения. Действие: связаться с абонентом, проверить настройки роутера.
3. Lost-Carrier раз в 30–60 минут — нестабильный канал, наводки, перегрев SFP/коммутатора. Менее острый сигнал, но повод заявить в техобслуживание.
4. «Оплатил, но заблокирован» (50 pts) — смотрим в карточке последние FinanceOperations и AbonentsBlock. Обычно это сбой автоматики разблокировки после платежа. Жмём «Разблокировать» вручную, проверяем что в Celery-beat работает task recheck_blocks.

Что смотреть в карточке абонента:

• Вкладка «RADIUS» (build 469+) — последние 50 сессий с END_REASON, длительностью, IP, NAS. Главный диагностический инструмент.
• Вкладка «История» — кто и когда менял состояние блокировок.
• Вкладка «HelpDesk» — все тикеты абонента + быстрая ссылка в HelpDesk.

Состав строки в блоке: цветной score-badge → имя абонента (ссылка на карточку) → список причин («N разрывов», «тикет», «оплатил, но заблокирован») → баланс (красный если долг) → стрелка перехода в карточку.

CRM сегодня — сводка из HelpDesk (mailbox=1) за календарный день:

• Открыто — count createdAt >= 00:00
• Закрыто — count status=closed с updatedAt >= 00:00
• Среднее закрытие — avg(updatedAt − createdAt) для закрытых сегодня (мин/ч/д)
• Бейдж ⚠ Висят: N — активные старше 30 мин без assignee

Под цифрами — 3 последних тикета (build 554) с цветной точкой статуса (active/pending/closed/spam), темой #N · subject (truncate 60 симв, кликабельно → support.smit34.ru/conversation/<id>), абонент + исполнитель + возраст. Кеш 5 мин по ключу dashboard_crm_24h.

Heat-map + Цели + Что нового

Build 555–557. Три узких карточки в одной строке.

Heat-map платежей 7×24 (фиолетовая палитра) — день недели × час, цветовая интенсивность rgba(#6f42c1, alpha) от количества платежей. SQL:

SELECT EXTRACT(ISODOW FROM "OP_DATE"), EXTRACT(HOUR FROM "OP_DATE"), COUNT(*)
FROM finance_operations WHERE "OP_DATE" >= now() - 7 days AND "OP_SUMMA" > 0
GROUP BY 1, 2;

Hover увеличивает ячейку 1.4× с tooltip «N пл.». Помогает увидеть паттерн — например, пик платежей в Пн ~17:00.

KPI с целями — читает SystemSettings:

• DASH_MONTHLY_REVENUE_TARGET — план кассы за месяц (₽)
• DASH_ACTIVE_ABONENTS_TARGET — план активных абонентов
• DASH_NEW_MONTH_TARGET — план подключений за календарный месяц

Без таргетов карточка скрыта. Цветной progress-bar (зелёный ≥100% / синий ≥70–80% / оранжевый ниже). Меняются через /admin/settings/system/?tab=params (категория dashboard) без релиза.

Что нового — 2 секции из dev_reports/ (build 557):

• Отчёты — 4 свежих .md файла из подкаталога «Отчёты» (по mtime DESC). Заголовок = первая Markdown H1 строка.
• Планы — 4 свежих из подкаталога «Планы».

Каждая запись с нумерацией 1–4, кликабельна → /admin/reports/dev/?file=<path>. Подкаталог Документация исключён.

Итого за период + Финансовая динамика (старые блоки)

Сохранены: 3-row «Итого за период» (Поступления/Списания/Баланс с дельтами) и линейный график «Финансовая динамика» с переключателями типа (Область/Линия/Столбцы) и периода (7д/14д/30д/90д/180д/1г). Кнопки в чистом стиле (build 542 — фикс «серой губой» заливки .btn-outline-secondary).

Auto-refresh

Переключатель в шапке: Выкл / 30с / 1м / 2м / 5м / 10м. Состояние сохраняется в localStorage.dashboard_refresh_sec. Дефолт — выкл. Кнопка «Обновить сейчас» и таймер «Просмотрено: N сек/мин назад» рядом.

2. Тарификация

Раздел меню «Тарификация» содержит всё, что связано с услугами, которые получают абоненты, и правилами их тарификации.

Тарифы — назначение и роль

Тариф (Tarif) — это шаблон услуг и цен, которые получает абонент после подключения. Хранится в таблице tarif, редактируется на /admin/tarifs/Tarif/.

Зачем нужен тариф

Тариф решает три задачи:

1. Группировка услуг — один тариф = пакет из 1-N услуг (интернет 100 Мбит + IPTV + статический IP) с заданными ценами;
2. Автоматическое списание — Celery-задача billing_worker раз в день обходит активных абонентов, выбирает их тариф, проходит по списку услуг и списывает с лицевого счёта;
3. Применение шейпера — через TarifRadiusParams FreeRADIUS получает атрибут Mikrotik-Rate-Limit или аналог. На NAS включается ограничение скорости.

Структура: Tarif + TarifUsersUsluga

Как биллинг использует тариф

1. Привязка к абоненту: Abonents.TARIF_ID (главное поле), опционально Users.TARIF_ID для специальных учёток;
2. Ежемесячное списание (billing_worker.py):
   • Берёт abonent.tarif.tarif_tuu.all() — все услуги тарифа;
   • Для каждой услуги ищет соответствующую UsersUsluga у абонента (или создаёт новую);
   • Списывает каскадно: UsersUsluga.summ → usluga.summa → usluga.price (берётся первое заполненное);
   • Создаёт FINANCE_OPERATIONS с op_type=32 (тарифное списание);
3. RADIUS: при авторизации FreeRADIUS подгружает TarifRadiusParams и отдаёт NAS-у соответствующий шейпер.

Архивирование vs удаление

• IS_ARCHIVE=true — тариф недоступен для назначения новым абонентам, но текущие подписчики продолжают на нём работать. Это правильный путь для устаревших тарифов;
• Удаление — почти невозможно, FK PROTECT блокирует если есть хоть один абонент или один TUU. Можно удалять только если 0 ссылок;
• Перевод абонентов на новый тариф — массовое действие в глобальном поиске /admin/Abonents/search/ (chip «Тариф» + bulk action change_tarif).

Специальные сценарии

2.1. Тарифы

Список всех тарифных планов оператора. Открывается из меню Тарификация → Тарифы. Над таблицей — два фильтра по типу клиента: «Бизнес» и «Физ.лица» (по признаку «Для юр.лиц» у тарифа). Рядом — счётчик количества тарифов в текущем фильтре.

Toolbar над таблицей:

• Поиск по имени, описанию или ID тарифа. Шорткат Ctrl+K ставит фокус в поле.
• Кнопка «Компактный вид» уменьшает плотность строк и скрывает столбец «Описание».
• Кнопка «CSV» экспортирует видимый срез (с учётом фильтра Бизнес/Физ.лица, поиска и линейки).
• Кнопка «Добавить тариф» открывает модальное окно нового тарифа.

Колонки таблицы:

• Название с подсказкой ID при наведении.
• Цена в рублях.
• Линейка услуг (см. 1.6).
• Юр.лиц — иконка ✓ если тариф предназначен только организациям.
• Абоненты: основное число + красный ▼N (заблокированные). Tooltip разворачивает разбивку Активных / Заблокированных / Всего.
• Привязок — сколько услуг привязано к тарифу.
• Действия: ✏ редактировать, 🗑 удалить (заблокировано если есть активные абоненты).

Сортировка работает по любому столбцу — клик по заголовку. Активная сортировка выделяется синим цветом и стрелкой ▲/▼.

Bulk-операции — выберите тарифы галочками, появится плавающий тулбар со следующими действиями: В архив, Из архива, привязка к Линейке, CSV-экспорт выбранных, Удалить. Удаление блокируется на сервере, если у тарифа есть активные абоненты — выводится список ID, которые надо сначала перевести на другой тариф.

Модальное окно тарифа делится на четыре верхних вкладки (Основное / Услуги / RADIUS / Абоненты) и пять секций левой side-nav во вкладке «Основное». В шапке модалки бейдж «Назначено абонентам: N». На мобильном side-nav становится горизонтальным скроллбаром.

Вкладка «Основное» → секция «Общее»

Идентификация тарифа: название, описание, валюта, привязка к линейке услуг и оператору связи, флаг «Введён в эксплуатацию», «Архивный», «Отображать на сайте», период действия. Цена считается автоматически по сумме привязанных услуг.

Секция «Лимиты»

Объёмы и пороги: лимит трафика (ГБ/мес), число подключений, число VPN-сессий, размер скидки за неиспользование. Используется в комплекте с услугами типа «Трафик».

Секция «Смена тарифа»

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

Секция «ОП и Доб. блок»

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

Секция «NAT и прочее»

NAT-пулы (для трансляции серых IP в публичные), параметры RADIUS-атрибутов, дополнительные сетевые настройки. На большинстве тарифов остаётся пустой — заполняется только если используется специфическая сетевая логика.

Вкладка «Услуги»

Список услуг, привязанных к этому тарифу. Сюда добавляются абонплата, бонусы по умолчанию, шейпер. Цена тарифа = сумма цен этих услуг (с учётом методов и периодичности).

Вкладка «RADIUS»

RADIUS-атрибуты, которые попадают в Access-Accept абонентов на этом тарифе: ограничение скорости (Mikrotik-Rate-Limit), ACL (Filter-Id), pool name и т.д. Эти значения уходят на NAS и определяют поведение сети для абонента.

Вкладка «Абоненты»

Список абонентов, которые сейчас на этом тарифе. Можно перейти в карточку кликом по имени, либо массово перевести группу на другой тариф.

Услуги (Usluga) — назначение и роль

Услуга (Usluga) — атомарная единица биллинга: то, что списывается со счёта (абонплата, статический IP, IPTV-пакет) или начисляется (бонус, компенсация). Хранится в таблице usluga.

Зачем нужна услуга

Услуга решает три задачи:

1. Списание с баланса — раз в месяц billing_worker создаёт FinanceOperations на сумму услуги и уменьшает OSTATOK;
2. Применение скорости через шейпер — поля RATE_IN, RATE_OUT попадают в RADIUS-ответ как Mikrotik-Rate-Limit;
3. Бонусирование — услуги с отрицательной ценой или системные (system_type) выполняют разные роли: ОП, акции, компенсации.

TUU (шаблон) vs UsersUsluga (экземпляр)

Один usluga может фигурировать в нескольких TUU (для разных тарифов) и иметь много UU (по одной на каждого подписчика). Удаление usluga заблокировано FK PROTECT, если есть хоть один TUU или UU.

Каскад цены

Когда billing_worker списывает абонплату, он берёт цену из первого заполненного источника (build 101):

1. UsersUsluga.summ — индивидуальная скидка/цена для конкретного абонента;
2. Usluga.summa — стандартная сумма услуги;
3. Usluga.price — fallback цена (часто за единицу, например за Мбайт трафика).

В UI это видно в списке услуг: если используется fallback, цена подсвечена оранжевым с tooltip «эффективная цена: X ₽ / источник: Usluga.price».

Системные услуги

Несколько услуг имеют особое поведение, защищены от удаления и не показываются в обычных списках:

Поле system=true у услуги — флаг «не показывать абоненту в счётах», даже если списывается.

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

• Не используется ни в TUU, ни в UU — кандидат на удаление. Можно удалять через UI;
• Используется в TUU — сначала уберите её из тарифов (или архивируйте тарифы);
• Используется в UU — отвяжите от абонентов или дождитесь пока услуга выключится по сроку;
• Системные (id 30353/30280) — не удалять никогда, потеря этих записей сломает ОП и системные функции.

SELECT u.* FROM usluga u
WHERE NOT EXISTS (SELECT 1 FROM "USERS_USLUGA" WHERE "USLUGA_ID"=u."ID" AND "DELETED"=false)
  AND NOT EXISTS (SELECT 1 FROM "TARIF_USERS_USLUGA" WHERE "USLUGA_ID"=u."ID")
  AND u."ID" NOT IN (30353, 30280) AND u."ID" >= 0;

2.2. Услуги и Бонусы

Услуги — то, что списывается с лицевого счёта (абонплата, доп. услуги, разовые работы). Бонусы — то, что начисляется на счёт (компенсации, скидки, акции). Для оператора это один справочник, разделённый по знаку суммы и типу.

Toolbar:

• Вкладки по типам (абонплата, разовая, бонус, обещанный платёж и т.д.); вкладка «Все» показывает полное имя.
• Чип «Не привязанные» с счётчиком — показывает услуги-сироты, которые не используются ни в одном тарифе и ни одним абонентом. Полезно для уборки справочника.
• Поиск по имени, тарифу или точному ID.

Колонки таблицы:

• Услуга — название с тултипом ID.
• Эфф. цена — итоговая цена, рассчитанная по каскаду: индивидуальная сумма абонента → шаблон summa у услуги → шаблон price у услуги. Если используется fallback — цена показана оранжевым с подчёркиванием, а в tooltip написан источник. Пустое значение «—» означает что услуга бесплатна или цена назначается индивидуально.
• Метод — иконка fa-sync (Ежемесячно) или fa-bolt (Разово).
• В ЛК — отмечены услуги, которые абонент видит в личном кабинете.

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

Модальное окно услуги делится на 6 секций (вертикальная навигация слева). Открывается кликом по карандашу в строке списка.

Секция «Основные»

Название, тип услуги (трафик / IP-телевидение / стандартный / бонус / обещанный платёж / системный), цена, валюта, тип абонплаты (помесячно / разово / детализированно). Также — флаг «Включена», описание для оператора.

Секция «Периодичность»

Когда услуга списывается. Варианты: ежемесячно (1-го числа или произвольная дата), разово (при подключении), в определённые дни месяца (1-го + 15-го), при превышении лимита. Дополнительные параметры: количество периодов, дата окончания, сдвиг даты списания.

Секция «ЛК абонента»

Отображение услуги в личном кабинете абонента: видимое имя, иконка, описание, флаг «Доступна для подключения через ЛК» (абонент может сам её включить), флаг «Видна» (только показывать без возможности изменения).

Секция «Скидки»

Условия скидок при подключении услуги: фиксированная сумма / процент, условия применения (для определённых тарифов или типов абонентов), даты действия скидки.

Секция «Шейпер»

Параметры ограничения скорости (только для услуг типа «Трафик»). RX/TX скорости, burst-параметры, размер очереди. Эти значения попадают в RADIUS-атрибут Mikrotik-Rate-Limit или аналогичный для других вендоров.

Секция «Связи»

Привязка к подсети (Tariff Ruleset — для специальной тарификации в локальной сети) и к типу услуги (используется в RADIUS-фильтре и СОРМ-выгрузке).

2.3. Правила и сети

Подсети, которые тарифицируются по особым правилам — например, локальный ресурс с собственной ценой за ГБ, отдельный шейпер для торрентов, белая сеть для корпоративных абонентов.

Параметры записи:

• Имя и комментарий.
• Цена входящего и исходящего трафика (за ГБ).
• Лимит — суточный/месячный объём в МБ/ГБ.
• HTTP-адрес — URL локального ресурса (для статистики и отчётов).

Удалить запись нельзя, если она используется в услугах — счётчик «Услуг» в строке показывает количество ссылок.

2.4. Карты оплаты

Серии бумажных карт оплаты с PIN-кодами. Каждая серия — это пакет карт номинала N₽ с уникальными PIN. Абонент пополняет счёт, введя PIN в личном кабинете или через кассу.

Серия определяется: имя серии, номинал, количество карт, дата выпуска, дата окончания действия. PIN-коды генерируются автоматически и выгружаются в PDF/CSV для печати.

Программы лояльности — назначение и роль

Программа лояльности — механизм скидок, акций и спец-условий для группы абонентов. Реализуется двумя моделями: Loyaltys (сама программа = шаблон) и AbonentsLoyalty (привязка абонента к программе = экземпляр).

Зачем нужна лояльность

Программы решают четыре задачи:

1. Скидки — социальные тарифы (пенсионеры, многодетные), корпоративные скидки, акции «приведи друга»;
2. Спец-условия для группы — например, «жильцы дома №15 платят на 100 ₽ меньше за интернет» (распределённая по адресу программа);
3. Бонусы за продление — «оплатил год вперёд → 10% скидка»;
4. Учёт в финансовых отчётах — отдельная строка «Скидки по программам лояльности».

Модели

Приоритет и применение

Один абонент может попасть в несколько программ одновременно (например: пенсионер + жилец акционного дома). При начислении скидки выбирается одна:

• Поле priority у Loyaltys — целое число. Выше = раньше применяется;
• Цветовое кодирование в UI:
  • ≥ 100 — красный бейдж «критично» (типа «соцтариф для всех»);
  • ≥ 50 — оранжевый «важно» (корпоративные);
  • < 50 — серый (обычные акции).
• Применение в billing_worker: при начислении тарифа проверяются все активные AbonentsLoyalty абонента, выбирается с максимальным priority, скидка применяется к op_summa.

Связь с линейками услуг

Поле Loyaltys.usluga_range (FK на UslugaRangeTypes) ограничивает применимость:

• Если usluga_range = NULL — программа применяется ко всем услугам тарифа;
• Если usluga_range = X — только к услугам в линейке X (например, скидка только на интернет, не на IPTV);
• Это требует, чтобы Tarif.usluga_range_type_id у тарифа абонента совпадал с Loyalty.usluga_range_id;
• См. подробнее в 2.6 Линейки услуг.

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

• Программа закончилась (срок акции прошёл) — выключить через enabled=false вместо удаления. Нельзя удалить, если есть активные AbonentsLoyalty (build 325 защита);
• Завершить программу для всех — перед удалением программы проставить end_date у всех AbonentsLoyalty. Тогда программа становится «архивной» и удаляется;
• Удалить отдельную привязку — кнопка в карточке абонента, вкладка «Лояльность». Это не удаляет программу, только конкретную привязку.

2.5. Программы лояльности

Программа лояльности — это скидка или специальные условия для определённой группы абонентов: социальный тариф, корпоративные клиенты, многоквартирный дом, пилотный район.

Параметры программы:

• Имя и комментарий.
• Приоритет — чем выше число, тем раньше применяется (≥100 — критично, красный бейдж; ≥50 — важно, оранжевый; меньше — серый).
• Оператор — на которого распространяется (для агентских схем).
• Линейка услуг — каким услугам применяется скидка.
• Параметры скидки — процент или фиксированная сумма.

В модалке программы есть две вкладки:

• Параметры — настройка самой программы.
• Абоненты — список абонентов на программе, массовое назначение и снятие.

Программа применяется автоматически при ежемесячном списании. Назначить программу абоненту вручную можно из карточки абонента, вкладка «Лояльность». Удаление программы заблокировано, если есть активные участники.

2.6. Линейки услуг

Линейка услуг (модель UslugaRangeTypes) — это группа тарифов и услуг одного оператора связи или одной целевой аудитории. Линейка решает две задачи: логически разграничить тарифные планы между юр.лицами-операторами на одной инсталляции биллинга и технически ограничить, какие тарифы попадают в выпадающие списки в личном кабинете абонента и в программах лояльности.

Примеры использования

• Разделение по аудиториям: «Физические лица», «Юридические лица», «Социальные тарифы» — каждой линейке привязаны свои тарифы. В Quick Add абонента линейки переключаются автоматически вместе с флагом «Юр.лицо» (см. раздел 7.1).
• Несколько операторов на одной инсталляции: «СмИТ Волгоград», «СмИТ Камышин», «Малдер-связь». Оператор-инсталлятор обслуживает несколько юр.лиц с одним биллингом, у каждого свой набор тарифов. В отчётах СОРМ выгрузка идёт по оператору-владельцу линейки.
• Промо-кампании: «Акция «Лето 2026»», «Тарифы для пенсионеров» — отдельная линейка содержит только промо-тарифы; в программах лояльности (Loyaltys) включается через поле usluga_range, и абонентам с этой лояльностью становится доступен льготный тариф.
• Технические/служебные тарифы: линейка «Внутренние» — для сотрудников, тестовых учёток, оборудования. Не показывается в ЛК обычных абонентов через настройку LK_TARIFF_REQUIRE_RANGE.

Модальное окно «Добавить / Редактировать линейку»

Открывается кнопкой «Линейка» в правом верхнем углу списка или иконкой карандаша в строке таблицы (urtModal в шаблоне usluga_range_types_list.html). Поля:

• Название * — текст, как будет отображаться в селектах при создании тарифа и программы лояльности. Примеры: «Бизнес-линейка», «Эконом физ.лица», «Промо Лето 2026».
• Оператор — выпадающий список абонентов из служебной папки «Операторы» (id = 9002). Это юр.лицо, владеющее линейкой: именно ему уходит выручка по тарифам этой линейки в финансовой отчётности и СОРМ-выгрузках. Можно оставить пустым («не указан») — тогда линейка считается общей.

Сохранение через POST /admin/tarifs/range_types_crud/ (или /<id>/ для редактирования). Удаление — DELETE /admin/tarifs/range_types_crud/<id>/; защищено: если на линейку ссылается хотя бы один тариф или программа лояльности, сервер вернёт ошибку с понятным текстом.

Колонки списка

• # — внутренний ID линейки (используется во внешних интеграциях и SQL-отчётах).
• Название — заголовок линейки.
• Оператор — связанный абонент-юр.лицо или прочерк.
• Тарифов — счётчик тарифов с этой линейкой (Tarif.usluga_range_type_id). Синий бейдж, если есть привязки; серый, если линейка пустая. Клик по тарифу в карточке открывает модалку правки тарифа с предзаполненной линейкой.
• Лояльности — счётчик программ лояльности (Loyaltys.usluga_range_id). Жёлтый бейдж, если есть привязки.
• Действие — карандаш (правка) и корзина (удаление с проверкой ссылок).

В шапке списка — поиск (Ctrl+K) по названию или оператору и счётчик отфильтрованных линеек. На мобильном — горизонтальный скролл таблицы.

Связи и где используется

• Тариф (Tarif.usluga_range_type) — поле «Линейка» на форме редактирования тарифа. Один тариф может принадлежать одной линейке.
• Программа лояльности (Loyaltys.usluga_range) — определяет, какой набор тарифов доступен участнику программы.
• Личный кабинет — настройка LK_TARIFF_REQUIRE_RANGE (ЛК → Возможности) включает фильтрацию: абоненту в ЛК показываются только тарифы из той же линейки, что и его текущий тариф. Полезно когда у одной инсталляции несколько операторов и нельзя смешивать тарифы.
• Quick Add абонента (7.1) — при включении чекбокса «Юр.лицо» автоматически отбираются тарифы с признаком is_business=True; линейка же определяет, какому оператору такой тариф принадлежит.

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

Раздел меню «Оборудование» объединяет всё сетевое и абонентское оборудование, через которое работает биллинг.

3.1. NAS

Список всех NAS (Network Access Server) — серверов доступа: BRAS, MikroTik, Cisco, Redback и т.п. NAS — это «сетевой шлюз», через который абонент выходит в интернет.

Карточки KPI над таблицей: Всего NAS / UP / DOWN / Абонентов онлайн. Кликом по карточке-ссылке можно перейти на дашборд состояния (см. 2.2).

Чипы-фильтры: Все · UP · DOWN · Без RADIUS · Без SSH · PROD · Выключенные. Состояние сохраняется в URL (?chip=down) и можно поделиться ссылкой.

Колонки таблицы:

• Состояние (UP / DOWN / OFF) с тултипом длительности простоя.
• Имя и IP NAS, тип оборудования.
• Онлайн — прогресс-бар занятости пула: зелёный <75%, оранжевый 75–90%, красный ≥90%. Клик по числу открывает модалку со списком абонентов в активной сессии.
• Действия: тест ping, синхронизация сессий, ✏ редактирование, 🗑 удаление.

Подсветка строк: DOWN — красноватый фон, выключенные — приглушённый цвет, без RADIUS/SSH — оранжевая полоса слева, PROD — зелёная.

Кнопка «Перезапустить RADIUS» появляется в шапке после правки настроек NAS. Биллинг помечает изменения флагом radius_dirty; кнопка пропадает, когда рестарт выполнен и FreeRADIUS перечитал клиентов.

Модалка «Онлайн абоненты»

Клик по числу в колонке «Онлайн» открывает список абонентов с активной RADIUS-сессией на этом NAS. Полезно для оперативной диагностики — узнать кто сейчас онлайн, какой IP получил, когда стартовала сессия.

В модалке: поиск по логину/ФИО/договору/IP, ссылки-абоненты в карточку (открывают новую вкладку), лог IN, IP-адрес из RADIUS-сессии, время начала и последнего обновления. Кнопки «Обновить» и «Закрыть». Подгружается до 100 строк за раз со скроллом для подгрузки следующих.

Модалка редактирования NAS — 6 вкладок

Карандаш в строке открывает большую модалку с шестью вкладками для всех настроек NAS.

Вкладка «Основное» — общие параметры: название, IP, маска, тип NAS (Mikrotik/Cisco/Redback…), адрес физической установки, серийный номер, регистрационный №, код активации, флаги «Включён» и «В эксплуатации». В шапке модалки бейджи «Активных» / «Макс» / «Авт» для быстрой оценки нагрузки.

Вкладка «RADIUS» — параметры аутентификации: secret-ключ, порты Auth/Acct/CoA, IP для CoA Disconnect, флаги поддержки разных RADIUS-возможностей. Эти данные FreeRADIUS читает из БД и формирует clients.conf при старте.

Вкладка «Авторизация» — параметры подключения абонентов: типы аутентификации (PPPoE / IPoE / Hotspot / 802.1x), VPN, тегирование VLAN, поведение при отсутствии IP в пуле.

Вкладка «Управление» — SSH/Telnet-доступ для дистанционного управления: адрес, порт, протокол, логин и пароль, тип ОС (для подбора шаблонов команд). Используется при ручном обращении к NAS из админки и в OSS-задачах (см. вкладка «OSS»).

Вкладка «IP-пулы» — какие пулы IP-адресов доступны NAS для выдачи абонентам. Можно назначить отдельные пулы для разных ролей: основной (PPPoE), NAT, белые IP (corporate), Hotspot. Если пул исчерпан, биллинг ходит по цепочке next_pull.

Вкладка «OSS» — Operations Support System: автоматизация управления. Активация и деактивация абонентов через шаблоны команд (включить/выключить порт, сменить VLAN, обновить ACL). Команды отправляются через SSH/Telnet, описанные на вкладке «Управление».

Внизу модалки — кнопка «Полная форма» (открывает развёрнутую страницу со всеми низкоуровневыми параметрами), «Удалить» (с подтверждением), «Отмена» и «Сохранить».

3.2. Состояние NAS

Дашборд мониторинга всех NAS в реальном времени. Открывается из меню Оборудование → Состояние NAS. Делится на две вкладки: «Текущее состояние» и «История событий».

Вкладка «Текущее состояние»

Сводка по всем NAS на текущий момент: статус UP/DOWN, длительность последнего простоя, абоненты онлайн, sparkline за 24 часа, SLA-показатели.

Возможности вкладки:

• KPI-блок сверху: всего NAS, UP, DOWN, общее число онлайн-абонентов.
• Алерт-баннер вверху появляется, как только хотя бы один NAS переходит в состояние DOWN. Содержит список упавших NAS, длительность простоя и число затронутых абонентов.
• Sparkline 24 часа в каждой строке — 24 столбика по часам: зелёный (UP всё время), оранжевый (частичный простой 5–50%), красный (≥50% времени DOWN).
• SLA-цели настраиваются в общих параметрах: цель 99.5% и предупреждение 99.0%. При падении ниже строка получает соответствующую подсветку.
• Auto-refresh — выключатель и выбор интервала: 30 сек / 1 мин / 5 мин. Обновление без перезагрузки страницы (только tbody + KPI).
• Кнопка «Обновить» рядом с auto-refresh для ручного триггера.
• CSV-экспорт состояний за выбранный период (сутки / неделя / месяц).
• Telegram-индикатор в шапке показывает, включены ли алерты в чат оператора.
• Затронутые абоненты — клик по числу открывает модалку со списком сессий (та же, что в разделе 2.1).

Вкладка «История событий»

Лента всех переходов UP↔DOWN за последние дни. Каждое событие — это запись в таблице NAS_STATUS_LOG: дата/время, NAS, тип события (DOWN или UP), длительность простоя (только для UP-событий), детальное описание.

Возможности вкладки:

• Группировка по дням со sticky-заголовком даты и счётчиком событий.
• Фильтр на клиенте: Все / Только DOWN / Только UP.
• Каждая запись связана с записью в Аудите (drill-down по клику).
• По умолчанию показываются последние 50 записей. Старые события удаляются автоматически (см. 5.12. Очистка БД и сессий).

На основе истории строится SQL-отчёт «NAS uptime за 30 дней» в библиотеке отчётов (см. 3.2) — таблица uptime% по каждому NAS с количеством падений и общим простоем в минутах.

Кэш авторизаций (Redis fast-path для FreeRADIUS)

Виджет на дашборде «Состояние NAS». Решает проблему массового падения NAS: когда тысячи абонентов одновременно переавторизуются, FreeRADIUS не успевает обрабатывать пакеты из-за серии SQL-запросов на каждый Access-Request.

Без кэша один authorize() делал 5 SQL-запросов: Users + abonent + nas + NasRadiusParams + TarifRadiusParams + VpnConst, суммарно 5–15 ms на пакет. При 1000 пакетов/сек FreeRADIUS не успевал, очередь max_requests=16384 заполнялась за 16 сек, NAS retry'ил пакеты, БД захлёбывалась.

С кэшем (build 524+): при штатной авторизации (не заблокирован, NAS назначен, IP в пуле) ответ строится из снапшота в Redis — 1 ms вместо 10 ms, SQL не выполняется. Эффективная capacity FreeRADIUS Python module растёт в 5–10 раз.

Архитектура

• Сервис: billing/services/radius_user_cache.py
• Ключи Redis:
  • radius_user:{login} — снапшот, TTL 5 мин
  • radius_user_neg:{login} — маркер «не найден», TTL 60 сек (защита от перебора)
  • radius_cache_stats (HSET) — счётчики hits/misses/negatives/invalidations
• Содержимое снапшота: user_id, psw, enabled, ip, nas_id, abonent_tarif_id, объединённый список reply_attrs из NasRadiusParams + TarifRadiusParams

Fast-path vs Slow-path

Fast-path (новый, без БД) активируется только при штатных условиях: enabled=True, abonent_enabled=True, есть пароль и NAS, ip в пулах NAS. Иначе срабатывает slow-path с ORM — для блокированных абонентов (нужна логика soft-block), OPT82, auto-assign NAS/IP, cache miss. После успешного slow-path снапшот пишется в кэш для следующих пакетов.

flowchart LR
    REQ["Access-Request
от NAS"] --> CACHE{"Снапшот
в Redis?"}
    CACHE -->|"hit"| CHKFAST{"Штатные
условия?"}
    CACHE -->|"miss"| PWD{"Пароль
верный?"}
    CHKFAST -->|"да · fast-path 1 ms"| OK["RLM_MODULE_OK
+ Framed-IP
+ Rate-Limit"]
    CHKFAST -->|"нет"| PWD

    PWD -->|"нет"| REJ["REJECT"]
    PWD -->|"да · slow-path ~10 ms"| TARIF{"tarif_id?"}
    TARIF -->|"NULL"| REJT["REJECT
no tariff"]
    TARIF -->|"есть"| BLOCK{"Заблоки-
рован?"}
    BLOCK -->|"да"| SOFT["soft-block
блок-пул"]
    BLOCK -->|"нет"| WRITE["Снапшот → Redis
TTL 5 мин"]
    WRITE --> OK
    OK --> AB(("Абонент
в сети"))

    style REQ fill:#1e3a5f,stroke:#5BA89D,color:#fff
    style CHKFAST fill:#14532d,stroke:#16a34a,color:#fff
    style OK fill:#43b77a,stroke:#2d9a5f,color:#fff
    style REJ fill:#7f1d1d,stroke:#dc2626,color:#fff
    style REJT fill:#7f1d1d,stroke:#dc2626,color:#fff
    style SOFT fill:#78350f,stroke:#d97706,color:#fff
    style AB fill:#134e4a,stroke:#43b77a,color:#fff

Инвалидация

5 Django signals (post_save) сбрасывают соответствующие ключи:

Дополнительно — TTL 5 минут гарантирует протухание даже без сигналов (защита от рассинхрона при ручном UPDATE через psql).

Метрики и UI

Виджет «Кэш авторизаций» на дашборде «Состояние NAS» показывает:

• Hits — попадания в кэш (1 ms, без БД)
• Misses — промахи (10 ms через ORM)
• Hit ratio % — целевое значение > 90% (после прогрева)
• В кэше — количество ключей radius_user:* в Redis
• Инвалид — счётчик сбросов по сигналам
• Кнопка «Сбросить» (для superuser) — полный flush, например после массового импорта Users

Endpoint: GET /admin/equipment/radius_cache_stats/ возвращает JSON с метриками. POST /admin/equipment/radius_cache_flush/ сбрасывает весь кэш (только superuser).

Реальная статистика testbill через 5 минут после деплоя build 524 при штатной нагрузке ~10–20 авторизаций/сек: hits=838, misses=92, hit ratio=90.1%. При hit ratio 90% среднее время authorize() снизилось с 10 ms до ~2 ms, эффективная пропускная способность выросла в ~5 раз без увеличения ресурсов.

RADIUS REJECT без тарифа (build 772+)

Защита от бесплатного интернета у абонентов без тарифа. До фикса абонент с Abonents.TARIF_ID=NULL авторизовывался в RADIUS, получал IP и нерезаную скорость канала (без Mikrotik-Rate-Limit). Параллельно billing_worker его не списывал — у абонента без тарифа нет связанных UsersUsluga.

Симметричная дыра: интернет работал бесплатно, пока кто-то не назначит тариф вручную. Полный отчёт о баге: dev_reports/Отчёты/2026-05-13_CRIT_RADIUS_пускает_без_тарифа.md.

Логика после фикса (radius_python/internet.py::authorize и _try_authorize_from_snapshot):

• После проверки пароля проверяется user.abonent.tarif_id
• Если NULL → RLM_MODULE_REJECT с пометкой no tariff assigned
• Fast-path (Redis cache) тоже валидирует tarif_id из snapshot — иначе fall-through на slow-path → REJECT

Quick Add (создание абонента) — валидация на billing/views/abonents.py::abonent_quick_add: поле «Тариф» помечено required, при пустом значении возвращается HTTP 400 с сообщением «Тариф обязателен — выберите тариф для нового абонента».

Management-команда зачистки «осиротевших»:

python manage.py disable_abonents_without_tariff --dry-run
python manage.py disable_abonents_without_tariff --apply

Команда находит активных абонентов с TARIF_ID IS NULL и блокирует их через ab.block(comment='Автоблок: нет назначенного тарифа', flags=['b_sys']). На testbill 2026-05-13 нашла 72 таких абонента (6 с активной RADIUS-сессией, суммарно ~12 ГБ нерезаного трафика).

Telegram-алерт (опционально): Celery beat-задача раз в час шлёт уведомление, если за последние 24 часа создан абонент с tarif_id IS NULL. Защита на случай если основной REJECT кто-то откатит.

В разделе «Диагностика связи» (карточка абонента) добавлена красная плашка «⚠ Тариф не назначен — RADIUS должен отклонять авторизацию» — оператор видит проблему сразу при открытии карточки.

3.2А. Мониторинг оборудования

Оборудование → Мониторинг оборудования, URL /admin/equipment/monitoring/. Опрос управляемых коммутаторов по SNMP: состояние (в сети / не отвечает), число активных портов, история падений. Биллинг опрашивает устройства сам, раз в 5 минут, и присылает алерт в Telegram при падении.

Дашборд состояния

Над таблицей — счётчики Всего / В сети / Не отвечают / Неизвестно. В таблице по каждому устройству:

• Статус — цветная точка: зелёная «в сети», красная «не отвечает», серая «неизвестно» (ещё не опрашивалось).
• Порты — прогресс-бар и счётчик активных портов (например, 29 / 48).
• Модель — определяется автоматически из ответа устройства (sysDescr).
• Последний опрос — время последнего успешного опроса.
• Действия: опросить сейчас, снять MAC портов, пауза, удалить.

Ниже — блок «Последние события» с историей падений и восстановлений (время, устройство, событие, длительность простоя).

Добавление устройства

Кнопка «Добавить устройство» открывает окно выбора коммутатора (показываются записи с заполненным IP, ещё не под мониторингом), SNMP community и интервал опроса. После добавления устройство попадает в очередь опроса автоматически.

Отображение на карте сети

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

MAC на портах (кто где подключён)

Кнопка «Снять MAC портов» читает у коммутатора таблицу MAC-адресов по портам и сопоставляет их с MAC-адресами абонентов в биллинге. Совпавшие записи показывают, на каком физическом порту (и в каком VLAN) подключён конкретный абонент. Точность зависит от того, насколько заполнены MAC-адреса в карточках абонентов.

3.3. IPTV

Тот же список NAS, но отфильтрованный по типу оборудования IPTV-серверы: middleware и stream-серверы провайдера (TVIP Media, LFStream «Смотрёшка»).

Привязка пакетов IPTV к услугам биллинга настраивается отдельно — в разделе Настройки → IPTV-пакеты (см. 5.6).

3.4. Коммутаторы

Список всех коммутаторов в сети оператора. Записи используются для:

• Привязки точек подключения абонентов (порт коммутатора + VLAN).
• DHCP Option 82 — распознавание абонента по физическому подключению.
• Генерации конфигов и SORM-отчётов.

В списке доступны поиск, модальное добавление/редактирование/удаление. Колонка «Тип» показывает модель коммутатора (бренд + серия) и скрывается на мобильном.

3.5. Типы коммутаторов

Шаблоны типов коммутаторов: бренд, модель, число портов, наличие Opt82. Используется при создании коммутатора чтобы не вводить параметры вручную.

3.6. Настройки СОРМ

Список конфигураций выгрузки данных в СОРМ-3 на FTP-сервер РКН. Каждая конфигурация определяет: имя оператора СОРМ, FTP-сервер, расписание выгрузки, набор отчётов.

3.7. Карта сети

Интерактивная GIS-карта сети оператора на Leaflet: узлы (PoP / боксы / муфты / опоры / колодцы / шкафы / NAS), оптические трассы с классами (магистраль / распределение / абонентская), зоны покрытия, точки подключения, а также заявки Поддержки и мониторинг состояния NAS — всё на одном слоистом полотне. URL: /admin/equipment/netmap/. Меню: Оборудование → 🗺 Карта сети.

Слои и тулбар

• 6 переключаемых слоёв: Узлы · Оборудование · Трассы · Зоны · Точки (точки подключения, ~3.5к — рисуются лениво) · Заявки. Кнопка-чип подсвечивает активный слой.
• Статистика отдельной строкой: число узлов, единиц оборудования, трасс и суммарная длина волокна (км).
• Мониторинг NAS (кнопка «Монитор») — наложение состояния UP/DOWN на маркеры NAS, авто-обновление каждые 30 с, счётчик онлайн-абонентов.
• Режим редактора (кнопка-карандаш) — рисование/перетаскивание объектов (Geoman): маркер = узел/бокс, линия = трасса, полигон = зона.
• Обновить — перезагрузка данных без перезагрузки страницы.
• Поиск по оборудованию/адресу через выпадающий список.

Оптические волокна и трассировка

Трасса хранит структуру кабеля по стандарту TIA-598 (модули × волокна), панель свойств показывает разварку (splice) на муфтах и узлах. Поддерживается трассировка пути волокна от точки к точке — подсветка участков на карте.

Заявки Поддержки на карте

Слой «Заявки» накладывает геопривязанные тикеты Поддержки СмИТ Биллинг. Клик по маркеру открывает панель тикета: ответ клиенту, Нейроответ (AI-черновик), внутренняя заметка, назначение ответственного, а также drawer карточки абонента.

Мониторинг NAS

Включённый «Монитор» подсвечивает аварийные NAS, в панели узла доступны действия Ping, Синхронизация, Рестарт RADIUS и список онлайн-абонентов.

Слои и источники данных

flowchart LR
    MAP["Карта Leaflet
6 слоёв"] --> N(("Узлы /
оборуд."))
    MAP --> R(("Трассы
(волокна)"))
    MAP --> Z(("Зоны
покрытия"))
    MAP --> CP(("Точки
подключения"))
    MAP --> TK(("Заявки
Поддержки"))
    MAP --> MON(("Монитор
NAS"))

    N -->|"редактор"| EDIT["Geoman
CRUD + drag"]
    R -->|"клик"| FIB["Панель волокон
splice · трассировка"]
    TK -->|"клик"| TPANEL["Панель тикета
ответ · AI · заметка"]
    MON -->|"клик NAS"| NAS["Ping · Sync ·
Restart · онлайн"]

    style MAP fill:#134e4a,stroke:#43b77a,color:#fff
    style FIB fill:#1e3a5f,stroke:#5BA89D,color:#fff
    style TPANEL fill:#78350f,stroke:#d97706,color:#fff
    style NAS fill:#7f1d1d,stroke:#dc2626,color:#fff
    style EDIT fill:#43b77a,stroke:#2d9a5f,color:#fff

Тёмная тема и адаптив

При тёмной теме интерфейса карта переключается на тёмный скин CARTO Dark Matter (узлы, трассы и зоны контрастно читаются на тёмном фоне), zoom-контролы и легенда адаптированы. На мобильном тулбар сжимается в один ряд (Монитор / Редактор / Обновить / Фильтры), а слои переезжают в выезжающую снизу панель фильтров.

4. Отчёты

Раздел меню «Отчёты» объединяет аналитику для руководителя, библиотеку SQL-отчётов, аудит действий персонала и журналы.

Пользовательские SQL-отчёты — назначение и роль

AdminCustomReports — таблица сохранённых SQL-запросов, доступных оператору через UI. Каждая запись = один отчёт с именем, описанием и SQL-кодом. Хранится в таблице ADMIN_CUSTOM_REPORTS, редактируется на /admin/reports/AdminCustomReports/.

Зачем нужны кастомные отчёты

Биллинг — это система с ~150 таблицами и 600+ полей. Готовых отчётов в админке всегда не хватает: бухгалтер хочет один формат, директор — другой, техподдержка — третий. Решение:

1. Гибкость без релизов — оператор-аналитик пишет SQL прямо через UI, без ожидания deployment'а;
2. Параметризация — встроенный синтаксис :Имя|тип$ позволяет добавлять параметры (даты, абонент, сумма) без знания Python;
3. Экспорт — результат отчёта сразу в Excel/CSV/DBF без программирования;
4. Историческая часть — каждый запуск сохраняется в AdminCustomReportsHistory, можно вернуться к старому результату.

Поля и связанные таблицы

Связанные таблицы:

• AdminCustomReportsType — справочник типов (см. ниже);
• AdminCustomReportsHistory — история запусков (user_id, params JSON, row_count, execution_time, sql_hash);
• report_executions — текущие выполнения (для предотвращения двойного запуска);
• report_favorites — закладки оператора (звёздочки).

Параметры в SQL — синтаксис

Внутри SQL можно использовать спец-плейсхолдеры в формате :Имя|тип$ или :Имя|тип[аргументы]$. Когда оператор запускает отчёт — UI генерирует форму с этими параметрами, подставляет значения и выполняет SQL.

Парсинг — regex в AdminCustomReports._get_sql_fields(), подстановка в _execute_sql() с защитой от SQL-injection.

Типы отчётов

Справочник ADMIN_CUSTOM_REPORTS_TYPE — 7 категорий с цветными бейджами:

• 🛠 Техсервис — для техников (NAS, RADIUS, оборудование)
• 📈 Руководство — KPI, статистика, тренды
• ⛑ Техподдержка — заявки, тикеты, проблемы клиентов
• 🎧 ЦОК (call-центр) — обращения, ответственные
• 💰 Бухгалтерия — финансы, оплаты, счета
• 📞 Телефония — VoIP, звонки
• 🛡 ЦУС — централизованное управление сетью

Один отчёт может быть без типа (NULL) или привязан к одной категории. На странице есть фильтр-вкладки по типам.

CodeMirror + AI Builder

CodeMirror 5.65.16 (build 449) — встроенный SQL-редактор в модалке:

• Подсветка синтаксиса PostgreSQL (тема material-darker, чёрный фон);
• Live-counter параметров — автоматически считает :Имя|тип$ в коде;
• Подсветка плейсхолдеров жёлтым overlay'ем;
• Hot-keys: Ctrl+/ comment, Ctrl+F find, Tab indent;
• Auto-fix SQL — _fix_sql_column_case() для миграций Carbon4 → PostgreSQL (uppercase ID → lowercase id).

AI Builder (build 455): кнопка «✨ AI» в toolbar. Открывает чат с Claude API:

1. Оператор описывает что нужно: «Топ-10 должников за месяц с балансом и телефоном»;
2. Claude задаёт уточняющие вопросы (период, фильтры);
3. Возвращает готовый SQL с правильными именами таблиц/полей и параметрами;
4. Оператор проверяет, при необходимости правит, сохраняет.

Контекст БД для Claude — schema из information_schema.columns для 15 ключевых таблиц + критические правила биллинга (DB_MONEY_KOEF, MPTT-фильтры, регистр имён).

Отчёты в ЛК абонента

Если у отчёта ALLOW_IN_CABINET=true — он показывается абоненту в ЛК (раздел «Мои отчёты»). При запуске:

• Параметры :Абонент|select[Abonents]$ автоматически фиксируются текущим абонентом (нельзя посмотреть чужие данные);
• Параметры дат/сумм абонент задаёт сам;
• Результат отображается с пагинацией, экспорт в CSV.

4.1. Библиотека отчётов

URL: /admin/reports/AdminCustomReports/

Каталог пользовательских SQL-отчётов. Отчёт — это сохранённый SQL-запрос с настраиваемыми параметрами, сгруппированный по типам (Техсервис, Бухгалтерия, Руководство, Поддержка и т.д.), который оператор запускает кликом и получает таблицу с возможностью экспорта в Excel, CSV или DBF.

Список отчётов

• Вкладки по типам с цветными бейджами: 🛠 Техсервис, 📈 Руководство, ⛑ Техподдержка, 🎧 ЦОК, 💰 Бухгалтерия, 📞 Телефония, 🛡 ЦУС. Тип хранится в AdminCustomReportsType, редактируется через кнопку «+» в правой части toolbar.
• Поиск по имени и SQL-коду с шорткатом Ctrl+K.
• Звёздочка избранного (build 446) — отмеченные отчёты попадают в виджет «Избранные отчёты» на дашборде директора и в профиле сотрудника.
• Бейдж «🤳 ЛК» у отчётов с allow_in_cabinet=True — они доступны абоненту в его ЛК (например, «История платежей»).
• Sticky toolbar при скролле — поиск, фильтр избранного, кнопки «+ Типы», «+ Добавить отчёт», «✨ AI» остаются видны.
• Кнопки в строке: ▶ Запустить, ✏ Редактировать, 🗑 Удалить с подтверждением через Bootstrap-confirm.
• Bulk-операции (build 452): чекбокс-колонка с master-чекбоксом, sticky-toolbar при выборе — Удалить / Сменить тип / Экспорт CSV выбранных.
• На мобильном (≤575px, build 454) — read-only режим: только имя + кнопка ▶ Запустить, CRUD скрыт.

Запуск отчёта

URL: /admin/reports/AdminCustomReports/<id>/executesql/

Кнопка ▶ Запустить в строке списка ведёт на форму с параметрами отчёта. Параметры извлекаются из SQL-кода по синтаксису :Имя|тип$ и рендерятся в форму автоматически.

На скриншоте — форма отчёта «Действия сотрудника» (#136): три параметра — Дата с, Дата по, Сотрудник. По умолчанию период — последний месяц (07.04 → 07.05), сотрудник = «Все сотрудники».

Внизу формы — четыре кнопки действий:

• Выполнить — открывает результат в HTML-таблице (на этой же странице).
• Excel (.xlsx) — скачивает результат как Excel-файл.
• CSV — скачивает CSV (UTF-8 BOM, разделитель ; для Excel RU).
• DBF — экспорт в DBF (legacy формат для интеграции с 1С).

Пример: запуск с фильтром по конкретному сотруднику

Выбор конкретного сотрудника из выпадающего списка choices:

На скриншоте — выбран сотрудник uspeshnyy (Aleksandr Uspeshnyy), период 01.05.2026 → 07.05.2026. Список доступных значений для параметра :Sotrudnik|choices[...]$ формируется на лету: SQL-генератор выбирает уникальных owner из AuditOperations и подставляет их в опции.

Пример: результат выполнения

После клика «Выполнить» срабатывает редирект на /admin/reports/AdminCustomReports/<id>/history/<run_id>/ — каждое выполнение получает свой run_id (хранится 30 дней для повторного открытия результата без перезапуска SQL):

На скриншоте — результат отчёта «Действия сотрудника» за месяц: 604 строки, колонки #, Дата/время, Сотрудник, ФИО, Событие, IP-адрес, Подробности. Каждая строка — один аудит-event с детализацией («FIN_TYPES: Тип фин. операции #28 «Перевод средств…»», «ABONENTS: создан абонент…», «USERS_USLUGA: услуга подключена…»).

Возможности страницы результата:

• Sticky-заголовок таблицы при прокрутке — колонки видны всегда.
• Поиск по таблице (Ctrl+K) — клиентский фильтр без перезапуска SQL.
• Кнопки экспорта в шапке — Excel / CSV / DBF (тот же набор что на форме параметров, но без перезапуска).
• Кнопка «← Назад к форме» — возврат к форме параметров для перезапуска с другими значениями.
• История запусков — каждый запуск сохраняется в AdminCustomReportsHistory с user_id, params, row_count, execution_time.

Модалка редактирования отчёта

Открывается кликом по имени отчёта или по карандашу. Делится на две колонки:

• Слева: название, описание, тип (select), Bootstrap-switch «🤳 Доступен в ЛК», развёрнутая справка по 4 типам параметров (:Имя|date$, :Имя|sum$, :Имя|select[Model]$, :Имя|choices[v1^Лейбл1|v2^Лейбл2]$) с примером SQL-сниппета.
• Справа: SQL-редактор CodeMirror 5 (build 449) с подсветкой синтаксиса PostgreSQL, тёмная тема material-darker, номера строк, перенос длинных строк, soft-wrap. Hot keys: Ctrl+/ toggle comment, Ctrl+F find. Параметры :Имя|тип$ подсвечиваются жёлтым фоном через CodeMirror-overlay.

Live-counter под редактором обновляется на каждом change-event: «N строк · M парам.», справа от него — список найденных параметров с типами.

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

Параметры записываются в SQL как :Имя|тип$ и автоматически становятся полями формы запуска:

Пример SQL с параметрами:

SELECT a.id, a.name, a.contract_number,
       aa.ostatok / 10000000000.0 AS balance_rub
FROM abonents a
LEFT JOIN admin_accounts aa ON aa.id = a.account_id
WHERE a.is_folder = false
  AND a.deleted = false
  AND aa.ostatok < -:Долг|sum$ * 10000000000
  AND a.create_date BETWEEN :Дата с|date$ AND :Дата по|date$
ORDER BY aa.ostatok ASC
LIMIT :Лимит|sum$;

AI-помощник написания SQL

Кнопка «✨ AI» в шапке открывает чат с ИИ-ассистентом (Claude Haiku 4.5 через Anthropic API, build 455). Ассистент знает структуру 15 ключевых таблиц биллинга (abonents, admin_accounts, tarif, finance_operations, users_usluga, pay_log, users, homes, nas, connection_points и др.) и формат параметров, умеет писать SQL по словесному описанию задачи.

Типичный сценарий:

1. Оператор пишет: «топ-10 должников за месяц с балансом и телефоном»
2. AI задаёт уточняющие вопросы: какой период (последний месяц / произвольный), какой минимальный долг, нужен ли фильтр по тарифу
3. Оператор отвечает свободным текстом
4. AI возвращает готовый SQL с блоком JSON {"name": "...", "description": "...", "sql": "..."}
5. Зелёный draft-banner с кнопкой «➡ Создать отчёт» передаёт черновик в основную модалку с предзаполненными name/description/sql
6. Оператор проверяет SQL в CodeMirror, при необходимости правит, нажимает «Сохранить»

Каждый AI-запрос пишется в AuditOperations (table_name='ADMIN_CUSTOM_REPORTS', descr='AI-консультация: …'). Запросы идут через Telegram-прокси (api.anthropic.com заблокирован для RU).

Права и audit

• SQL выполняется с правами Django БД-юзера (carbon на testbill, full access). Это значит, что любой оператор с правом «Запуск отчётов» может прочитать любую таблицу. Опасные SQL (UPDATE, DELETE, DROP) не блокируются на уровне приложения — защита только через PostgreSQL-роль (рекомендуется отдельный read-only role для отчётов).
• Каждое выполнение пишется в AdminCustomReportsHistory: user_id, params (JSON), row_count, execution_time, sql_hash. Доступно через «История запусков» в правом меню отчёта.
• allow_in_cabinet=True: отчёт доступен абоненту в ЛК через /lk/reports/<id>/. Для безопасности параметры могут содержать только тип date и sum (запрещены select[Model] и choices, иначе абонент мог бы перебирать ID).

4.2. Аудит

Журнал всех значимых действий в биллинге: создание, изменение, удаление абонентов, подключение услуг, платежи, блокировки, изменения настроек, действия СОРМ.

Каждая запись содержит дату/время, оператора, тип события, абонента и описание. Для большинства событий есть drill-down: клик по записи открывает изменённый объект в нужной вкладке.

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

• Фильтр периода с кнопками Сегодня / Неделя / Месяц / Год.
• Фильтр по типу события и текстовый поиск.
• Цветные бейджи категорий (status / block / payment / SORM).
• Sticky-заголовок таблицы при прокрутке.

4.3. Журнал платежей

Сводный журнал финансовых операций по всем абонентам — приходы, списания, сторно, обещанные платежи. Это представление таблицы FinanceOperations с серверной пагинацией (поддерживает сотни тысяч записей).

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

• Быстрые периоды: Сегодня / Неделя / Месяц / Квартал / Год.
• Селектор количества строк: 50 / 100 / 200 / 500.
• Цветовое кодирование сумм: приход — зелёный, расход — красный.
• Клик по абоненту открывает его карточку в новой вкладке.
• Серверный фильтр по типу операции и текстовый поиск.
• По умолчанию показан текущий месяц.

4.4. Журнал сообщений

Единый сводный журнал всех сообщений (MsgStack) по всем абонентам — SMS, Email, Telegram, Push, VK, ЛК. И точечные отправки из карточки абонента, и массовые рассылки попадают в один список. Доступен по адресу /admin/reports/messages/ (пункт меню «Отчёты → Журнал сообщений», build 588+).

Что внутри

• 4 KPI-карточки сверху: Всего, Доставлено SMS (с процентом доставляемости), В очереди, Ошибки SMS. Период переключается кнопками Сегодня / Неделя / Месяц / Все.
• Фильтры: текстовый поиск по сообщению/заголовку/абоненту/договору, диапазон дат, кнопки быстрых периодов.
• Чипы каналов: Все каналы / SMS / Email / Telegram / Push / VK / Только ЛК.
• Фильтр SMS-статуса справа: только delivered / sent / pending / failed.
• Колонка «Отправитель» (build 594) показывает кто отправил каждое сообщение. Aleksandr Uspeshnyy для ручных отправок, Система — для автоматических (биллинг, Celery, webhook). Рядом — фильтр Отправитель — любой / Мои / Системные + список всех операторов с рассылками.
• Цветные бейджи каналов с tooltip'ами: ✓✓ delivered, ✓ sent, ⏱ pending, ✕ failed (для SMS — на основе webhook-статуса sms-gate.app).
• Клик по строке открывает модалку с полным текстом и деталями.
• Pagination 25/50/100/200, server-side.
• Экспорт CSV текущей выборки (UTF-8 BOM, разделитель ;, лимит 50 000 строк).

Массовая рассылка

Кнопка «Рассылка» в правом верхнем углу открывает модальное окно для отправки одинакового текста группе абонентов через выбранные каналы (SMS / Email / Telegram / Push). Hard-limit — 500 получателей на одну рассылку (защита от случайного спама).

5 способов выбора получателей:

1. Категории — 8 готовых chip-фильтров: Должники, Сейчас онлайн, Заблокированные, Об. платёж, Юр. лица, Без email, Без телефона, Не платил 30 дн.
2. Тарифы — multi-select из ~78 тарифов. Отправит всем абонентам на выбранных тарифах.
3. Папки — древовидный picker с MPTT-обходом всех вложенных подпапок автоматически. Поиск по имени, expand/collapse, кнопка очистки выбора.
4. NAS — multi-select NAS-серверов. Отправит всем абонентам с учётками на выбранных NAS (через Users.nas_id).
5. Поиск — Select2 AJAX по имени/договору для точечного выбора.

Live-preview снизу всегда показывает: фактическое количество получателей, первые 10 имён + «…и ещё N», статистику доступности каналов («SMS: 267 · Email: 13 · TG: 0 · Push: 1»). Кнопка «Отправить» дизаблится при count = 0 или count > 500 (бейдж становится красным «макс 500!»).

Счётчик символов и SMS-сегментов справа от лейбла «Текст» обновляется на каждый ввод. Кириллица (UCS-2) → 70 символов на сегмент, латиница (GSM 7-bit) → 160. Цвет меняется на оранжевый при ≥2 сегментов и красный при ≥3.

Дерево папок

Вкладка «Папки» отрисована как полноценное tree-list с иконками и счётчиками абонентов в каждой папке (включая подпапки). Поддерживается keyboard-навигация (Tab → Enter/Space), live-фильтр по имени с автоматическим раскрытием родителей, кнопки Раскрыть всё / Свернуть всё / Очистить выбор.

Рассылка по NAS-серверам

Полезно когда нужно предупредить абонентов конкретного NAS (профилактические работы, замена оборудования, миграция). Каждый NAS показывается с IP, статусом (включён / выкл) и количеством абонентов.

Аудит рассылок

Каждая отправка пишется в AuditOperations (категория «Сообщения», см. раздел 4.2 Аудит):

• Точечная отправка (карточка абонента → «Отправить»): «Сообщение #N → Иванов И.И. (SMS, Email): «текст…»» с указанием owner = текущий оператор.
• Массовая рассылка — одна summary-запись на всю операцию: «Рассылка: uspeshnyy → категория «business» (SMS, EMAIL), получателей: 270/270: «текст…»».

Поле MsgStack.owner_id хранит pk оператора, поэтому в журнале можно отфильтровать «все мои отправки» или «всё что отправлял Петров».

Адаптивность

На mobile (≤767px) скрываются колонки «Договор» и «Отправитель» (видны только при открытии модалки деталей). KPI перестраивается в 2×2 grid. Всё кликабельно с touch.

Endpoint'ы

4.5. Разработка и логи

Раздел для администратора-разработчика. Доступен только пользователям с правами root. Делится на две вкладки.

Отчёты — встроенный markdown-просмотрщик внутренних документов проекта (отчёты по разработке, планы, документация).

Поддерживается сортировка по дате/имени или ручной drag-and-drop, inline-переименование, создание папок, загрузка новых .md-файлов через интерфейс.

Возможности просмотрщика .md

Markdown-просмотрщик поддерживает удобную навигацию и работу с документами:

• Поиск по документам — поле над списком файлов. Ввод фильтрует список по имени мгновенно; нажатие Enter запускает полнотекстовый поиск по содержимому всех документов — с подсветкой числа совпадений и сниппетом. Горячая клавиша Ctrl+F ставит фокус в поиск.
• Кликабельные ссылки на разделы биллинга — пути вида /admin/..., /lk/... и полные http(s) прямо в тексте документа становятся ссылками (с иконкой) и открываются в новой вкладке.
• Переходы между документами — ссылки на другие .md-файлы (отчёт → план → ТЗ) открываются в том же просмотрщике, превращая документы в связанную базу знаний.
• Чек-листы — пункты - [ ] / - [x] отображаются как ☐ / ☑ (выполненные зачёркнуты).
• Вложенные списки — многоуровневые перечни сохраняют отступы.
• Копирование кода — кнопка «копировать» при наведении на блок кода (команды деплоя, SQL).
• Диаграммы Mermaid и комментарии к заголовкам (командное обсуждение прямо в документе).

Логи — просмотр серверных логов прямо из админки.

Доступны каналы:

• error.log — общие ошибки приложения;
• payment.log — платежи (ЮKassa, W1, webhook);
• radius.log — авторизация и accounting;
• sorm.log — выгрузка СОРМ;
• staff.log — действия сотрудников;
• celery_worker.log, celery_beat.log — фоновые задачи;
• nginx_access.log, nginx_error.log — веб-сервер;
• freeradius.log — нативные логи FreeRADIUS.

Показываются последние 500 строк, есть кнопка обновления. Файлы автоматически ротируются (10 МБ × 5 копий).

4.6. Должники

Отдельная страница /admin/debtors/ — список абонентов с отрицательным балансом или активной блокировкой b_negbal. Раздел рассчитан на ежедневную работу бухгалтерии и операторов поддержки: KPI-блок сверху помогает быстро оценить ситуацию по компании, а drawer-панель — разобраться с конкретным абонентом без ухода на полную карточку.

KPI и статистика по периодам

Над таблицей — четыре карточки-показателя: общее количество должников, суммарный долг (в рублях), средний долг и доля должников с активным обещанным платежом. Карточки реагируют на выбранный период: переключатель chips сверху позволяет видеть динамику за сегодня / неделю / месяц / квартал / год. Цифры пересчитываются прямо в браузере без перезагрузки — у каждой карточки есть мини-индикатор изменения относительно предыдущего периода.

Фильтры и чипы

• Период — chip-фильтр (сегодня, неделя, месяц, квартал, год, всё время). Активный чип подсвечивается.
• Категория — отдельные чипы: с обещанным платежом, с контактом и небольшим долгом (кому имеет смысл звонить), заблокированные, без оплат за 60 дней.
• Поиск — по ФИО, договору, телефону, email — мгновенный фильтр без перезагрузки.
• Состояние сохраняется — выбранный период и чип запоминаются в URL, ссылку можно отправить коллеге.

Таблица и сортировка

Колонки: ФИО, договор, тариф, точка подключения, баланс, дней без оплаты, телефон, email, статус. По умолчанию сортировка — по убыванию суммы долга. Клик на заголовок любой колонки переключает порядок (▲▼). Цветовое кодирование: красные строки — заблокированные за неуплату, жёлтые — на грани блокировки, серые — с активным обещанным платежом. В каждой строке справа — кнопка ℹ Подробнее, которая открывает drawer.

Drawer-панель абонента

Клик на ℹ открывает боковую панель справа (overlay поверх таблицы) с краткой сводкой по абоненту — без перехода на полную карточку и потери контекста списка. Внутри панели:

• Шапка: ФИО, договор, тариф, тек. баланс, дата последней оплаты, статус блокировки.
• График: динамика баланса за последние 3 месяца — наглядно видно, когда «ушёл в минус».
• Последние финансовые операции (топ-10): дата, тип (приход/расход), сумма, описание.
• Сообщения: история отправленных SMS/Email/Push с галочками доставки.
• Комментарии операторов: можно добавить новый комментарий прямо из drawer (хранится в AbonentsComments), история подписана автором и временем.
• Лицевые счета: связанные счета с остатками (если у абонента несколько).
• Действия: отправить SMS-напоминание о долге, активировать обещанный платёж, открыть полную карточку.

Массовые действия и экспорт

• Чекбоксы в каждой строке + выбрать все на странице — для bulk-операций над отмеченными должниками.
• Действия над выбранными: массовая отправка SMS/Email, блокировка, прощение долга (создаёт компенсирующий FinOp).
• Экспорт CSV (UTF-8 BOM, разделитель ;) — выгружает текущую выборку с учётом фильтров для сверки с бухгалтерией или загрузки в 1С.

4.7. Миграция с других биллингов

Раздел /admin/settings/migration/ — мастер импорта данных абонентов из других биллинговых систем. Пошаговый wizard с предпросмотром и dry-run.

Импорт из предыдущей версии (Firebird)

/admin/settings/migration/cb4/ — специализированный импорт данных из предыдущей версии биллинга (Firebird). Учитывает специфику:

• Денежные поля × 10⁷ → нормализуются в × 10¹⁰ (новый DB_MONEY_KOEF).
• PGP-зашифрованные пароли NAS → расшифровываются через ключ из EBS audit log.
• MPTT-дерево абонентов с папками сохраняется через parent_id.
• Услуги маппятся через таблицу соответствий (legacy USLUGA.ID → новый pk).
• RADIUS-сессии и USERS_RADIUSAUTH мигрируются последним этапом.

Загрузка из CSV

/admin/settings/migration/csv_loading/ — общий импорт абонентов/услуг/платежей через CSV файлы. Поддерживается:

• Загрузка через UI (drag-and-drop) или путь к файлу на сервере.
• Маппинг колонок CSV ↔ поля модели через интерактивную форму.
• Dry-run перед применением — показывает что будет создано/обновлено/пропущено.
• Отчёт по результатам с подсветкой ошибок построчно.

Авто-импорт CSV (схемы)

/admin/settings/autocsv/ — настройка повторяющихся импортов: оператор сохраняет «схему» (маппинг колонок + способ обработки дубликатов), и потом загрузка одной кнопкой берёт CSV и применяет схему без повторной настройки. Полезно для ежемесячных выгрузок из бухгалтерии или экспорта из биллинга мобильного оператора (массовое зачисление платежей).

FrameworkFormGroupFields — назначение и роль

FrameworkFormGroupFields (FFG) — таблица настроек UI для всех админских форм биллинга. Управляет тем, какие поля видны на форме редактирования, как они сгруппированы в вкладки и в каком порядке. По сути это «генеральный настройщик» админки без правки кода.

Что это и зачем

Биллинг — это унаследованный движок с десятками моделей, у каждой по 30-100 полей. Большая часть из них — технический шум для оператора. Решения:

• Без FFG — generic-форма со всеми 100 полями. Оператор не знает что важно;
• С FFG — оператор видит только нужные 10 полей, разбитые по 3 вкладкам с понятными русскими названиями. Скрытые поля остаются в БД и работают.

Это безопасный способ упростить UI без боязни сломать логику.

Ключевые поля

Как работает

1. При открытии формы редактирования модели (например /admin/Abonents/<id>/) view вызывает safe_globals.get_groups_from_model('ABONENTS');
2. Функция читает все записи FFG где TABLE_NAME='ABONENTS' и INTERFACE_ID IS NULL;
3. Записи группируются по GROUP_ID → каждая группа = одна вкладка формы;
4. Внутри группы поля сортируются по ORDER, скрытые (SHOW_ON_FORM=0) исключаются;
5. Применяются VERBOSE_NAME для русификации лейблов;
6. Кеш Django сохраняет результат — после изменения FFG нужен cache.clear().

Опасные моменты

1. INTERFACE_ID=NULL — это дефолт, не «отсутствие настройки». Если поле SHOW_ON_FORM=0 для INTERFACE_ID=NULL, оно скрыто во всех интерфейсах. Чтобы показать только в одном — нужны 2 записи: NULL с 0 и INTERFACE_ID=1 с 1;
2. Дубликаты Python dict — баг был с 'Users' ключом, появлявшимся дважды в _EXCLUDE_FORMS. Второе значение тихо перезаписывало первое. Перед добавлением нового ключа всегда grep;
3. UPPERCASE имя таблицы — критично для PostgreSQL. 'abonents' != 'ABONENTS'. Используйте Model._meta.db_table.upper() чтобы не ошибиться;
4. FIELD_NAME — Django-имя, не SQL-имя. Поле create_date в FFG, не "CREATE_DATE".

Реальные примеры скрытия полей

4.8. Настройки интерфейса (формы)

/admin/settings/interface_settings/ — конфигурация полей форм для каждой модели. Через FrameworkFormGroupFields можно:

• Скрывать/показывать поля без правки кода (флаг show_on_form).
• Менять порядок полей (drag-and-drop).
• Группировать поля по вкладкам (FrameworkFormGroup).
• Делать поля required / readonly через UI.

Пример использования: на форме Users скрыты 17 технических полей (IPV6, MASK, EXT_ID, IS_TEMPLATE, и т.д.) — оставлены только реально используемые. Изменения применяются для всех операторов одновременно после cache.clear().

5. Игры (Маркетинг)

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

Список игр: Pacman, Tetris, Snake, Minesweeper, 2048, Breakout, Flappy Bird, Helicopter. Доступны в админке, мобильном приложении и ЛК.

5.1. Архитектура модуля

Единый источник настроек (GAMES_* в SystemSettings) питает три точки потребления: профиль-меню админки, карточку абонента, мобильное приложение. Данные результатов хранятся в GameScore, история победителей — в GameMonthWinner.

5.2. Настройки модуля «Маркетинг»

Настройки находятся в /admin/settings/system/ → вкладка «Маркетинг» (рядом с Брендинг / Безопасность / … / Профиль). Сейчас Маркетинг = Игры; в будущем туда добавятся другие маркетинговые механики (акции, реферальные программы, бонусы за активность).

Страница содержит 5 секций:

• Общее — Включить игры (глобальный выключатель) + Пункт «Игры» в меню профиля.
• Мобильное приложение — Разрешить игры абонентам + чекбоксы 8 доступных игр.
• Игра месяца — розыгрыш, игра, дни бесплатного интернета, минимальный счёт, режим начисления (авто/ручной).
• Условия участия — оценки в сторах / на картах (см. §5.4).
• Текущий лидер и история — live-превью лидера + список победителей.

5.3. «Игра месяца» — бесплатный интернет

Главная механика. Абонент с максимальным счётом за календарный месяц получает бесплатный месяц интернета — кредит-финоперацию на сумму месячной стоимости его тарифа.

Настройки розыгрыша:

• Игра розыгрыша — какая из 8 игр участвует в текущем месяце.
• Дней бесплатного интернета — 30 по умолчанию.
• Мин. счёт для участия — отсекает «нулевые» результаты.
• Авто-начисление / ручное — по умолчанию оператор подтверждает победителя кнопкой (защита от ошибок).
• Исключать сотрудников — результаты из админки в розыгрыше не участвуют.
• Уведомлять победителя — MsgStack + Push.

Подведение итогов — Celery-задача game_of_month_finalize запускается 1-го числа в 02:00, определяет лидера прошлого месяца и (в авто-режиме) начисляет приз; в ручном — ставит «ожидает подтверждения» + Telegram-алерт оператору.

Ручное начисление. В блоке «Текущий лидер» кнопка «Начислить победителю вручную» открывает окно подтверждения с данными победителя — игра, ФИО, договор, набранные очки и сумма приза. Если для турнира заданы условия участия (см. §5.4), оператор отмечает их выполнение прямо в окне; кнопка «Начислить» становится доступной только после подтверждения всех условий.

5.4. Условия участия в турнире

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

Включённые условия показываются абоненту в мобильном приложении как требования перед участием в розыгрыше. По умолчанию все выключены.

Ссылки на оценку

Под переключателями условий задаются ссылки, по которым абонент оставляет оценку. Источники ссылок разделены:

• Ссылка на приложение — берётся из раздела ЛК → Мобильное (Google Play и App Store), чтобы не дублировать. В настройках Маркетинга она показана только для справки; если ссылки в ЛК не заполнены — выводится подсказка с переходом в нужный раздел.
• Яндекс Карты и 2ГИС — задаются прямо в настройках Маркетинга (GAMES_OF_MONTH_YANDEX_URL, GAMES_OF_MONTH_2GIS_URL).

5.5. Вкладка «Маркетинг» в карточке абонента

В карточке абонента появляется вкладка «Маркетинг» — только если модуль игр включён и у абонента есть лицевой счёт.

Содержимое вкладки:

• Карточка «Игра месяца» — результат абонента vs лидер, прогресс-бар, бейдж «Лидер!» если он первый.
• Лучшие результаты по играм — по каждой игре, в которую играл абонент: лучший счёт + глобальный ранг (🏆 за 1 место, 🥈🥉 за 2–3).
• Empty-state — если абонент ещё не играл.

Оператор видит игровую активность абонента прямо в его профиле, не переходя в раздел игр.

5.6. Профиль-меню и мобильное приложение

Профиль-меню (справа у аватара) — пункт «Игры» появляется, когда включены GAMES_ENABLED + GAMES_ADMIN_ENABLED. Управляется через context-processor — без жёсткой проверки прав, видимость определяется единым тогглом.

Мобильное приложение (/mobile-api/v1/game/config) отдаёт список доступных игр (из GAMES_MOBILE_ALLOWED) и данные текущего розыгрыша (мой счёт, счёт лидера, дни приза). Фильтрация submit_score / leaderboard по GAMES_MOBILE_ENABLED.

Ключи настроек (SystemSettings, категория games)

GAMES_ENABLED / GAMES_ADMIN_ENABLED / GAMES_MOBILE_ENABLED / GAMES_MOBILE_ALLOWED
GAMES_OF_MONTH_ENABLED / GAMES_OF_MONTH_KEY / GAMES_OF_MONTH_REWARD_DAYS
GAMES_OF_MONTH_MIN_SCORE / GAMES_OF_MONTH_AUTO_AWARD / GAMES_OF_MONTH_EXCLUDE_STAFF
GAMES_OF_MONTH_NOTIFY / GAMES_OF_MONTH_OPTYPE
GAMES_OF_MONTH_REQUIRE_APP_RATING / _YANDEX_MAPS / _2GIS
GAMES_OF_MONTH_YANDEX_URL / GAMES_OF_MONTH_2GIS_URL

Ссылка на приложение для условий участия берётся из MOBILE_FORCE_UPDATE_URL_ANDROID / _IOS (раздел ЛК → Мобильное).

6. Настройки

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

6.1. Настройки системы

Единая страница системных параметров с тремя вкладками: Параметры, Брендинг, Безопасность.

Вкладка «Параметры» — общие настройки биллинга, сгруппированные по типам: RADIUS, валюта, ЛК, общие, сообщения, учёт, интерфейс. Каждая настройка имеет имя, значение и описание.

Примеры параметров: лимит обещанного платежа в днях, частота auto-assign NAS, SLA-цели для NAS-мониторинга, частота автоматической очистки БД.

Вкладка «Брендинг» — фирменное оформление: название компании, логотип, цвет акцента, контактные данные. Эти данные показываются в админке, в личном кабинете и в шаблонах печати.

Вкладка «Безопасность» — политика финансовых операций (build 768)

На Безопасности — глобальные ограничения для ручных финансовых операций (создание/редактирование/удаление через UI). Доступна только пользователям группы root или is_superuser=True.

5 настроек (все по умолчанию выключены — стандартное поведение Django admin):

Все ограничения проверяются и в backend (HTTP 403/400 на endpoints finops_ajax, finops_crud_ajax, FinOpChangeView) и в frontend (кнопки/ссылки/поля скрыты в HTML).

Важно: ограничения касаются только ручных операций через UI. Автоматические процессы — Celery worker billing_worker для абонплаты, webhook ЮKassa, обещанный платёж, auto-block по отрицательному балансу — работают как обычно, без проверок. Это нужно чтобы политика «только суперюзер» не сломала автоматическое начисление.

Вкладка «Безопасность» — авторизация: FIDO2, reCAPTCHA, блокировка, сессии (build 1171)

Ниже блока «Финансовые операции» на странице /admin/settings/system/security/ расположены 4 блока управления безопасностью входа.

Все настройки в категории security, по умолчанию выключены. Миграция 0230 добавляет модель StaffWebAuthnCredential (passkey сотрудников).

Адаптивная шапка админки (builds 1180–1182)

Верхнее меню сжимается ступенями при нехватке ширины (только десктоп ≥768px), освобождая место без потери пунктов.

• Пункт «Продажи» переименован в «CRM».
• Ступень 0 — сворачивается левый сайдбар (ручной выбор пользователя не трогается).
• Ступень 1 — имя пользователя → фамилия, «Тарификация» → «Тарифы», «Справочники» → «Справ.».
• Ступень 2 — пункты Видео / IPTV / IP-телефония группируются в выпадающее меню «Услуги» (сразу после «Тарифы»).
• При расширении окна всё откатывается обратно.

Вкладка «Аудит» — настройки журнала действий по абонентам (build 778)

Управление параметрами вкладки Аудит в карточке абонента и общим поведением логирования. Доступна по адресу /admin/settings/system/?tab=audit только пользователям группы root или с is_superuser=True.

Все 4 настройки хранятся в таблице system_settings (category = audit), читаются через хелперы в billing/services/settings_service.py (get_audit_default_period_months(), get_audit_per_page(), get_audit_csv_export_limit(), is_audit_hide_system_events()) с clamp в коде на случай некорректного значения в БД.

Срок хранения записей аудита (по умолчанию 365 дней) настраивается отдельно в разделе Очистка БД — параметр DB_CLEANUP_AUDIT_DAYS. Это сделано чтобы retention-политика управлялась рядом с другими параметрами очистки (MSG_STACK, RADIUS_SESSIONS), а не дублировалась.

Быстрый переход в настройки: для пользователей с is_superuser=True в toolbar вкладки «Аудит» карточки абонента появляется иконка-шестерёнка справа от кнопки CSV-экспорта — клик ведёт прямо в /admin/settings/system/?tab=audit.

Вкладка «Логи» — хранение и уровень логирования (build 801)

Управление файлами журналов в /var/log/django/: ротация, сжатие, уровень логирования Django и FreeRADIUS. Раньше логи росли без ограничений — на тестовом сервере freeradius.log вырастал до 22 ГБ за месяц при FREERADIUS_DEBUG_LEVEL=trace.

Параметры:

Справа на вкладке — таблица текущего размера всех файлов в /var/log/django/ с подсветкой больших (≥100 МБ оранжевый, ≥1 ГБ красный). Клик по имени файла → переход в просмотр содержимого (/admin/reports/dev/logs/).

Просмотр логов с подсветкой

Страница /admin/reports/dev/logs/ (раздел «Отчёты → Разработка и логи», только root-доступ) показывает 12 каналов журналов слева с текущим размером, справа — содержимое выбранного файла.

• Чтение с конца файла — функция _tail_log() читает последние 500 строк, двигаясь от конца файла чанками, не загружая его целиком в память. Поэтому даже лог на десятки гигабайт открывается мгновенно (в шапке показано «Показано: 500 / N строк»). Это защищает от OOM, который раньше валил контейнер при открытии многогигабайтного freeradius.log.
• Подсветка по уровням (colorizeLog) — каждая строка раскрашивается по содержимому: красный для error / traceback / exception, оранжевый для warning, серый для debug, обычный для info. Цвета адаптируются под тёмную тему.
• Кнопки: обновить, скачать файл, поделиться ссылкой (?log=имя), очистить лог / очистить все логи (только суперадмин).

Ротация логов на сервере

Часть логов пишет Django через RotatingFileHandler (error.log, radius.log, payment.log, sorm.log, staff.log — maxBytes 10 МБ, backupCount 5, в просмотрщике видны как radius.log.1….5). Но нативный freeradius.log пишет сам FreeRADIUS (C-side), и Django его не ротирует. Если FreeRADIUS запущен в trace-режиме (-xx), этот файл растёт на ~5 ГБ/сутки — на rbill он однажды вырос до 43 ГБ.

Лечение (build 967, host-side на rbill):

• Уровень детализации FreeRADIUS задаётся переменной RADIUS_DEBUG_LEVEL в .env (читается docker/freeradius/entrypoint.sh): info (без флага, ~1 ГБ/сутки, только Accept/Reject и блокировки), debug (-x), trace (-xx, не использовать в проде). После правки — docker compose up -d --force-recreate freeradius.
• /etc/logrotate.d/smit-freeradius — ротация нативного лога (daily, rotate 5, maxsize 100M, compress, copytruncate — обязателен, т.к. FreeRADIUS держит файл открытым, su root root — т.к. каталог volume world-writable). Файл больше не превышает ~600 МБ.
• /etc/cron.daily/smit-radacct-cleanup — удаляет accounting detail-файлы radacct/<NAS>/detail-YYYYMMDD старше 14 дней (эти данные уже продублированы в таблице RADIUS_SESSIONS).

Текущий размер каждого файла виден в просмотрщике — после фикса freeradius.log держится в районе десятков мегабайт:

Вкладка «Скорость» — Gunicorn / Celery / БД / Throttling (build 803, переименована в build 885)

Параметры процессов и ресурсов. Изменения требуют перезапуска контейнеров (web, celery). 4 группы настроек 2×2 + статус-блок снизу.

Статус-блок снизу (read-only метрики, обновляется при загрузке страницы): CPU, RAM, Load average, PostgreSQL соединений (с алертом если >80%), размер БД, Celery очередь, Redis память.

Вкладка «RADIUS» — таймауты, retention, NAS auto-assign (build 803, переименована в build 885)

Параметры RADIUS-сессий, NAS-мониторинга и хранения истории. Применяются при следующей авторизации или ближайшем прогоне Celery beat (cleanup-stale-sessions каждые 5 минут, db-cleanup-daily в 03:00 UTC).

Статус-блок снизу: NAS всего / UP / DOWN (если есть), Сейчас онлайн (LOGGED), Активных RADIUS-сессий, Расхождение, размер таблиц RADIUS_SESSIONS / AUDIT_OPERATIONS / MSG_STACK.

Вкладка «Сообщения абонентам» — политика уведомлений (build 805)

Единая страница для управления всеми каналами доставки сообщений: Email, SMS, Push, Telegram, VK. Объединяет настройки из 4 разных мест в одну ментальную модель оператора («Сообщения»). 4 группы 2×2 + статистика снизу.

Подключение: billing/services/notification_policy.py::should_send(channel, abonent_id, head_txt) вызывается в billing/tasks/messaging.py:_dispatch_message для каждого канала. Пропущенные сообщения логируются в MsgStack.sms_status='skipped' с sms_error=причина — оператор видит почему сообщение не доставлено.

Шлюзы каждого канала настраиваются в отдельных разделах: Email /admin/settings/email/, SMS /admin/settings/sms/, Push /admin/settings/firebase/. Здесь — общая политика на уровне всей системы.

Статистика снизу: отправлено сегодня по каналам, в очереди, SMS-ошибки, SMS-пропуски (тихий час / дубль), бейдж «Тихий час сейчас».

Доступ суперпользователя — 2FA, IP-ограничение, политики паролей (build 971)

В правой колонке вкладки Безопасность — карточка «Доступ суперпользователя». Все политики применяются только к is_superuser и по умолчанию выключены (поведение входа не меняется, пока администратор не включит их осознанно). Управление доступно только суперпользователю.

Двухфакторная аутентификация (TOTP). Подключение в профиле: сканируете QR-код приложением-аутентификатором, подтверждаете кодом — 2FA активна. При активации выдаются 10 резервных кодов (формат XXXX-XXXX, показываются один раз) — на случай потери телефона. При входе после логина/пароля запрашивается 6-значный код (можно ввести backup-код). Отключить 2FA нельзя, пока включена политика «Обязательная 2FA».

Защита от self-lockout: все политики выключены по умолчанию; backup-коды 2FA; IP-список fail-open при пустоте; аварийный сброс через консоль сервера (set_setting('SU_REQUIRE_2FA', False)). Каждое изменение политик пишется в AuditOperations.

Подключение: billing/services/su_security.py (логика IP/2FA/паролей), billing/views/auth.py (вход), billing/views/profile.py (2FA + смена пароля).

Вкладка «Блокировки и финансы» — captive-portal + бизнес-правила (build 808)

Управление блокировкой абонентов за долг и базовыми правилами биллинга. 4 группы 2×2 + статус блокировок. Закрывает давнюю боль «Не авторизовать по RADIUS при отрицательном балансе» (build 419 soft-block) и задачу №4 Марии (captive-portal).

Подключение: billing/services/block_policy.py в 4 точках кода — radius_python/internet.py:authorize() (kill-switch ДО soft-block), billing/models/abonents.py:block() (пропуск CoA), billing/tasks/billing_worker.py:_process_service() (skip списания), billing/views/finops_list.py (queryset filter).

Статус-блок снизу: Активных / Заблокированных абонентов, по b_negbal / b_admin / b_own, активных Обещанных Платежей, заблокировано/разблокировано сегодня. Большой красный alert над формой если включён аварийный kill-switch.

Вкладка «Прокси» — пул прокси для Telegram и Нейросети (build 1056–1064)

Из России api.telegram.org и api.anthropic.com заблокированы — биллинг ходит к ним через прокси. Раздел Настройки системы → Прокси (/admin/settings/system/proxy/) — единый пул прокси с ролями, авто-проверкой и журналом. Заменил прежний блок «Прокси для Telegram» из Интеграций (старые плоские ключи остаются как fallback).

Как работает выбор прокси (fallback):

Переключатель «Использовать прокси»

Глобальный тоггл сверху. Выключен → get_api_proxies() возвращает None, Telegram/Нейросеть подключаются напрямую (настройка PROXY_ENABLED в БД). При выключении форма/таблица/журнал скрываются.

Добавление прокси

Список прокси по одному на строку. Поддерживаемые форматы: ip:port:login:password, login:password@ip:port, ip:port (без авторизации). Тип — Авто-определение (по умолчанию; живая проба HTTP→SOCKS5), HTTP или SOCKS5. Роли — «для Telegram» / «для Нейросети» (можно обе). При добавлении параллельно определяется тип и геолокация по IP (ip-api.com). Прокси добавляется всегда, даже если автопроверка не достучалась — со статусом 🔴 и подсказкой (например провайдер отвечает 407 при неверных кредах / IP-binding).

Таблица «Прокси-серверы»

Колонки: Тип (бейдж HTTP/SOCKS5), Адрес (ip:port, иконка-ключ + тултип логин/пароль), Гео (флаг страны + город), Роли (TG / Нейросеть), Статус (🟢 доступен · 🔴 недоступен · ⚪ не проверялся, с латентностью в тултипе), Приоритет, Ред (kebab-меню действий). Действия в kebab: Проверить, Включить/Выключить, Назначить роль (Только Telegram / Только Нейросеть / Обе), Удалить.

«Проверить все» — проверяет все прокси и расставляет приоритеты: живые по возрастанию задержки (быстрый = приоритет 1), мёртвые в конец. Если есть нерабочие — кнопка превращается в «Удалить нерабочие (N)».

Автопроверка и уведомления

Celery beat proxy-pool-check проверяет пул каждые PROXY_CHECK_INTERVAL_MIN минут (default 60). При переходе прокси в недоступное состояние и при полном отсутствии живых прокси для роли — Telegram-алерт (тоггл PROXY_ALERTS_ENABLED). События пишутся в Аудит (добавление/удаление — с указанием кто, системное «нет доступных прокси»).

Журнал событий

Правая колонка — последние 50 событий (проверки, переходы up/down, добавление/удаление) с авто-обновлением каждые 30с. Кнопка «Скачать» выгружает журнал в CSV (до 1000 записей).

Тёмная тема и мобильная вёрстка поддержаны (UX-аудит build 1063). Потребители прокси (Telegram-рассылки, AI-чаты ЛК/мобильного, геокодер и др., ~18 точек) используют пул автоматически через get_api_proxies().

6.2. Шаблоны печати

Шаблоны документов — договоры, акты, квитанции. Шаблон — это HTML или Word-файл с подстановочными переменными вида {{ contract_number }}, {{ abonent.name }}, {{ tariff }}. Готовый документ генерируется при печати из карточки абонента.

6.3. Фискализация (54-ФЗ)

Полное описание модуля автоматической отправки кассовых чеков в ОФД — в разделе 6.3.1. Модуль фискализации ниже.

6.3.1. Модуль фискализации 54-ФЗ

Модуль автоматически формирует кассовый чек и передаёт его в ОФД при каждом приёме реальной оплаты — согласно Федеральному закону № 54-ФЗ. Чеки бьются собственной кассой ООО «СмИТ» (а не делегируются платёжному агрегатору) по всем каналам: ЮKassa, Wallet One, банковские выписки и ручные пополнения. Реквизиты продавца (ИНН, СНО, НДС) берутся из брендинга компании — единый источник, без дублирования.

Как работает (поток чека)

1. Приём оплаты — webhook ЮKassa/W1, зачисление банковской выписки или ручное пополнение создаёт финоперацию (FinanceOperations).
2. Движок FiscalManager.enqueue() проверяет, подлежит ли операция фискализации (приход реальных денег; обещанный платёж, ежемесячные списания и бонусы — не фискализируются), собирает состав чека по 54-ФЗ и ставит задачу в очередь.
3. Очередь Celery отправляет чек в ОФД (АТОЛ Онлайн: sell / sell_refund), опрашивает статус, повторяет при сбоях и шлёт Telegram-алерт на «застрявшие» чеки.
4. Чек клиенту — электронный чек на e-mail/телефон абонента, ссылка в личном кабинете и мобильном приложении, статус и фискальные реквизиты — в карточке операции.

Статусы чека

• В очереди (pending) — операция помечена к фискализации.
• Отправлен (sent) — чек ушёл в ОФД, получен UUID запроса.
• Ожидает ОФД (wait) — ОФД обрабатывает, статус опрашивается периодически.
• Принят ОФД (done) — чек зарегистрирован, сохранены № ФД, ФП и ссылка на чек.
• Ошибка (fail) — ОФД отклонил или недоступен; авто-повтор до N попыток, затем Telegram-алерт.

Страница настроек /admin/settings/AtolConfig/

В шапке — главный выключатель «Фискализация включена» с бейджем режима, реквизиты ООО «СмИТ» (ИНН, без НДС / УСН) и индикатор связи с ОФД с кнопкой «Проверить связь».

Параметры чека:

• Провайдер ОФД — АТОЛ Онлайн (основной) или OrangeData.
• Контакт в чек — e-mail или телефон абонента по умолчанию.
• Наименование позиции — текст в чеке (по умолчанию «Услуги связи / доступ к сети Интернет»), либо брать из услуги абонента.
• Типы операций для чека — мультивыбор типов финопераций, по которым бить чек. Пусто = все приходы реальных денег, кроме обещанного платежа и ежемесячных списаний.
• Попыток отправки, опрос ОФД (мин), алерт застрявших (ч) — параметры очереди и мониторинга.

Внизу — статус-блок с реальной сводкой за день (пробито / ожидают ОФД / в очереди / с ошибкой) и ссылкой на журнал fiscal.log. Страница полностью поддерживает тёмную тему.

Касса (доступ к ОФД)

Кассовые параметры доступа суперпользователь вводит в модалке кассы: тип кассы, URL сервера ОФД, группа ККТ, логин и пароль, СНО, адрес размещения ККТ, e-mail продавца, флаг тестового сервера.

Чек в карточке операции

На странице Финансовые операции в карточке появляется секция «Чек» со статусом ОФД, номером ФД/ФП, ссылкой на электронный чек и кнопкой «Пробить чек» (для суперпользователя, приходные операции). Абонент видит ссылку на чек в личном кабинете и в мобильном приложении (поле receipt_url в истории операций).

Налогообложение

ООО «СмИТ» работает на УСН без НДС — в чек ОФД передаётся признак «НДС не облагается». Ставка НДС и система налогообложения берутся из реквизитов компании (Брендинг); при переходе на ОСН переключатель ставки уже готов.

6.4. Платёжные системы

Настройка приёма онлайн-платежей. Поддерживается несколько провайдеров.

• ЮKassa (REST API v3) — современный API, рекомендован. Параметры: shopId, secret key (формат live_XXX или test_XXX), webhook URL (привязывается в личном кабинете ЮKassa).
• ЮKassa HTTP — старый протокол на форме POST. Параметры: shopId, scid, shopPassword. Используется только для legacy-договоров.
• Wallet One (W1) — альтернативный провайдер. Параметры: merchant ID, secret key, валюта (643 = RUB), URL успеха и ошибки.
• Универсальный webhook — единый endpoint /lk/payments/webhook/, который принимает все форматы (W1, ЮKassa HTTP, ЮKassa REST v3, Generic) и зачисляет на счёт.

Справа на странице — карточка с описанием комиссии каждого провайдера и краткой инструкцией.

Маппа платёжных систем → FinTypes (build 510)

При успешном платеже webhook (lk/services/payment.py::_credit_abonent) создаёт FinanceOperations с типом операции, выбираемым по pay_system. Маппа настраивается через справочник типов + ключи SystemSettings:

Зачем это нужно: до build 510 все онлайн-платежи через ЮKassa и W1 одинаково записывались под type_id=23 «Оплата через платежные системы», что мешало бухгалтерии разделять источники. Теперь каждая платёжная система имеет свой FinTypes — отчёты «итого через ЮKassa за месяц» работают через простой фильтр по op_type_id без парсинга поля descr.

Как изменить:

1. Создать новый тип в Справочники → Типы фин. операций (например, «СБП» или «T-Bank»).
2. Установить SystemSettings.value для соответствующего ключа = type_id нового типа. Через /admin/settings/system/ или management-команду set_system_setting LK_PAYMENT_OPTYPE_YOOKASSA 51.
3. Webhook автоматически подхватит новое значение при следующем платеже (без рестарта).

Старые операции (под type_id=23) не переразмечаются — они остаются в истории под прежним типом. Только платежи, начисленные после миграции 0115 (build 510), получают новые типы. Это безопасно: отчёты с интервалом «после 2026-05-08» получат правильную разбивку, ранние периоды останутся как есть.

6.4.1. Банковские выписки (автообработка)

Модуль автоматического приёма и зачисления платежей из банковских выписок. Письма с CSV/TXT-вложениями приходят на собственный почтовый ящик bank@billing.smit34.ru (Mailcow на 31.44.7.144), парсер раскладывает операции в очередь модерации, matching сопоставляет с абонентами по 4 стратегиям (ИНН/лицевой счёт/назначение/fuzzy), оператор подтверждает или система автоматически зачисляет high-confidence матчи. Для юр.лиц генерируются PDF счёт-фактуры и акты (WeasyPrint), опционально загружаются в GCS и отправляются абоненту на email через noreply@billing.smit34.ru.

Полная карта URL:

• /admin/settings/bank_statements/ — настройки модуля
• /admin/settings/bank_statements/parsers/ — «Банки и парсеры»
• /admin/finance/bank_queue/ — очередь модерации
• /admin/finance/bank_imports/ — журнал импортов

Архитектура (8 фаз)

1. Mailcow на demo-сервере 31.44.7.144 — 4 ящика (bank/noreply/info/support) на subdomain billing.smit34.ru, MX/SPF/DKIM/DMARC в cloudns.net
2. IMAP-приёмник (billing/services/imap_client.py) — Celery beat bank-statements-pull ежечасно, реально работает в час/минуту из BANK_PULL_SCHEDULE_HOUR/MINUTE (default 6:00)
3. Парсеры (billing/services/bank_parsers/) — sber.py (TXT, cp1251, разделитель ;), alfa.py (CSV, cp1251, разделитель \t), dispatcher.py определяет формат по filename + первым байтам
4. Matching (bank_matching.py) — 4 стратегии в порядке приоритета: inn → account → purpose → fuzzy (отключаем для prod). AmbiguousMatch исключение если несколько кандидатов — операция уходит в очередь модерации
5. Credit (bank_credit.py) — transaction.atomic + select_for_update на AdminAccounts, kill-switch BANK_AUTO_CREDIT_ENABLED (default OFF), auto-unblock b_negbal при ostatok ≥ 0
6. PDF счёт+акт (bank_documents.py, WeasyPrint) — атомарная нумерация СЧ-2026-NNNN/АКТ-2026-NNNN через BankDocumentCounter, опциональная GCS-загрузка, учёт per-abonent настроек (send_act, auto_account, next_auto_acount)
7. Уведомления (bank_notifications.py) — Telegram-сводка по unmatched с anti-spam (cache 24h) + email абоненту с PDF-attached (до 8MB)
8. Admin UI — 4 страницы с UX-доводкой Sprint 1-4 (Health Score 58→88)

Главная страница настроек

Структура страницы (build 914):

• Tab-навигация: «Общие настройки» ↔ «Банки и парсеры»
• Статистика: hero-карточка «В модерации» — кликабельная (ведёт на ?status=manual_review), красный фон если >50; остальные 4 KPI (Импортов/За сегодня/Операций/Зачислено) — компактные
• Главный выключатель BANK_AUTO_CREDIT_ENABLED — отдельной карточкой full-width. По умолчанию ВЫКЛ — модуль обрабатывает выписки и наполняет очередь модерации, но НЕ создаёт FinanceOperations
• Дополнительные тогглы с цветовой меткой: 🟢 safe (auto_generate_docs, send_email_to_abonent), 🔴 danger (fuzzy_match с явным предупреждением «может ошибочно сопоставить»)
• Расписание (час+минута), день месяца отправки акта, GCS toggle, кнопки «Счёт»/«Акт» предпросмотра (модалка с iframe PDF)
• IMAP-приёмник (host/port/user/password/folder/SSL + whitelist) — кнопка «Проверить» с inline-результатом
• Telegram-алерты — поле «Ссылка на чат» парсит https://t.me/c/<chat_id>/<thread_id> или @username и заполняет chat_id + thread_id + название

Все тогглы (детальное описание)

IMAP-приёмник и whitelist

IMAP-настройки подключаются к Mailcow на mail.billing.smit34.ru:993 (SSL). Ящик bank@billing.smit34.ru читает все UNSEEN-письма, сохраняет вложения .csv/.txt в таблицу BankStatementImport. Whitelist отправителей в виде запятой-разделённой строки доменов: @alfabank.ru,@sberbank.ru,@sbrf.ru. Письма от других отправителей игнорируются (статус skipped).

Telegram-алерты по unmatched

Celery beat bank-statements-unmatched-alert запускается ежечасно. Если есть pending платежи ≥ BANK_TG_ALERT_MIN, отправляет сводку в чат: список последних 10 платежей (сумма, плательщик, банк, дата) + итоговая сумма + кнопка-ссылка на очередь модерации. Anti-spam: при стабильном количестве pending повторный алерт не отправляется (cache bank_unmatched_alert:last_count TTL 24h).

В UI кнопка «Добавить» парсит ссылку https://t.me/c/2910452601/18140 → автоматически заполняет chat_id=-1002910452601 и thread_id=18140. Поддерживаются 3 формата: /c/<chat>/<thread>, https://t.me/<username>, числовой -100....

6.4.2. Банки и парсеры

Регистр банков с привязкой к парсерам и email-доменам отправителей. По умолчанию загружены Сбербанк и АльфаБанк через миграцию 0144 (data-seed). Без активных записей здесь IMAP-приёмник игнорирует все входящие письма.

Колонки таблицы: # | Банк (название + slug) | Email-домен | Парсер (цветной чип) | Импортов (async-счётчик) | Статус (активен/выключен) | Заметки | Действия (редактировать/удалить).

Модалка «Добавить банк»:

• Название банка (например, «Тинькофф Банк»)
• Slug — латинский идентификатор. Автогенерация через транслитерацию ГОСТ 7.79: «Сбербанк» → sberbank
• Email-домен отправителя (валидация: должен начинаться с @ и содержать точку)
• Парсер: sber / alfa / generic (custom mapping для нестандартных CSV)
• Toggle «Включён»
• Заметки (textarea)

Добавление нового банка (например, Тинькофф):

1. Создать парсер в billing/services/bank_parsers/<slug>.py — наследовать от BankParser, реализовать parse(content: bytes) → List[ParsedOperation]
2. Зарегистрировать в billing/services/bank_parsers/__init__.py::detect_and_parse() — добавить ветку определения формата
3. Через UI «Добавить банк» создать BankParserBinding с новым parser_slug
4. Whitelist в настройках обновится автоматически (читает из BankParserBinding)

Защита от потери данных: при удалении банк-парсера BankStatementImport с этим email_domain в БД сохраняются (FK не настроен). Новые письма с домена будут игнорироваться. Восстановить — повторное добавление с тем же доменом.

6.4.3. Очередь модерации

Ключевая страница для финансиста-оператора. Обрабатывает 50-100 платежей в день. После 4 спринтов UX-аудита время обработки одного платежа сокращено с 5-7 кликов до 1 клика через bulk или 2 клика через one-shot модалку.

Возможности (Sprint 1-4)

• Chip-фильтры по статусу: На модерации / Сопоставлены / Зачислены / Отклонены / Все — со счётчиками, auto-refresh 30 сек (pulse-анимация при изменении), Page Visibility API (пауза при скрытой вкладке)
• Bulk-actions: чекбоксы + master-checkbox + sticky-toolbar gradient — «Зачислить выбранные» / «Отклонить» (с dropdown типовых причин)
• BS-модалки вместо confirm/prompt/alert:
  • Credit — preview через credit_preview/ endpoint: баланс «До → После», risk-флаги (большая сумма / fuzzy / расхождение ФИО)
  • Adaptive confirm-button: зелёная без рисков, жёлтая warning, красная danger. Auto-focus только если нет danger (защита от случайного Enter)
  • Reject — dropdown типовых причин (Не наш / Дубль / Возврат / Ошибка плательщика / Другая) + textarea
• AJAX-update без reload: Toast + зелёная вспышка строки (1.7 сек), scroll и фильтр НЕ теряются
• Undo-banner: 8 сек countdown после Credit/Reject/Bulk — кнопка «Откатить» создаёт storno FinOp + откат баланса + status → manual_review
• Keyboard shortcuts (vim-style): j/k навигация, x чекбокс, c/r/l Credit/Reject/Link, a выбрать всё, g m/c/a/r навигация по фильтрам, ? help-модалка со всеми shortcut'ами
• Sticky-колонки: чекбокс слева, «Действия» справа — на 1366px laptop скроллится середина, ключевые колонки всегда видны
• Иконки в статусах для colour-independence: fa-hourglass-half/fa-link/fa-check-circle/fa-times-circle
• Onboarding-tooltip 4 шага при первом визите (localStorage bq_onboarding_seen=v4). Shift+Click на help-иконку для перезапуска
• Empty-state с CTA: контекстный текст по фильтру + кнопки «Забрать сейчас / Журнал импортов / Показать все»

Credit-модалка (детально)

При клике «Зачислить» fetch'ит /admin/finance/bank_queue/<id>/credit_preview/ и собирает модалку с:

• 2 колонки (Платёж / Абонент) — детальные таблицы
• Balance-flow box «До → После» с цветной типографикой (красный для отрицательных, зелёный для положительных)
• Risk-флаги (warning/danger alerts) — большая сумма ≥ BANK_CREDIT_WARN_AMOUNT, fuzzy-стратегия, расхождение ФИО плательщика и абонента
• Adaptive button — цвет и текст меняются по уровню риска

Onboarding-tooltip

При первом визите показывает 4-step tour: Bulk-операции → Keyboard shortcuts → Undo → Risk-проверка. Bump версии (v4 → v5 в JS) — снова покажется после новых фич. Shift+Click на help-иконку (клавиатура в toolbar) — перезапуск.

6.4.4. Журнал импортов

Полный лог писем от банков с возможностью отладки. По умолчанию показывает последние 30 дней (защита от бесконечной выдачи при N тысячах импортов).

Фильтры в одну строку: Банк (Альфа/Сбер/Неизвестно/Все) | Статус (Новые/Разобранные/Ошибки/Без вложений) | Период (7д/30д/90д/Все) | кастомный date-range. Meta-bar над таблицей показывает текущий период + количество найденных записей.

Колонки: # | Получено (datetime) | От (email) | Тема | Банк (chip) | Файл (filename) | Статус (с иконкой) | Операций (всего / сматч. / зачисл.) | Действия.

Действия:

• «Операции» (fa-eye) → переход в очередь модерации с фильтром ?import_id=<pk> (отображает только операции этого письма)
• «Перепарсить» (fa-redo-alt) — для status=error: сбрасывает parser_error + ставит status=new + запускает process_pending_imports.apply()
• Для status=parsed — кнопка fa-sync-alt для повторного парсинга (создаст дубликаты только если UNIQUE(bank, external_id) не сработает)

Статусы письма-импорта

Колонка «Статус» в журнале — это статус письма с выпиской (модель BankStatementImport, набор IMPORT_STATUS_CHOICES). Всего 5 значений:

Как меняется статус: «Новый» → «Разобран»

Переход выполняет фоновая задача Celery, оператор в нём не участвует. Цепочка:

1. bank-statements-pull (Celery beat, ежечасно) — приёмник billing/services/imap_client.py читает UNSEEN-письма из ящика bank@billing.smit34.ru и создаёт BankStatementImport со статусом new.
2. bank-statements-process (Celery beat, каждые 5 минут) — функция process_pending_imports() в billing/tasks/bank_statements.py:
   • берёт BankStatementImport.objects.filter(status='new')[:20];
   • вызывает парсер по parser_slug банка (sber/alfa/generic);
   • на каждую строку выписки создаёт BankStatementOperation + запускает matching;
   • при успехе — imp.status = 'parsed'; при сбое парсера — status = 'error' + текст в parser_error.

То есть письмо в статусе Новый автоматически становится Разобран в течение ~5 минут после получения — на следующем тике bank-statements-process. Если статус не меняется дольше — см. блок «Диагностика» ниже.

Диагностика: статус долго не меняется

Если письма зависают в статусе Новый и не переходят в Разобран — задача bank-statements-process не выполняется. Что проверить:

• Жив ли планировщик — контейнер celery-beat должен быть в статусе running (docker ps).
• Видит ли beat банковские задачи — после деплоя новых beat-задач контейнер celery-beat обязательно пересоздаётся. Если он запущен на устаревшем образе, задачи из CELERY_BEAT_SCHEDULE в его расписание не попадают, и bank-statements-process молча не запускается (контейнер при этом «running», ошибок нет).
• Ручной запуск как обходной путь — задачу можно выполнить немедленно: process_pending_imports() разберёт все письма со статусом new.
• Кнопка «Перепарсить» в журнале — для писем со статусом error сбрасывает ошибку, ставит new и сразу запускает разбор.

Шрифтовая пара для PDF

В Брендинге → карточка «Документы» → селект «Шрифтовая пара для PDF». 5 кириллических вариантов:

• pt_serif — PT Serif + PT Sans (классика, ParaType, default)
• roboto — Roboto Slab + Roboto (современный, Google)
• inter — Inter (UI-friendly, наиболее читаемый)
• merriweather — Merriweather + Open Sans (газетный)
• golos — Golos Text (российский, Geometric grotesque)

⚠ Ограничение WeasyPrint: в Docker-контейнере нет доступа к fonts.googleapis.com, поэтому в PDF — fallback на DejaVu Sans. Шрифты применятся только при печати через браузер либо при переходе на Playwright/Chrome headless для PDF-генерации. Поле font_pair сохраняется корректно.

Per-abonent настройки документов

Учитываются существующие поля абонента (вкладка «Настройки» в карточке):

• send_act «Отправлять счёт» — выпускать счёт-фактуру
• auto_account «Формировать акт автоматически» — выпускать акт
• next_auto_acount «Дата выставления акта» — откладывает акт до даты

Если у юр.лица оба флага OFF — документы не генерируются даже при BANK_AUTO_GENERATE_DOCS=true. Если next_auto_acount не задан, используется fallback на BANK_DOC_DEFAULT_SEND_DAY (день месяца).

6.4.5. Почтовый сервер (SmitMailServ)

URL: /admin/settings/mailserver/ (build 960+) — управление собственным почтовым сервером SmitMailServ (форк Mailcow), развёрнутым на хосте mail.billing.smit34.ru. Раньше операции с ящиками/доменами требовали входа в Mailcow Admin UI — теперь всё доступно из биллинга через API https://mail.billing.smit34.ru/api/v1/.

Вкладка «Обзор»

Состояние сервера, настройки API, защищённые ящики, DKIM/SPF/DMARC.

• Состояние сервера — Статус (Online/Offline) · Версия SmitMailServ · Ящиков (всего/лимит) · Использовано места. Кнопка «Проверить подключение» делает test-request к API.
• Настройки API — Endpoint API, API-ключ (rw) с переключателем видимости, Основной домен (<select>, подгружается через GET /admin/settings/mailserver/api/domains/), toggle «Проверять SSL-сертификат».
• Защищённые ящики — bank@billing.smit34.ru, noreply@billing.smit34.ru, ask@support.smit34.ru и др. Нельзя удалить через UI (server-side защита в get_protected_mailboxes()), чтобы не сломать банковские выписки/рассылку.
• DKIM / SPF / DMARC — статус DNS-записей по нажатию «Обновить».

Вкладка «Ящики»

AJAX-таблица всех ящиков выбранного домена. Колонки: Email | Имя | Квота (использовано / лимит) | Активен | Создан | Действия (редактировать / сменить пароль / удалить). Поиск по email/имени с debounce. У защищённых ящиков рядом с email иконка-щит (fa-shield-alt).

Добавление ящика (кнопка «Добавить ящик»):

• Домен — теперь <select> с подгрузкой реального списка из SmitMailServ (build 960). Раньше — текстовое поле, легко было опечататься.
• Логин (до @) — локальная часть адреса.
• Пароль + Подтверждение — обязательны. Генератор пароля рядом (фиолетовая иконка fa-magic).
• Квота (МБ) — default 1024. Активен — toggle.
• При создании системных ящиков (bank@/noreply@/ask@…) пароль автоматически синхронизируется в SystemSettings (_sync_password_to_settings()), чтобы IMAP-парсер банковских выписок и SMTP-рассылка биллинга получили актуальный пароль одним нажатием.

Вкладка «Админы доменов»

Управление доменными админами SmitMailServ. У админа можно назначить набор доменов, которыми он управляет (<select multiple> с тем же AJAX-источником). Полезно если на сервере несколько обслуживаемых доменов — каждому даём отдельного админа.

REST API внутри биллинга

Все endpoint'ы за @user_passes_test(_is_superadmin) — только суперадмин. Каждая CRUD-операция пишет в AuditOperations с table_name='MAILSERVER'.

Backend: billing/services/mailcow_client.py (MailcowClient — 15 методов API, retries через urllib3.Retry, MailcowAPIError) + billing/views/mailserver_settings.py. Endpoint API хранится в MAILCOW_API_URL, ключ в MAILCOW_API_KEY (категория mailcow).

6.4.5А. Домены и DNS (Cloudflare)

URL: /admin/settings/dns/ — управление DNS-зонами через Cloudflare API прямо из биллинга: зоны и записи (CRUD), сценарии в один клик и диагностика.

• Доступ — Global API Key или Scoped Token; ключи задаются глобально либо для каждой организации отдельно (мультиорг: у каждой компании свой аккаунт Cloudflare).
• 1-клик «Почта» — создаёт полный набор записей домена: A (mail.домен), MX, SPF, DKIM, DMARC.
• 1-клик «Поддомен» — добавляет A/CNAME на сервер (например lk.домен).
• Диагностика — проверка почтовых записей домена и резолва хоста.

6.4.6. Автонастройка почтовых ящиков и DNS

Единый сервис провижинга (billing/services/mailbox_provisioning.py) создаёт почтовый ящик, прописывает DNS-записи и заполняет настройки подключения — одной кнопкой. Работает везде, где системе нужен ящик.

Что делает автонастройка

1. Регистрирует домен в почтовом сервере (идемпотентно — повторный запуск безопасен).
2. Создаёт ящик <имя>@<домен> с сгенерированным паролем. Если ящик уже существует — переиспользует его пароль, ничего не сбрасывая.
3. Прописывает DNS-записи почты в Cloudflare: A (mail.домен), MX, SPF, DKIM, DMARC.
4. Заполняет параметры подключения (SMTP и/или IMAP) в том модуле, откуда запущена.

Где доступна

Ящик сотрудника и пересылка

В профиле (/admin/settings/profile/) сотрудник создаёт себе ящик, если включена настройка «Разрешить персоналу создавать email». Логин подставляется из имени пользователя, пароль генерируется автоматически — достаточно нажать «Создать». Опционально указывается адрес пересылки: копии входящих уходят на внешний адрес, оригинал остаётся в ящике.

6.5. Интеграции

Единая точка управления внешними сервисами. Страница разделена на 8 вкладок. В нижней части любой страницы биллинга в футере отображается мини-индикатор статуса ИИ-ассистента (✓ AI / ✗ AI / ⏸ AI / ? AI) с количеством сообщений за сегодня.

Вкладка «Обзор»

Сводка всех настроенных интеграций со статусами. Цветной бейдж справа от каждой интеграции показывает: ✓ настроена / ✗ ошибка / ⏸ выключена / ? не настроена. Кнопка «Проверить все» запускает последовательно тест каждой настроенной интеграции; результаты появляются как Bootstrap-toast в правом верхнем углу.

Вкладка «Telegram»

Подключение Telegram-бота для двух целей: отправка уведомлений абонентам (те, кто подписался через личный кабинет) и чат оператора для системных алертов (NAS DOWN, ошибки платежей, СОРМ-выгрузка).

Параметры: токен бота, прокси SOCKS5 (api.telegram.org заблокирован для российских IP), ID чата администратора, переключатели типов алертов, тест отправки сообщения.

Вкладка «VK»

Интеграция VKontakte для двух функций: OAuth-логин в ЛК (абонент может зайти через свой VK-аккаунт) и отправка сообщений в личку группы.

Параметры: App ID для OAuth-логина, Community Token для отправки сообщений, ID группы. Тест соединения проверяет валидность токена.

Модуль «Поддержка» — единое окно техподдержки

Поддержка (/admin/support/) — нативный модуль техподдержки внутри биллинга: приём обращений из всех каналов, карточка тикета со связью с абонентом и CRM, AI-ответы, база знаний, аналитика. Заменил внешний FreeScout — весь приём и обработка теперь внутри СмІТ Биллинг.

i-иконка рядом с заголовком раздела Поддержки и в модалках тикета ведёт прямо сюда.

Приём обращений — единая точка

Все каналы (email IMAP, VK, Telegram, MAX, голосовая почта Mango, веб-виджет) сходятся в единую функцию приёма, создающую или дополняющую тикет; AI-бот AIDA может ответить автоматически или эскалировать на оператора.

flowchart TD
    EM["Email (IMAP)"] --> IN
    VK["VK"] --> IN
    TG["Telegram (polling)"] --> IN
    MAX["MAX (WS)"] --> IN
    VM["Голосовая почта Mango"] --> IN
    WG["Веб-виджет"] --> IN
    IN["ingest_message()"] --> CONV["Тикет (SupportConversation)"]
    CONV --> AI{"AI-бот доступен?"}
    AI -- "да" --> REPLY["Автоответ"]
    AI -- "эскалация/нет" --> OP["Оператор: Входящие"]
    REPLY -. "ESCALATE_TO_HUMAN" .-> OP

Входящие: список тикетов, поиск

KPI-карточки (Активные/Ожидают/Закрыто/Спам), статусные папки, фильтры (приоритет/категория/период/ящик) и умный поиск.

Поиск по тексту переписки. Ищет по теме, тексту сообщений, ФИО/договору абонента, адресу, телефону (любой формат) и №. Если совпадение не в теме — в строке тикета показывается сниппет-выдержка из тела сообщения с жёлтой подсветкой, чтобы оператор видел, почему тикет найден.

Карточка тикета и сайдбар

Слева — тред сообщений и редактор ответа (шаблоны saved-replies, AI-«Нейроответ»). Справа — сайдбар: Ответственный + Приоритет, Категория, Биллинг (аватар/баланс/тариф/статус/соцсети), SLA-таймер «Ждёт ответа», Прошлые обращения абонента, Теги, Доп. поля, Логи времени.

• SLA-таймер — время с последнего сообщения клиента без ответа оператора; цвет по порогу (зелёный <1 ч · оранжевый <4 ч · красный ≥4 ч).
• Прошлые обращения — последние 5 тикетов абонента (№ · тема · статус · дата), клик открывает тикет.

Выезжающая панель тикета

Клик по тикету из «Входящих» выдвигает панель быстрого просмотра без ухода со списка: мини-Биллинг (аватар/баланс/тариф/статус/соцсети), быстрая смена приоритета одним кликом, SLA-таймер, прошлые обращения, тред и блок ответа.

Мобильная адаптация

На узком экране над тредом появляется свёрнутая sticky-шапка абонента (аватар/ФИО/баланс/статус); разворот показывает SLA, договор/тариф/телефон и кнопки «Карточка» / «Управление». Ключевой контекст всегда перед глазами.

Вложения: политика, оптимизация, архив в GCS

• Политика вложений (настройки) — множественный выбор типов файлов (изображения / документы / архивы / …) + макс. объём; список расширений динамически мержится в accept форм загрузки.
• Оптимизация картинок — изображения сжимаются при загрузке (Pillow, ≤1600px, JPEG q82) — экономия диска без видимой потери качества.
• Архивация в GCS — Celery-задача переносит старые вложения (настройки: возраст в днях, порог объёма) в облако; локальный файл удаляется только после успешного аплоада.

Категории обращений и «Перезвонить»

Категории настраиваются пер-ящик (у каждой — имя и иконка), выбираются в сайдбаре тикета и в модалке создания; фильтр по категории — в списке. Отметка «Перезвонить» на тикете создаёт заметку (с необязательным комментарием) и поднимает тикет в блок «требующие внимания».

Тикеты, требующие внимания + кнопка «следующий»

Под формой ответа — до 3 карточек тикетов, требующих внимания оператора («Перезвонить» и «Клиент ждёт N мин»); в шапке — кнопка перехода к следующему такому тикету. Включается настройкой.

Прочие возможности карточки

• Редактирование своего ответа/заметки — автор может исправить отправленное (с отметкой о правке); суперадмин — любое такое сообщение.
• Нормализация адресов — адрес из текста тикета прогоняется через DaData ФИАС (для голосовых — предварительно Claude переводит адрес прописью в цифры), геокод попадает на карту сети.
• AI авто-триаж — команда закрытия/классификации старых тикетов с помощью AI (массовая разгрузка очереди).
• Модалка нового тикета — поиск абонента (имя/телефон/договор/ адрес), контакты и ящик подставляются по организации абонента, вложения-скриншоты, цветные кружки приоритета.
• Рейтинги — оценка ответа оператора клиентом (настройка).
• Учёт времени — таймер (авто-старт на своих тикетах) + ручное добавление, блок «Логи времени» в сайдбаре.

Настройки, база знаний, аналитика

Настройки Поддержки — вкладки (единый стиль): Общие, Авто-назначение ответственного/наблюдателя, Категории, Рейтинги, Учёт времени, IMAP+SMTP, Telegram/каналы (пер-ящик). Также: База знаний, Аналитика, Голосовая почта, Мессенджеры, Теги.

Интеграция с HelpDesk (FreeScout, устар.) — назначение и роль

СмИТ HelpDesk — независимая система поддержки клиентов на собственном поддомене support.smit34.ru. СмИТ Биллинг интегрирован с ним двусторонне: данные абонента видны в карточке тикета, тикеты доступны во вкладке «HelpDesk» абонента, AI-ассистент Claude отвечает на простые вопросы автоматически.

Полное описание системы поддержки — рабочее место оператора, канбан-доска подключений, теги, база знаний, AI-ассистент, отчёты — вынесено в отдельный раздел:

Что синхронизируется с биллингом

REST API биллинга для FS-плагина

В HelpDesk установлен модуль SmitBilling — он показывает оператору информацию об абоненте прямо в карточке тикета. Модуль читает из биллинга по REST API:

Конфигурация в .env HelpDesk: SMIT_BILLING_API=https://rbill.smit34.ru/rest_api/v2/. Аутентификация — Bearer-токен интеграции. После изменения настроек выполняется очистка кеша и перезапуск очереди HelpDesk (системным администратором).

Webhook-события из HelpDesk в биллинг

Регистрация webhook’ов — в админке HelpDesk, раздел «API и Webhooks → Добавить». URL приёма webhook на стороне биллинга — https://rbill.smit34.ru/api/helpdesk/webhook/.

Вкладка HelpDesk в карточке абонента

В /admin/Abonents/<id>/ есть вкладка HelpDesk:

• Список тикетов абонента (читается через FS API при открытии вкладки);
• Кнопка «+ Создать тикет» — модальное окно с темой и текстом, отправка через POST /api/v1/conversations;
• Каждый тикет — клик ведёт в HelpDesk в новой вкладке;
• Статусы тикетов с цветными бейджами: 🟢 active, 🟡 pending, ⚫ closed.

На стороне биллинга — REST-клиент с retry-логикой и кешированием ответов.

Claude AI как агент HelpDesk

В HelpDesk установлен модуль ClaudeAI — AI-ассистент Anthropic. Подробнее — в разделе HelpDesk → AI-ассистент Claude. Кратко: используется для автоответа в чате ЛК и мобильного приложения, для подсказки ответа оператору в карточке тикета, для автоклассификации тегов. Настройка — support.smit34.ru/claudeai/settings.

Вкладка «HelpDesk + Claude AI»

Система обработки заявок поддержки. HelpDesk — независимая система поддержки клиентов; биллинг общается с ним через REST API. Claude AI — встроенный AI-ассистент HelpDesk, который автоматически отвечает на простые вопросы абонентов в чате личного кабинета, эскалируя сложные обращения оператору.

Параметры: URL HelpDesk, API-ключ, mailbox по умолчанию для новых заявок. Claude AI настраивается отдельно (API-ключ Anthropic, прокси для api.anthropic.com).

Вкладка «AIDA»

Fallback ИИ-ассистент на случай, если Claude недоступен. Используется те же сценарии (чат в ЛК и мобильном приложении), но через альтернативный API.

Параметры: URL AIDA-сервера, API-ключ, переключатели мест использования (LK / Mobile / Billing-monitor). При обоих настроенных Claude и AIDA — приоритет у Claude.

Вкладка «IPTV» (TVIP Media + LFStream)

Подразделы вкладки для двух IPTV-провайдеров: TVIP Media (российский middleware) и LFStream «Смотрёшка». Биллинг управляет пакетами абонента через их API: при активации или деактивации соответствующей услуги в биллинге автоматически включается/выключается пакет в middleware.

Параметры обоих сервисов: URL API, login/pass или API-ключ, ID оператора, тест соединения. Маппинг услуг → пакетов задаётся отдельно в разделе 5.6 IPTV-пакеты.

Вкладка «GCS» (Google Cloud Storage)

Google Cloud Storage используется для публичных файлов: скриншоты документации, иконки услуг, отчёты для скачивания.

Параметры: Service Account JSON-ключ (загружается через файл или вставляется как текст), имя GCP-проекта, имя бакета, префикс для путей внутри бакета.

Вкладка «География» (Адреса + Карта)

Объединяет два геосервиса: геокодер DaData (поиск адреса с автокомплитом и автоматический расчёт координат) и тайловый слой карты (OpenStreetMap / 2ГИС / Yandex Maps). Используется в карте абонентов и при создании адреса.

Параметры DaData: API-ключ. KPI-блок показывает сколько адресов уже геокодировано из общего числа (на демо: 4045 / 4261 = 94.93%).

6.5А. Голосовая связь (провайдеры телефонии)

URL: /admin/settings/telephony/ · Модуль: voice «Голосовая связь» (тариф Pro и выше) — приём звонков операторами: голосовая почта, click-to-call, записи разговоров → тикеты Поддержки и сделки CRM.

Оператор телефонии — плагины

Оператор подключается как плагин: базовый интерфейс TelephonyProvider в billing/services/telephony_providers.py. Новый оператор = новый класс в реестре, страница настроек не меняется. Активный провайдер хранится в настройке TELEPHONY_PROVIDER.

Карточка провайдера показывает бейджи «настроен / click-to-call / записи». Кнопка «Проверить связь» делает реальный запрос к API оператора и возвращает результат прямо на странице.

Голосовая почта — маршрутизация линий

Оператор присылает запись звонка письмом на служебный ящик. По номеру, на который позвонил клиент (VoiceMailLine.phone), выбирается:

• Ящик Поддержки или ящик Подключения — куда попадёт обращение (тикет или лид);
• Сегмент — физлица (B2C) / юрлица (B2B) / бренд / поддержка;
• Тип сделки в CRM и организация (мультиорг);
• UTM-метки и привязка к рекламной кампании.

Расшифровка звонка нормализуется AI и классифицируется: обращение в поддержку, заявка на подключение или мусор. Абонент определяется по номеру — если номер принадлежит абоненту, всегда создаётся тикет (не лид).

Пропущенные звонки → «Неразобранное»

Тумблер на странице включает настройку CRM_UNSORTED_MANGO: пропущенный входящий (и невнятное голосовое) создаёт сделку в воронке «Неразобранное» с дедупликацией по телефону — обращение не теряется, оператор разбирает его вручную. Запись разговора прикрепляется к сделке (DealCall.recording_gcs_url).

6.6. IPTV-пакеты

Маппинг услуг биллинга на IPTV-пакеты провайдера. Например: услуга «IPTV Базовый» в биллинге → пакет ID 12 в TVIP, услуга «IPTV Премиум» → пакет ID 18. При активации/деактивации услуги абонента биллинг автоматически включает/выключает соответствующий пакет в middleware.

Встроенный просмотр ТВ в ЛК и приложении

Абонент с активной IPTV-подпиской может смотреть каналы прямо в личном кабинете и в мобильном приложении — без установки стороннего приложения провайдера. В ЛК это HTML5-плеер (нативный HLS в Safari/iOS или через hls.js в остальных браузерах), в приложении — нативный video_player (ExoPlayer на Android, AVPlayer на iOS).

Плейлист каналов формируется по шаблону URL провайдера с подстановкой {login} / {account} абонента из таблицы маппинга (IptvAccountMapping). Просмотр доступен только при выполнении всех условий:

• Просмотр включён — настройка IPTV_WATCH_ENABLED;
• Активна IPTV-подписка абонента (UsersUsluga, system_type=21);
• Абонент в сети СмИТ — у него есть интернет-тариф;
• опционально только онлайн — при активной RADIUS-сессии (IPTV_WATCH_REQUIRE_ONLINE);
• задан шаблон плейлиста провайдера.

Если условие не выполнено, абоненту показывается понятная причина («Просмотр доступен только в сети СмИТ», «Плеер каналов настраивается» и т.п.).

Реализация: сервис billing/services/iptv_playlist.py (can_watch / playlist_url / watch_context), ЛК /lk/iptv/, мобильный экран «Интерактивное ТВ» (GET /mobile-api/v1/iptv/packages возвращает блок watch).

6.6А. Модуль IPTV — раздел /admin/iptv/

Отдельный раздел сайдбара IPTV объединяет управление интеграцией с TV-провайдерами (TVIP Media и LFStream «Смотрёшка»): дашборд, пакеты, аккаунты абонентов, журнал API и настройки.

Дашборд

Бизнес-метрики: выручка IPTV (MRR — сумма активных подписок UsersUsluga с system_type=21), число активных подписок и витринных пакетов, динамика подключений/отключений за 30 дней, здоровье интеграции (% успешных запросов к провайдерам за сутки), топ-пакеты, распределение по провайдерам.

Пакеты и витрина провайдеров

Витрина-справочник популярных РФ-провайдеров: TVIP Media и LFStream — с рабочей интеграцией, остальные (24часаТВ, LIME HD, Ministra, Микроимпульс, Смартила) — справочно. Ниже — таблица маппинга «услуга биллинга ↔ пакет провайдера» с автоподбором по имени и подсветкой несопоставленных строк.

Аккаунты абонентов

Список связок «абонент ↔ аккаунт у провайдера» (IptvAccountMapping). Чипы-фильтры по статусу (Все / Подтверждённые / Не подтверждённые / С ошибкой), колонки Пакет и Услуга (берутся из БД через активные IPTV-услуги абонента, без онлайн-опроса провайдера).

Клик по кнопке «Подробнее» открывает модалку деталей аккаунта в три колонки — статус, синхронизация, аккаунт/логин, договор, тариф, баланс, блокировки + IPTV-услуги абонента и журнал запросов к провайдеру. Клик по имени абонента открывает слайд-панель (см. ниже).

Подтверждение аккаунта (account_verified): ресинк находит аккаунт у провайдера по логину; только для подтверждённых аккаунтов реально выполняются block/unblock (гейт защищает от массовых ложных ошибок). В TVIP-панели ~127 аккаунтов, из них принадлежат СмИТ — 16.

Журнал API и настройки

Журнал всех запросов к провайдерам (IptvApiLog) с человекочитаемым действием и телом ошибки. Настройки — credentials TVIP/LFStream, тест подключения, биллинг-toggle.

Биллинг IPTV и kill-switch

IPTV-подписка — обычная услуга абонента (UsersUsluga, system_type=21), списывается billing_worker штатно (1-го числа). В настройках есть переключатель «Не списывать деньги за IPTV» (IPTV_BILLING_DISABLED) — режим тестирования: плата за IPTV не списывается, дата следующего списания сдвигается вперёд (задним числом долг не образуется), провижининг у провайдера продолжает работать. Блокировка IPTV при долге — опциональна (IPTV_BLOCK_ON_NEGBAL, по умолчанию выкл).

Привязка пакета в карточке услуги

В модалке услуги типа «IP телевидение» есть вкладка IPTV — выбор провайдера и пакета. Связь «услуга ↔ пакет» можно задавать прямо из карточки услуги (не только на странице Пакеты).

На карточке абонента

На вкладке «Услуги» абонента в колонке «Примечание» для IPTV-услуги показывается «📺 провайдер: пакет», для трафика — «⚡ N Мбит/с» (макс. скорость CEIL_IN). У IPTV-услуги — бейдж «провайдер», открывающий модалку диагностики (сводка/пакеты/аккаунты/журнал).

Слайд-панель абонента: блок «Услуги» и IPTV-сайдбар

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

У IPTV-услуги — кнопка «Провайдер», открывающая поверх вложенный IPTV-сайдбар (сводка, активные пакеты, аккаунты у провайдеров с отметкой «подтверждён», журнал запросов).

6.7. ЛК и мобильные

Настройки личного кабинета и мобильных приложений. Страница в админке разделена на 5 вкладок.

Вкладка «Обзор»

Сводка статуса ЛК: количество активных абонентов в личном кабинете за месяц, количество установок мобильного приложения, ссылки на сторы (Google Play / App Store), ссылка на сам ЛК и на админ-страницы HelpDesk.

Вкладка «Брендинг»

Фирменное оформление ЛК: логотип, цвет акцента, доменное имя (lk.example.ru), favicon, OG-теги для соцсетей. Эти данные применяются к ЛК отдельно от админки — у админки и у ЛК могут быть разные цвета и логотипы.

Вкладка «Функции»

Toggle-переключатели видимости разделов в ЛК. Каждый переключатель — это глобальное правило, видит ли его абонент. Например, выключив «Тариф», оператор скрывает у всех абонентов возможность сменить тариф самостоятельно.

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

Вкладка «Безопасность»

Параметры доступа в ЛК: разрешать ли вход только из сети оператора (когда абонент дома), автологин по IP без логина и пароля, запрет смены пароля абонентом (полезно при общем семейном договоре).

Вкладка «Мобильное»

Настройки мобильных приложений Android и iOS: текущая версия в сторе, минимальная версия для force-update (если абонент использует более старую — увидит диалог обновления), ссылки на стора, параметры push-уведомлений (Firebase).

6.8. Сообщения

Настройка каналов отправки уведомлений абонентам. Страница разделена на 5 вкладок.

Вкладка «Email (SMTP)»

Параметры SMTP-сервера для исходящей почты: «От кого» (From), хост, порт, логин/пароль, режим шифрования, проверка SSL-сертификата. Кнопка «Отправить тест» отправляет письмо на указанный адрес через текущие несохранённые значения формы — это позволяет проверить настройки до сохранения.

Шифрование SMTP — radio-группа (build 961)

Раньше тип шифрования управлялся двумя независимыми toggle (STARTTLS + SSL), и оператор мог случайно включить оба — это приводило к ошибке Django EMAIL_USE_TLS/EMAIL_USE_SSL are mutually exclusive при попытке отправки.

С build 961 это одна radio-группа из трёх взаимоисключающих кнопок:

• STARTTLS (587) — наиболее распространённый вариант, default. Подключение в plain-text с upgrade до TLS через команду STARTTLS.
• SSL (SMTPS) (465) — TLS с первого байта (implicit TLS).
• Без шифрования — порт 25, plain SMTP. Только для внутренних SMTP-relays/локальной тестовой инфраструктуры.

Авто-подстановка порта. При смене radio JS подставляет порт (587/465/25), если в поле сейчас стоит один из «дефолтных» портов. Если оператор задал кастомный порт (например, 2525) — он сохраняется.

Защита на back-end. Если из формы каким-то образом пришли email_use_tls=True и email_use_ssl=True одновременно (старый кэш браузера, legacy POST), email_test_send и email_settings_save применяют XOR-нормализацию: оставляют тот режим, который соответствует порту (465 → SSL, иначе STARTTLS), второй гасят. В SystemSettings теперь никогда не лежат оба True.

Поле «От кого» и политика отправителя

Большинство SMTP-серверов (включая SmitMailServ) применяют политику «отправитель должен совпадать с авторизованным пользователем». Если у вас логин noreply@billing.smit34.ru, но в поле «От кого» вы указали billing@support.smit34.ru — сервер вернёт ошибку:

SMTPRecipientsRefused: 553 5.7.1 <billing@support.smit34.ru>:
Sender address rejected: not owned by user noreply@billing.smit34.ru

Решения:

• Простое — в поле «От кого» укажите тот же адрес, что и в «Логин».
• Гибкое — создайте alias на mail-сервере, чтобы noreply@billing.smit34.ru имел право отправлять от имени нужного адреса. Для SmitMailServ это делается через раздел «Почтовый сервер» → вкладка «Ящики» → редактирование ящика → поле sender_acl (или API edit_mailbox).

Вкладка «SMS»

Выбор провайдера SMS из четырёх: SMSAero, SMSC.ru, SMS.ru, Свой шлюз (Android-телефон). Каждый со своими параметрами (логин/пароль или API-ключ), общий — имя отправителя. Тест отправки на тестовый номер.

Свой шлюз — СмИТ SMS Gate for Android

Установите приложение СмИТ SMS Gate for Android на телефон с SIM-картой и следуйте инструкциям прямо в приложении (мастер первого запуска подготовит всё за 1–2 минуты).

Старый Android-смартфон с SIM-картой превращается в локальный SMS-шлюз биллинга. Стоимость — только тариф вашего мобильного оператора (часто пакеты «безлимитный SMS» 200–300 ₽/мес). Приложение — re-skin форк open-source SMS Gateway for Android (capcom6, Apache-2.0) под брендом СмИТ; см. MobileApp/SmitSMSGateway/ в репозитории биллинга.

Поддерживается 2 режима:

• Local Server — биллинг шлёт прямо на IP телефона (требует чтобы биллинг и телефон были в одной сети). URL: http://192.168.1.50:8080.
• Cloud Server — телефон через WebSocket подключается к api.sms-gate.app, биллинг шлёт REST туда. URL: https://api.sms-gate.app/3rdparty/v1. Не требует прямой связи между сетями.

Настройка телефона (Cloud-режим)

1. Установить приложение СмИТ SMS Gate for Android на телефон с SIM-картой.
2. На главном экране — переключатель «Облачный сервер» → ON.
3. Скопировать Имя пользователя и Пароль с экрана.
4. Включить Автозапуск (внизу экрана).
5. В настройках Android: Батарея → СмИТ SMS Gate → «Без ограничений» (иначе уйдёт в фоновую заморозку).
6. Внизу должна гореть надпись ОНЛАЙН — телефон подключён к cloud.

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

После сохранения — поле «Тестовая отправка» внизу страницы. Введите свой номер, нажмите Отправить тест. Должно прийти SMS в течение 5–30 секунд.

Webhook delivery-status (builds 514–518)

Только для cloud-режима sms-gate.app. Биллинг получает подтверждение реальной доставки SMS абоненту (не «отдано в шлюз», а «доставлено на телефон оператора»). Без webhook'а биллинг знает только что POST в шлюз вернул 200 OK — между «принято cloud'ом» и «дошло до пользователя» проходит от секунд до часов (если телефон-шлюз оффлайн).

Настройка (4 шага)

1. В UI /admin/settings/messaging/sms/ при выборе шлюза «Свой шлюз (Android-телефон)» внизу появляется блок «Webhook delivery-status».
2. Скопировать URL для регистрации кнопкой «📋 Копировать» (формат https://<ваш-биллинг>/api/sms/webhook/sms-gate/).
3. Нажать «🎲 Сгенерировать» для случайного 32-символьного hex-ключа HMAC-SHA256. Сохранить настройки.
4. Регистрация webhook'ов в sms-gate.app — через REST API (в приложении на телефоне нет UI для этого):

   curl -u USERNAME:PASSWORD https://api.sms-gate.app/3rdparty/v1/webhooks \
     -H 'Content-Type: application/json' \
     -d '{"url":"https://testbill.smit34.ru/api/sms/webhook/sms-gate/",
          "event":"sms:delivered","signingKey":"<ваш-secret>"}'

   Повторить для всех 3 событий: sms:sent, sms:delivered, sms:failed. Каждый зарегистрированный webhook возвращает свой ID.

Жизненный цикл SMS

Реальная статистика (с testbill 2026-05-07): pending → sent → delivered за 4–6 секунд при онлайн-телефоне. Если телефон оффлайн — sms-gate.app ставит сообщение в очередь и доставляет когда телефон вернётся (тестировано: 11 минут оффлайна — webhook'и пришли retry'ями сразу как телефон поднялся).

HMAC-подпись

Sms-gate.app шлёт подпись по схеме (официальная docs):

X-Signature: hex(HMAC-SHA256(secret, body + X-Timestamp))
X-Timestamp: 1715091045   # Unix epoch

Биллинг проверяет подпись через billing/views/sms_webhook.py::_verify_signature с поддержкой 4 форматов (для совместимости):

1. HMAC(body+timestamp, secret) hex — официальный формат sms-gate.app
2. HMAC(body, secret) hex — legacy без timestamp
3. base64 любого из вышеперечисленных
4. С префиксом sha256= или hmac-sha256= (стандартные конвенции webhook)

Constant-time сравнение для каждого кандидата. Если SMS_GATE_WEBHOOK_SECRET в SystemSettings пустой — подпись не проверяется (для теста / отладки). В production обязательно задавайте secret.

Защиты

От подделки

HMAC-SHA256 с секретом из SystemSettings.SMS_GATE_WEBHOOK_SECRET. Невалидная подпись → HTTP 401 + лог с диагностикой (sig, ts, body_len, headers).

От downgrade статусов

Если уже delivered, повторный event sms:sent не сбросит обратно. Приоритет: pending=0 < sent=1 < failed=2 < delivered=3. Учитывается только апгрейд по rank.

От Denial-of-Service

Endpoint работает без auth (стандарт webhook'ов), но без подписи или с невалидной — атакующий может только обновить sms_status для уже существующих sms_external_id. Записи не создаются, FK не нарушаются. Реальный риск — флуд логов, лечится rate-limit на nginx (опционально).

От retry-flood

Sms-gate.app шлёт webhook несколько раз для одного события (retry'ит при failure). Биллинг идемпотентен: повторный webhook на тот же messageId+status — no-op (запись уже обновлена с правильным rank).

Endpoint

URL: POST /api/sms/webhook/sms-gate/ (публичный, CSRF-exempt).

Headers (от sms-gate.app):

• Content-Type: application/json
• X-Signature: <hex> — HMAC-SHA256(body+timestamp)
• X-Timestamp: 1715091045 — Unix epoch

Body (JSON):

{
  "deviceId": "fIuD_aVrUyAIuN7DhxDw8",
  "event": "sms:delivered",
  "id": "<webhook-event-id>",
  "payload": {
    "messageId": "8_EwH18QDve2RnA_Sx7ye",   // совпадает с MsgStack.sms_external_id
    "phoneNumber": "+79991234567",
    "deliveredAt": "2026-05-07T14:13:50.923+03:00",
    "errorCode": "..."  // только для sms:failed
  },
  "webhookId": "..."
}

Responses:

• 200 {"ok": true, "msg_id": 20697, "status": "delivered"} — успех, MsgStack обновлён
• 200 {"ok": true, "matched": false, "message_id": "..."} — messageId не найден в БД (например, MsgStack удалена)
• 200 {"ok": true, "ignored": true} — неизвестное event, не падаем
• 200 {"ok": true, "skipped": "downgrade"} — попытка понизить статус (delivered → sent отвергнуто)
• 400 {"ok": false, "error": "bad_json"} — невалидный JSON
• 400 {"ok": false, "error": "no_message_id"} — нет messageId в payload
• 401 {"ok": false, "error": "invalid_signature"} — HMAC не сходится (только если secret задан)

UI отображения статуса (build 518)

На карточке абонента → вкладка «Сообщения» (8.16) бейдж SMS теперь показывает реальный статус доставки:

JS-функция _smsBadge(msg) в send_message_tab.html строит бейдж динамически после AJAX-create. MutationObserver на #msg-history-tbody автоинициализирует Bootstrap-tooltips на новых строках. После отправки бейдж 🟡 pending → через несколько секунд webhook → 🔵 sent → 🟢 delivered. Авторефреша без F5 пока нет (планируется отдельным билдом — JS-poll на /sms_status/<msg_id>/).

Решение проблем

SMS уходит, но в БД sms_status='pending' навсегда

Webhook'и не зарегистрированы в sms-gate.app. Проверь GET /3rdparty/v1/webhooks с твоей auth — должно быть 3 записи (sent / delivered / failed).

Webhook прилетает, но в логах invalid HMAC signature

Secret в биллинге и в webhook-регистрации не совпадают. Удали webhook и зарегистрируй заново с правильным secret. Или временно очисти secret в UI — webhook начнёт работать без проверки подписи (для теста).

SMS отправляется, но в БД sms_external_id=''

Используется тестовая отправка из UI (кнопка «Отправить тест») — она шлёт напрямую через _send_sms_tecno без создания MsgStack. Это by design. Для реального теста с tracking — отправь сообщение через карточку абонента → вкладка «Сообщения».

Webhook прилетает, но MsgStack не обновляется ({"matched": false})

Не совпадает messageId ↔ sms_external_id. Проверь что биллинг сохраняет id из ответа sms-gate.app: SELECT pk, sms_external_id FROM msg_stack WHERE sms_done=true ORDER BY id DESC LIMIT 5.

DNS-резолюция падает (NameResolutionError 'api.sms-gate.app')

Известная нестабильность Docker-DNS. В docker-compose.prod.yml блоки web и celery должны содержать extra_hosts: - "api.sms-gate.app:94.241.170.26". После добавления — recreate контейнеров.

Подтверждено вживую

Build 518 (2026-05-07) на testbill, абонент Письменный Павел (#7686, +79177271796):

14:13:44  Биллинг → POST api.sms-gate.app/3rdparty/v1/messages
          MsgStack #20697.sms_external_id = "8_EwH18QDve2RnA_Sx7ye"
          MsgStack #20697.sms_status = 'pending'
14:13:46  cloud → телефон ОНЛАЙН → отправка SMS
14:13:48  оператор → +79177271796 (SMS доставлена)
14:13:50  cloud → POST webhook event=sms:delivered → HMAC ✓
          MsgStack #20697.sms_status = 'delivered'
          MsgStack #20697.sms_status_date = 2026-05-07 14:13:50

Полная цепочка от отправки до подтверждения доставки в БД — 6 секунд. UI обновляется при F5 страницы.

Вкладка «Telegram»

Отправка уведомлений абонентам через Telegram-бота. Условие — абонент должен один раз связать свой Telegram-аккаунт с учётной записью в личном кабинете (нажав кнопку «Привязать Telegram»).

Бот используется тот же, что и в разделе Интеграции → Telegram. На этой вкладке только переключатели: посылать ли уведомления через Telegram и какие именно типы.

Вкладка «Push»

Firebase Cloud Messaging для push-уведомлений в мобильном приложении. Параметры: путь к Service Account JSON-файлу Firebase, имя проекта, переключатели типов событий.

Вкладка «Шаблоны»

Текстовые шаблоны уведомлений с переменными подстановки. Каждое событие имеет свой шаблон и список включённых каналов. Например, событие «Низкий баланс» может отправляться по Email + SMS, а «Подключение услуги» — только по Push.

Поддерживаемые события: низкий баланс, обещанный платёж активирован, обещанный платёж истёк, услуга подключена, услуга отключена, тариф изменён, платёж зачислен, блокировка / разблокировка. Доступные переменные: {{ abonent.name }}, {{ contract_number }}, {{ balance }}, {{ tariff }}, {{ amount }}, {{ end_date }} и т.д.

Редактор шаблонов: Plain + HTML (build 595–596)

Модальное окно редактирования шаблона расширено: 2 вкладки — «Текст (plain)» для коротких сообщений (SMS / Push / Telegram / VK / ЛК) и «HTML (Email)» с WYSIWYG-редактором TinyMCE 6 для оформленных HTML-писем. Plain-текст используется для всех каналов кроме Email; для Email — берётся HTML, если он заполнен, иначе fallback на plain (с заменой переносов на <br>).

Возможности

• WYSIWYG TinyMCE 6 на вкладке HTML: заголовки, списки, ссылки, изображения, таблицы, выравнивание, шрифт, цвета. Подгружается с CDN при первом показе вкладки (lazy-load) — не нагружает страницу пока шаблон не открыт.
• Большое окно: modal-xl (1140 px) с плавающим переходом в fullscreen на mobile/tablet (≤991 px). Высота TinyMCE — 520 px, можно растянуть кнопкой resize. Полноэкранный режим — кнопка fullscreen в toolbar.
• Plain-текстарея увеличена до 14 строк (минимум 320 px) — удобнее редактировать длинные шаблоны для Email с уведомлением.
• Кликабельные переменные в правой панели: клик по %(contract_number)s или {{ balance }} вставляет переменную в позицию курсора активного редактора (plain или HTML). Подсказка «Клик — вставить в редактор» под заголовком блока.
• Бейдж рядом с вкладкой HTML: ✓ если HTML-версия заполнена, скрыт если пусто. Ссылка «очистить» под редактором — сбрасывает HTML.
• Санитайзер bleach при сохранении: разрешены теги p, br, strong, em, a, ul, ol, li, h1-h6, table, tr, td, img, span, div и атрибуты class, style, href, src, alt, target, rel. Скрипты, on*-обработчики, iframe — удаляются. Защита от XSS в HTML-шаблонах.

Кликабельные переменные

В правой панели модалки — справочник переменных в двух форматах: Python format (%(name)s) и Jinja2 ({{ name }}, при включённом флаге «Jinja»). Каждая переменная обёрнута в кликабельный <code>: hover подсвечивает её зелёным, клик — вставляет в позицию курсора. Если активна вкладка HTML — вставка идёт в TinyMCE через insertContent(); если plain — в обычное <textarea>.

Какой канал берёт что

Готовые HTML-шаблоны писем (build 597)

В toolbar визуального редактора добавлена кнопка «Шаблоны писем» (зелёная, с иконкой ). Клик открывает выпадающий список из 8 готовых пресетов с автоматической подстановкой брендинга компании (CompanyBranding) — название, логотип, ИНН/КПП, контакты, адрес, акцентный цвет.

Каждый пресет — полноценное Email-письмо с тремя секциями:

• Шапка: логотип (или fallback-буква в круге с акцентным цветом) + название компании + ИНН/КПП. Снизу — 3px полоса акцентного цвета из брендинга.
• Контент: заголовок-сценарий, обращение к абоненту через %(abonent_name)s, основной текст с %(contract_number)s и %(balance)s, при необходимости — CTA-кнопка с акцентным цветом.
• Подвал: контакты компании (телефон, email, сайт) с иконками 📞 ✉ 🌐, юридический адрес, дисклеймер и подпись директора (если задано director_name в брендинге).

Поведение при вставке:

• Если редактор пуст или содержит менее 50 символов — пресет вставляется без подтверждения.
• Если в редакторе уже есть HTML — confirm-диалог: «Заменить готовым шаблоном «N»?».
• После вставки автоматически переключается на вкладку «Визуальный», чтобы оператор сразу увидел результат.
• Брендинг подгружается из CompanyBranding при каждом запросе — изменения логотипа/реквизитов мгновенно отражаются в новых пресетах.

Endpoint'ы:

• GET /admin/settings/messaging/email_presets/ → список пресетов ({items:[{id,name,icon,description}]})
• GET /admin/settings/messaging/email_presets/?preset=<id> → готовый HTML с подставленным брендингом ({ok:true, preset_id, html})

Реализация: billing/services/email_presets.py — изолированный модуль с реестром PRESETS. Каждый пресет — функция-сборщик контента, обёрнутая в общий wrapper _wrap() с шапкой и подвалом из _branding_dict(). Добавление нового пресета = одна функция + запись в PRESETS.

Миграция и схема

Поле AdminMsg.html_body (TextField, nullable) добавлено в build 595 (миграция 0120_adminmsg_html_body). Существующие шаблоны не затронуты — у них html_body = NULL, Email-канал продолжает работать через txt. Заполнить HTML можно постепенно по мере необходимости (приветствие новому абоненту → красивая HTML-вёрстка, авто-уведомление о низком балансе → plain).

6.9. Персонал и доступ

Управление сотрудниками биллинга. Доступно только пользователям с правами root. Страница разделена на 4 подраздела.

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

Список сотрудников с фильтрами «Активные» / «Архив». Уволенный сотрудник переводится в архив (не удаляется), его действия в аудите остаются. Auto-аватары с инициалами на цветном градиенте (хеш от имени).

Карточка сотрудника содержит: ФИО, e-mail, телефон, должность, дату приёма, группы доступа, настройки уведомлений. Дополнительно у каждого сотрудника есть Профиль — личные настройки (аватар, избранные отчёты, журнал собственных действий).

Подраздел «Интерфейс»

Настройка видимости полей в формах для каждой роли. Поля можно скрыть от группы, сделать read-only или required. Например, кассиру оставить только поле «Сумма платежа», а инженеру — все поля кроме финансовых.

Подраздел «Доступ к моделям»

Какие модели биллинга видит каждая группа пользователей. Чекбоксы Read / Create / Update / Delete для каждой модели (Tarif, Usluga, Abonents, NAS, и т.д.). Без галочки Read — пункт меню скрывается у этой группы.

Подраздел «Доступ к абонентам»

Какие папки абонентского дерева видит каждая группа. Полезно для разделения филиалов: агент филиала «Север» видит только папку «Север», агент филиала «Юг» — только папку «Юг», главный администратор видит весь корень.

6.10. Лицензия

Информация о действующей лицензии: количество разрешённых абонентов, дата окончания, тип (коммерческая / тестовая / OEM).

6.10А. Модули и расширения

URL: /admin/settings/modules/ — каталог модулей биллинга: что включено, что доступно в вашем тарифе и что можно докупить.

Карточка модуля

Каждый модуль показан карточкой с обложкой, номером версии (в правом верхнем углу), кратким описанием и чипами тарифов, в которые он входит. Управление:

• Тумблер — включить/выключить модуль. Выключенный модуль скрывается из меню и его разделы недоступны по прямой ссылке.
• «Настроить» — переход на страницу настроек модуля.
• «Подробнее» — модальное окно с полным описанием.

Недоступные модули

Модули, не входящие в ваш тариф, отображаются полупрозрачными с приглушённой обложкой, замком и подписью «Доступно в тарифе: …». Их карточки видны — чтобы понимать, что даёт переход на старший тариф. Ссылка «Перейти на тариф →» ведёт в раздел Лицензия.

Окно «Подробнее»

Открывает карточку модуля как в маркетплейсе: обложка, строка «категория · разработчик · тарифы» с кнопкой «Документация», полное описание и четыре вкладки:

• Возможности — что умеет модуль; здесь же список модулей, от которых он зависит.
• Как это работает — порядок действий по шагам.
• Скриншоты — реальные экраны раздела (клик открывает полноразмерное изображение).
• История версий — changelog по каждому релизу модуля.

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

Виджеты-плагины

Рядом с модулями — каталог виджетов (/admin/settings/widgets/): небольшие расширения, которые встраиваются в дашборды, карточку абонента, карточку сделки и сайдбар тикета. Виджет привязан к модулю и доступен, только если этот модуль включён.

6.11. Резервные копии

Резервные копии — самостоятельный таб в группе «Обслуживание».

Типы копий:

• db — только база данных (pg_dump в формате custom).
• files — медиа-файлы и шаблоны печати (tar.gz).
• both — БД + файлы.
• docker — самодостаточный пакет: БД, код, Dockerfile, docker-compose, .env, медиа и скрипт restore.sh. Достаточно для развёртывания на новом сервере.
• configs («Конфиги сервера», build 967) — лёгкий снимок только серверной конфигурации: .env, docker-compose*.yml, Dockerfile, gunicorn.conf.py, requirements.txt и весь каталог docker/ (nginx / freeradius / postgres). Без БД и кода — обычно несколько килобайт. Удобно для быстрого сравнения/отката настроек сервера.

Настройка: имя конфигурации, тип, расписание (cron-выражение), количество хранимых копий, включить/выключить, кнопка «Сделать сейчас» (запуск вне расписания).

Список копий — записи с датой, размером, статусом, типом. Кнопки в строке: Скачать, Восстановить, Удалить. В процессе backup'а строка показывает анимированный прогресс-бар (опрос статуса каждые 3 секунды).

Защита от «зависших» копий (build 967): если Celery-воркер падает или перезапускается во время резервного копирования (например, при переезде сервера), запись могла навсегда остаться в статусе running — на странице крутился вечный спиннер и шёл бесконечный опрос статуса. Теперь функция _reap_stale_running() автоматически помечает любую запись в running старше 30 минут как «Ошибка» с понятным сообщением. Срабатывает при открытии страницы и при каждом опросе статуса (раз в 3 секунды), так что зомби-запись сбрасывается сама. Дополнительно run_backup теперь явно завершается ошибкой при неизвестном типе бекапа или если файл не был создан (раньше такая копия молча сохранялась как «Выполнена» без файла).

Восстановление — модалка с выбором: только БД / только файлы / полное восстановление. Для типа docker показывается инструкция как развернуть копию на новом сервере.

6.12. Очистка БД и сессий

URL: /admin/settings/db_cleanup/ (раздел «Обслуживание», только root-доступ).

Раздел централизованного автоматического обслуживания БД и борьбы с «зомби»-сессиями RADIUS. Состоит из 5 блоков (сверху вниз): Состояние БД, Автоочистка, История запусков, Аудит зомби-сессий, Выбор NAS для аудита.

Состояние БД сейчас

Верхний блок — реальный счётчик записей в 4 ключевых таблицах (обновляется AJAX):

• MSG_STACK — журнал отправленных сообщений (Email/SMS/Push/Telegram). На testbill ~100K записей при ежедневной нагрузке 500–2000.
• AUDIT_OPERATIONS — аудит действий (создание/правка/удаление). На testbill ~600K записей за всё время.
• RADIUS_SESSIONS — история RADIUS-сессий (включая закрытые). На testbill ~5–7M записей при 1000+ онлайн-абонентах.
• NAS_EVENTS — события NAS (UP/DOWN, аларм). Маленькая таблица, чистится редко.

Каждая ячейка показывает размер (Кб/Мб/Гб) + количество записей. Если рядом с цифрой растёт ⚠ — таблица превышает порог опасного роста и требует внимания.

Автоочистка БД

Параметры retention (период хранения, после которого записи удаляются):

Расписание: Celery beat-задача db-cleanup-daily запускается ежедневно в 03:30 по серверному времени. Время фиксированное, для теста есть кнопка «Запустить чистку сейчас».

Что делает задача (build 453, billing/tasks/db_cleanup.py::run_db_cleanup):

1. Создаёт запись в DbCleanupRun с status='running'.
2. Для каждой из 4 таблиц считает порог cutoff = now - timedelta(days=N).
3. В цикле: DELETE ... LIMIT batch_size пока есть записи. Между батчами 100мс паузы — снижает нагрузку.
4. Записывает в результат: msg_deleted, audit_deleted, sessions_deleted, events_deleted, execution_time.
5. Обновляет DbCleanupRun.status='ok' + finished_at. При ошибке — status='failed' + error.
6. Если за прогон удалено > 100K записей — отправляет Telegram-уведомление.

Кнопки управления:

• «Применить» — сохранить изменённые retention-параметры в SystemSettings (без перезапуска чистки).
• «Запустить чистку сейчас» — синхронный запуск task'а через Celery .delay(). UI показывает spinner, через ~30 сек обновляет «Историю запусков».
• Тогл «Включено» — глобально отключить автоочистку (полезно при миграциях/бэкапах).

История запусков

Таблица последних 50 запусков из DbCleanupRun:

• Время старта и длительность в секундах.
• Статус: 🟢 ok / 🔴 failed / 🟡 running.
• Удалено: разбивка по 4 таблицам (Msg / Audit / RadSes / Events).
• Запустил: scheduled для beat-task или username при ручном запуске.
• Ошибка: tooltip с traceback при status='failed'.

Аудит зомби-сессий на NAS

Зомби-сессия — это запись в RADIUS_SESSIONS с END_TIME IS NULL (то есть «сессия активна»), но при этом NAS не подтверждает её существование. Возникает когда:

• NAS перезагрузился / упал и не прислал Accounting-Stop для последних сессий.
• Сетевой обрыв между NAS и FreeRADIUS — Accounting-Stop потерян.
• Bug в прошивке NAS (типичный пример — MikroTik с переполнением счётчика, см. build 445).

Зомби-сессии искажают виджет «Онлайн сейчас» на дашборде (показывает большее число, чем реально), мешают корректному выбору IP из пула при переавторизации, и забивают `RADIUS_SESSIONS` лишними «открытыми» строками.

Beat-задача session-audit-hourly (build 453, billing/tasks/session_audit.py):

1. Запускается раз в час (default; настраивается через SESSION_AUDIT_INTERVAL_MINUTES).
2. Берёт ровно 4 NAS (default SESSION_AUDIT_NAS_PER_RUN=4) — те, у которых давно не было аудита (sort by last_audit_at ASC). Так за сутки покрывается ~96 NAS — больше, чем у любого реального оператора.
3. Для каждого NAS берёт батч из 50 активных сессий (default SESSION_AUDIT_BATCH_SIZE=50). Это ~2 минуты времени NAS — не нагружает его.
4. Для каждой сессии: radclient запрос Status-Server или Accounting Interim-Update к NAS — если NAS не подтверждает наличие session-id → метим как «подозрительную».
5. Через 5 минут идёт повторная проверка тех же сессий. Если NAS ещё раз не подтверждает — сессия считается зомби, ставится END_TIME=now(), END_REASON='zombie-cleanup'.
6. Counter подтверждённых zombie добавляется в SessionAuditRun.zombie_killed.
7. Если zombie_killed > 0 — отправляется Telegram-алерт с разбивкой по NAS.

Параметры аудита:

История аудитов ниже — таблица из SessionAuditRun: время, NAS, проверено сессий, найдено зомби, длительность, статус.

Выбор NAS для аудита

Таблица всех NAS с enabled=True и колонками:

• Имя + IP NAS.
• Чекбокс «Включён в аудит» — индивидуально для каждого NAS (тогл сохраняется в Nas.session_audit_enabled). Удобно отключить аудит для проблемного NAS на время разбора.
• Последний аудит — дата/время последнего SessionAuditRun для этого NAS.
• Найдено зомби — счётчик из последнего аудита.
• Активных сессий сейчас — текущее количество.
• Кнопка «Запустить» — мгновенный аудит конкретного NAS (вне очереди), полезно для отладки.

На testbill сейчас в активном аудите 4 NAS: TOY, JOY, FAG, POT. Зомби-сессии редки (1–3 в неделю) — после фиксов build 445 (zombie-LOGGED + bigint миграция) это в основном NAS-перезагрузки.

Решение проблем

Чистка не отрабатывает в 03:30

Проверь Celery beat: docker logs app-celery-beat-1 | grep db-cleanup. Должна быть запись «Scheduler: Sending due task db-cleanup-daily». Если нет — beat не запущен или не видит задачу (импорт config/celery.py).

«MSG_STACK слишком большой» — 5М+ записей

Уменьши DB_CLEANUP_MSG_DAYS до 14 или 7 → жми «Запустить чистку сейчас». При первом проходе может удалить миллионы строк (займёт 10–20 минут). Дальше beat-задача держит размер в норме.

RadiusSessions растёт быстрее, чем чистится

В норме: 1 сессия = 1 строка с END_TIME IS NOT NULL через 5–10 минут. Если строк с END_TIME IS NULL много — есть зомби, запусти аудит. Если все закрытые, но всё равно много — увеличь DB_CLEANUP_BATCH_SIZE до 20000.

Telegram-алерт «zombie cleanup: 50+ sessions» каждый час

Один из NAS постоянно теряет Accounting-Stop. Проверь логи NAS, прошивку, сетевые потери до FreeRADIUS. Временно отключи аудит для этого NAS (чекбокс «Включён в аудит» = False) пока разбираешься.

Вернуть удалённые данные

Backup до чистки берётся ежедневно в 03:00 (за 30 минут до db-cleanup) — в /var/backups/carbon/. Восстановление таблицы: pg_restore -t msg_stack <dump-file>.dump в отдельную БД, потом INSERT нужных строк.

6.13. Диагностика

Набор готовых команд для диагностики проблем с конкретным абонентом или NAS. Запускаются прямо из веб-интерфейса, результат показывается в модалке-терминале.

Примеры команд: пинг NAS, проверка живости абонента, тест авторизации radtest, проверка SSH-доступа к NAS.

6.14. Массовые действия

Подменю с тремя инструментами обслуживания, объединёнными по смыслу «одно действие сразу для большой группы записей».

Подраздел «Разблокировать»

Массовая разблокировка абонентов. Открывается, если, например, партнёр-сборщик заплатил оптом за весь дом, и нужно одной кнопкой снять блокировку «долг» с десятков абонентов. Можно задать тип блокировки (b_negbal — долг, b_admin — админская) и фильтр абонентов (папка, тариф, дата блокировки).

Подраздел «Чистка БД»

Удаление тестовых/демо-данных при первичной настройке системы. Удаляет демо-абонентов, тестовые услуги, фейковые финансовые операции — всё, что было в стартовой поставке для демонстрации. Не трогает реальные данные оператора.

Запускать только один раз — после первичной настройки и до загрузки реальных абонентов. Действие необратимо, перед запуском система запрашивает подтверждение.

Подраздел «Закрытие периода»

Финальное действие месяца. Фиксирует балансы абонентов, переводит «корзину» (soft-deleted абонентов) в архив, готовит данные для бухгалтерской выгрузки. Запускается оператором вручную — обычно в первые дни нового месяца.

6.15. Производительность и оптимизация

В мае 2026 в биллинг внедрён пакет оптимизаций производительности (билды 813-821). Главная цель — устранить «тяжёлые» страницы которые открывались по 3-4 секунды и тормозили работу операторов при одновременной нагрузке.

Что было сделано

Семь пакетов улучшений, выкаченных за один день без даунтайма биллинга:

1. 8 composite-индексов PostgreSQL на самых частых полях запросов (audit, abonents_block, users_usluga, users.nas_id, radius.logged, finance_operations.op_date). Применены с CREATE INDEX CONCURRENTLY — без блокировки таблиц.
2. Redis-кеши для главного дашборда (TTL 60с), мониторинга NAS (TTL 60с), карты абонентов (TTL 5 мин), VpnConst-настроек (TTL 60с с автоматической инвалидацией при сохранении через UI).
3. Денормализация Abonents.last_payment_at — дата последнего платежа теперь хранится прямо у абонента, обновляется автоматически PostgreSQL-триггером на finance_operations.INSERT. Используется в фильтрах должников (period chips: новые/средние/старые/хронические).
4. Денормализация Abonents.primary_nas_id + primary_pool_id — основной NAS и пул IP-адресов абонента (по самой свежей учётной записи Users). Используется в списке абонентов папки, глобальном поиске и AJAX-подгрузке. Обновляется тремя триггерами на users.INSERT/UPDATE/DELETE.
5. statement_timeout=30s для пользовательских SQL-отчётов (/admin/reports/AdminCustomReports/) — защита от тяжёлых запросов которые вешали gunicorn-worker на минуты. После таймаута показывается понятное сообщение «Отчёт прерван по таймауту».
6. Устранение N+1-запросов в 5 горячих местах: NAS list (DISTINCT ON для last_event), NAS Monitor (GROUP BY вместо N COUNT), AdminAccounts (3 count → 1 aggregate с filter=Q), folder/search (lookup из Nas/IpPull вместо JOIN Users).
7. Убран функциональный cast op_date::date в FinanceOperations view — теперь используются B-Tree индексы вместо seq scan.

Что это дало

Главный эффект — страница должников (одна из самых частых для операторов отдела взысканий) теперь открывается мгновенно вместо 4 секунд ожидания.

Защитные механизмы

• Backup при деплое: код (tar 254 МБ) + pg_dump (29 МБ) — откат 5-10 минут.
• Celery beat safety-net: раз в неделю запускается rebuild-last-payment-at и rebuild-primary-nas-pool — полная сверка денормализованных полей с реальной таблицей. Если триггер пропустил какой-то платёж (например, при массовом импорте с отключёнными триггерами) — данные восстанавливаются автоматически.
• CONCURRENTLY-индексы: создание индекса не блокирует таблицу для чтения и записи, абоненты ничего не замечают.

Документы (для разработчиков)

• Отчёт директору — «Ускорение биллинга» — общее описание простыми словами
• Раздел «Документы для разработчиков» — все технические отчёты по фазам 1-4: план оптимизации, реализация индексов и кешей, денормализация last_payment_at, денормализация primary_nas/pool

6.16. Captive Portal (финблокировка)

Captive Portal Engine — единый движок порталов для перехвата трафика через walled-garden. Должник с отрицательным балансом не отрезается полностью, а перенаправляется на страницу «пополните баланс», сохраняя доступ к ЛК, банкам и госуслугам — это ускоряет возврат дебиторки и снижает нагрузку на поддержку.

Раздел в админке: Настройки → Captive Portal (/admin/settings/captive_portal/). Три вкладки:

• Финблокировка — профиль financial: блок-пул IP, RADIUS Filter-Id, белый список (ACL-группа), URL заглушки + правила (аварийный kill-switch «разрешить всем», разрыв сессии при долге, жёсткий REJECT) + блок состояния блокировок (активные / заблокированные / b_negbal / обещанные / сегодня).
• Гостевые порталы — список гостевых порталов турбаз: турбаза, ссылка, привязка NAS, гостей / онлайн, статус. Кнопка «Настроить сеть» — привязка блок-пула, Filter-Id, ACL и гостевых NAS, плюс режим адаптера B (чужой MikroTik). Подробнее — ниже.
• Белые списки (ACL) — список ACL-групп (наборы разрешённых хостов: банки, госуслуги, портал), доступных из walled-garden даже у должника. Полное редактирование правил — в справочнике ACL.

Как устроено

Движок построен на единой модели PortalProfile, рассчитанной на три типа портала: financial (финблокировка должников), guest (гостевой Wi-Fi турбаз — бесплатный и платный) и paid (платные точки):

• RADIUS-резолвер (radius_python/internet.py): при блокировке только за долг (b_negbal) возвращает не REJECT, а Access-Accept с атрибутами Framed-IP-Address (из блок-пула) + Filter-Id — NAS заворачивает такого абонента в walled-garden.
• Источник правды — профиль: при сохранении на странице параметры дублируются в служебные настройки (BLOCK_POOL_ID / BLOCK_FILTER_ID / BLOCK_PORTAL_URL), поэтому RADIUS и правила блокировок остаются согласованы.
• Выход из блока: оплата → снятие блокировки + CoA Disconnect → при переавторизации абонент получает обычный интернет.

Гостевой Wi-Fi портал для турбаз

На том же движке (PortalProfile тип guest) работает гостевой Wi-Fi портал — инструмент для турбаз, кафе, отелей: гость подключается к Wi-Fi, попадает на брендированную страницу, подтверждает телефон по SMS и заполняет анкету, после чего получает интернет. Турбаза собирает легальную базу контактов с согласием на рекламу и автоматически рассылает SMS-поздравления с днём рождения.

Подключение: услуга «Гостевой Wi-Fi портал» (system_type=12) абоненту-турбазе (юр.лицо). При подключении автоматически создаётся портал с дефолтной анкетой (телефон + дата рождения). На карточке абонента появляется вкладка «Гость wifi» со статусом и ссылкой на портал.

• Captive-страница /portal/<slug>/ — брендированная (логотип, цвет, тексты турбазы), мобильная, самодостаточная. Flow: телефон → SMS-код → анкета → согласие на ПДн → доступ.
• Конструктор анкеты — турбаза в своём ЛК (/lk/guest-portal/) задаёт, какие поля собирать (имя, авто, тип отдыха и т.д.), брендинг, текст согласия и рассылки.
• Два адаптера сети: A — наше оборудование (RADIUS guest-ветка + CoA-разблокировка по MAC); B — чужой MikroTik турбазы (hotspot login, разблокировку делает MikroTik сам — работает без нашего RADIUS). Адаптер выбирается в модалке «Настроить сеть».
• ДР-рассылки — Celery beat раз в сутки шлёт SMS гостям, у кого день рождения через N дней. Только гостям с согласием на рекламу (152-ФЗ), с защитой от повторной отправки.

Платный доступ к гостевой сети (продажа по QR)

Гостевой портал можно сделать платным: гость сканирует QR-наклейку, подтверждает телефон по SMS, выбирает тариф (например «100 ₽ — 3 часа»), оплачивает через ЮKassa и получает интернет на оплаченный срок. По истечении доступ автоматически отключается. Чек 54-ФЗ пробивает ЮKassa, выручка идёт на организацию-провайдера. Применение — платные точки в парках, на турбазах, на мероприятиях.

Поток гостя: сканирует QR → телефон + SMS-код → выбор тарифа → e-mail для чека → оплата картой → чек на почту → интернет на срок тарифа → по истечении снова на портал.

• Тарифы = услуги. Тариф доступа — обычная услуга Usluga (system_type=12) в разделе Тарификация → Услуги: цена = «Сумма», длительность = поле «Длительность доступа» (часы/минуты). Новой тарифной сущности не вводится. К порталу тарифы привязываются галочками в модалке «Настроить сеть» (блок «Платный доступ»).
• Чек 54-ФЗ — формируется ЮKassa по e-mail гостя (онлайн-касса ЮKassa); отдельная фискализация не нужна.
• Выручка — приходная финоперация на организацию-провайдера (по умолчанию основная организация), тип «Платный гостевой Wi-Fi». Лицевые счета абонентов не затрагиваются.
• Отсечка по времени — два механизма: NAS сам разрывает сессию по Session-Timeout (остаток оплаченного времени) + страховочная задача раз в 5 минут. По истечении гость попадает обратно на портал оплаты.
• Статистика — вкладка «Платежи» в разделе Captive Portal: выручка (сегодня / за месяц / всего + средний чек), активные доступы сейчас, таблица платежей со статусами, экспорт CSV.

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

Раздел меню «Справочники» — все нормативно-справочные данные системы: пулы 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 позволяет связать пулы в цепочку резервирования: когда основной пул исчерпан, аллокатор автоматически переходит к следующему. Пример (testbill, 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» для пулов в цепочке (build 443) — суммарная занятость всех пулов цепочки JOY-1 → JOY-2 → JOY-3 с разбивкой в tooltip. Без этого блока админ видит «JOY-1 = 100 % занято» и думает «всё пропало», на самом деле есть запас в JOY-2/3.
• Привязка к NAS — цветные бейджи ролей (main / nat / white / hotspot), tooltip раскрывает все привязки одного NAS.
• Бейдж «🔗 → #N» в колонке «Название» — ссылка на следующий пул в цепочке (клик открывает его модалку).
• Сортировка сохраняется в localStorage (build 441) — после 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-алерт.

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

Пулы VLAN

URL: /admin/dictionary/VlanPull/

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

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

• Список с поиском по названию и оператору.
• Колонка «Использовано» — счётчик точек подключения, занявших VLAN из пула.
• Бейдж активности (enabled) — Bootstrap-switch прямо в строке (build 456).
• Скрытие «оператора», если у системы единственный оператор (build 456): колонка убирается через .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, но с заполненными значениями + кнопкой «Удалить» снизу слева.

Защита удаления (build 456): 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. На testbill 2026-05: 4045/4261 (94.93%) адресов имеют lat/lon;
• Использование на карте: для отображения абонента на карте нужен заполненный lat/lon у его дома. Если координат нет — абонент в маркер не попадёт.

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

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

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

• Не удалять автоматически. Адресная база заполнялась заранее (DaData импорт), пустые адреса ждут подключения новых клиентов;
• Удалять только конкретные ошибки — дубли, неверные индексы, переименованные улицы. Удаление через UI кнопкой 🗑;
• Защита FK: на homes ссылаются NO ACTION поля из Abonents, users, switch, nas, CONNECTION_POINTS. 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 группы (build 149+):

В 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-го по последний день»). Период определяет дату списания абонплаты, формирование отчётов, закрытие периода.

8. Абоненты

Раздел меню «Абоненты» — основной рабочий раздел оператора.

Папки абонентов — назначение и роль

Папка абонентов — это «контейнер-узел» в дереве абонентов с флагом IS_FOLDER=true. Хранится в той же таблице abonents (поле parent_id), но не имеет тарифа, счёта и финансовых атрибутов. Корневая папка имеет ID=9001.

Зачем нужны папки

Папки решают три задачи:

1. Логическая группировка — абоненты раскладываются по агентам, филиалам, типам клиентов, географическим зонам. Это удобно для навигации и фильтрации в админке;
2. Контроль доступа операторов — через AbonentGroupAccess Django-группа привязывается к конкретным папкам, и оператор видит только своих абонентов;
3. Корзина удалённых — обычно это спец-папка (на testbill #9003 «Удалённые»), куда перемещаются deleted=true-абоненты для возможного восстановления.

MPTT-дерево

Иерархия реализована через библиотеку django-mptt:

• Поля MPTT: lft, rght, tree_id, level — для быстрого поиска всех потомков одним SQL-запросом без рекурсии (метод get_descendants());
• parent_id — FK на самого себя. NULL у корня (#9001), у остальных — на родителя;
• Подпапки поддерживаются. Папка может содержать другие папки (несколько уровней вложенности);
• FK с PROTECT — нельзя удалить папку, у которой есть дочерние записи. Сначала перенесите/удалите детей.

Группы и контроль доступа

Связь «Группа Django ↔ Папка абонента» хранится в AbonentGroupAccess:

• Каждая запись — это «группа GroupX имеет доступ к папке #N и её потомкам»;
• Один оператор может состоять в нескольких группах — тогда видит абонентов из объединения папок;
• Настраивается в /admin/settings/abonent_group_permissions/ (дерево с чекбоксами);
• Если у оператора нет ни одной записи AbonentGroupAccess — он видит всех абонентов (нет ограничений по умолчанию);
• Поиск по папкам, экспорт CSV, bulk-actions — все они учитывают этот фильтр.

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

• Пустая папка без активных детей — можно удалить через UI (build 121+ разрешает). FK PROTECT защитит если в ней не считая deleted-абонентов есть живые;
• Папка с deleted-абонентами — нельзя удалить, soft-deleted записи всё ещё ссылаются на parent_id. Сначала «жёстко» удалить deleted-абонентов или перенести в общую корзину;
• Папка «Корзина» (#9003 на testbill) — не удалять. Это служебная папка-приёмник для восстановления абонентов из архива;
• Перемещение абонента в другую папку — bulk action move_folder в глобальном поиске (11 операций).

8.1. Абоненты

Главный список абонентов. Можно работать в двух режимах: дерево папок (по умолчанию) и глобальный поиск. Папки удобны для иерархической навигации по агентам/филиалам/адресам, глобальный поиск — для массовых операций над всей базой.

Папка абонентов

Папка абонентов (/admin/Abonents/<id>/, корень — /admin/Abonents/9001/) — список абонентов конкретной папки с поддержкой подпапок. Каждая папка имеет свой набор быстрых фильтров и массовых действий, рассчитанный на ежедневную работу оператора с одним сегментом базы.

KPI и статистика

Над таблицей выводятся 4–5 счётчиков по абонентам текущей папки (без учёта подпапок): Активных, Сейчас онлайн, Выключенных, Всего, Юр. лиц. Числа обновляются вместе с применённым фильтром-чипом.

Чипы быстрых фильтров

Под счётчиками — ряд чипов с готовыми фильтрами. Активен может быть только один. Повторный клик снимает фильтр. Состояние сохраняется в URL — ссылку можно отправить коллеге:

• Должники — баланс счёта < 0.
• Бизнес — юр. лица (company=true).
• Без email / Без телефона — пустые поля контактов (чтобы дополнить данные).
• Онлайн — сейчас в RADIUS-сессии (< 15 мин с last update).
• Заблокированные — есть активная запись в ABONENTS_BLOCK (admin / negbal / own).
• Обещ. платёж — активен ОП (Usluga 30353).

Поиск, сортировка и multi-tarif

• Поиск в шапке таблицы по ФИО, номеру договора, e-mail, телефону. Минимум 2 символа, мгновенный фильтр.
• Шорткат Ctrl+K — фокус в поле поиска из любого места страницы.
• Сортировка по любой колонке кликом на заголовок (▲▼). Стрелка показывает направление.
• Multi-tarif фильтр — checkbox-список тарифов с поиском по названию. Позволяет ограничить выборку папки одним или несколькими тарифами одновременно.

Колонки таблицы

1. ☑ — чекбокс выбора для массовых операций.
2. № — внутренний ID абонента.
3. ФИО — клик открывает карточку.
4. Дог. — номер договора.
5. Тариф — с иконкой 💼 для бизнес-тарифов.
6. Адрес — короткий формат (через фильтр home_short: ВО → Волгоградская обл., Влг → Волгоград).
7. Контакты — иконки ✉ / 📞 с tooltip-значениями. Серая иконка = пустое поле.
8. Баланс — баланс счёта. Рядом 🤝 при активном обещанном платеже.
9. Подкл. — дата подключения.
10. 📡 — флаг «онлайн сейчас» (RADIUS-сессия < 15 мин).
11. Статус — цветной бейдж: Активен / Заблок. / Удалён.
12. ℹ Подробнее — кнопка открывает drawer-панель без перехода на полную карточку.

Подсветка строк: красный фон — заблокированные за неуплату, синий — soft-deleted (видны только администратору), оранжевая полоса слева — глубокий долг (более одной месячной абонплаты).

Бесконечная подгрузка

Папка не использует пагинацию. При прокрутке вниз автоматически догружается следующая порция (по 100 записей) через AJAX-endpoint /admin/Abonents/<id>/children_json/. На больших папках (1000+ абонентов) загрузка остаётся плавной — браузер рендерит только видимый кусок.

Массовые действия и экспорт

Чекбокс в первой колонке + «Выбрать все на странице» в шапке. После выделения появляется меню «Действия (N)» — те же 11 операций, что и в глобальном поиске: включить / выключить / удалить / изменить тариф / точку подключения / перенести в другую папку / добавить услугу / бонус / финоперацию / лояльность / отправить сообщение. Destructive-операции защищены confirm-модалкой с предпросмотром имён, для большинства — кнопка «Откатить» в баннере на 1 час.

Экспорт CSV — кнопка «📥 CSV» в шапке выгружает текущий срез папки (/admin/Abonents/<id>/export/): UTF-8 BOM, разделитель «;» для Excel RU. Колонки совпадают с видимыми в таблице плюс расшифровка тарифа, оператора, баланс в рублях. Учитываются текущий фильтр-чип и текстовый поиск.

Навигация по подпапкам

Если у текущей папки есть подпапки — они выводятся отдельным блоком над таблицей абонентов: карточки с именем подпапки и счётчиком абонентов внутри (включая глубоких потомков). Клик переходит в подпапку (отдельный URL). Хлебные крошки в шапке страницы показывают полный путь от корня (#9001 → город → улица → дом), кликабельны.

Глобальный поиск

Глобальный поиск (Абоненты → 🔍 Глобальный поиск, URL /admin/Abonents/search/) — плоский список всех абонентов без иерархии папок, с расширенными фильтрами и массовыми операциями. Папки в выборку не попадают (is_folder=false).

Раздел рассчитан на сценарии, когда нужно работать со всей базой сразу: найти абонента по обрывку информации (часть телефона, дома, фамилии), сделать массовую рассылку по тарифу, выгрузить срез для бухгалтерии.

KPI-бейджи в шапке

Над таблицей выводится 4 счётчика по результатам текущей выборки: Активных (enabled=true) / Сейчас онлайн (RADIUS-сессия < 15 мин) / Выкл (enabled=false) / Всего. Цифры пересчитываются на каждой смене фильтра.

Чипы быстрых фильтров (7 штук)

Чипы взаимоисключающие — активен может быть только один. Кликом по уже активному чипу фильтр сбрасывается. Состояние записывается в URL (?chip=debtors) — ссылку можно отправить коллеге.

Multi-select фильтры

• Тариф — checkbox-список с поиском по названию. Можно выбрать несколько тарифов одновременно. URL: ?tarif=131&tarif=43. Применение через кнопку «Применить», сброс — «Очистить».
• Точка подключения — checkbox-список ConnectionPoints (NAS-узлов и магистралей). URL: ?cp=Узел 1&cp=Узел 2. Полезно для оператора-инсталлятора, обслуживающего несколько домов / улиц / районов.

Текстовый поиск

Поле в шапке таблицы. Серверный поиск по: ФИО, номер договора, e-mail, телефон, адрес (город / улица / дом / квартира). Минимум 2 символа, debounce 300 мс. Шорткат Ctrl+K ставит фокус в поле поиска из любого места страницы.

Колонки таблицы (12)

1. ☑ — чекбокс выбора для bulk-операций.
2. № — внутренний ID абонента.
3. ФИО — имя, кликабельно (открывает карточку).
4. Дог. — номер договора.
5. Тариф — название текущего тарифа; для бизнес-тарифов иконка 💼.
6. Адрес — короткий формат через фильтр home_short (ВО → Волгоградская обл., Влг → Волгоград, район сокращённо).
7. Точка подкл. — название ConnectionPoint.
8. Контакты — иконки ✉ / 📞 с tooltip-значениями. Серая иконка = не заполнено.
9. Баланс — баланс счёта; рядом 🤝 при активном ОП.
10. Подкл. — дата подключения.
11. 📡 — флаг «онлайн сейчас» (RADIUS-сессия < 15 мин).
12. Статус — цветной бейдж (Активен / Заблок. / Удалён).

Подсветка строк: красный фон — заблокированные, синий — удалённые, оранжевая полоса слева — глубокий долг (более одной месячной абонплаты).

Бесконечный скролл

Глобальный поиск не использует пагинацию: при прокрутке вниз подгружается следующая порция результатов. Папочные страницы (/admin/Abonents/<id>/) работают по тому же принципу через AJAX-endpoint /admin/Abonents/<id>/children_json/ по 100 записей за запрос.

Массовые действия — 11 операций

Выбираете абонентов галочками в первой колонке (или «Выбрать все» в шапке) — в шапке появляется выпадающее меню «Действия (N)» с дюжиной операций. Endpoint: POST /admin/Abonents/bulk_action/ (payload: action + ids[] + параметры).

Для destructive-операций (Включить / Выключить / Удалить / Изменить тариф / Перенести в папку) после выполнения в шапке появляется баннер «Откатить (доступно N мин)» с таймером 1 час. Клик отменяет изменение для всех затронутых абонентов через POST /admin/Abonents/bulk_undo/. Undo-токен хранится в sessionStorage браузера. Create-операции (Добавить услугу / бонус / финоперацию / лояльность / отправить сообщение) не откатываются — придётся вручную удалять созданные записи.

Подтверждение опасных операций

Удаление, отключение, включение и смена тарифа открывают модальное окно подтверждения: показывает превью первых 5 имён выбранных абонентов, общее их количество и требует ввести точное число выбранных записей для активации кнопки «Подтвердить». Это защита от случайной массовой операции по невнимательности.

CSV-экспорт

Кнопка «📥 CSV» в шапке выгружает текущий видимый срез (/admin/Abonents/search/export/): UTF-8 BOM, разделитель «;» для Excel RU. Колонки те же что в таблице плюс расшифровка тарифа, оператор и баланс в рублях.

Слайд-панель абонента (drawer)

В строках таблиц списков абонентов (папка, глобальный поиск, должники) у каждой записи справа есть кнопка ℹ Подробнее (на mobile — клик по имени). Клик открывает выезжающую справа панель (slide-panel / drawer) с краткой сводкой по абоненту — без ухода со списка и потери контекста (фильтры, прокрутка, выделение сохраняются).

Панель решает задачу «быстро глянуть и сделать», когда полная карточка с десятком вкладок избыточна. Типичные сценарии за 5–30 секунд: проверить баланс и активировать ОП, посмотреть статус сессии при жалобе на интернет, отправить SMS-напоминание, добавить комментарий-заметку для коллег.

Где доступна панель

• Папка абонентов (/admin/Abonents/<id>/) — кнопка ℹ в каждой строке.
• Глобальный поиск (/admin/Abonents/search/) — кнопка ℹ после колонки «Статус».
• Должники (/admin/debtors/) — последняя колонка таблицы.
• На mobile — клик по имени абонента в любом списке (.abd-name-link).

Программный API из любой страницы: window.AbDrawer.open(abonentId).

Шапка с плашками статуса

Вверху панели — компактные плашки с ключевыми атрибутами абонента (видно с одного взгляда, без скролла):

Шапка имеет фон заметно темнее тела (light #e8edf2 / dark #14171b) — оператор сразу различает «где статус, где данные».

Финансовый KPI-блок

Сразу под шапкой — KPI-сетка 2×2 с самыми важными цифрами:

• Баланс — с цветным акцентом (зелёный для +, красный для −).
• Дней долга или Хватит на N дней — label меняется в зависимости от знака баланса. При плюсе показываем «Хватит на N дней» = balance / стоимость_тарифа × 30. Цвет: зелёный ≥30 дней, нейтральный 7–29, красный <7 дней (нужен платёж).
• Тариф — название текущего тарифа (truncate с tooltip).
• Посл. платёж — дата последнего входящего платежа.

Если активен обещанный платёж — отдельная плашка с суммой и датой окончания под KPI-сеткой.

Аккордеон 6 разделов и smart-defaults

Шесть разделов панели объединены в аккордеон — оператор сам открывает что нужно, не скроллит мимо. Состояние свёрнутости запоминается в localStorage отдельно по каждой секции — выбор оператора сохраняется.

Если оператор однажды раскрыл/свернул секцию вручную — это его выбор сохраняется в localStorage и smart-defaults больше не перетирают.

Раздел «Поддержка» (HelpDesk)

Шестой раздел аккордеона — интеграция с HelpDesk. Биллинг показывает все обращения абонента в техподдержку прямо в слайд-панели, без перехода в HelpDesk:

• Pill-счётчик в заголовке: «Поддержка 3» показывает количество открытых тикетов. Если есть тикеты, ожидающие ответа от нас (customerWaitingSince из FS), счётчик становится красным с pulse-анимацией — оператор сразу видит «горящие» обращения.
• Summary-stats внутри: «Ждёт ответа N · Открыто M · Ожидание K · Закрыто L».
• До 5 свежих тикетов карточками: # · статус · «ждёт N часов» бейдж → клик открывает обращение в HelpDesk (новая вкладка).
• Smart-default: раздел открыт если waiting_for_us > 0.
• Резильентность: если HelpDesk недоступен — раздел просто пуст, ошибки в drawer не пробрасываются.

Sticky footer — форма отправки всегда видна

Форма отправки сообщений и табы каналов прилеплены ко дну панели (не уезжают при скролле истории сообщений). Оператор не скроллит чтобы написать SMS — форма всегда на виду, как в современных мессенджерах.

Каналы отправки (SMS / Email / Telegram / ЛК / ВК / Push)

Над формой ввода — chip-табы с каналами отправки. Показываются только доступные абоненту каналы:

• SMS — если у абонента указан телефон.
• Email — если указан email.
• Telegram — если привязан Telegram-чат (telegram_chat_id).
• ЛК — всегда доступен (push в личный кабинет через MsgStack).
• ВК — если привязан VK-аккаунт.
• Push — если установлено мобильное приложение и есть push-токен.

При выборе таба Email над формой появляется поле «Тема письма» — если оператор не укажет, дефолтная тема возьмётся из первой строки текста (до 80 символов).

SMS-форма поддерживает дефолтный шаблон: при пустом тексте у должника автоматически отправляется напоминание «Договор XXX. Задолженность YYY ₽. После пополнения счёта доступ к услугам восстановится. Узнать баланс или взять ОП — отправьте «Баланс» или «Оп» в ответ на это сообщение. ЛК: lk.smit34.ru».

Для абонентов с положительным балансом дефолтный шаблон не отправляется — backend возвращает ошибку no_text_positive_balance, оператор должен ввести текст вручную.

Email в фирменном брендинге

Email-сообщения отправляются HTML в фирменном стиле — не plain text, а полноценное письмо с шаблоном emails/generic.html:

• Header: brand-color #43b77a, имя оператора, дата.
• Персональное приветствие: «Здравствуйте, <Имя>!» — имя берётся из ФИО абонента (parts[1] для физ.лиц, generic для юр.лиц).
• Тело письма с текстом оператора (форматирование переносов).
• Footer: реквизиты компании, телефон поддержки, договор, баланс — из _build_msg_email_context.
• Без CTA-кнопки «Открыть личный кабинет» (hide_cta=True) — она не нужна для ручных сообщений оператора, только для авто-уведомлений.

Авто-детект шаблона по теме/тексту: если содержит «обещанн», «оплат», «блокир», «возобновл», «баланс+низк» — выбирается специализированный пресет (promise_pay/payment_received/blocked/ unblocked/low_balance), иначе generic.

Доступность (WCAG colour independence)

Все цветовые статусы дублируются иконками — пользователи с deuteranopia (8% мужчин) различают информацию без полагания на цвет:

• FinOps: знак +/− + иконка ↑/↓ перед суммой.
• Учётные записи: fa-check-circle (online), fa-circle outline (offline), fa-times-circle (disabled).
• Сессия: fa-play-circle (active) / fa-stop-circle (closed) — раньше были одинаковые fa-circle разного цвета.
• SMS-статусы: цветные плашки «доставлен» (зелёный), «отправл.» (синий), «ожидание» (серый), «ошибка» (красный).

Mobile-режим

На mobile (≤600px) drawer занимает весь экран. Поведение одинаковое с desktop, только:

• Login-бейдж в шапке скрыт (длинный логин ломает строку).
• Textarea формы отправки одной строки (height: 38px) с font-size: 16px — iOS Safari не зумит при фокусе.
• Sticky footer с safe-area padding (iPhone home indicator).

Тёмная тема

Drawer полностью адаптирован под тёмную тему. Header ещё темнее тела (#14171b vs body #1f2227), все секции и формы имеют тёмные варианты, footer-actions с своим bg.

Карточка абонента

Переход кликом по строке абонента — открывается отдельная страница с вкладками Информация, История, Тариф и услуги, Бонусы, Финансы, Точки подключения, Учётные записи, RADIUS, СОРМ, Реквизиты, HelpDesk, Лояльность. Подробное описание каждой вкладки — в отдельном разделе 9. Карточка абонента.

Bulk-операции и Undo

Выберите абонентов галочками — появится плавающая панель действий внизу экрана.

Доступные действия:

• Включить / Выключить / Удалить (с Bootstrap-confirm и превью имён).
• Сменить тариф / точку подключения / папку.
• Подключить услугу / бонус / финоперацию / программу лояльности.
• Отправить сообщение (e-mail / SMS / Push / Telegram).

Для destructive-операций (delete, disable, enable, change_tarif, move_folder) после выполнения в шапке появляется баннер «Откатить (доступно N мин)» с таймером 1 час. Клик отменяет изменение для всех затронутых абонентов.

8.2. На карте

Карта абонентов в браузере (Leaflet + OSM / 2ГИС / Yandex). Каждый маркер — абонент; отдельно показываются NAS и слой заявок Поддержки. URL: /admin/abonents/map/. Меню сайдбара: Абоненты → 🗺 На карте.

Возможности

• Поиск с автокомплитом в три секции: Адреса, Абоненты, Оборудование. Шорткат Ctrl+K (или ⌘+K на Mac) ставит фокус в поле, не открывая поиск navbar. Минимум 2 символа, debounce 300 мс. Клавиатура: ↑↓ Enter Esc.
• Фильтр статусов (Активные / Заблокированные / Приостановленные) и фильтр услуг (Интернет / Видео / IPTV / Телефония / ЧОП) — выпадающие селекторы с toggle. Минимум один статус выбран всегда; дефолт — Активные + Интернет.
• Кластеры — на низком zoom маркеры группируются. Свёртываемая легенда (правый-нижний угол) объясняет цвета и размеры кластеров (5 / 25 / 120 точек) и статусов.
• NAS на карте — включённые серверы доступа показываются по координатам адреса. Popup NAS: бейджи PROD / CoA / SSH, состояние UP/DOWN, прогресс-бар «онлайн / всего», кнопки «Абоненты» (открывает сайдбар, см. ниже) и «Связи» (покрытие). Инфраструктура (Switch / узлы / трассы) — на отдельной карте сети.
• Слой «Заявки» — тикеты Поддержки СмИТ Биллинг с геопривязкой по адресу абонента. Включён при загрузке; клик по маркеру открывает карточку тикета.
• Popup абонента (см. скриншот ниже): Договор + лейбл организации (при multi-org), NAS ссылкой (→ сайдбар абонентов NAS), тариф, адрес, баланс, иконки услуг. Клик по ФИО открывает карточку абонента с прокруткой к блоку «Услуги»; «Позвонить» / «E-mail» — карточку с прокруткой к блоку сообщений.
• Сохранение viewport в браузере (localStorage.map_last_view, TTL 7 дней) + shareable URL ?center=lat,lon&zoom=N — карта помнит положение, ссылку можно отправить коллеге.
• Тёмная тема — карта переключается на тёмный скин (CARTO Dark Matter), попапы и сайдбары адаптированы под тёмный фон. Адаптив: на мобильном поиск — отдельной строкой, фильтры — в bottom-sheet по кнопке «Фильтры».

Сайдбар «Абоненты на NAS»

Клик по NAS-маркеру (кнопка «Абоненты») или по NAS-ссылке в попапе абонента открывает слайд-панель справа со списком абонентов выбранного NAS. Фильтр-чипы Все / Online / Offline со счётчиками, поиск (ФИО / логин / договор / IP), бесконечная прокрутка. Каждая строка — кликабельна (→ карточка абонента) и показывает: ФИО, бейдж «Заблок.» при блокировке, логин·IP, тариф, баланс (цветной ↑/↓) и иконки услуг.

Поток: маркер → попап → карточка / сайдбар

flowchart LR
    DATA["/admin/abonents/map/data/
points + NAS + заявки"] --> MAP["Карта Leaflet
кластеры"]
    MAP --> ABM(("Маркер
абонента"))
    MAP --> NASM(("Маркер
NAS"))
    MAP --> TKT(("Маркер
заявки"))

    ABM --> POP["Popup абонента
org · NAS · услуги"]
    POP -->|"ФИО"| DRAWER["Карточка абонента
→ блок «Услуги»"]
    POP -->|"Позвонить / E-mail"| DRAWERM["Карточка абонента
→ сообщения"]
    POP -->|"NAS-ссылка"| PANEL["Сайдбар «Абоненты NAS»
Все / Online / Offline"]

    NASM -->|"«Абоненты»"| PANEL
    PANEL -->|"строка"| DRAWER
    TKT --> TICKET["Карточка тикета
Поддержка СмИТ"]

    style DATA fill:#1e3a5f,stroke:#5BA89D,color:#fff
    style MAP fill:#134e4a,stroke:#43b77a,color:#fff
    style POP fill:#1e3a5f,stroke:#5BA89D,color:#fff
    style PANEL fill:#43b77a,stroke:#2d9a5f,color:#fff
    style DRAWER fill:#43b77a,stroke:#2d9a5f,color:#fff
    style DRAWERM fill:#14532d,stroke:#16a34a,color:#fff
    style TICKET fill:#78350f,stroke:#d97706,color:#fff

Тёмная тема и мобильный вид

Попап и сайдбар NAS полностью адаптированы под тёмную тему (контраст лейблов/значений ≥ WCAG AA). На мобильном панель фильтров — bottom-sheet.

Геокодирование адресов

Чтобы абонент появился на карте, его адрес (Homes.parent_id) должен иметь координаты lat и lon. Заполнение координат происходит автоматически через геокодеры — внешние сервисы, которые по строке адреса возвращают координаты.

Поддерживаются два провайдера:

API-токены задаются в разделе «Настройки → Интеграции → География» (вкладка «География → Адреса»). Здесь же есть кнопка «Проверить» для теста подключения и счётчик геокодированных адресов.

Запуск геокодирования

На testbill сейчас геокодировано ~95% адресов (4045 из 4261), из активных абонентов ~90% на карте. Чтобы геокодировать новый адрес автоматически — введите его в форме абонента, и при следующем прогоне команды (или nightly Celery-задаче) он попадёт на карту. Запустить геокодирование вручную:

docker compose exec web python manage.py geocode_homes_dadata
# или принудительно для всех (включая уже геокодированные):
docker compose exec web python manage.py geocode_homes_dadata --re-geocode

Команда:

• Берёт все Homes где lat IS NULL OR lon IS NULL (или все, если --re-geocode).
• Обращается к DaData suggest API (https://suggestions.dadata.ru/.../suggest/address) с полным адресом из иерархии Homes (регион → город → улица → дом).
• Записывает координаты geo_lat / geo_lon и поле qc_geo (precision: 0=точно дом, 1=улица, 2=город — чем меньше, тем точнее).
• Делает паузу между запросами (по умолчанию 0.1 сек) чтобы не превысить лимит сервиса.

Маркеры абонентов на адресах с qc_geo=2 (только город) на карте отображаются как «приблизительные» — несколько абонентов одного города могут лечь на одну точку. Для повышения точности проверьте, что у адреса заполнены поля «Улица» и «Дом».

Reverse-геокодинг (заполнение города/района по координатам)

Если у адреса есть координаты, но не заполнен город или район (после миграции из старых биллингов это бывает), используйте команду manage.py enrich_homes — она через Яндекс.Геокодер (обратное направление: координаты → адрес) восстанавливает текстовые поля.

Тайловый слой (фон карты)

Подложка карты выбирается на той же вкладке «География → Карта»: OpenStreetMap (бесплатно), 2ГИС (требует ключ), Yandex Maps. Дефолт — OSM. Стиль карточки в /admin/settings/integrations/?tab=geo показывает количество геокодированных адресов и точность (% домов с qc_geo=0).

Обещанный платёж (Promise Pay) — назначение и роль

Обещанный платёж (ОП) — короткий «кредит» абоненту: биллинг временно увеличивает его баланс, чтобы интернет работал ещё несколько дней до фактической оплаты. Реализован через Usluga id=30353 с system_type=11. Ключевые поля абонента: Abonents.promise_pay (сумма ₽) и promise_date_end (дата истечения).

Что такое ОП и зачем нужен

Сценарий типичного использования:

1. Абонент в командировке, ушёл в минус по балансу. Биллинг блокирует (b_negbal);
2. Абонент через ЛК / SMS / звонок в поддержку запрашивает ОП;
3. Биллинг временно зачисляет ему ₽ на 5 дней (срок настраивается);
4. Финансовая блокировка снимается, интернет возвращается через CoA Disconnect (build 258);
5. Через 5 дней абонент пополняет счёт. Иначе ОП истекает, баланс возвращается к минусу, блокировка повторяется.

Экономика (build 656)

Eligibility — 4 политики

Перед активацией _check_promise_pay_eligibility() в lk/views/promise_pay.py проверяет:

1. LK_PROMISE_PAY_MIN_DEBT — минимальный долг (например, ОП доступен только при балансе < -100 ₽);
2. LK_PROMISE_PAY_MAX_LIMIT_OVERRIDE — макс. лимит ОП (если задан, перебивает расчёт по тарифу);
3. LK_PROMISE_PAY_MIN_AGE_DAYS — минимальный «возраст» абонента (с момента create_date). Защита от мошеничества: создал договор и сразу взял ОП;
4. LK_PROMISE_PAY_COOLDOWN_DAYS — пауза между ОП. Защита от циклов «брать ОП каждую неделю».

Все политики — настройки SystemSettings. Если значение = 0 — политика отключена. По умолчанию все включены.

Что происходит при активации

В одной транзакции:

1. Создаётся UsersUsluga(usluga_id=30353, system_type=11, end_time=now+5дней, limit=<сумма ОП>);
2. Создаётся FinanceOperations(op_type_id=31, op_summa=+limit, descr='[ЛК/SMS/Mobile] Обещанный платёж...');
3. abonent.account.ostatok += limit (баланс пополняется);
4. abonent.promise_pay = limit, abonent.promise_date_end = now+5дней — для бейджа в UI и баннера;
5. Если был AbonentsBlock(b_negbal=true) — удаляется, Abonents.enabled=true;
6. CoA Disconnect на NAS (build 258) — текущая Reject-сессия разрывается, абонент переавторизуется, RADIUS отвечает Accept → интернет работает в течение секунд;
7. Аудит — запись в AUDIT_OPERATIONS с подробной descr.

Каналы активации

Завершение ОП — 4 сценария (build 656)

Есть четыре пути завершить активный ОП — все приводят к одному финалу: возврат лимита через обратную FinOp, очистка promise_pay/promise_date_end, удаление UsersUsluga, и при отрицательном балансе — авто-блок.

Дневная плата 30 ₽/день (build 656)

Услуга 30353 имеет price=30 ₽, is_periodic=true, every_day=true. До build 656 эти поля были декоративными — при активации UU.sched_date не устанавливался, billing_worker услугу пропускал, дневная плата фактически не списывалась.

В build 656 при активации:

1. Если LK_PROMISE_PAY_DAILY_CHARGE=1 — UU.sched_date = now+1d 09:00;
2. Каждый день в 09:00 billing_worker списывает Usluga.price (30 ₽) с лицевого счёта;
3. Запись FinanceOperations(op_type=32, descr='Списание абонплаты ...');
4. sched_date сдвигается на следующий день — пока ОП активен, плата идёт ежедневно;
5. При завершении ОП (любой из 4 сценариев) UU удаляется → списания прекращаются.

Чтобы выключить дневную плату: LK_PROMISE_PAY_DAILY_CHARGE=0 в /admin/settings/system/ + переименовать услугу 30353 (убрать «30 руб/день» из названия).

Уведомления

• Активация: SMS-ответ + Push «ОП {N}₽ активирован до DD.MM.YYYY». Если cap упёрся и баланс остался отрицательным — добавляется «Баланс X ₽ — недостаточно, требуется доплата».
• За 24 часа до окончания: push.promise_pay_expiring beat-задача (раз в сутки) шлёт push «Обещанный платёж истекает через N ч». Окно настраивается через MOBILE_PUSH_PROMISE_PAY_EXPIRE_HOURS (default 24).
• В день истечения: push.promise_pay_expired beat-задача шлёт push «Обещанный платёж истёк. Пополните баланс».
• При погашении оплатой: уведомление об оплате (стандартное «На счёт зачислено …») + Audit-запись о закрытии ОП.

Audit (build 655)

Все операции с ОП пишутся в AUDIT_OPERATIONS с TABLE_NAME='USERS_USLUGA' через billing.services.audit_log.write_audit():

• Активация через ЛК / SMS — «Обещанный платёж активирован через ЛК/SMS: {usluga.name} (#id, UU={pk}), лимит {N} ₽, до DD.MM.YYYY»;
• Завершение (любой из 4 сценариев) — «Обещанный платёж завершён ({reason}): {N} ₽, удалено UU={count}»;
• Запись попадает на вкладку Аудит → услуги карточки абонента (раньше активация через SMS была невидима — пряталась в SMS_INBOUND).

Сводка настроек ОП (build 656)

Все настройки в SystemSettings (/admin/settings/system/):

Defaults применяются миграцией 0127_promise_pay_defaults. UPSERT — существующие значения не перезаписываются, на проде с 0 (выкл) останется 0 пока админ сам не включит.

Блокировки (AbonentsBlock) — назначение и роль

AbonentsBlock — таблица записей о блокировках абонента. Один абонент может иметь одну активную запись с несколькими булевыми флагами (один флаг = одна причина блокировки). Хранится в ABONENTS_BLOCK.

Три типа блокировок

Блокировка vs Abonents.enabled

Это два разных механизма, иногда путают:

Корректная схема — блокировка всегда сопровождает enabled=false. Рассинхрон («есть запись блокировки, но enabled=true» или наоборот) — это баг, чинится через метод process_blocks или ручную правку через UI.

Жизненный цикл блокировки

1. Создание:
   • process_blocks (Celery, раз в 5 мин) — сравнивает OSTATOK с LIMIT у всех абонентов и создаёт b_negbal;
   • accounts_payment_ajax (build 541) — мгновенно блокирует если расход через UI ушёл в минус;
   • Кнопка «Заблокировать» в карточке абонента — ставит b_admin;
   • Abonents.add_promise_pay() при истечении срока ОП — возвращает b_negbal если баланс остался отрицательный.
2. Активные действия при блокировке (см. Abonents.block()):
   • Создаётся / обновляется запись в ABONENTS_BLOCK;
   • Abonents.enabled = false;
   • Все Users.enabled = false (учётки) → RADIUS отвечает Reject при следующей авторизации;
   • На все NAS параллельно отправляется CoA Disconnect (см. ниже) — текущие сессии разрываются;
   • Пишется аудит-запись в AUDIT_OPERATIONS с table_name='ABONENTS_BLOCK';
   • Опционально — IPTV sync (отключить пакеты в TVIP / LFStream).
3. Снятие:
   • process_blocks при пополнении баланса убирает b_negbal;
   • accounts_payment_ajax (build 541) — мгновенно снимает b_negbal когда баланс >= 0;
   • Кнопка «Разблокировать» в карточке — снимает b_admin;
   • SMS-команда «ВКЛ» снимает b_own;
   • Если все флаги в записи стали false — AbonentsBlock удаляется, Abonents.enabled=true, услуги возвращаются.

CoA Disconnect — что происходит с активной сессией

Чтобы блокировка отрабатывала немедленно (а не через 5-15 мин когда сессия сама закроется), биллинг шлёт CoA Disconnect:

• Параллельно (ThreadPoolExecutor) на ВСЕ enabled NAS — потому что биллинг может не знать через какой NAS реально идёт сессия;
• NAS отвечает Disconnect-ACK если у него есть сессия с этим логином, или Disconnect-NAK если нет;
• FreeRADIUS закрывает сессию, абонент видит обрыв линии;
• При попытке переподключения FreeRADIUS отвечает Reject (Users.enabled=false);
• Сессия закрывается в RADIUS_SESSIONS с END_REASON='Disconnect-ACK'.

Без CoA Disconnect блокировка работала бы только при следующей перерегистрации абонента — а это иногда раз в сутки. С CoA — за 5-10 секунд.

Лицевые счета (AdminAccounts) — назначение и роль

Лицевой счёт (AdminAccounts) — это финансовый «кошелёк» абонента в биллинге. Хранит баланс, бухгалтерские дебет/кредит, лимит блокировки, валюту. Хранится в таблице admin_accounts.

Зачем нужен лицевой счёт

Счёт решает четыре задачи:

1. Учёт денег абонента — пополнения и списания идут через счёт. Текущий баланс — поле OSTATOK;
2. Финансовая блокировка по порогу — если OSTATOK < LIMIT, Celery-задача process_blocks блокирует абонента (см. Блокировки);
3. Бухучёт — поля DEBIT (поступления) и CREDIT (расходы) накапливают полные суммы для отчётности;
4. Группа абонентов на одном счёте — можно привязать несколько Abonents к одному AdminAccounts (через Abonents.ACCOUNT_ID) для семейных тарифов или корпоративных схем.

Поля и связи

DB_MONEY_KOEF — почему ×10^10

Все денежные поля биллинга (OSTATOK, DEBIT, CREDIT, LIMIT, op_summa в FINANCE_OPERATIONS, price/summa в usluga) хранятся как целые числа, умноженные на 10^10. Это позволяет избежать ошибок округления плавающей запятой и хранить суммы с точностью до 10 знаков после запятой.

• В БД: 50000000000 (целое число, тип numeric);
• В UI/коде: 5.00 ₽ (после деления на 10^10);
• Константа: DB_MONEY_KOEF = Decimal('10000000000') в billing/models/admin_accounts.py, billing/services/sms_inbound.py и других местах;
• Кастомное поле MoneyField (наследуется от DecimalField) — при вводе формы умножает на коэф, при отображении делит. UI работает в рублях, а БД хранит в «копейках × 10^8».

Кто меняет баланс

Финансовые операции (FinanceOperations) — назначение и роль