MK Utilities Коммунальные платежи

Помощь и документация

Как пользоваться дашбордом и Telegram-ботом

Обзор системы

MK Utilities — внутренняя система для учёта коммунальных платежей, статусов и напоминаний. В неё входят FastAPI-дашборд (веб) и Telegram-бот.

Основные сущности

Роли и доступ

Работа с дашбордом

  1. На странице «Объекты» выберите год и месяц, чтобы увидеть статусы «Всё оплачено», «Есть долги» или «Нет данных».
  2. Откройте объект, чтобы увидеть услуги, последние показания и платежи.
  3. Кнопка «Показание» — заполните прибор, дату, значение и при необходимости приложите фото.
  4. Кнопка «Платёж» — укажите услугу, период, сумму, статус и приложите чек.
  5. Ссылки «Фото»/«Чек» в таблицах ведут на файл из раздела /media.

Добавление счётчиков

На странице объекта возле каждой услуги появилась ссылка «+ счётчик». Она раскрывает инлайн-форму с двумя вкладками: «Ручной ввод» и «JSON». Можно быстро добавить прибор, указав серийный номер, производитель, расположение и первое показание, либо вставить заранее подготовленный JSON.

Пример JSON (горячая вода):

{
  "service_kind": "water_hot",
  "serial_raw": "07-131435-??",
  "vendor": "Берегун",
  "placement": "Ванная",
  "status": "active",
  "reading": {
    "value": 439.524,
    "taken_at": "2025-11-14T12:00:00+03:00"
  },
  "attachments": {
    "photo_hint_filename": "meter_hot_2025-11-14.jpg"
  }
}

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

Админка

Перейдите на /dashboard/login под учёткой администратора и откройте «Админка → Управление объектами». Здесь добавляются объекты, услуги, счётчики и пользователи. Менеджерам назначаются регионы, чтобы ограничить список доступных объектов.

Импорт объекта из JSON

Администраторы могут в один шаг создать объект, лицевые счета и услуги на странице «Импорт по JSON». Форма принимает заранее подготовленный JSON по структуре ЕПД (см. пример внутри страницы):

Сервис валидирует JSON через Pydantic: ошибки подсвечиваются над формой с указанием поля (например, accounts.0.services.1.amount). Импорт работает идемпотентно — повторная загрузка того же JSON обновляет объект, лицевые счета и услуги, не создавая дубликаты. Если суммы не сходятся с расчётом (qty×tariff), в карточке услуги появится предупреждение Δ. Ссылки на ЕПД подтягиваются автоматически, если файл лежит в media/epd.

ЕПД: импорт счетов и платежей (JSON/CLI/API)

Шаг 2A mini — CLI и API для загрузки JSON с объектом ЕПД. Используйте пример с формы «Импорт по JSON» и выполните:

$ python -m backend.app.management.epd_import_cli --json epd_object.json
# либо через API (только админ-сессия):
$ curl -X POST http://127.0.0.1:8000/api/epd/import \
  -H \"Content-Type: application/json\" \
  --cookie \"session=...\" \
  -d @epd_object.json

Команда вернёт {"{"}"results": [{"{"}"bill_id": 42, "created": true{"}"},{"{"}...{"}"}]{"}"}, а API ответит объектом {"{"}"bill_id": 42, "created": true{"}"}.

Шаг 2C — CLI платежей. Формат JSON:

{
  "epd_code": "1011399699",
  "period": "2025-10",
  "amount": 18234.55,
  "paid_at": "2025-11-12T13:45:00+03:00",
  "bank_ref": "SBP:1234567890",
  "meta": { "receipt_path": "media/epd/receipts/2025-11-12_1011399699.pdf" }
}

Вызовите python -m backend.app.management.epd_payment_cli --json payment.json. Скрипт найдёт счёт по коду ЕПД (или FLS) и периоду, создаст запись epd_bill_payments, пересчитает paid_sum и статус (pending/partial/paid/overpaid). Повторный запуск для того же платежа заблокирован уникальным индексом.

ЕПД в админке: импорт, статусы и платежи

На карточке объекта появился блок «ЕПД» со сводкой по счетам (к оплате, оплачено, остаток) и кнопкой «Открыть ЕПД». Внутри отдельного раздела /dashboard/admin/objects/<id>/epd доступна таблица всех счетов, кнопка импорта JSON и быстрая навигация к карточке конкретного счёта.

Карточка счёта показывает статусы и историю платежей, а форма «Добавить оплату» поддерживает два режима: заполнение полей и вставка готового JSON. При отправке форма вызывает REST API POST /api/epd/payments/import, поэтому все валидации и расчёт статуса происходят на одном контуре.

Лицевые счета визуализированы как «подобъекты»: видно поставщика, FLS/ЕПД, количество услуг и последний статус. Сервисы со scope object выводятся в отдельном блоке «Общие услуги и счётчики» и отображают метки всех прикреплённых счётчиков. Для админа доступны действия «Сделать общим» / «Вернуть к ЛС» прямо из карточек услуг.

Антидублирование: перед вставкой вычисляется dedupe_key = sha1(f"{'{'}bill_id{'}'}|{bank_ref or ''}|{amount:.2f}|{paid_at.isoformat(timespec='minutes')}"). Если такой ключ уже есть — API возвращает имеющийся платёж с duplicate=true, повторная запись не создаётся и в UI напротив платежа появляется бейдж Duplicate.

Вложения чеков: API и админ-форма принимают файл через поле attachment (PDF/PNG/JPG). Файл сохраняется в media/epd_payments/<bill_id>/…, в карточке счёта отображается превью (для изображений) или ссылка «Скачать PDF».

Загрузка чеков и авто-платежи

  1. Менеджер открывает нужный объект и нажимает «Загрузить чек».
  2. Файл сохраняется, а парсер пытается определить услугу, сумму, период и дату оплаты.
  3. Если найдено достаточно подсказок — запись получает статус «Есть предложение», иначе остаётся «Новая».
  4. Карточка импорта видна на странице объекта и в разделе «Админка → Импорт чеков», откуда можно открыть форму проверки.
  5. На форме review менеджер/админ корректирует поля и нажимает «Применить» либо помечает импорт как ошибочный.

Файлы чеков лежат в media/imports. Админский список позволяет фильтровать импорты по статусу и региону, чтобы анализировать ошибки распознавания. Если переменная CHEQUE_AI_ENABLED включена, backend сохраняет в карточке подсказки ИИ (сумма, период, услуга) и выводит их на форме подтверждения.

Лог разработки

Страница /dashboard/devlog показывает краткую историю итераций: что уже сделано, какие заглушки остались и планируемые шаги. Источник данных — файл infra/DEV_LOG.md; при добавлении значимых фич обновляйте запись с датой и статусом (STUB / IN_PROGRESS / DONE).

Roadmap / чек-лист

Все авторизованные пользователи видят пункт «✨ Roadmap» в шапке, который ведёт на страницу /dashboard/roadmap. Там задачи живут в базе (roadmap_items): показываются описание, статус, приоритет и сколько времени заняла реализация (разница между датой создания и завершения). Прогресс-бар учитывает только активные задачи, а снятые помечаются статусом dropped.

Типовой сценарий: добавьте идею → переведите в in_progress, когда началась работа → отметьте done, чтобы увидеть длительность и включить её в статистику Roadmap.

Telegram-бот

Напоминания используют параметры REMINDER_INTERVAL_MINUTES и REMINDER_DAYS_BEFORE_DUE из .env.

Резервное копирование и версии

Все бэкапы лежат в /opt/mk-utilities/backups, журнал версий — VERSIONS.log. Подробный список и инструкции доступны на странице «Шаги разработки и версии». Рекомендуется запускать ./infra/backup_mku.sh <label> перед крупными изменениями.