expense-bot

Telegram-бот для учёта расходов. Записывает траты в Google Таблицу, показывает отчёты, остаток бюджета, ведёт накопления и квартальные цели, а раз в 3 дня присылает финансовый анализ от ИИ. Валюта — таджикский сомони (с.).

Возможности

• Быстрый ввод: напиши 350 или 350 такси — бот сразу предложит выбрать категорию
• 14 категорий расходов с месячными лимитами
• Запись прихода: 5000 зарплата
• Отчёт за месяц с разбивкой по категориям и процентом исполнения лимита
• Баланс: сколько осталось и сколько можно тратить в день (с учётом переноса с прошлых месяцев)
• 🏦 Накопления: пополнение и снятие, отдельный лист в таблице
• 🎯 Квартальные цели: название, целевая сумма, квартал, статус
• 🤖 ИИ-отчёт: анализ финансов от Gemini — по кнопке и автоматически каждые 3 дня (файлом .md)
• Многопользовательский режим: у каждого пользователя свои листы в таблице
• Авторизация по Telegram ID (опционально)

Структура таблицы

Все листы создаются автоматически. Каждый пользователь получает свой набор листов:

Лист	Колонки	Назначение
<Telegram ID>	Дата | Время | Категория | Сумма | Описание | Месяц	Основной журнал: расходы (отрицательная сумма) и приход (положительная, категория «Приход»)
<Telegram ID>_savings	Дата | Время | Сумма | Описание | Месяц	Накопления: пополнения (+) и снятия (−)
<Telegram ID>_goals	Название | Целевая сумма (с.) | Квартал | Статус | Описание	Квартальные цели
Пользователи	UserID | Имя | Username | Дата регистрации	Реестр пользователей (заполняется при /start)

Пример строки основного листа:

Дата	Время	Категория	Сумма	Описание	Месяц
18.03.2026	14:32	Еда	-350	обед	2026-03

Категории

Категория	Лимит (с./мес.)
🍽 Еда/Продукты	2 000
🏠 Аренда/ЖКХ	300
🚗 Транспорт	1 000
👗 Одежда	1 000
💊 Здоровье	500
📱 Связь	200
🎭 Развлечения	500
💰 Накопления	5 000
📚 Обучение	200
🎒 Обучение детей	3 000
💄 На себя	1 000
💼 Бизнес	300
🔧 Другое	500
🤷 Не знаю на что потратила	450

Лимиты и список категорий задаются в internal/category/category.go.

Настройка

1. Telegram Bot

1. Создай бота через @BotFather → получи BOT_TOKEN

2. Google Sheets

1. Создай Service Account в Google Cloud
2. Включи Google Sheets API в проекте
3. Скачай JSON-ключ сервисного аккаунта (credentials.json)
4. Создай новую Google Таблицу и дай сервисному аккаунту доступ Редактор
5. Скопируй ID таблицы из URL: https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/

3. Gemini API (опционально, для ИИ-отчётов)

1. Получи ключ в Google AI Studio → GEMINI_API_KEY

Без ключа бот работает полностью, кроме кнопки «🤖 ИИ-отчёт» и автоматических отчётов.

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

Переменная	Обязательная	Описание
BOT_TOKEN	да	Токен бота от @BotFather
SPREADSHEET_ID	да	ID Google Таблицы
GOOGLE_CREDENTIALS_JSON	да (прод)	Содержимое credentials.json одной строкой
GEMINI_API_KEY	нет	Ключ Gemini для ИИ-отчётов
SALARY	нет	Зарплата в сомони (по умолчанию: 16000)
ALLOWED_USER_IDS	нет	Telegram ID через запятую — кто может пользоваться ботом
PORT	нет	Порт health-check сервера (по умолчанию: 8080)

Запуск локально

# Установи зависимости
go mod tidy

# Создай config.json в корне проекта
cat > config.json <<EOF
{
  "bot_token": "...",
  "spreadsheet_id": "...",
  "salary": 16000,
  "gemini_api_key": "..."
}
EOF

# Положи credentials.json в корень проекта

# Запуск
go run ./cmd/bot

Или через переменные окружения:

export BOT_TOKEN=...
export SPREADSHEET_ID=...
export GOOGLE_CREDENTIALS_JSON=$(cat credentials.json)
export GEMINI_API_KEY=...
go run ./cmd/bot

Деплой на Render

1. Запушь репозиторий на GitHub
2. В Render: New → Blueprint → выбери репозиторий
3. В настройках сервиса добавь секретные переменные окружения:
   • BOT_TOKEN
   • SPREADSHEET_ID
   • GOOGLE_CREDENTIALS_JSON
   • GEMINI_API_KEY (опционально)

Регион: Frankfurt (ближайший к ЦА). Бот сам пингует свой /health каждые 45 секунд, чтобы бесплатный инстанс не засыпал.

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

cmd/bot/main.go               # точка входа: конфиг + sheets + бот + advisor + health-сервер
internal/
  config/config.go            # загрузка конфига из env или файла
  category/category.go        # 14 категорий с лимитами
  sheets/client.go            # Google Sheets: расходы, накопления, цели, пользователи
  advisor/advisor.go          # ИИ-советник (Gemini): анализ раз в 3 дня и по кнопке
  bot/
    bot.go                    # инициализация и polling loop
    handler.go                # маршрутизация сообщений и колбэков
    state.go                  # диалоговые состояния (sync.Mutex)
    keyboard.go               # клавиатуры
    formatter.go              # форматирование отчётов

Стек

• Go 1.26
• Telegram: github.com/go-telegram-bot-api/telegram-bot-api/v5
• Google Sheets: google.golang.org/api/sheets/v4
• ИИ: Google Gemini 2.5 Flash (REST API)
• Deploy: Render (Web Service, Docker)