Telegram-gifts-autobuy

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #llm #go #android #machine-learning #linux #docker #kubernetes #pytorch #security #open-source

Telegram-gifts-autobuy

(★ 14)

No description available.

Telegram-gifts-autobuy Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GiftBuyer

Веб-панель и бот для **мониторинга и автопокупки Telegram-подарков** на базе **Flask + SQLAlchemy + Pyrogram** (backend) и **React + Vite** (frontend).
Поддерживается работа с несколькими аккаунтами, просмотр баланса звёзд, список доступных подарков с предпросмотром **.tgs (Lottie)**, хранилище каналов с фильтрами (по цене и supply), отправка уведомлений в каналы/ЛС и **автопокупка лимитных подарков на нужные каналы**.

---

## Ключевые возможности

*  Регистрация/логин (httpOnly cookie, 7 дней).
*  Несколько **API-профилей** (api\_id/api\_hash) и **несколько Telegram-аккаунтов** на пользователя.
*  Просмотр Premium, **баланс звёзд**, принудительное обновление данных аккаунтов со стримом стадий (NDJSON).
*  **Подарки (Gifts)**: список, ручное/фоновое обновление, SSE-стрим, предпросмотр .tgs (серверный кэш).
*  **Каналы**: добавление по `channel_id` (формат `-100…`), проверка членства, хранение названия и фильтров **цена/supply**, CRUD.
*  **Автопокупка** лимитных подарков на каналы по заданным фильтрам, с отчётами в ЛС и подробными причинами, если не купилось.
*  **Уведомления** о новых подарках в указанные каналы/ЛС (со стикером и кратким текстом).
*  Бэкграунд-воркер подарков, устойчивый к падениям и переподключениям, с «горячим» перечитыванием аккаунтов.
---

## Как работает автопокупка (кратко про алгоритм)

Файл: `backend/services/autobuy_service.py`

1. **Сбор входных данных**

* Берём **все аккаунты** пользователя и узнаём их **баланс звёзд**.
   * Берём **все каналы** пользователя и их фильтры:

* диапазон `price_min..price_max`;
     * диапазон `supply_min..supply_max` (если `null` — без ограничения).
   * Берём **новые подарки**, пришедшие от воркера.
     ⚠ В боевом режиме покупаем **только лимитные** (`is_limited=True`). Нелимитные сразу скипаем с причиной.

2. **Фильтрация и приоритезация подарков**

* Отсекаем мусор (некорректные `id/price/supply`).
   * Сортируем лимитки по ключу: **меньше supply → дороже → случайность(если одинаковая цена и supply)**.

3. **Планирование («план покупок»)**
   Для **каждого аккаунта** (в порядке убывания баланса) распределяем покупки:

* Для конкретного подарка ищется **подходящий канал** (по фильтрам цены/supply).
   * Рассчитывается максимально возможное количество отправок с учётом **остатка баланса** аккаунта и **доступности** подарка.
   * В план добавляются операции: `(account_id, channel_id, gift_id, price, supply)`.
   * Если на этапе планирования что-то не сошлось (нет подходящих каналов, не хватило звёзд и т.п.), это фиксируется в `plan_skips`.

4. **Исполнение плана**

* Идём по плану и на каждой операции вызываем:

```
     await tg_client.send_gift(chat_id=<ID канала>, gift_id=<ID подарка>)
     ```
   * Успех/неуспех детально логируются в статистике **по каналам** и **по аккаунтам**.

5. **Отчёты**

* Формируется отчёт: общая сводка, по подаркам, по каналам и по аккаунтам.
   * Отчёт уходит в **лс всех ваших аккаунтов** (через ваш Bot Token из «Настроек»).

6. **Параллельно** воркер шлёт **уведомления** о новых подарках в каналы/ЛС.
   В `gifts_service` покупка и уведомления запускаются одновременно (`asyncio.gather`), покупка **не блокирует** уведомления.

## Требования

* **Python** 3.13+
* **Node** 18+ / npm 9+
* Рабочий **api\_id/api\_hash** (my.telegram.org → API development tools)
* Ваш **Bot Token** (BotFather), чтобы слать .tgs-превью и отчёты в ЛС
* Чаты, куда бот имеет право писать (если хотите уведомления в каналы)

---

## Установка и запуск (локально)

### Backend

```bash
cd backend
python -m venv .venv
# Windows:
.\.venv\Scripts\activate
# macOS/Linux:
# source .venv/bin/activate

pip install -r requirements.txt

# запуск dev-сервера (Flask)
python -m backend.app     # http://localhost:5000
```

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

Создайте файл `.env` в корне проекта (рядом с `backend/` и `frontend/`). Все настройки автоматически загружаются из переменных окружения.

### Базовые настройки

* `SECRET_KEY` — секретный ключ Flask (обязательно в продакшене!)
* `DATABASE_URL` — строка подключения к БД (по умолчанию `sqlite:///app.db`)
* `DATABASE_POOL_SIZE` — размер пула подключений (по умолчанию `10`)
* `DATABASE_MAX_OVERFLOW` — максимальное переполнение пула (по умолчанию `5`)
* `DATABASE_POOL_TIMEOUT` — таймаут пула в секундах (по умолчанию `30.0`)

### Настройки подарков и кэша

* `GIFTS_DIR` — каталог с данными подарков (по умолчанию `gifts_data`)
* `GIFTS_CACHE_DIR` — кэш .tgs файлов (по умолчанию `backend/instance/gifts_cache`)
* `GIFTS_ACCS_TTL` — период обновления аккаунтов воркером в секундах (по умолчанию `60`)

### Настройки безопасности

* `COOKIE_SECURE` — использовать Secure флаг для cookies (по умолчанию `false`, в продакшене `true`)
* `COOKIE_SAMESITE` — SameSite политика для cookies (по умолчанию `Strict`)
* `ALLOWED_ORIGINS` — разрешенные домены для CORS через запятую (по умолчанию `*`)
* `ENABLE_CSRF` — включить CSRF защиту (по умолчанию `false`, в продакшене `true`)
* `ENABLE_RATE_LIMIT` — включить rate limiting (по умолчанию `true`)
* `RL_LIMIT` — лимит запросов на окно (по умолчанию `10`)
* `RL_WINDOW` — окно rate limiting в секундах (по умолчанию `60`)
* `ENABLE_HSTS` — включить HSTS заголовок (по умолчанию `false`, только для HTTPS)

### Настройки устойчивости

* `RESILIENCE_TIMEOUT` — таймаут внешних запросов (по умолчанию `15.0`)
* `RESILIENCE_RETRIES` — количество повторов (по умолчанию `3`)
* `RESILIENCE_BACKOFF_BASE` — базовая задержка для экспоненциального backoff (по умолчанию `0.5`)
* `RESILIENCE_BACKOFF_CAP` — максимальная задержка (по умолчанию `8.0`)
* `RESILIENCE_CIRCUIT_THRESHOLD` — порог срабатывания circuit breaker (по умолчанию `5`)
* `RESILIENCE_CIRCUIT_RESET` — время сброса circuit breaker в секундах (по умолчанию `60.0`)

### Настройки наблюдаемости

* `METRICS_ENABLED` — включить Prometheus метрики (по умолчанию `true`)
* `TRACING_ENABLED` — включить трейсинг (по умолчанию `false`)
* `SERVICE_NAME` — имя сервиса для метрик (по умолчанию `giftbuyer-backend`)

### Настройки очереди

* `QUEUE_MAX_SIZE` — максимальный размер очереди (по умолчанию `1000`)
* `QUEUE_VISIBILITY_TIMEOUT` — таймаут видимости сообщений в очереди (по умолчанию `30.0`)

### Настройки кэша

* `CACHE_TTL` — время жизни кэша в секундах (по умолчанию `3600`)

## Примеры конфигурации

### Для разработки (.env)

```bash
# Базовые настройки
SECRET_KEY=dev-secret-key-change-in-production
DATABASE_URL=sqlite:///app.db

# Безопасность (мягкие настройки для разработки)
COOKIE_SECURE=false
COOKIE_SAMESITE=Lax
ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
ENABLE_CSRF=false
ENABLE_HSTS=false

# Rate limiting (можно отключить для удобства)
ENABLE_RATE_LIMIT=false
```

### Для продакшена (.env)

```bash
# Базовые настройки
SECRET_KEY=your-super-secret-key-generated-by-secrets-token-urlsafe-32
DATABASE_URL=postgresql://user:password@localhost:5432/giftbuyer

# Безопасность (строгие настройки)
COOKIE_SECURE=true
COOKIE_SAMESITE=Strict
ALLOWED_ORIGINS=https://your-frontend.com,https://www.your-frontend.com
ENABLE_CSRF=true
ENABLE_HSTS=true

# Rate limiting
ENABLE_RATE_LIMIT=true
RL_LIMIT=10
RL_WINDOW=60
```

### Для Docker (.env)

```bash
# База данных в контейнере
DATABASE_URL=postgresql://giftbuyer:password@postgres:5432/giftbuyer

# CORS для контейнерной среды
ALLOWED_ORIGINS=https://your-domain.com

# Остальные настройки как в продакшене
COOKIE_SECURE=true
ENABLE_CSRF=true
ENABLE_HSTS=true
```

### Создание .env файла

1. Скопируйте `env.example` в `.env`:
   ```bash
   cp env.example .env
   ```

2. Отредактируйте `.env` под свои нужды

3. Сгенерируйте SECRET_KEY:
   ```bash
   python -c "import secrets; print(secrets.token_urlsafe(32))"
   ```

### Frontend

```bash
cd frontend
npm i
npm run dev     # http://localhost:5173
```

При необходимости настройте прокси `/api` → `http://localhost:5000` во `vite.config.js`.

#### Архитектура фронтенда

* Вся клиентская логика разложена по слоям FSD: `src/app` (провайдеры и инфраструктура), `src/pages` (маршруты), `src/features` (интерактивные блоки), `src/entities` (типизированные модели и адаптеры), `src/shared` (UI-примитивы, библиотеки, API-клиент).
* Типы DTO ↔ ViewModel конвертируются в `src/shared/api/adapters`, что позволяет изолировать компоненты от форматов REST-ответов.
* Управление UI-состоянием реализовано на **Zustand** — состояние небольшое (тема, глобальный лоадер), Redux Toolkit показался избыточным, а Zustand остаётся прозрачно типизированным и не требует громоздкой обвязки.
* Формы собираются на React Hook Form + Zod (см. `LoginForm` и модальные окна каналов/API). Валидация на уровне схем облегчает поддержку контрактов.
* CSP и безопасность: `index.html` и `vite.config.ts` задают строгую политику `default-src 'self'`, `connect-src` ограничен API, fetch-обёртка добавляет `X-CSRF-Token` и экранирует ответы, глобальный `ErrorBoundary` и перехват 401-х защищают UI.
* Темизация: дизайн-токены вынесены в `src/app/styles/tokens.css`, есть хук `useTheme` и кнопка переключения темы в сайдбаре.

#### Полезные команды

```bash
npm run lint        # ESLint (TS + React правила)
npm run test        # Vitest + снапшоты сторей
npm run storybook   # Storybook с базовыми историями для UI-примитивов
npm run build       # Проверка типов + production-сборка Vite
```

Перед коммитом husky запускает `lint-staged`, форматируя и линтя только изменённые файлы. Storybook снапшоты лежат в `src/shared/ui/*/*.stories.test.tsx`.

### Здоровье и наблюдаемость

* `/healthz` — базовая проверка живости процесса.
* `/readyz` — проверяет подключение к БД.
* `/metrics` — Prometheus-метрики (`giftbuyer_request_latency_seconds`, `giftbuyer_requests_total`, `giftbuyer_workers`).

### Миграции и безопасный перенос данных

* Первичное создание схемы выполняет `python -m backend.migrate_app_db` или `python -m backend.scripts.migrate_data app.db --migration 0001_initial.sql`.
* `backend/scripts/migrate_data.py` перед применением SQL-файла создаёт резервную копию `<имя>.bak` рядом с БД.
* Для отката достаточно остановить приложение, заменить рабочий файл БД на `.bak` и повторить миграцию после фикса ошибки.
* Миграции атомарны (`BEGIN/COMMIT`), индексы (`idx_channels_user_id`, `idx_channels_channel_id`) ускоряют выборки фильтров.

### Метрики, трейсинг и примеры дашбордов

* Метрики Prometheus включаются переменной `METRICS_ENABLED`. Базовый набор:
  * `giftbuyer_request_latency_seconds` (Histogram) — латентность HTTP. Пример запроса: `histogram_quantile(0.95, sum(rate(giftbuyer_request_latency_seconds_bucket[5m])) by (le))`.
  * `giftbuyer_requests_total{endpoint="api.gifts"}` — частота обращений к конечным точкам.
  * `giftbuyer_workers` — текущее число фоновых воркеров.
* Рекомендуемый Grafana-дэшборд:
  * Панель «P95 HTTP latency» с формулой выше и единицами «milliseconds».
  * Панель «Request rate by endpoint» c `sum(rate(giftbuyer_requests_total[1m])) by (endpoint)`.
  * Панель «Active workers» c `giftbuyer_workers` (stat / gauge).
* Трейсинг можно подключить через OpenTelemetry, установив `TRACING_ENABLED=1` и интегрировав собственный OTLP экспортёр (точка расширения — `backend/infrastructure/observability.py`).

### Конфигурация и секреты

* Все параметры читаются из переменных окружения и валидируются Pydantic-моделью (`backend/config.py`).
* Секреты (токены, ключи) рекомендуется передавать через секрет-менеджер (Docker Secrets, Vault) и экспортировать в окружение процесса.
* При запуске директории `GIFTS_DIR` и `GIFTS_CACHE_DIR` создаются автоматически.

### Точки отказа и устойчивость

* Внешние запросы Telegram обёрнуты в `resilient_call` с таймаутом, экспоненциальным бэкоффом и circuit breaker (см. `backend/infrastructure/resilience.py`). При достижении порога отказов запросы блокируются до истечения `RESILIENCE_CIRCUIT_RESET`.
* Очередь уведомлений использует `ResilientQueue` с visibility timeout, позволяющим повторно ставить сообщения при сбоях воркера (`backend/infrastructure/queue.py`).
* Доступ к БД через UoW (`backend/infrastructure/unit_of_work.py`) гарантирует rollback при исключениях.
* Health/ready-пробы автоматически отлавливают недоступность БД и позволяют оркестратору перезапустить контейнер.

### Производительность и нагрузочные проверки

* Синтетический тест автопокупки (100 аккаунтов, 200 подарков) выполняется скриптом: `python -m backend.tests.synth_bench_autobuy` (см. примеры в разделе тестов).
* На эталонной машине (2 vCPU, 4 ГБ RAM) полный цикл планирования + отправки отчёта занял ~0.84 с, при этом средняя скорость обработки составила ~238 операций/с (см. раздел «Testing» ниже).

## Автопокупка — правила и приоритеты

* Покупаем **только лимитные** подарки (`is_limited=True`). Нелимитные фиксируются как «пропущены» с причиной.
* Для каждого подарка подбирается **лучший канал** среди подходящих по фильтрам `price` и `supply`:

* Если `supply_min/max` у канала `null` — без ограничения.
  * Чем **уже** «окно» по supply и чем **выше** `price_max`, тем **выше приоритет** канала.
* План распределяется **по всем аккаунтам** (сортируются по убыванию баланса):

* На каждый аккаунт ставится столько покупок, сколько позволяет **баланс** и **доступность** подарка.
* Отправка происходит именно **в канал**: `send_gift(chat_id=<ID канала>, gift_id=...)`.
* Подробные причины, почему не купили:

* `no_channel_match` — не нашлось каналов, где и `price`, и `supply` укладываются в фильтры.
  * `not_enough_stars` / `insufficient_account_balance` — не хватило звёзд.
  * `send_gift_failed` — сам вызов `send_gift` провалился (нет прав писать в канал, не член канала, gift больше недоступен, требуются Premium, и т.п.).
  * `invalid/price/supply` — подарок не прошёл базовую валидацию.
* В ЛС уходит **отчёт** с эмодзи: сводка, по подаркам (что и куда купили, либо почему пропущено), по каналам и по аккаунтам.

## Настройки и важные поля

* **User.gifts\_autorefresh** — вкл/выкл автопокупку.
* **UserSettings.bot\_token** — используется для отправки .tgs-стикеров и текстов в каналы/ЛС (уведомления и отчёты).
* **Channel**:

* `channel_id` вида `-100…` (обязательно).
  * `price_min` / `price_max` — в звёздах.
  * `supply_min` / `supply_max` — общее издание (если `null`, ограничения нет).
* **Account**:

* привязан к API-профилю;
  * в UI виден баланс звёзд; баланс запрашивается при планировании.

---

## Отчёты и логи

* В **консоли**: подробно логируется план/исполнение, причины ошибок по каналам/аккаунтам, глобальные пропуски.
* В **ЛС (всем вашим аккаунтам)**:

```
🧾 Отчёт автопокупки
📊 Новых: 3 | Куплено: 2 | Пропущено: 1

📦 По подаркам:
• ✅ 123456 | 25⭐ | supply=1000 → ch=-100111 acc=1337
• ⏭️ 654321 | 50⭐ | supply=∞ → non-limited (skipped)
• ❌ 222333 | 10⭐ | supply=500 → причина ch=-100222: insufficient_account_balance acc=1338 bal=5 need=10

🛰️ По каналам:
• -100111: plan=1 ok=1 fail=0 reasons=0
• -100222: plan=1 ok=0 fail=0 reasons=1

👤 По аккаунтам:
• acc=1337: plan=1 💰spent=25 start=100 end=75 buys=1
• acc=1338: plan=1 💰spent=0 start=5 end=5 buys=0
```

---

## Частые проблемы и решения

* **`send_gift_failed`**
  Проверьте:

* аккаунт **состоит** в канале;
  * у бота есть право писать (для уведомлений), и **аккаунт** имеет право отправлять gift;
  * gift уже не закончился/не изменился;
  * gift **не требует Premium**, если у аккаунта его нет;
  * баланс достаточен.

* **Нет покупок, «no\_channel\_match»**
  Подарок не попал в рамки ни одного канала. Проверьте `price_min/max` и `supply_min/max`.

* **Ничего не видно в «Подарках»**
  Нажмите ручное обновление или дождитесь воркера. Проверьте токен бота (для предпросмотра .tgs).

* **Windows продакшен**
  Gunicorn недоступен. Используйте `waitress-serve` или разворачивайте на Linux-сервере.

## Лицензия

---

Telegram-gifts-autobuy

Telegram-gifts-autobuy Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Telegram-gifts-autobuy

Telegram-gifts-autobuy Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README