{"id":24490238,"url":"https://github.com/ivanoskov/financial_bot","last_synced_at":"2025-08-12T05:07:34.197Z","repository":{"id":273243183,"uuid":"918864149","full_name":"ivanoskov/financial_bot","owner":"ivanoskov","description":"Бот для учета финансов на Go и Serverless","archived":false,"fork":false,"pushed_at":"2025-03-07T16:08:19.000Z","size":23836,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-02T01:36:56.769Z","etag":null,"topics":["aws-lambda","bot","finance","golang","serverless","yandex-cloud"],"latest_commit_sha":null,"homepage":"https://t.me/cash_spending_bot","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivanoskov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-19T04:02:26.000Z","updated_at":"2025-03-07T16:08:23.000Z","dependencies_parsed_at":"2025-07-02T01:43:25.758Z","dependency_job_id":null,"html_url":"https://github.com/ivanoskov/financial_bot","commit_stats":null,"previous_names":["ivanoskov/financial_bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ivanoskov/financial_bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanoskov%2Ffinancial_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanoskov%2Ffinancial_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanoskov%2Ffinancial_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanoskov%2Ffinancial_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivanoskov","download_url":"https://codeload.github.com/ivanoskov/financial_bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanoskov%2Ffinancial_bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270005591,"owners_count":24510939,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-lambda","bot","finance","golang","serverless","yandex-cloud"],"created_at":"2025-01-21T17:17:29.153Z","updated_at":"2025-08-12T05:07:34.174Z","avatar_url":"https://github.com/ivanoskov.png","language":"Go","readme":"# Telegram-бот для учета личных финансов, написанный на Go\n\nПроект демонстрирует практическое применение чистой архитектуры, работу с Telegram Bot API и визуализацию данных. Разработан с целью тестирования использования Golang в serverless архитектуре.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/screencast.gif\" alt=\"screencast\" style=\"width: 50wh;\"\u003e\n\u003c/div\u003e\n\n## Режимы работы\n\nБот поддерживает два режима работы:\n\n### 1. Long Polling Mode\n\nКлассический режим работы через long polling:\n```bash\ngo build cmd/bot/main.go\n./main\n```\n\n### 2. Serverless Mode (AWS Lambda)\n\nБот может работать в serverless режиме через AWS Lambda или аналогичные сервисы:\n\n- `cmd/function/WebhookHandler` - обработка входящих сообщений через webhook\n- `cmd/function/DailyReportHandler` - отправка ежедневных отчетов (триггер по расписанию)\n\n#### Настройка Webhook\n\n1. Разверните функцию в AWS Lambda\n2. Создайте API Gateway endpoint\n3. Настройте webhook в Telegram:\n```bash\ncurl -X POST https://api.telegram.org/bot\u003cYOUR_BOT_TOKEN\u003e/setWebhook \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"url\": \"https://your-api-gateway-url/prod/webhook\"}'\n```\n\n### Настройка логирования с BetterStack\n\nБот поддерживает отправку логов в сервис BetterStack:\n\n1. Создайте аккаунт на [BetterStack](https://betterstack.com/)\n2. Получите токен и эндпоинт для отправки логов\n3. Настройте переменные окружения в файле `.env`:\n   ```\n   BETTERSTACK_TOKEN=your_token\n   BETTERSTACK_ENDPOINT=your_endpoint\n   BETTERSTACK_ENABLED=true\n   ```\n4. При запуске бота логи автоматически будут отправляться в BetterStack\n\nПри отсутствии настроек BetterStack или при установке `BETTERSTACK_ENABLED=false`, логи будут выводиться только в консоль.\n\n### Настройка триггера напоминаний в Yandex Cloud\n\nДля настройки автоматических напоминаний пользователям:\n\n1. Создайте триггер \"Timer\" в Yandex Cloud\n2. Настройте расписание (например, ежедневно в 21:00)\n3. Выберите функцию WebhookHandler в качестве целевой\n4. Укажите следующий JSON-параметр:\n   ```json\n   {\"notification_trigger\": true}\n   ```\n5. Сохраните триггер\n\nФункция будет вызываться в заданное время и отправлять напоминания всем пользователям, у которых включены уведомления.\n\n## Архитектура\n\nПроект построен с использованием принципов чистой архитектуры:\n\n```\n.\n├── cmd/\n│   ├── bot/              # Точка входа для long polling режима\n│   └── function/         # AWS Lambda handlers\n├── internal/\n│   ├── bot/             # Telegram бот и обработка команд\n│   ├── model/           # Доменные модели\n│   ├── repository/      # Работа с данными (Supabase)\n│   ├── service/         # Бизнес-логика\n│   ├── charts/          # Генерация графиков\n│   ├── logger/          # Работа с логами\n│   └── config/          # Конфигурация\n└── migrations/          # Миграции бд\n```\n\n### Технические решения\n\n#### 1. Управление состоянием\n\n- Паттерн конечного автомата для управления диалогами\n- In-memory хранение состояний пользователей\n- Автоматический сброс состояния после завершения операций\n\n#### 2. Работа с данными\n\n- **База данных**: Supabase (PostgreSQL)\n- **Схема данных**:\n  ```sql\n  -- Категории доходов/расходов\n  CREATE TABLE categories (\n      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n      user_id BIGINT NOT NULL,\n      name TEXT NOT NULL,\n      type TEXT NOT NULL,\n      created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n  );\n\n  -- Финансовые операции\n  CREATE TABLE transactions (\n      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n      user_id BIGINT NOT NULL,\n      category_id UUID REFERENCES categories(id),\n      amount DECIMAL NOT NULL,\n      description TEXT,\n      date TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n      created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n  );\n  ```\n\n#### 3. Логирование\n\n- Интеграция с BetterStack для централизованного сбора логов\n- Структурированное логирование с использованием `slog`\n- Отслеживание ошибок в реальном времени\n\n#### 4. Визуализация данных\n\nИспользует библиотеку `go-chart` для генерации графиков:\n\n- **Типы графиков**:\n  - Линейные графики (динамика доходов/расходов)\n  - Круговые диаграммы (распределение по категориям)\n  - Столбчатые диаграммы (сравнение периодов)\n\n- **Оптимизации**:\n  - Предварительная фильтрация данных\n  - Адаптивные размеры для Telegram\n  - Группировка малых категорий\n  - Оптимизированные форматы изображений\n\n#### 5. Аналитика и отчеты\n\n- **Типы отчетов**:\n  ```go\n  type ReportType int\n\n  const (\n      DailyReport ReportType = iota\n      WeeklyReport\n      MonthlyReport\n      YearlyReport\n  )\n  ```\n\n- **Метрики**:\n  - Основные показатели (доходы, расходы, баланс)\n  - Сравнение с предыдущими периодами\n  - Тренды и изменения\n  - Статистика по категориям\n\n#### 6. Обработка ошибок\n\n- Многоуровневая валидация\n- Контекстные ошибки\n- Информативные сообщения пользователю\n- Логирование для отладки\n\n### Используемые библиотеки\n\n- `github.com/go-telegram-bot-api/telegram-bot-api/v5` - Telegram Bot API\n- `github.com/supabase-community/supabase-go` - Работа с Supabase\n- `github.com/go-redis/redis/v8` - Работа с Redis\n- `github.com/samber/slog-betterstack` - Интеграция с BetterStack для логирования\n\n### Особенности и оригинальные решения\n\n1. **Умная агрегация данных**\n   - Автоматическое определение периодов\n   - Расчет трендов и изменений\n   - Выявление значимых изменений\n\n2. **Оптимизация графиков**\n   - Предварительная фильтрация данных\n   - Адаптивные размеры\n   - Оптимизированные форматы для Telegram\n\n3. **UX-решения**\n   - Информативные сообщения об ошибках\n   - Поддержка частичного ввода (транзакции без описания)\n\n4. **Масштабируемость**\n   - Чистая архитектура\n   - Независимые модули\n   - Легкое добавление новых типов отчетов и графиков\n\n## Развертывание\n\n### 1. Подготовка Supabase\n\n```sql\nCREATE TABLE categories (\n    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n    user_id BIGINT NOT NULL,\n    name TEXT NOT NULL,\n    type TEXT NOT NULL,\n    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n);\n\nCREATE TABLE transactions (\n    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),\n    user_id BIGINT NOT NULL,\n    category_id UUID REFERENCES categories(id),\n    amount DECIMAL NOT NULL,\n    description TEXT,\n    date TIMESTAMP WITH TIME ZONE DEFAULT NOW(),\n    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n);\n\nCREATE TABLE IF NOT EXISTS user_states (\n    user_id BIGINT PRIMARY KEY,\n    selected_category_id TEXT,\n    transaction_type TEXT,\n    awaiting_action TEXT,\n    notifications BOOLEAN DEFAULT TRUE,\n    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()\n);\n```\n\n### 2. Настройка окружения\n\n```bash\n# Основные настройки\nTELEGRAM_TOKEN=\"your_telegram_bot_token\"\nSUPABASE_URL=\"your_supabase_url\"\nSUPABASE_KEY=\"your_supabase_key\"\nREDIS_URL=\"your_redis_url\"\n\n# Настройки логирования\nBETTERSTACK_TOKEN=\"your_betterstack_token\"\nBETTERSTACK_ENDPOINT=\"your_betterstack_endpoint\"\nBETTERSTACK_ENABLED=true\n```\n\n### 3. Запуск\n\n#### Long Polling Mode\n```bash\ngo build cmd/bot/main.go\n./main\n```\n\n#### Serverless Mode\n1. Создайте ZIP для AWS Lambda:\n```bash\nzip function.zip bootstrap\n```\n\n2. Загрузите ZIP в AWS Lambda и настройте триггеры:\n   - API Gateway для webhook\n   - EventBridge для ежедневных отчетов\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanoskov%2Ffinancial_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivanoskov%2Ffinancial_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanoskov%2Ffinancial_bot/lists"}