chore: remove outdated monitoring documentation files

- Deleted FIX_PROMLEMS.md and MONITORING_AUTH.md as they contained obsolete information regarding Prometheus and Alertmanager configurations. - This cleanup helps streamline the documentation and focuses on current setup practices.
2026-01-25 19:02:46 +03:00
parent 34b0345983
commit 8e595bf7f2
4 changed files with 533 additions and 219 deletions
--- a/.cursor/rules/my-custom-rule.mdc
+++ b/.cursor/rules/my-custom-rule.mdc
@@ -0,0 +1,409 @@
+---
+name: prod-project-rules
+description: Правила работы с проектом prod - инфраструктура, боты, CI/CD
+---
+
+# Правила работы с проектом prod
+
+## 📋 Обзор проекта
+
+**prod** — проект для управления Telegram ботами и мониторинга инфраструктуры в продакшене.
+
+### Основные компоненты:
+- **Инфраструктура мониторинга**: Prometheus, Grafana, Alertmanager, Uptime Kuma
+- **Telegram боты**: telegram-helper-bot, AnonBot (в отдельных поддиректориях)
+- **CI/CD**: GitHub Actions с автоматическим тестированием, созданием PR и деплоем
+- **Контейнеризация**: Docker Compose для оркестрации сервисов
+
+---
+
+## 🌿 Работа с ветками и Git
+
+### Структура веток:
+- **`main`** — продакшен ветка, защищена, только через PR
+- **`develop`** — ветка разработки (опционально)
+- **`dev-*`** — ветки для разработки (например, `dev-4`)
+- **`feature/**`** — ветки для новых фич
+
+### Workflow разработки:
+
+1. **Создание ветки для разработки:**
+   ```bash
+   git checkout -b dev-4  # или feature/my-feature
+   ```
+
+2. **Перед коммитом - проверка качества кода:**
+   ```bash
+   make code-quality  # Проверяет форматирование, импорты, линтинг
+   # Или автоматически исправить:
+   make format        # Исправить форматирование
+   make import-fix    # Исправить сортировку импортов
+   ```
+
+3. **Коммит и пуш:**
+   ```bash
+   git add .
+   git commit -m "feat: описание изменений"
+   git push -u origin dev-4
+   ```
+
+4. **Автоматические действия после push:**
+   - ✅ Запускаются тесты (Black, isort, flake8, pytest)
+   - ✅ При успешных тестах автоматически создается/обновляется PR в `main`
+   - ✅ Отправляется уведомление в Telegram
+
+5. **После мержа PR в `main`:**
+   - ✅ Автоматически запускается деплой в продакшен (`deploy.yml`)
+   - ✅ Проверяются токены ботов
+   - ✅ Выполняется деплой на сервер
+   - ✅ Запускаются health checks и smoke tests
+   - ✅ При падении smoke tests — автоматический rollback
+
+---
+
+## 🎨 Стандарты кода
+
+### Форматирование (Black):
+- **Обязательно**: Все Python файлы должны быть отформатированы через Black
+- **Проверка**: `make format-check` или `black --check .`
+- **Исправление**: `make format` или `black .`
+- **Правила**:
+  - Двойные кавычки `"` вместо одинарных `'`
+  - 2 пустые строки между импортами и определениями функций/классов
+  - Автоматический перенос длинных строк
+
+### Сортировка импортов (isort):
+- **Обязательно**: Импорты должны быть отсортированы
+- **Проверка**: `make import-check` или `isort --check-only .`
+- **Исправление**: `make import-fix` или `isort .`
+- **Порядок**: стандартная библиотека → сторонние → локальные
+
+### Линтинг (flake8):
+- **Критические ошибки** (E9, F63, F7, F82) — блокируют пайплайн
+- **Предупреждения** (F821, F822, F824) — игнорируются в CI
+- **Проверка**: `make lint-check`
+- **Исключения**: `.venv`, `venv`, `__pycache__`, `.git`
+
+### Перед коммитом:
+```bash
+make code-quality  # Проверяет всё сразу
+```
+
+---
+
+## 🧪 Тестирование
+
+### Структура тестов:
+- **`tests/`** — тесты инфраструктуры проекта
+- **`bots/*/tests/`** — тесты ботов (в их репозиториях)
+
+### Запуск тестов:
+```bash
+make test              # Все тесты
+make test-infra        # Только тесты инфраструктуры
+make test-coverage     # С отчетом о покрытии
+make test-clean        # Очистить кэш и отчеты
+```
+
+### Конфигурация pytest:
+- Файл: `pytest.ini` в корне проекта
+- Автоматическое обнаружение тестов в `tests/`
+- Маркеры: `slow`, `integration`, `unit`
+- Asyncio режим: автоматический
+
+### Правила написания тестов:
+- Используй описательные имена: `test_prometheus_config_is_valid`
+- Группируй связанные тесты в классы
+- Используй фикстуры для общих setup/teardown
+- Тесты должны быть независимыми и идемпотентными
+
+---
+
+## 🐳 Docker и контейнеризация
+
+### Структура:
+- **`docker-compose.yml`** — основной файл оркестрации
+- **`Dockerfile`** — базовый образ (если нужен)
+- **`bots/*/Dockerfile`** — Dockerfile для каждого бота
+
+### Сервисы в docker-compose:
+- `prometheus` — сбор метрик (порт 9090)
+- `grafana` — дашборды (порт 3000)
+- `alertmanager` — управление алертами (порт 9093)
+- `uptime-kuma` — мониторинг доступности (порт 3001)
+- `telegram-bot` — Telegram Helper Bot (порт 8080)
+- `anon-bot` — AnonBot (порт 8081)
+
+### Команды:
+```bash
+make build            # Собрать все контейнеры
+make up               # Запустить все сервисы
+make down             # Остановить все сервисы
+make restart          # Перезапустить все сервисы
+make logs             # Логи всех сервисов
+make logs-bot         # Логи Telegram бота
+```
+
+### Важные правила:
+- **Токены ботов**: Используются из GitHub Secrets через переменные окружения
+- **Формат**: `TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-${BOT_TOKEN}}` (Secrets имеют приоритет)
+- **Build**: Используй `docker-compose build --pull` (не `--no-cache`) для оптимизации
+- **Graceful shutdown**: `docker-compose down -t 30` для корректного завершения
+
+---
+
+## 🔐 Безопасность и секреты
+
+### GitHub Secrets (обязательные):
+- `TELEGRAM_BOT_TOKEN` — токен Telegram Helper Bot
+- `TELEGRAM_TEST_BOT_TOKEN` — токен тестового бота (опционально)
+- `ANON_BOT_TOKEN` — токен AnonBot
+- `SSH_PRIVATE_KEY` — приватный ключ для SSH доступа к серверу
+- `SERVER_HOST`, `SERVER_USER`, `SSH_PORT` — данные сервера
+- `TELEGRAM_CHAT_ID` — ID чата для уведомлений
+
+### Локальная разработка:
+- Используй `.env` файлы для локальных переменных
+- `.env` файлы в `.gitignore` — никогда не коммить!
+- Токены из Secrets имеют приоритет над `.env` в продакшене
+
+### Правила:
+- ❌ **НЕ коммить** токены, пароли, секреты
+- ❌ **НЕ коммить** `.env` файлы
+- ✅ Используй `env.template` как шаблон
+- ✅ Все секреты храни в GitHub Secrets
+
+---
+
+## 🚀 CI/CD Pipeline
+
+### Два основных workflow:
+
+#### 1. `pipeline.yml` (CI):
+- **Триггер**: Push в `main`, `develop`, `dev-*`, `feature/**`
+- **Jobs**:
+  - `test` — проверка качества кода и тесты
+  - `create-pr` — автоматическое создание/обновление PR (только для `dev-*` и `feature/**`)
+  - `rollback` — ручной откат через `workflow_dispatch`
+
+#### 2. `deploy.yml` (CD):
+- **Триггер**: Мерж PR в `main`
+- **Jobs**:
+  - `deploy` — деплой на сервер
+  - `smoke-tests` — проверка работоспособности ботов
+  - `auto-rollback` — автоматический откат при падении smoke tests
+
+### Правила работы с пайплайном:
+
+1. **Перед push** — всегда запускай `make code-quality` локально
+2. **После успешных тестов** — PR создастся/обновится автоматически
+3. **После мержа PR** — деплой запустится автоматически
+4. **При проблемах** — используй manual rollback через Actions → Run workflow
+
+---
+
+## 📁 Структура проекта
+
+```
+prod/
+├── .github/workflows/     # CI/CD пайплайны
+│   ├── pipeline.yml       # CI: тесты, создание PR
+│   └── deploy.yml         # CD: деплой, smoke tests, rollback
+├── bots/                  # Директория для ботов (submodules)
+│   ├── telegram-helper-bot/  # Telegram Helper Bot
+│   └── AnonBot/              # AnonBot
+├── infra/                 # Инфраструктура
+│   ├── prometheus/        # Конфигурация Prometheus
+│   ├── grafana/          # Дашборды и provisioning Grafana
+│   ├── alertmanager/      # Конфигурация Alertmanager
+│   ├── nginx/            # Nginx конфигурация
+│   └── ansible/          # Ansible playbooks
+├── scripts/              # Скрипты развертывания
+├── tests/                # Тесты инфраструктуры
+│   └── infra/           # Тесты инфраструктуры
+├── docker-compose.yml    # Docker Compose конфигурация
+├── Makefile             # Команды для управления проектом
+├── pytest.ini           # Конфигурация pytest
+└── README.md            # Документация проекта
+```
+
+### Важные файлы:
+- **`docker-compose.yml`** — основная конфигурация сервисов
+- **`Makefile`** — команды для разработки и управления
+- **`pytest.ini`** — конфигурация тестов
+- **`.gitignore`** — исключает `.env`, `.venv`, логи, кэш
+
+---
+
+## 🔧 Разработка
+
+### Локальная настройка:
+
+1. **Клонирование и настройка:**
+   ```bash
+   git clone <repo>
+   cd prod
+   cp env.template .env
+   # Отредактируй .env с локальными значениями
+   ```
+
+2. **Установка зависимостей:**
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   pip install black isort flake8 pytest
+   ```
+
+3. **Проверка перед коммитом:**
+   ```bash
+   make code-quality
+   ```
+
+### Работа с ботами:
+
+- Боты находятся в `bots/` как отдельные репозитории (submodules или клоны)
+- Каждый бот имеет свой Dockerfile
+- Токены ботов передаются через environment variables в docker-compose
+
+---
+
+## 📝 Коммиты и PR
+
+### Формат коммитов:
+Используй понятные сообщения:
+```
+feat: добавлена функция X
+fix: исправлена ошибка Y
+chore: обновлены зависимости
+docs: обновлена документация
+refactor: рефакторинг модуля Z
+```
+
+### Pull Request:
+- **Автоматическое создание**: Для веток `dev-*` и `feature/**` после успешных тестов
+- **Обновление**: PR автоматически обновляется при новых коммитах в той же ветке
+- **Мерж**: После мержа в `main` запускается автоматический деплой
+
+---
+
+## 🚨 Деплой и Rollback
+
+### Автоматический деплой:
+1. Мерж PR в `main` → запуск `deploy.yml`
+2. Валидация токенов ботов
+3. Деплой на сервер (SSH)
+4. Пересборка контейнеров с `--pull`
+5. Health checks с экспоненциальным retry
+6. Smoke tests (отправка сообщений в Telegram)
+7. При успехе — обновление истории деплоев
+
+### Автоматический rollback:
+- Срабатывает при падении smoke tests
+- Откатывается к последнему успешному коммиту из истории
+- Пересобираются контейнеры
+- Проверяются health checks
+
+### Ручной rollback:
+- Actions → CI & CD pipeline → Run workflow
+- Выбери `rollback` и опционально укажи commit hash
+- Если commit не указан — используется последний успешный деплой
+
+---
+
+## 🛠️ Полезные команды Makefile
+
+### Качество кода:
+```bash
+make code-quality    # Все проверки (Black, isort, flake8)
+make format         # Автоисправление форматирования
+make import-fix     # Автоисправление импортов
+make format-diff    # Показать что будет изменено
+```
+
+### Docker:
+```bash
+make build          # Собрать контейнеры
+make up             # Запустить сервисы
+make down           # Остановить сервисы
+make restart        # Перезапустить
+make logs           # Логи всех сервисов
+make logs-bot       # Логи бота
+```
+
+### Тестирование:
+```bash
+make test           # Все тесты
+make test-infra     # Тесты инфраструктуры
+make test-coverage  # С покрытием
+make test-clean     # Очистить кэш
+```
+
+### Мониторинг:
+```bash
+make monitoring     # Открыть Grafana
+make prometheus     # Открыть Prometheus
+make status         # Статус контейнеров
+make health         # Health checks
+```
+
+---
+
+## ⚠️ Важные замечания
+
+### НЕ делай:
+- ❌ Коммить `.env` файлы с секретами
+- ❌ Коммить токены ботов в код
+- ❌ Использовать `docker-compose build --no-cache` без необходимости
+- ❌ Пуш в `main` напрямую (только через PR)
+- ❌ Игнорировать ошибки форматирования перед коммитом
+
+### Всегда делай:
+- ✅ Запускай `make code-quality` перед коммитом
+- ✅ Используй ветки `dev-*` или `feature/**` для разработки
+- ✅ Проверяй, что тесты проходят локально
+- ✅ Используй GitHub Secrets для токенов в продакшене
+- ✅ Проверяй логи после деплоя
+
+---
+
+## 📚 Дополнительные ресурсы
+
+- **README.md** — основная документация проекта
+- **`.cursor/rules/release-notes-template.md`** — шаблон для Release Notes
+- **`pytest.ini`** — конфигурация тестов
+- **`Makefile`** — все доступные команды (`make help`)
+
+---
+
+## 🔄 Workflow схема
+
+```
+1. Создание ветки (dev-* или feature/**)
+   ↓
+2. Разработка + локальные тесты (make code-quality)
+   ↓
+3. Git commit + push
+   ↓
+4. GitHub Actions: автоматические тесты
+   ↓
+5. При успехе: автоматическое создание/обновление PR
+   ↓
+6. Ручной review и мерж PR в main
+   ↓
+7. GitHub Actions: автоматический деплой
+   ↓
+8. Health checks + Smoke tests
+   ↓
+9. При успехе: ✅ Деплой завершен
+   При падении: 🔄 Автоматический rollback
+```
+
+---
+
+## 💡 Советы
+
+1. **Используй Makefile** — все команды там, не запоминай длинные команды
+2. **Проверяй локально** — запускай `make code-quality` перед каждым коммитом
+3. **Следи за уведомлениями** — Telegram уведомления показывают статус деплоя
+4. **Используй правильные ветки** — `dev-*` для автоматического создания PR
+5. **Читай логи** — при проблемах смотри логи в GitHub Actions и на сервере