# Инструкция по деплою на продакшен

## Общая информация

**⚠️ ВАЖНО:** Креды для доступа к серверу (SSH хост, порт, пользователь) предоставляются пользователем в запросе и НЕ должны сохраняться в этой документации!

**Технологический стек:**
- Python: 3.11.9
- Docker: Alpine Linux
- База данных: SQLite

**Директория проекта на сервере:** `/home/prod/bots/telegram-helper-bot`  
**Директория для команд инфраструктуры:** `/home/prod`  
**База данных:** `/home/prod/bots/telegram-helper-bot/database/tg-bot-database.db`

---

## Этап 1: Подготовка на локальной машине

### 1.1. Проверка состояния репозитория

```bash
git status
git log --oneline -10
git diff master...HEAD --stat
```

### 1.2. Пуш ветки в репозиторий

```bash
git push -u origin <branch-name>
```

### 1.3. Создание Release Notes

**ВАЖНО:** Release notes создаются ПОСЛЕ пуша, чтобы не попали в репозиторий!

1. Использовать шаблон из `.cursor/rules/release-notes-template.md`
2. Создать файл `RELEASE_NOTES_DEV-XX.md` в корне проекта
3. Собрать информацию о коммитах:
   ```bash
   git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse
   ```
4. Заполнить release notes по шаблону:
   - Обзор (количество коммитов и основные направления)
   - Ключевые изменения (каждый значимый коммит)
   - Основные достижения (чекбоксы с эмодзи ✅)
   - Временная шкала разработки

**Примечание:** Release notes используются для Pull Request, затем файл удаляется из рабочей директории.

### 1.4. Создание дополнительной документации (если требуется)

**ВАЖНО:** Документацию создавать ПОСЛЕ пуша, чтобы она не попала в репозиторий!

1. Создать или обновить инструкции по деплою
2. Обновить необходимую техническую документацию
3. Убедиться, что не добавляются файлы с секретами

---

## Этап 2: Деплой на сервер (тестовая ветка)

**ВАЖНО:** Креды для подключения к серверу должны быть предоставлены пользователем в запросе.

### 2.1. Подключение к серверу и остановка инфраструктуры

```bash
# Подключиться к серверу через SSH
# Перейти в директорию для команд инфраструктуры
cd /home/prod
make down
```

**Проверка:** Убедиться, что все контейнеры остановлены.

### 2.2. Создание бэкапа базы данных

```bash
cd /home/prod/bots/telegram-helper-bot/database
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db
ls -lh tg-bot-database*.db
```

**ВАЖНО:** Всегда создавать бэкап с timestamp перед применением миграций!

### 2.3. Переключение на ветку и подтягивание изменений

```bash
cd /home/prod/bots/telegram-helper-bot
git fetch origin
git checkout <branch-name>
git pull origin <branch-name>
```

### 2.4. Установка зависимостей (если изменились)

#### Если виртуальное окружение уже существует:

```bash
cd /home/prod/bots/telegram-helper-bot
.venv/bin/pip install -r requirements.txt
```

#### Если виртуального окружения нет:

```bash
cd /home/prod/bots/telegram-helper-bot
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt
```

**Примечание:** Виртуальное окружение `.venv` на сервере используется только для применения миграций и утилит. Бот работает в Docker-контейнере.

### 2.5. Применение миграций базы данных

```bash
cd /home/prod/bots/telegram-helper-bot
.venv/bin/python scripts/apply_migrations.py
```

**ВАЖНО:**
- Миграции применяются **ПЕРЕД** запуском контейнеров
- База должна быть "спящей" (контейнеры выключены)
- Проверить вывод скрипта на наличие ошибок

**Вывод при успехе:**
```
📋 Найдено новых миграций: X
✅ Все миграции применены успешно (X шт.)
```

### 2.6. Запуск инфраструктуры

```bash
cd /home/prod
make up
```

### 2.7. Пересборка контейнера telegram-bot

Используем команду с гарантией применения изменений:

```bash
cd /home/prod
docker-compose up -d --build --force-recreate --no-deps telegram-bot
```

**Что делает команда:**
- `--build` - пересобирает образ
- `--force-recreate` - принудительно пересоздает контейнер
- `--no-deps` - не затрагивает зависимые сервисы
- Гарантирует доставку нового кода в контейнер без кэша

### 2.8. Проверка работоспособности

```bash
# Проверка статуса всех контейнеров
docker-compose ps

# Проверка логов telegram-bot
docker-compose logs telegram-bot --tail=50

# Или напрямую
docker logs bots_telegram_bot --tail=50
```

**Что проверять в логах:**
- ✅ База данных инициализирована
- ✅ Scoring Manager инициализирован (если используется)
- ✅ Metrics server запущен на порту 8080
- ✅ Нет критических ошибок
- ✅ Бот обрабатывает команды

**На этом этапе:** Ждать подтверждения от владельца о мердже ветки в master.

---

## Этап 3: Финальный деплой на master

**ВАЖНО:** Выполняется только после подтверждения мерджа ветки в master!

### 3.1. Остановка инфраструктуры

```bash
cd /home/prod
make down
```

### 3.2. Переключение на master и получение изменений

```bash
cd /home/prod/bots/telegram-helper-bot
git checkout master
git pull origin master
```

**Проверка:** Убедиться, что получен коммит с мерджем.

### 3.3. Запуск инфраструктуры

```bash
cd /home/prod
make up
```

### 3.4. Пересборка контейнера telegram-bot с кодом master

```bash
cd /home/prod
docker-compose up -d --build --force-recreate --no-deps telegram-bot
```

### 3.5. Финальная проверка

```bash
# Статус контейнеров
docker-compose ps

# Логи
docker logs bots_telegram_bot --tail=50
```

**Проверить:**
- ✅ Все контейнеры в состоянии `Up` и `healthy`
- ✅ Логи не содержат критических ошибок
- ✅ Бот отвечает на команды в Telegram

### 3.6. Завершение работы

- Выйти с сервера
- Забыть все креды доступа (не сохранять их)

---

## Troubleshooting

### Проблема: Миграции не применяются

**Решение:**
1. Проверить, что контейнеры остановлены
2. Проверить права доступа к файлу БД
3. Посмотреть логи скрипта apply_migrations.py
4. Восстановить БД из бэкапа при необходимости:
   ```bash
   cd /home/prod/bots/telegram-helper-bot/database
   cp tg-bot-database_YYYYMMDD_HHMMSS.db tg-bot-database.db
   ```

### Проблема: Контейнер не запускается

**Решение:**
1. Проверить логи контейнера:
   ```bash
   docker logs bots_telegram_bot --tail=100
   ```
2. Проверить переменные окружения в `.env`
3. Проверить healthcheck:
   ```bash
   docker inspect bots_telegram_bot | grep -A 20 Health
   ```

### Проблема: Код не обновился в контейнере

**Решение:**
Использовать принудительную пересборку без кэша:
```bash
docker-compose down telegram-bot
docker-compose build --no-cache telegram-bot
docker-compose up -d telegram-bot
```

### Проблема: Нет виртуального окружения

**Решение:**
Создать виртуальное окружение:
```bash
# Установить python3-venv (если нужно)
sudo apt install -y python3.11-venv

# Создать venv
cd /home/prod/bots/telegram-helper-bot
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt
```

---

## Последовательность действий для агента

### Этап 1: Локальная подготовка

1. Проверить состояние репозитория (`git status`, `git log`)
2. Запушить ветку в репозиторий
3. Создать Release Notes по шаблону - **ПОСЛЕ пуша!**
4. Создать дополнительную документацию (если требуется) - **ПОСЛЕ пуша!**
5. Сообщить пользователю о готовности к деплою

### Этап 2: Деплой на dev-ветку

1. Подключиться к серверу (креды из запроса пользователя)
2. Остановить инфраструктуру (`make down` из `/home/prod`)
3. Создать бэкап БД с timestamp
4. Переключиться на dev-ветку и подтянуть изменения
5. Установить/обновить зависимости Python (если требуется)
6. Применить миграции БД (через `.venv/bin/python scripts/apply_migrations.py`)
7. Проверить успешность применения миграций
8. Запустить инфраструктуру (`make up`)
9. Пересобрать контейнер telegram-bot с `--build --force-recreate --no-deps`
10. Проверить статус контейнеров и логи
11. Сообщить пользователю о готовности и ждать подтверждения "ОК"

### Этап 3: Финальный деплой на master

**Выполняется только после получения "ОК" от пользователя (означает мердж в master)**

1. Остановить инфраструктуру
2. Переключиться на master и подтянуть изменения
3. Запустить инфраструктуру
4. Пересобрать контейнер telegram-bot с `--build --force-recreate --no-deps`
5. Проверить финальный статус и логи
6. Сообщить о успешном завершении деплоя
7. Завершить SSH-сессию и забыть все креды

---

## Важные команды

### Docker

```bash
# Просмотр всех контейнеров
docker-compose ps

# Логи конкретного сервиса
docker-compose logs <service-name> --tail=N

# Перезапуск конкретного сервиса
docker-compose restart <service-name>

# Остановка всей инфраструктуры
docker-compose down

# Запуск всей инфраструктуры
docker-compose up -d

# Пересборка без кэша
docker-compose build --no-cache <service-name>

# Принудительное пересоздание контейнера
docker-compose up -d --build --force-recreate --no-deps <service-name>
```

### Git

```bash
# Проверка состояния
git status
git branch

# Переключение веток
git checkout <branch-name>

# Получение изменений
git fetch origin
git pull origin <branch-name>

# История коммитов
git log --oneline -N
git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse
```

### Работа с БД

```bash
# Создание бэкапа с timestamp
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db

# Просмотр бэкапов
ls -lh tg-bot-database*.db

# Восстановление из бэкапа
cp tg-bot-database_BACKUP.db tg-bot-database.db
```

---

## Примечания

1. **Виртуальное окружение на сервере** - используется только для запуска утилит и миграций. Бот работает в Docker-контейнере.

2. **Бэкапы БД** - создаются перед каждым применением миграций с timestamp в имени файла.

3. **Пересборка контейнера** - всегда использовать `--force-recreate --no-deps` для гарантии применения изменений.

4. **Миграции** - применяются только при остановленных контейнерах к "спящей" базе данных.

5. **Release notes** - создаются ПОСЛЕ пуша, чтобы не попадали в репозиторий. Используются для Pull Request, затем удаляются из рабочей директории.

6. **Документация после пуша** - вся документация и инструкции создаются ПОСЛЕ пуша в репозиторий, чтобы не попадали в коммиты и удалённый репозиторий.

7. **Креды доступа** - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды.

---

## Контакты

При возникновении проблем или вопросов обращаться к владельцу проекта.