Настройки: система и платежи

Общие настройки, печатные формы, фискализация, платёжные системы, банковские выписки и почтовый сервер.

6. Настройки

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

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

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

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

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

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

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

На Безопасности — глобальные ограничения для ручных финансовых операций (создание/редактирование/удаление через 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, блокировка, сессии

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

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

Адаптивная шапка админки

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

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

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

Управление параметрами вкладки Аудит в карточке клиента и общим поведением логирования. Доступна по адресу /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.

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

Управление файлами журналов в /var/log/django/: ротация, сжатие, уровень логирования Django и FreeRADIUS. Без ограничения по сроку хранения журнал FreeRADIUS на уровне trace вырастает до десятков гигабайт за месяц.

Параметры:

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

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

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

• Чтение с конца файла — функция _tail_log() читает последние 500 строк, двигаясь от конца файла чанками, не загружая его целиком в память. Поэтому даже лог на десятки гигабайт открывается мгновенно (в шапке показано «Показано: 500 / N строк»). Это защищает от переполнения памяти при открытии многогигабайтного 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 ГБ/сутки — он однажды вырос до 43 ГБ.

Лечение:

• Уровень детализации FreeRADIUS задаётся переменной RADIUS_DEBUG_LEVEL в .env (читается docker/freeradius/entrypoint.sh): info (без флага, ~1 ГБ/сутки, только Accept/Reject и блокировки), debug (-x), trace (-xx, не использовать в проде). Если переменная не задана вовсе, контейнер стартует именно с trace — на новой установке задайте info явно. После правки — 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 (переименована)

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

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

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

Параметры 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.

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

Единая страница для управления всеми каналами доставки сообщений: 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-ограничение, политики паролей

В правой колонке вкладки Безопасность — карточка «Доступ суперпользователя». Все политики применяются только к 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 + бизнес-правила

Управление блокировкой клиентов за долг и базовыми правилами биллинга. 4 группы 2×2 + статус блокировок. Закрывает давнюю боль «Не авторизовать по RADIUS при отрицательном балансе» и задачу №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 и Нейросети

Из России api.telegram.org и внешние API AI-провайдеров недоступны — биллинг ходит к ним через прокси. Раздел Настройки системы → Прокси (/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 записей).

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

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

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

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

Автоматическая отправка кассовых чеков в ОФД: модуль фискализации, какие платежи фискализируем, чек-лист готовности и очередь чеков.

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

Модуль формирует кассовый чек и передаёт его в ОФД при приёме оплаты — согласно Федеральному закону № 54-ФЗ. Чек бьётся собственной кассой организации, реквизиты продавца (ИНН, СНО, ставка НДС) берутся из брендинга компании — единый источник, без дублирования в карточке кассы.

Какие платежи фискализируем

Настройка на странице фискализации — чипы источников. Отмеченный источник попадает в очередь чеков, снятый не попадает в неё вовсе.

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

Параметры чека — что указывать

Блок на странице фискализации задаёт, что попадёт в чек и как модуль его отправляет. Значения ниже — рекомендация для провайдера, который фискализирует пополнения счёта из банковских выписок.

Плейсхолдеры в наименовании позиции

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

• Пример: шаблон Пополнение лицевого счёта, договор {договор} на чеке превращается в «Пополнение лицевого счёта, договор 1484».
• Если у операции нет договора, плейсхолдер убирается, а лишние пробелы схлопываются (не остаётся «висящего» слова).
• Подстановка работает и когда наименование берётся из услуги клиента (чек-бокс «Имя позиции из услуги клиента») — плейсхолдер в названии услуги тоже раскроется.
• Итоговая длина обрезается до 128 символов (тег 1030).

Готовность к боевому режиму

Главный выключатель FISCAL_ENABLED по умолчанию выключен: чеки в ОФД не уходят. Включить его напрямую нельзя — тумблер ведёт в чек-лист, и пока обязательные пункты не выполнены, кнопка «Включить боевой режим» заблокирована. Сервер проверяет то же самое: запрос на включение мимо интерфейса будет отклонён.

Очередь чеков

Раздел Отчёты → Очередь чеков (/admin/reports/fiscal_queue/) показывает, что именно ждёт отправки. Раньше состояние очереди было видно только строкой счётчиков в настройках, без возможности посмотреть содержимое.

Список построен на единых компонентах: строки подгружаются по мере прокрутки (бесконечная загрузка), действия строки собраны в компактное меню, клик по имени клиента открывает боковую карточку клиента, а на телефоне строки превращаются в карточки с подписями полей. Период задаётся единым выбором дат с пресетами. Клик по имени клиента открывает боковую карточку абонента и сразу прокручивает к блоку «Банк» с его платежами из выписок.

• Состояния — «ждут отправки», «ждут ответа ОФД», «с ошибкой», «пробиты», со счётчиками; те же счётчики на странице настроек стали ссылками сюда.
• Фильтры — период, поиск по клиенту, договору, номеру операции и тексту ошибки.
• Колонка «Источник» — откуда платёж; у выключенных источников подпись зачёркнута.
• Отправка — по одной операции (сразу с ответом ОФД) или пачкой через очередь. Каждая отправка требует подтверждения (чек уходит в ОФД и ФНС) и пишется в журнал аудита. Отправлять может тот, у кого есть право на финансовые настройки.
• Защита отправленных — у операций, чек по которым уже ушёл («ждёт ОФД», «пробит»), меню действий не показывается: повторная отправка означала бы дубль чека в ОФД. Вместо него — прямая ссылка на электронный чек, а у даты на мобильном стоит зелёная галочка «отправлен».
• Значок песочных часов — операция старше порога автоматической досылки; автоматика такие не трогает.
• Убрать из очереди (корзина в строке или массово) — снимает операцию с фискализации: чек по ней не пробьётся, но само движение денег остаётся. Уже пробитые чеки не затрагиваются — в ОФД по ним лежит фискальный документ, его нельзя «удалить», для отмены нужен чек возврата.
• Отчёт в Telegram — кнопка в шапке шлёт сводку в Telegram-группу: пробито за сутки и на какую сумму, сколько ждёт отправки, ошибки. Тот же отчёт уходит автоматически раз в сутки, если включён (настройка «Отчёт в Telegram», час — «Час отправки отчёта»; канал — «chat_id группы», по умолчанию общий админ-чат).

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

flowchart LR
  A["Приём оплаты
банковская выписка"] --> B{"Источник
подлежит?"}
  B -->|"нет — агрегатор"| X["Пропуск: чек бьёт
ЮKassa / Wallet One"]
  B -->|"да — свой безнал"| C["Движок:
состав чека 54-ФЗ"]
  C --> D["Очередь чеков"]
  D --> E["АТОЛ → ОФД"]
  E -->|"done"| F["Чек клиенту
e-mail / SMS / ЛК"]
  E -->|"fail"| G["Авто-повтор →
Telegram-алерт"]

1. Приём оплаты — зачисление банковской выписки создаёт финоперацию.
2. Движок проверяет источник, сумму и тип операции, собирает состав чека по 54-ФЗ и ставит задачу в очередь.
3. Очередь отправляет чек в ОФД, опрашивает статус, повторяет при сбоях и шлёт Telegram-алерт на застрявшие чеки.
4. Чек клиенту — электронный чек на e-mail или телефон, ссылка в личном кабинете и в мобильном приложении, фискальные реквизиты в карточке операции.

Статусы чека

• Ждёт отправки — операция помечена к фискализации.
• Ждёт ответа ОФД — чек ушёл, ОФД обрабатывает; статус опрашивается периодически.
• Пробит — чек зарегистрирован, сохранены № ФД, ФП и ссылка на чек.
• Ошибка — ОФД отклонил или недоступен; авто-повтор до N попыток, затем Telegram-алерт.

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

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

• Организация — чей чек пробивает касса. По 54-ФЗ касса привязана к ИНН юрлица, поэтому у каждой организации должна быть своя. Касса без организации служит запасной для тех, у кого своей нет. Реквизиты продавца (название, ИНН, НДС) правятся в карточке организации на вкладке «Реквизиты» — карандаш рядом со строкой реквизитов ведёт туда напрямую.
• Боевой режим кассы и источники кассы — у каждой кассы свой выключатель и свой набор источников. По умолчанию касса наследует общие настройки; можно переопределить, когда у разных организаций разный статус.
• ИНН — 10 цифр для юрлица, 12 для ИП; должен совпадать с ИНН компании, иначе чек-лист покажет расхождение.
• Место расчётов — тег 1187. Для расчётов через интернет туда идёт адрес сайта, зарегистрированного в ОФД, а не улица.
• Пароль — наружу не отдаётся: карточка показывает только факт «задан». Пустое поле при сохранении означает «не менять».
• Ставка НДС — в карточке кассы её нет: она берётся из реквизитов компании, единым источником для всех чеков.

В списке касс колонка «Состояние» показывает, чего кассе не хватает («нет: логин, пароль, группа ККТ») или что ИНН расходится с компанией — без открытия карточки.

Боевой режим: общий и по кассе

Чек уходит в ОФД, только когда включён и общий рубильник (FISCAL_ENABLED), и боевой режим кассы организации платежа. Касса без явного флага наследует общий — так одна касса работает как раньше, а у нескольких организаций режим и источники независимы.

flowchart TD
  S{"Общий рубильник
FISCAL_ENABLED"} -->|"выключен"| N["Чек не уходит"]
  S -->|"включён"| K{"Режим кассы
организации"}
  K -->|"наследует общий"| Y["Чек уходит в ОФД"]
  K -->|"включён"| Y
  K -->|"выключен"| N

Права и журнал

• Страница фискализации, сохранение настроек и проверка связи закрыты правом «Настройки · Финансы».
• Список касс, выпадающий список компаний и счётчики очереди показывают только те организации, которые доступны сотруднику.
• Включение и выключение боевого режима, правка и удаление касс пишутся в журнал аудита с перечнем изменений.

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

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

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

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

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

Настройка приёма онлайн-платежей: через что клиент платит из личного кабинета и мобильного приложения, какая берётся комиссия и с каких адресов принимается webhook.

Наборы настроек: общие и кассы организаций

Страница правит два разных набора, между ними переключает полоса в шапке:

• Общие настройки — глобальные ключи. По ним платят клиенты организации по умолчанию и все, у кого организация не проставлена.
• Касса организации — собственные реквизиты приёма оплат конкретного юрлица (OrgPaymentSettings). При создании платежа биллинг сначала берёт кассу организации клиента и только при её отсутствии откатывается на общие ключи.

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

Секретные ключи

Секреты в браузер не отдаются: в поле показывается только маска с опознавательным хвостом (••••••••2bc9). Пустое поле при сохранении означает «не менять» — чтобы заменить ключ, введите новый.

Проверка подключения

Кнопка «Проверить подключение» различает три исхода, а не два:

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

Провайдеры

• Ю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) и зачисляет на счёт.

Комиссия

Задаётся в процентах (например, 4,5), максимум 20 %; значение проверяется на сервере. Комиссия добавляется клиенту сверху: при пополнении на 500 ₽ и ставке 4,5 % платёжная система спишет 522,50 ₽, а на счёт зачислится ровно 500 ₽. Карточка справа пересчитывает пример при вводе.

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

• Белый список IP (CIDR через запятую) — запросы с других адресов получают 403. Пустой список означает набор по умолчанию: ЮKassa, W1 и localhost. Кнопки-пресеты добавляют адреса без дублей, «Очистить» запрашивает подтверждение.
• Секрет подписи Generic/UCS — обязателен для приёма через «Единую кассу». Пока он не задан, канал помечается бейджем «не задан — канал отключён», а webhook отвечает 403. Кнопка «Генерировать» создаёт секрет криптостойким генератором браузера.

Аудит и сохранение

Каждое изменение пишется в журнал аудита (PAYMENT_SETTINGS) с автором и перечнем изменённых параметров: для обычных полей — старое и новое значение, для секретов — только факт замены. Кнопка «Сохранить настройки» закреплена внизу формы, не исчезает после сохранения и снова гаснет, когда изменений нет. Перезапуск сервера вынесен отдельной кнопкой и требует подтверждения.

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

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

Зачем это нужно: у каждой платёжной системы свой 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, получают новые типы. Это безопасно: отчёты с интервалом «после 2026-05-08» получат правильную разбивку, ранние периоды останутся как есть.

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

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

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

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

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

1. SmitMailServ на demo-сервере сервер приложения — 4 ящика (bank/noreply/info/support) на почтовом поддомене, 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 — четыре страницы раздела

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

Структура страницы:

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

Автонастройка ящика. Кнопка «Автонастроить ящик» создаёт почтовый ящик приёма выписок (по умолчанию bank@billing.smit34.ru — на домене почтовой инфраструктуры биллинга, а не на домене ЛК организации), прописывает DNS-записи и заполняет IMAP автоматически. Если ящик уже задан в IMAP_BANK_USER, берётся его адрес. Когда ящик настроен, блок сворачивается в строку «Ящик bank@billing.smit34.ru настроен для приёма выписок» с кнопкой «Изменить» — поля IMAP скрыты, чтобы не мешать; «Изменить» раскрывает их обратно.

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 платежей в день. Один платёж разбирается в один клик через массовое действие или в два — через модальное окно.

Возможности

• 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) — перезапуск.

Путь платежа: от письма банка до баланса клиента

flowchart TD
  MAIL["Письмо банка
с выпиской"] --> PARSE["Разбор вложения"]
  PARSE --> ORG["Определение юрлица
по счёту получателя"]
  ORG --> CHK{"Сводное перечисление
приёмщика платежей?"}
  CHK -->|"да"| REG["Статус «Сводный реестр»
по клиентам не разносится"]
  CHK -->|"нет"| MATCH{"Сопоставление
с клиентом"}
  MATCH -->|"нашли одного"| MTD["Сопоставлена"]
  MATCH -->|"несколько или никого"| MAN["На модерации
оператор привязывает вручную"]
  MAN --> MTD
  MTD --> RISK{"Есть признаки
расхождения?"}
  RISK -->|"да"| ONE["Разбирается поштучно
в массовое зачисление не попадает"]
  RISK -->|"нет"| CRED["Зачисление на баланс"]
  ONE --> CRED
  CRED --> DOC["Счёт и акт для юрлица
от нужной организации"]

Сводные перечисления приёмщиков платежей

Клиент платит через кассу Сбербанка или терминал «Единой кассы», приёмщик копит оплаты за период и перечисляет провайдеру одной строкой. В назначении так и написано:

ЗА ИНТЕРНЕТ,ТВ,СВЯЗЬ; ПО ПЛАТЕЖАМ С 01/06/2026 ПО 01/06/2026, СУММА 136398.00, КОЛ-ВО 138, ЭЛ.РЕЕСТР EPS…

За такой строкой стоят 138 разных клиентов, и их оплаты уже зачислены другим каналом. Привязать перечисление к одному клиенту нельзя, а разнести повторно — задвоить деньги. Поэтому оно получает статус «Сводный реестр», уходит из очереди ручного разбора и остаётся в журнале как поступление на расчётный счёт.

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

Как отличается реестр от обычного платежа

flowchart LR
  P["Платёж из выписки"] --> A{"ИНН плательщика
в списке приёмщиков?"}
  A -->|"нет"| ORD["Обычный платёж
идёт на сопоставление"]
  A -->|"да"| B{"В назначении есть
признак реестра?"}
  B -->|"нет"| ORD
  B -->|"да"| REG["Сводный реестр"]

Признаков должно быть два сразу. Одного ИНН мало: со счёта того же банка приходят и обычные платежи юрлиц-клиентов — их распознавание пропускает дальше, на сопоставление. Признаки реестра в назначении: «ЭЛ.РЕЕСТР», «ПО ПЛАТЕЖАМ С …», «за приём платежей».

Список ИНН приёмщиков — настройка BANK_AGGREGATOR_INNS в модуле, а не константа в коде: появится третий приёмщик — оператор добавит его сам. По умолчанию там ПАО Сбербанк и РНКО «Единая касса».

Разбор очереди, организации и аудит

Аудит модуля 24.08.2026 показал, что очередь стояла не из-за неудобств интерфейса, а из-за трёх дефектов.

• Ручная привязка платежа была невозможна. Поиск клиента уходил на /rest_api/v2/Abonents/?search=…, а этот API не знает параметра search — возвращались первые клиенты подряд. Плюс в разметке результатов стояло a.pk, тогда как ключ называется id: строки рисовались как #undefined, а клик отправлял abonent_id=undefined. Отсюда платежи, висевшие на модерации с мая.
• Баннер отката висел постоянно. Класс .bq-hidden объявлен выше по файлу, чем .bq-undo-banner{display:flex} — при равной специфичности побеждает нижнее правило. Жёлтая плашка «операция выполнена» показывалась на каждой загрузке, а панель массовых операций была развёрнута всегда.
• Счётчик импортов на странице парсеров запрашивал JSON у страницы, которая отдаёт HTML — спиннеры крутились вечно.

Привязка платежа: контекст и данные ФНС

Поиск клиента идёт по ФИО или названию, номеру договора, телефону, e-mail, ИНН и номеру клиента. Клиенты с совпавшим ИНН поднимаются в начало списка.

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

Видно сам платёж — сумму, дату, банк, плательщика с ИНН и назначение — и кнопки-подсказки с номерами из назначения: клиент часто пишет туда номер договора. Если ИНН плательщика в базе не найден, реквизиты подтягиваются из ФНС через DaData: название, адрес, руководитель и кнопка «Искать по названию из ФНС».

Организация платежа

Импорт и операция запоминают юрлицо-получателя — оно определяется по расчётному счёту из выписки. В очереди и журнале появилась колонка «Орг.», списки скоупятся переключателем организации в шапке и правами сотрудника.

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

Флаги расхождений в сопоставлении

Три случая помечаются значком и подсветкой строки: совпадение по похожести ФИО, один ИНН у разных клиентов, расхождение ФИО плательщика и клиента. Такие строки не попадают в массовое выделение — их разбирают по одному. При установке галочки «выбрать все» оператор видит, сколько платежей пропущено и почему.

Поиск, период, постраничный вывод и итоги

• Поиск по плательщику, ИНН, лицевому счёту, назначению, имени и договору клиента, номеру операции
• Диапазон дат через общий компонент выбора периода
• 20 / 50 / 100 / 200 строк на странице, постраничная навигация
• Итог по отфильтрованному: сколько платежей и на какую сумму. Крупная сумма показана коротко — «1,2 млн ₽», точное значение — во всплывающей подсказке.
• Фильтр по клиенту ?abonent=<id> — переход из карточки клиента

Панель управления — в одну строку. Поиск, выбор периода и размер страницы сужены так, чтобы вместе с кнопкой «Применить» и инструментами раздела (горячие клавиши, настройка колонок, «Журнал» импортов, «Настройки») уместиться в одну линию. Итог по выборке прижат к правому краю той же строки.

Журнал аудита

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

Вкладка «Банк» в карточке клиента

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

На телефоне

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

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@вашдомен.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 (день месяца).

Единое оформление всех четырёх страниц

Все четыре страницы раздела — Настройки, Банки и парсеры, Очередь модерации и Журнал импортов — работают на одних и тех же элементах интерфейса: таблицы, фильтры, подтверждения и уведомления ведут себя одинаково.

• Единые табличные компоненты. И очередь, и журнал импортов построены на SmitTable: порядок, ширина и видимость колонок настраиваются кнопкой «Колонки» и сохраняются в профиле сотрудника, а не в браузере; на телефоне строки автоматически становятся карточками с подписями полей. Полоса статусов — SmitChipBar, панель массовых действий — SmitBulkBar (появляется только при выборе), выбор периода — SmitDateRange, бейдж организации — OrgBadge, всплывающие уведомления — SmitToast, пустые состояния — smit-empty.
• Подтверждения. Каждый опасный шаг — включая «Забрать сейчас» — спрашивает подтверждение и перечисляет последствия. Диалог корректен в тёмной теме, на телефоне открывается панелью снизу.
• Тёмная тема — контраст. Приглушённые подписи (итоги, пейджер, мета-строки) в очереди, настройках и журнале читаются с контрастом не ниже WCAG AA.
• Превью документов — только в облаке. Превью PDF счёта/акта загружается в GCS и отдаётся редиректом на подписанный URL (правило проекта «файлы только в GCS»); локальная отдача из /var/db осталась fallback'ом при выключенной (BANK_DOC_UPLOAD_GCS=false) или недоступной GCS-загрузке.
• Защита от каскадного пробития чеков. «Забрать сейчас» при одновременно включённых автозачислении (BANK_AUTO_CREDIT_ENABLED) и боевом режиме (FISCAL_ENABLED) требует явного подтверждения: забор писем каскадом зачисляет платежи и пробивает фискальные чеки в ОФД — это необратимо. Осознанное подтверждение отдельно фиксируется в журнале аудита.
• Мобильная адаптация. На телефоне списки очереди, журнала и парсеров превращаются в карточки (данные не прячутся за горизонтальным скроллом). Кнопки и карточки статистики на странице настроек раскрываются на всю ширину, длинные подписи сокращены («Очередь», «Журнал», «Забрать»). Кнопки действий в карточках — не меньше 44×44 px (удобно попасть пальцем).
• Единые мобильные фильтры. В очереди и журнале фильтры на телефоне сворачиваются в единый компонент SmitMobileFilters — кнопку «Фильтры» со счётчиком активных фильтров, открывающую нижнюю панель (bottom-sheet). «Колонки» и справка на телефоне скрываются, а «Журнал»/«Настройки»/«Применить» остаются на виду. На странице парсеров кнопка добавления — компактный «+».
• Сквозной переход до чека ОФД. У зачисленной операции в очереди рядом со ссылкой «FinOp #N» появилась прямая ссылка на кассовый чек в ОФД (54-ФЗ) и индикатор статуса пробития (ожидает / ошибка). Цепочка навигации замкнута: письмо-импорт ↔ очередь → финансовая операция → чек ОФД (карточка финоперации, в свою очередь, показывает чек и обратную ссылку на банковскую операцию).
• Привязка платежа — раскрытием строки (по образцу Xero). На широком экране кнопка «Привязать» не открывает модальное окно, а раскрывает строку-аккордеон прямо под операцией: там карточка платежа (сумма, дата, плательщик, ИНН, назначение), поле поиска клиента (ФИО / договор / телефон / e-mail / ИНН / ID) с подсказками-кнопками из назначения платежа и подтверждением перед зачислением. На телефоне (< 768 px) — то же в виде модалки / слайд-панели.

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

URL: /admin/settings/mailserver/ — управление собственным почтовым сервером SmitMailServ, развёрнутым на хосте mail.вашдомен.ru. Операции с ящиками и доменами доступны из биллинга через API https://mail.вашдомен.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@вашдомен.ru, noreply@вашдомен.ru, ask@вашдомен.ru и др. Нельзя удалить через UI (server-side защита в get_protected_mailboxes()), чтобы не сломать банковские выписки/рассылку.
• DKIM / SPF / DMARC — статус DNS-записей по нажатию «Обновить».

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

Список всех ящиков сервера: кто владелец, сколько занято, что ящик обслуживает. Строки подгружаются AJAX-ом, поиск идёт по адресу и имени.

Одна строка тулбара: домен, тип ящика, поиск, колонки, добавление. Ниже — таблица с организацией, счётчиком писем и ролями.

Что показывает таблица

Роли ящика

Роль — это ответ на вопрос «что этот ящик делает для биллинга». Назначенная роль показана подписью, остальные остаются значком с подсказкой: в списке на сотню строк важно видеть включённое, а не перечень возможного.

flowchart LR
  BOX["Ящик
ask@вашдомен.ru"]
  BOX -->|Поддержка| TICKETS["Обращения
письмо → тикет"]
  BOX -->|Голосовая| VOICE["Голосовая почта
запись → заявка"]
  BOX -->|Рассылка| SEND["Уведомления и рассылки
отправитель писем"]
  BOX -->|Выписки| BANK["Банковские выписки
разбор вложений"]
  classDef on fill:#e8f7ef,stroke:#43b77a,color:#1b5e3f
  classDef box fill:#f4f6f8,stroke:#adb5bd,color:#212529
  class BOX box
  class TICKETS,VOICE,SEND,BANK on

На телефоне

Сверху остаётся то, за чем в раздел заходят: выбор домена и «Добавить». Ниже — поиск, «Фильтры» и обновление в одну строку; фильтр по типу ящика открывается шторкой снизу. Таблица превращается в карточки — по строке на ящик, без горизонтальной прокрутки.

flowchart TB
  subgraph D["Десктоп"]
    T["Одна строка тулбара:
домен · тип ящика · поиск · колонки · добавить"]
    TB["Таблица:
настраиваемые колонки, роли в строке"]
    T --> TB
  end
  subgraph M["Телефон"]
    P["Домен + Добавить"]
    S["Поиск + Фильтры + Обновить"]
    SH["Шторка: тип ящика"]
    C["Карточки ящиков"]
    P --> S --> C
    S -.-> SH
  end
  D -.->|те же элементы, другая раскладка| M

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

• Домен — <select> с подгрузкой реального списка из SmitMailServ: опечататься нельзя.
• Логин (до @) — локальная часть адреса.
• Пароль + Подтверждение — обязательны. Генератор пароля рядом (фиолетовая иконка 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'.

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

Веб-почта: календарь, контакты, брендинг

Сотрудники работают с почтой в браузере по адресу https://mail.<домен>/ (например mail.вашдомен.ru). Кроме писем там есть календарь, задачи и адресная книга. Интерфейс подхватывает данные из биллинга: имя сотрудника, его фото, подпись, контакты коллег и фирменные цвета организации, которой принадлежит домен.

Войти можно двумя способами: обычным логином и паролем от биллинга либо из админки — раздел «Почтовый сервер» → вкладка «Ящики» → меню строки → «Войти в ящик» (вход без ввода пароля, каждый такой вход пишется в аудит; возможность отключается настройкой, см. «Настройки сервера»).

flowchart LR
    U["Сотрудник
браузер"] --> HN["nginx хоста
mail.домен"]
    HN --> MN["nginx почты
статика + брендинг"]
    MN --> SG["SOGo
веб-интерфейс"]
    SG --> DV["Dovecot
письма IMAP"]
    SG --> PF["Postfix
отправка SMTP"]
    SG --> PG[("Настройки SOGo
база sogo")]
    SG --> BV[("Биллинг
ящики и контакты")]
    MN -. "цвета, логотип" .-> API["API брендинга
биллинга"]
    API --> ORG[("Карточка
организации")]

Брендинг по организации

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

Что окрашивается: верхняя панель и шапка списка, кнопка создания, ссылки, выделение выбранной папки, а в календаре — сегодняшний день, колонка текущего дня и события личного календаря. Логотип организации встаёт в левый край верхней панели.

sequenceDiagram
    participant B as Браузер
    participant N as nginx почты
    participant A as API биллинга
    participant O as Карточка организации
    B->>N: открыть почту
    N-->>B: страница SOGo + скрипт брендинга
    B->>A: какой брендинг у почтового домена
    A->>O: домен → организация
    O-->>A: цвет, логотип, название
    A-->>B: настройки брендинга
    B->>B: перекрасить интерфейс, вставить логотип

Справка внутри почты

В правом верхнем углу, слева от кнопки выхода, есть значок «?» — он открывает этот раздел документации.

Кнопка справки соседствует с выходом — там, где её ищут.

Имя, подпись и фото из профиля

Ящик сотрудника берёт данные из его профиля в биллинге: не нужно отдельно заполнять имя отправителя и вручную набирать подпись.

• Имя отправителя — ФИО из профиля. У ящиков со своим названием («Банковские выписки», «Поддержка СмИТ») название сохраняется: такие письма должны уходить от службы, а не от закреплённого за ящиком человека.
• Подпись — собирается автоматически: ФИО, роль, телефон, адрес ящика, сайт и реквизиты организации домена, плюс фото сотрудника.
• Фото — то же, что в профиле; видно и в интерфейсе почты, и в подписи у получателя письма.

Данные обновляются сами: при сохранении профиля, смене фото, создании ящика и смене владельца. Разовый прогон по всем ящикам — команда manage.py sync_mail_identities (ключ --dry-run покажет, что получится, без записи).

flowchart TD
    P["Профиль сотрудника
ФИО, телефон, фото"] --> S{"Синхронизация"}
    O["Организация домена
название, сайт, телефон"] --> S
    S --> N["Имя отправителя"]
    S --> G["Подпись письма"]
    S --> F["Фото в интерфейсе
и в подписи"]
    S --> C["Личная книга и календарь
названы по организации"]

Блок «Почта» в профиле: ящики сотрудника, переключатели уведомлений, адрес пересылки и подсказка про пароль.

Адресная книга из биллинга

В почте есть общая книга «Контакты». Она только читается — данные ведутся в биллинге:

• Сотрудники — ФИО, рабочий адрес и телефон из профиля. Показываются всегда.
• Клиенты — имя, адрес и договор. По умолчанию скрыты: это персональные данные, а книга видна всем владельцам ящиков. Включается переключателем в «Настройках сервера».

Поиск работает и по имени, и по адресу — достаточно начать набирать фамилию в поле получателя, и адрес подставится сам. Личная книга и календарь названы по организации домена (например «Контакты СмИТ Поддержка») вместо стандартного «Personal Address Book».

Общая книга «Контакты» рядом с личной книгой сотрудника.

Вкладка «Почта» в панели уведомлений

Чтобы прочитать письмо, не обязательно открывать веб-почту: в панели уведомлений биллинга (колокольчик в правом верхнем углу) есть вкладка «Почта». Там лента писем из всех ящиков сотрудника — с отправителем, адресом, папкой и временем («15 минут назад», «вчера»). Избранные письма закреплены сверху.

Письмо открывается в правой колонке. Оттуда же можно:

• ответить — поле с форматированием и вложениями, как в переписке чата;
• переслать письмо другому адресату;
• отметить избранным или непрочитанным, убрать в спам или корзину;
• скачать вложение и открыть письмо в самой почте.

Ответ уходит от ящика сотрудника, поэтому получатель отвечает ему, а не на общий адрес; ящик-отправитель выбирается списком, если ящиков несколько. Какие ящики показывать в ленте, каждый выбирает у себя в профиле; вкладку целиком можно выключить в «Настройках сервера».

Лента писем и открытое письмо с полем ответа.

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

Раздел «Почтовый сервер» → вкладка «Настройки сервера». Кроме технических параметров (имя сервера, размер письма, лимит отправки, relay, DKIM) там есть переключатели, которые влияют на повседневную работу:

Здоровье сервера и доставляемость

Вкладка «Сервер» отвечает на два вопроса: работает ли почта прямо сейчас и дойдут ли письма до получателя, а не в спам.

Здоровье сервера — по строке на каждую часть почты. Все строки зелёные — почта принимается и отправляется. Очередь показывает, сколько писем ждёт отправки; норма — ноль. Кнопка с круговой стрелкой перезапускает одну упавшую часть, не трогая остальные.

flowchart LR
  NET["Интернет"] -->|SMTP| PF["Приём и отправка
postfix"]
  PF --> RS["Антиспам
rspamd"]
  RS --> DC["Хранение и чтение
dovecot"]
  DC --> SG["Веб-почта
sogo"]
  SG --> NG["Веб-почта, сайт
sogo-nginx"]
  NG -->|браузер| USER["Сотрудник"]
  RD["Кэш
redis"] --- RS
  RD --- SG
  BIL["Биллинг"] -->|IMAP: обращения, выписки| DC
  BIL -->|SMTP: уведомления| PF

Письма доходят, а не в спам — четыре проверки на каждый домен: подпись писем, разрешение на отправку, защита от подделки и запись приёма почты. Все зелёные означают, что письма с этого домена принимают Gmail, Mail.ru и Яндекс; красная — письма могут уходить в спам, и настраивать её нужно в разделе «Домены и DNS».

Колонка «Писем» в списке ящиков

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

Список ящиков: роли, владелец, занятое место и счётчик писем.

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». Логин подставляется из имени пользователя, пароль генерируется автоматически — достаточно нажать «Создать». Опционально указывается адрес пересылки: копии входящих уходят на внешний адрес, оригинал остаётся в ящике.