Финансовый Telegram-бот

Аккуратный бот для повседневного учёта личных финансов. Расход записывается одной строкой — 467 ярче или 3000 бензин. Зарплата распознаётся по словам зп и зарплата, например 5000 ЗП.

Что уже работает

• автоматическое определение категорий: Продукты, Развлечения, Машина, Кредиты, Ремонт и Другое;
• доходы, расходы и точные суммы с копейками;
• изменение категории и удаление только что добавленной записи;
• итоги за текущий месяц и за всё время;
• аналитика по категориям с процентами и визуальными полосами — за месяц или всё время;
• последние 10 операций;
• ежедневный отчёт: траты и доходы за день плюс накопительный итог месяца;
• отдельные данные для каждого Telegram-пользователя;
• защищённый семейный бюджет для двух супругов с подтверждением владельца;
• мгновенные уведомления супругу и в подключённый семейный Telegram-чат;
• один общий вечерний отчёт в семейный чат;
• общий долг: доходы автоматически уменьшают его, расходы увеличивают;
• знак - у суммы принудительно уменьшает общий долг независимо от категории;
• категории и подкатегории с возможностью добавлять собственные;
• SQLite в режиме WAL и защита от повторного дневного отчёта;
• готовый Docker-запуск на сервере.

Развёртывание на сервере из GitHub

Ниже приведён готовый вариант для чистого сервера с Ubuntu 22.04/24.04 или Debian 12. Установщик сам поставит Docker и Docker Compose, запросит настройки и запустит бота с автоматическим перезапуском.

1. Подготовьте доступ к приватному репозиторию

Репозиторий приватный, поэтому серверу нужен SSH-ключ. На сервере выполните:

sudo apt update
sudo apt install -y git openssh-client
ssh-keygen -t ed25519 -C "finance-bot-server"
cat ~/.ssh/id_ed25519.pub

При создании ключа можно нажимать Enter, оставляя предлагаемые значения. Скопируйте строку, которую показала последняя команда. Откройте репозиторий в GitHub и добавьте ключ: Settings → Deploy keys → Add deploy key. Галочку Allow write access не включайте — серверу достаточно доступа на чтение только к этому репозиторию.

Проверьте подключение:

ssh -T git@github.com

При первом подключении ответьте yes. Сообщение GitHub об успешной аутентификации означает, что доступ настроен.

2. Скачайте и установите бота

cd ~
git clone git@github.com:ochenstarik-ui/finance-telegram-bot.git
cd finance-telegram-bot
sudo bash install.sh

Во время установки будут запрошены:

• папка установки — обычно достаточно нажать Enter, чтобы использовать /opt/finance-bot;
• токен бота, полученный у @BotFather;
• часовой пояс — по умолчанию Asia/Novosibirsk;
• время ежедневного отчёта — по умолчанию 21:00;
• разрешение установить Docker, если его ещё нет.

Токен при вводе не отображается. Настройки сохраняются в /opt/finance-bot/.env с доступом только для root, а база данных — в постоянном Docker-томе.

3. Проверьте запуск

sudo docker compose -f /opt/finance-bot/compose.yaml ps
sudo docker compose -f /opt/finance-bot/compose.yaml logs --tail=100 finance-bot

Для просмотра журнала в реальном времени:

sudo docker compose -f /opt/finance-bot/compose.yaml logs -f finance-bot

Выход из просмотра журнала — Ctrl+C; бот при этом продолжит работать.

Обновление до новой версии

После появления изменений в GitHub выполните:

cd ~/finance-telegram-bot
git pull --ff-only
sudo bash install.sh

Установщик предложит сохранить прежний токен. Повторное развёртывание пересоберёт контейнер, но не удалит .env, операции и настройки из базы данных.

Управление ботом

# Перезапустить
sudo docker compose -f /opt/finance-bot/compose.yaml restart finance-bot

# Остановить
sudo docker compose -f /opt/finance-bot/compose.yaml stop finance-bot

# Запустить после остановки
sudo docker compose -f /opt/finance-bot/compose.yaml start finance-bot

Если install.sh запустить отдельно, без остальных файлов проекта рядом, он по-прежнему сможет загрузить резервную копию с Яндекс.Диска.

Ручной запуск на сервере

Понадобятся Docker и Docker Compose.

1. Создайте бота через @BotFather и скопируйте токен.
2. На сервере скопируйте .env.example в .env.
3. В .env замените BOT_TOKEN, при необходимости настройте таймзону и время отчёта.
4. Запустите контейнер:

docker compose up -d --build

Посмотреть состояние и журнал:

docker compose ps
docker compose logs -f finance-bot

Данные сохраняются в Docker-томе finance-data и не исчезают при пересборке контейнера.

Настройки

Переменная	Пример	Назначение
BOT_TOKEN	123:ABC...	токен от BotFather
BOT_TIMEZONE	Asia/Novosibirsk	таймзона операций и отчётов
DAILY_REPORT_TIME	21:00	локальное время дневного отчёта
DATABASE_PATH	/app/data/finance.db	путь к SQLite
LOG_LEVEL	INFO	уровень журналирования

Семейный бюджет и общий чат

1. Первый супруг открывает кнопку «Семья» и выбирает «Создать общий бюджет».
2. Второй супруг запускает этого же бота, открывает «Семья», нажимает «Ввести код супруга» и отправляет полученный код.
3. Код не даёт доступ автоматически: создатель бюджета получает запрос с кнопками «Подтвердить» и «Отклонить».
4. После подтверждения итоги, аналитика и история становятся общими. Новые записи мгновенно отправляются второму супругу.
5. Для общего журнала создайте Telegram-группу, добавьте туда бота. Создатель семейного бюджета должен быть администратором этой группы и отправить в ней команду /family_chat.

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

Общий долг

После создания семейного бюджета откройте кнопку «💳 Общий долг» и укажите текущую сумму. Сделать это может только создатель бюджета, второй супруг видит результат.

Например, исходный долг составляет 530713. После записи 400000 зарплата бот покажет долг 130713. Следующая запись 5000 продукты увеличит его до 135713. Запись -5000 рабочий закуп уменьшит долг на 5000, хотя останется расходом в финансовой аналитике.

Расчёт ведётся по операциям после установки исходной суммы:

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

Повторная установка текущей суммы начинает новый расчёт с указанного значения, не меняя историю доходов и расходов.

Категории и подкатегории

В семейном бюджете доступна кнопка «🗂 Категории». Категории общие для обоих супругов: каждый участник может добавить новую основную категорию или подкатегорию. При создании основной категории выбирается тип «Расход» или «Доход»; подкатегория наследует тип родителя. Перенос операции в категорию другого типа меняет её тип и влияние на долг.

При создании бюджета бот автоматически добавляет базовое дерево, например:

• Машина → Бензин, Ремонт, Запчасти, Мойка и парковка, Страховка;
• Продукты → Еда, Алкоголь, Кафе и рестораны, Бытовые товары;
• Развлечения → Кино и театр, Игры, Подписки, Хобби;
• Кредиты → Ипотека, Кредиты, Рассрочки;
• Ремонт → Материалы, Мебель, Работы, Инструменты.

Стандартные подкатегории определяются автоматически: запись 3000 бензин попадёт в Машина → Бензин, а 500 пиво — в Продукты → Алкоголь.

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

После добавления расхода нажмите «Изменить категорию». Можно выбрать как основную категорию, так и любую подкатегорию. Это работает и для записей, которые первоначально попали в «Другое». Изменить категорию может только автор операции; супруг и семейный чат сразу получают уведомление о переносе.

Локальная разработка

Нужен Python 3.11 или новее.

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env               # Windows: copy .env.example .env

Переменные из .env нужно загрузить в окружение, затем запустить:

python -m app

Тесты:

pytest

Как расширять категории

Названия, иконки и ключевые слова находятся в app/categories.py. Новые ключевые слова можно добавлять без изменения базы данных. Суммы хранятся целым числом копеек, поэтому арифметика не накапливает ошибки float.