Skip to content

telnex/meterTrack

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
handlers
handlers
 
 
keyboards
keyboards
 
 
log
log
 
 
states
states
 
 
utils
utils
 
 
README.md
README.md
 
 
app.py
app.py
 
 
config.py
config.py
 
 
meter_track.db
meter_track.db
 
 
requirements.txt
requirements.txt
 
 

Repository files navigation

🏠 Meter Track - Telegram Bot для учета коммунальных платежей

Telegram бот для ведения учета показаний счетчиков и расчета коммунальных платежей с визуализацией данных и настраиваемыми тарифами.

📋 Содержание

✨ Особенности

🎯 Основной функционал

  • 📊 Добавление показаний - Ввод показаний счетчиков с валидацией
  • 📈 История показаний - Просмотр всех записей с пагинацией
  • 📊 Графики расходов - Линейные графики с точками для визуализации
  • ⚙️ Настройка тарифов - Индивидуальные тарифы для каждого пользователя
  • 🔒 Админ-контроль - Доступ только для администратора

🛡️ Валидация данных

  • Проверка на корректность введенных данных
  • Валидация: новые показания не могут быть меньше предыдущих
  • Автоматический расчет потребления и стоимости
  • Перезапись показаний за тот же месяц

📊 Аналитика

  • Сравнение с предыдущим месяцем (стрелки вверх/вниз)
  • Показ разности потребления в скобках
  • Линейные графики с точками для трендов
  • Показ только последних 12 записей на графике

🔧 Технические характеристики

📦 Зависимости

aiogram==2.20.0          # Telegram Bot API
matplotlib==3.7.2        # Генерация графиков
Pillow==10.0.0           # Обработка изображений

🗄️ База данных

  • SQLite - легковесная встроенная БД
  • Таблицы:
    • users - пользователи бота
    • user_settings - настройки тарифов
    • meter_readings - показания счетчиков

🏗️ Архитектура

  • FSM (Finite State Machine) - для управления состояниями ввода
  • Модульная структура - разделение по функциональности
  • Обработчики событий - асинхронные обработчики команд
  • Inline клавиатуры - интерактивные кнопки

🚀 Установка и настройка

1. Клонирование репозитория

git clone <repository-url>
cd meterTrack

2. Установка зависимостей

pip install -r requirements.txt

3. Настройка конфигурации

Отредактируйте config.py:

TOKEN = 'YOUR_BOT_TOKEN'          # Токен бота от @BotFather
ADMIN_ID = 123456789              # ID администратора
BD = 'meter_track.db'             # Имя базы данных

# Тарифы по умолчанию
DEFAULT_LIGHT_RATE = 4.5          # руб/кВт⋅ч
DEFAULT_GAS_RATE = 6.0            # руб/м³
DEFAULT_WATER_RATE = 35.0         # руб/м³
DEFAULT_DRAIN_RATE = 25.0         # руб/м³

4. Запуск бота

python app.py

📁 Структура проекта

meterTrack/
├── app.py                      # Точка входа приложения
├── config.py                   # Конфигурация бота
├── requirements.txt            # Зависимости Python
├── README.md                   # Документация
│
├── handlers/                   # Обработчики команд
│   ├── __init__.py
│   ├── main.py                 # Основные команды (/start, /help, /add, /history, /chart)
│   ├── menu_handlers.py        # Обработчики кнопок главного меню
│   ├── meter_readings.py       # FSM для ввода показаний
│   ├── settings.py             # Настройка тарифов
│   ├── callback.py             # Обработчики inline кнопок
│   └── navigation.py           # Навигация по логам
│
├── keyboards/                  # Клавиатуры
│   ├── default/               # Обычные клавиатуры
│   │   ├── main_menu.py       # Главное меню
│   │   └── keyboards.py      # Дополнительные клавиатуры
│   └── inline/                # Inline клавиатуры
│       ├── readings.py        # Клавиатуры для показаний
│       └── nav_log.py         # Навигация по логам
│
├── states/                     # FSM состояния
│   ├── __init__.py
│   └── client.py              # Состояния для ввода данных
│
├── utils/                      # Утилиты
│   ├── database.py            # Работа с базой данных
│   ├── text.py                # Тексты и константы
│   ├── chart_generator.py     # Генерация графиков
│   ├── analytics.py           # Аналитика
│   └── function.py            # Вспомогательные функции
│
├── log/                        # Логи
│   ├── bot.log                # Лог работы бота
│   └── metrics.json           # Метрики
│
└── cache/                      # Кэш

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

🚀 Первый запуск

  1. Отправьте /start боту
  2. Настройте тарифы в разделе "⚙️ Настройки"
  3. Добавьте первые показания через "📊 Добавить показания"

📊 Добавление показаний

  1. Нажмите "📊 Добавить показания" или отправьте /add
  2. Введите показания электросчетчика (кВт⋅ч)
  3. Введите показания газового счетчика (м³)
  4. Введите показания водосчетчика/слива (м³) - оба значения будут равны
  5. Бот автоматически рассчитает потребление и стоимость

📈 Просмотр истории

  • Команда: /history или кнопка "📈 История"
  • Пагинация: Навигация по страницам (по 5 записей)
  • Информация: Показ разности с предыдущим месяцем
  • Сортировка: От новых к старым

📊 Графики

  • Команда: /chart или кнопка "📈 График"
  • Тип: Линейный график с точками
  • Данные: Последние 12 записей
  • Цвет: Синий (#1f77b4)

⚙️ Настройки тарифов

  • Команда: /settings или кнопка "⚙️ Настройки"
  • Тарифы: Электроэнергия, газ, вода, слив
  • Сохранение: Автоматическое сохранение изменений

🤖 API и команды

📱 Основные команды

Команда Описание Доступ
/start Запуск бота и регистрация Админ
/help Справка по использованию Админ
/add Добавить показания Админ
/history История показаний Админ
/chart График расходов Админ
/settings Настройки тарифов Админ
/cancel Отмена текущей операции Админ

🎛️ FSM состояния

# Добавление показаний
MeterReadingStates.waiting_for_light      # Ожидание показаний света
MeterReadingStates.waiting_for_gas        # Ожидание показаний газа
MeterReadingStates.waiting_for_water      # Ожидание показаний воды/слива

# Настройки тарифов
SettingsStates.waiting_for_light_rate     # Ожидание тарифа за свет
SettingsStates.waiting_for_gas_rate       # Ожидание тарифа за газ
SettingsStates.waiting_for_water_rate     # Ожидание тарифа за воду
SettingsStates.waiting_for_drain_rate     # Ожидание тарифа за слив

🗄️ База данных

📊 Схема таблиц

👤 Таблица users

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    tg_id INTEGER UNIQUE NOT NULL,
    username TEXT,
    first_name TEXT,
    last_name TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)

⚙️ Таблица user_settings

CREATE TABLE user_settings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    light_rate REAL DEFAULT 4.5,
    gas_rate REAL DEFAULT 6.0,
    water_rate REAL DEFAULT 35.0,
    drain_rate REAL DEFAULT 25.0,
    FOREIGN KEY (user_id) REFERENCES users (id)
)

📊 Таблица meter_readings

CREATE TABLE meter_readings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    reading_date TEXT NOT NULL,
    light_reading REAL NOT NULL,
    gas_reading REAL NOT NULL,
    water_reading REAL NOT NULL,
    drain_reading REAL NOT NULL,
    light_consumption REAL DEFAULT 0,
    gas_consumption REAL DEFAULT 0,
    water_consumption REAL DEFAULT 0,
    drain_consumption REAL DEFAULT 0,
    total_cost REAL DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users (id)
)

🔄 Основные операции

  • Добавление показаний: add_meter_reading() - с валидацией и перезаписью
  • Получение истории: get_readings_with_differences() - с расчетом разностей
  • Настройки: update_user_settings() - обновление тарифов
  • Последние показания: get_last_reading() - для отображения

📊 Графики и аналитика

📈 Тип графиков

  • Линейные графики с точками
  • Цвет: Синий (#1f77b4)
  • Точки: Круглые маркеры с белой обводкой
  • Подписи: Значения в белых блоках над точками

📊 Аналитические данные

  • Потребление: Автоматический расчет разности с предыдущим месяцем
  • Стоимость: Расчет на основе настроенных тарифов
  • Тренды: Стрелки вверх/вниз для сравнения с предыдущим месяцем
  • Период: Показ последних 12 записей

🎨 Настройки matplotlib

plt.rcParams['font.family'] = ['DejaVu Sans', 'Arial', 'sans-serif']
plt.rcParams['axes.unicode_minus'] = False
# Отключение предупреждений о шрифтах
warnings.filterwarnings('ignore', category=UserWarning, module='matplotlib.font_manager')

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

👤 Контроль доступа

  • Админ-проверка: Только администратор может использовать бота
  • ID администратора: Настраивается в config.py
  • Валидация данных: Проверка корректности введенных значений

🛡️ Защита данных

  • Локальная БД: SQLite файл хранится локально
  • Валидация: Предотвращение некорректных данных
  • Обработка ошибок: Graceful handling исключений

📝 Логирование

📊 Уровни логирования

  • INFO: Обычная работа бота
  • ERROR: Ошибки и исключения
  • DEBUG: Детальная отладочная информация

📁 Файлы логов

  • log/bot.log - основной лог работы бота
  • log/metrics.json - метрики и статистика

⚙️ Настройка логирования

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler('log/bot.log', encoding='utf-8'),
        logging.StreamHandler()
    ]
)

🚀 Развертывание

🐳 Docker (рекомендуется)

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "app.py"]

🖥️ Локальный запуск

# Установка зависимостей
pip install -r requirements.txt

# Настройка конфигурации
# Отредактируйте config.py

# Запуск бота
python app.py

☁️ Облачное развертывание

  • Heroku: Простое развертывание с Procfile
  • Railway: Автоматическое развертывание
  • VPS: Полный контроль над сервером

🤝 Вклад в проект

🔧 Разработка

  1. Форкните репозиторий
  2. Создайте ветку для новой функции
  3. Внесите изменения
  4. Создайте Pull Request

🐛 Сообщение об ошибках

  • Используйте Issues для багов
  • Опишите шаги воспроизведения
  • Приложите логи ошибок

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.

Meter Track - Удобный учет коммунальных платежей в Telegram! 🏠📊

About

Telegram Bot для учета коммунальных платежей

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages