# GlitchUp Bot

Telegram-бот для GlitchTip, который:

- принимает webhook-алерты и отправляет их в Telegram;
- фильтрует окружения, делает dedup, mute по regex и мягкий rate limit;
- синхронизирует unresolved issues из GlitchTip API в локальный cache;
- строит digest, release summary и проектные сводки;
- поддерживает runtime-настройку ownership без рестарта через Telegram-команды;
- запускается локально через `uv` и в Docker через `docker compose`.

## Что сделано

В проекте уже реализовано:

- `POST /webhooks/glitchtip` для Slack-compatible payload из GlitchTip;
- Telegram polling с командами для просмотра сводок, релизов, sync-статуса и runtime-настроек;
- регулярный API sync в `issues_cache`;
- обновление `sync_state` для `api_sync` и `webhook`;
- release tracking через digest и команды `/releases`, `/release`;
- mute rules по regex с хранением в БД;
- rate limit для `P2`-алертов, при этом `P1` не режется;
- ownership overrides для project/topic/subscribers без рестарта;
- PostgreSQL + Alembic миграции;
- Docker-first запуск с авто-`alembic upgrade head`.

## Быстрый старт

### 1. Подготовить `.env`

Скопировать шаблон:

```bash
cp .env.example .env
```

Заполнить минимум:

```env
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_GROUP_CHAT_ID=-1001234567890
GLITCHTIP_URL=https://glitchtip.example.com
GLITCHTIP_API_TOKEN=your-token
GLITCHTIP_ORG_SLUG=your-org
DATABASE_URL=postgresql+asyncpg://glitchup:glitchup@db:5432/glitchup
```

Если хочешь ограничить админ-команды, укажи:

```env
TELEGRAM_ADMIN_IDS=123456789,987654321
```

Если список пустой, команды изменения конфигурации будут доступны всем.

### 2. Локальный запуск через `uv`

```bash
uv sync --dev
uv run alembic upgrade head
uv run glitchup-bot
```

Полезные команды разработки:

```bash
uv run pytest
uv run ruff check
uv run ruff format --check
uv run python -m glitchup_bot
```

### 3. Запуск через Docker

```bash
docker compose up --build
```

Что произойдёт:

- поднимется PostgreSQL;
- контейнер приложения выполнит `alembic upgrade head`;
- затем стартуют FastAPI, Telegram polling и scheduler.

Webhook endpoint:

```text
http://<host>:8080/webhooks/glitchtip
```

Healthcheck:

```text
http://<host>:8080/health
```

## Как пользоваться ботом

### Главное изменение интерфейса

Теперь ботом можно пользоваться не только командами, но и через inline-кнопки в Telegram:

- `/help` открывает экран поддержки и быстрых действий;
- `/admin` открывает админ-панель с основными управляющими действиями;
- для частых сценариев больше не нужно помнить все команды вручную.

### Обычный сценарий

1. Добавить бота в Telegram-группу.
2. Включить forum/topics режим в группе.
3. Создать топики:
   backend alerts, frontend alerts, digest.
4. Узнать их `topic_id` и записать в `.env`.
5. Добавить webhook в GlitchTip на `POST /webhooks/glitchtip`.
6. При необходимости задать `WEBHOOK_SECRET` и тот же заголовок в GlitchTip.
7. После запуска бот начнёт:
   - слать `P1/P2` алерты в Telegram;
   - синхронизировать issues из API;
   - строить digest и отвечать на команды.
8. Открой `/help`, чтобы пользоваться ботом через кнопки.

### Что делает бот в работе

- `P1`:
  критичный production alert, отправляется сразу.
- `P2`:
  production alert без критического цвета, отправляется сразу, но может быть ограничен rate limit.
- `P3`:
  не шлётся realtime, остаётся в sync/digest-данных.
- Uptime alert:
  идёт как `P1`.

### Основные команды

- `/help` — экран помощи, поддержки и быстрых кнопок.
- `/week` — digest за неделю.
- `/today` — новые issues за сегодня.
- `/project <slug>` — сводка по одному проекту.
- `/top` — самые шумные unresolved issues.
- `/stale` — самые старые unresolved issues.
- `/releases` — список релизов с незакрытыми issues.
- `/release <version>` — детали по конкретному релизу.
- `/sync_status` — время последней синхронизации.
- `/subscribe <backend|frontend>` — добавить себе runtime DM-подписку.
- `/unsubscribe <backend|frontend>` — убрать свою runtime DM-подписку.

### Админ-команды

- `/admin` — кнопочная админ-панель.
- `/sync` — принудительный sync cache.
- `/ownership` — показать текущие overrides.
- `/owner <slug> <backend|frontend>` — привязать проект к группе.
- `/owner_reset <slug>` — удалить runtime override проекта.
- `/topic <backend|frontend|digest> <topic_id>` — переопределить topic.
- `/topic_reset <backend|frontend|digest>` — снять topic override.
- `/mute_add <regex>` — добавить regex mute rule.
- `/mute_list` — показать mute rules.
- `/mute_del <id>` — удалить mute rule.

## Конфигурация

Основные переменные окружения:

```env
TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_GROUP_CHAT_ID=-1001234567890
TELEGRAM_ADMIN_IDS=123456789

TELEGRAM_BACKEND_TOPIC_ID=1
TELEGRAM_FRONTEND_TOPIC_ID=2
TELEGRAM_DIGEST_TOPIC_ID=3

BACKEND_PROJECTS=backend-production,backend-staging
FRONTEND_PROJECTS=frontend-production,frontend-staging

BACKEND_SUBSCRIBERS=123456789,987654321
FRONTEND_SUBSCRIBERS=

GLITCHTIP_URL=https://glitchtip.example.com
GLITCHTIP_API_TOKEN=your-token
GLITCHTIP_ORG_SLUG=your-org

DATABASE_URL=postgresql+asyncpg://glitchup:glitchup@db:5432/glitchup

API_PORT=8080
WEBHOOK_SECRET=

DIGEST_CRON_DAY=mon
DIGEST_CRON_HOUR=10
DIGEST_CRON_MINUTE=0
DIGEST_TIMEZONE=Asia/Krasnoyarsk
SYNC_INTERVAL_MINUTES=30

ALERT_ENVIRONMENTS=production
DEDUP_WINDOW_HOURS=6
ALERT_RATE_LIMIT_COUNT=10
ALERT_RATE_LIMIT_WINDOW_MINUTES=15
```

## Как это работает

### Webhook-контур

Для обычных issue-alert:

1. проверяется `X-Webhook-Secret`, если задан `WEBHOOK_SECRET`;
2. из attachment извлекается `Project`;
3. алерт фильтруется по `ALERT_ENVIRONMENTS`;
4. применяется dedup по fingerprint `project:title`;
5. `production + #e52b50` считается `P1`, остальное в production идёт как `P2`;
6. перед отправкой применяются mute rules;
7. для `P2` применяется rate limit по группе;
8. результат записывается в `notifications_sent`.

Для uptime-alert:

- сразу отправляется как `P1`;
- идёт в Telegram без обычного issue dedup.

### API sync

Sync:

- ходит в GlitchTip по всем проектам из конфигурации;
- upsert-ит unresolved issues в `issues_cache`;
- помечает пропавшие из unresolved issues как `resolved`;
- сохраняет release, regressions, event count, culprit и ссылки;
- обновляет `sync_state` для `api_sync`.

### Release tracking

- digest показывает блок "После релизов";
- `/releases` агрегирует issues по release;
- `/release <version>` показывает детали по одному релизу.

## Таблицы

Основные:

- `issues_cache` — кэш unresolved/resolved issues из API;
- `notifications_sent` — история alert/digest/uptime и статусы отправки;
- `sync_state` — состояние `api_sync` и `webhook`.

Runtime-настройки:

- `project_ownership_overrides` — project → group overrides;
- `group_topic_overrides` — topic overrides;
- `group_subscriber_overrides` — runtime subscriber overrides;
- `mute_rules` — regex mute rules.

## Тесты

```bash
uv run pytest
```

Покрыты базовые сценарии для:

- настроек;
- webhook endpoint;
- alert processor;
- digest builder;
- Telegram sender.

## Идеи и недоделки

Сейчас бот уже рабочий, но в этот блок вынесены идеи для следующих итераций:

- полноценный wizard-интерфейс в Telegram для изменения параметров без ручного ввода команд;
- отдельные команды для управления env-based подписчиками, а не только runtime overrides;
- более умный rate limit с burst/recovery-политикой и отдельной статистикой suppress-событий;
- mute rules с scope по проекту или группе, а не только глобальные regex;
- richer release analytics: сравнение "до/после релиза", отдельные regression-отчёты;
- отдельная admin-аутентификация вместо режима "если `TELEGRAM_ADMIN_IDS` пустой, можно всем";
- export/backup runtime-настроек ownership и mute rules;
- e2e-тесты с реальной БД и контейнерным прогоном;
- дополнительные команды для ручной диагностики sync и очередей уведомлений.