---
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 и на сервере