Finance Tracker Telegram Bot

Телеграм-бот для учёта ежедневных расходов и доходов в Google Spreadsheet.

Возможности

• Добавление расходов с указанием даты, категории, суммы и описания.
• Добавление доходов с указанием даты, категории, суммы и описания.
• Синхронизация с двумя листами Google Spreadsheet –
  Расходы
  и
  Доходы
  .
• Работа как в Docker-контейнере локально, так и в продакшене (Ansible + Docker).
• Ограничение доступа: бот отвечает только пользователям, перечисленным в переменной
  TELEGRAM_ALLOWED_USERNAMES
  .

Подготовка Google Spreadsheet

1. Создайте новую таблицу и добавьте два листа строго с названиями:
   • Расходы
   • Доходы
2. Убедитесь, что первый лист имеет следующие колонки в указанном порядке:
   1. Дата
      (формат
      ДД.ММ.ГГ
      )
   2. Категория
   3. Сумма
   4. Описание
3. Для листа доходов колонки аналогичны.
4. Создайте сервис-аккаунт в Google Cloud, выдайте ему роль Editor для Google Sheets и сохраните JSON-файл ключа. Поделитесь таблицей с почтой сервис-аккаунта.
5. Запишите ID таблицы (содержимое между
   /d/
   и
   /edit
   в URL).

Переменные окружения

Скопируйте файл

TELEGRAM_BOT_TOKEN=<токен вашего бота>
GOOGLE_SA_CREDS_FILE=/app/credentials.json
SPREADSHEET_ID=<id таблицы>
EXPENSES_SHEET_TITLE=Расходы
INCOMES_SHEET_TITLE=Доходы
TELEGRAM_ALLOWED_USERNAMES=

Важно: при запуске контейнера положите JSON-файл сервис-аккаунта в

/app/credentials.json

или измените путь в переменной

GOOGLE_SA_CREDS_FILE

.

Запуск локально (Docker)

Деплой на виртуальный сервер (Ansible)

1. Установите зависимости для Ansible-playbook (только один раз):

2. В файле

   ansible/inventory.ini
   замените
   vm_ip_address
   на IP или DNS вашей ВМ и при необходимости имя пользователя.

3. Убедитесь, что у вас есть SSH-доступ с sudo-правами.

   • При необходимости укажите приватный ключ через
     -u
     /
     --private-key
     при запуске playbook либо задайте
     ansible_ssh_private_key_file
     в
     inventory.ini
     .

4. Создайте

   .env
   и
   credentials.json
   в корне проекта (будут скопированы на сервер).

5. Запустите деплой:

Playbook выполнит:

• Установку Docker на сервере.
• Синхронизацию исходников проекта в
  /opt/finance-tracker-bot
  .
• Сборку образа
  finance-tracker-bot:latest
  .
• Запуск контейнера с автоперезапуском и использованием
  .env
  .

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

1. Убедитесь, что ваш Telegram-username присутствует в
   TELEGRAM_ALLOWED_USERNAMES
   .
2. Откройте диалог с ботом и отправьте команду
   /start
   (или
   /help
   ).
3. На экране появится клавиатура с двумя кнопками: Расход и Доход.
4. Выберите нужное действие и следуйте пошаговым инструкциям:

Добавление расхода

1. После нажатия Расход бот спросит дату:
   • Сегодня – текущая дата будет выбрана автоматически.
   • Другая дата – откроется интерактивный календарь, где можно выбрать день.
2. Бот предложит список категорий расходов – выберите нужную кнопку.
3. Введите сумму (целое или дробное число, разделители:
   .
   или
   ,
   ).
4. Укажите описание или нажмите кнопку Без описания для пропуска.
5. Получите подтверждение «Расход успешно добавлен 🎉» и вернитесь в главное меню.

Добавление дохода

1. После нажатия Доход бот также спросит дату (аналогично шагу 1 для расхода).
2. Выберите категорию из предложенного списка доходов.
3. Введите сумму дохода.
4. Укажите описание или нажмите кнопку Без описания.
5. Получите подтверждение «Доход успешно добавлен 🎉» и вернитесь в главное меню.

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

/cancel

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

Лицензия

Apache 2.0