site_aegisone/AGENTS.md

# Правила проекта AegisOne

> Любой AI-агент ОБЯЗАН прочитать этот файл перед началом работы.

---

## 0. Базовые правила

0.1. **Если что-то не знаешь — спроси!** Не додумывай, не предполагай.
0.2. **Любое общение только на русском языке.** Код, комментарии, коммиты, CHANGELOG — всё по-русски.
0.3. **Если предлагаешь варианты — обязательно указывай рекомендацию и пояснение.**

---

## 1. Архитектура проекта

| Часть | Домен | Стек | Статус |
|-------|-------|------|--------|
| Публичная | aegisone.ru | PHP | ✅ ГОТОВА — НЕ ТРОГАТЬ! |
| Сервисная | service.aegisone.ru | Python/FastAPI | В разработке |
| Бот | max.aegisone.ru | Python/FastAPI | В разработке |

**ВАЖНО:** Публичная часть полностью готова и не подлежит изменениям!

---

## 2. Версионирование

- **Формат:** Semantic Versioning (major.minor.patch)
  - `major` — ломающие изменения API/БД
  - `minor` — новый функционал
  - `patch` — исправления багов, косметические правки
- **Единый CHANGELOG:** `py_service/CHANGELOG.md`
- **version.txt:** `py_service/version.txt` и `max_bot/version.txt` — текущая версия
- **Агент ОБЯЗАН** обновить version.txt и CHANGELOG.md перед каждым деплоем

### Формат CHANGELOG

```markdown
## X.Y.Z (ДД.ММ.ГГГГ)
### Новые функции
- **Описание:** что сделано
### Исправления
- **Код (описание):** что исправлено
```

### Формат коммитов

```
vX.Y.Z: краткое описание изменений
```

Пример: `v1.8.2: fix consent flow — split-based word matching, revoke consent`

---

## 3. Workflow (порядок работы)

1. Получаешь задачу
2. Анализируешь код → предлагаешь варианты с рекомендацией и пояснением
3. Пользователь одобряет
4. Пишешь/переписываешь код **с комментариями**
5. Удаляешь мусор из кода
6. Запускаешь тесты локально
7. Обновляешь version.txt и CHANGELOG.md
8. Коммитишь
9. Деплоишь на сервер
10. Проверяешь логи

- **Ветвление:** всё в main (без feature-веток)
- **Локальная копия** = git clone. Правки сначала локально, потом деплой.
- **Не портить** то что есть. Если сомневаешься — спроси.

---

## 4. Комментарии в коде (ОБЯЗАТЕЛЬНО)

Любой человек или AI-агент должны сразу понимать что за часть кода и для чего.

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

1. **Каждый файл** имеет шапку с описанием назначения файла
2. **Каждая функция** имеет docstring:
   ```python
   async def handle_consent_yes(user_id: int, conv_id: int) -> None:
       """Обработка согласия пользователя на обработку ПД.
       
       Устанавливает consent_given=True, consent_date=now(),
       переводит диалог в состояние awaiting_contact.
       """
   ```
3. **Каждый неочевидный блок** имеет комментарий:
   ```python
   # Проверяем, не истёк ли таймаут диалога (10 минут)
   if conv.created_at and conv.created_at < stale_threshold:
       conv = BotConversation(...)  # Создаём новый диалог
   ```
4. **Импорты** группируются и комментируются при необходимости
5. **Комментарии на русском языке**

### Что НЕ комментировать:

- Очевидный код (`if user: user.name = name`)
- Геттеры/сеттеры
- Стандартные паттерны (`async with session() as db:`)

---

## 5. Тесты

- Тесты **ОБЯЗАНЫ пройти** перед деплоем
- **Основное тестирование:** локально (`pytest`)
- **CI** (GitHub Actions): страховка при пуше в main

### Как запускать тесты:

```bash
# py_service
cd py_service && pytest -v --tb=short -x

# max_bot
cd max_bot && pytest -v --tb=short -x

# Линтер
ruff check py_service/
```

- Если тестов нет для нового функционала — **пишем**
- Минимальный тест: проверка что код не падает с ошибкой

---

## 6. Миграции БД

- SQL-файлы в `migrations/` (формат: `001_description.sql`)
- Таблица `_applied_migrations` для отслеживания
- **Автоприменение** при старте приложения
- Пользователь **НЕ лазает на сервер** вручную

### Backup:

- Делать pg_dump **только при рисках** сломать данные
- Не засорять сервер старыми бэкапами и логами
- При низком риске — мигрируем без бэкапа

---

## 7. Безопасность

1. **Секреты только в .env** — никогда в коде, коммитах, логах
2. **Валидация входящих данных** — любые данные проверяются перед использованием
3. **Защита от SQL-инъекций** — SQL через ORM, никогда через конкатенацию строк
4. **Безопасность логов** — логи НЕ содержат пароли, токены, персональные данные

---

## 8. Обработка ошибок

```python
try:
    # операция
except Exception as e:
    logger.exception(f"Описание ошибки: {e}")
    # Пользователю — понятное сообщение, НЕ стектрейс
```

- **try/except** с логированием + пользовательское сообщение
- **Никогда** не показывать стектрейс пользователю
- **logger.exception** для исключений (автоматически добавляет стектрейс в лог)
- **logger.error** для ошибок бизнес-логики

---

## 9. Деплой

### Сервер: angel@81.177.141.34

### Контейнеры:

| Контейнер | Назначение | Порт |
|-----------|-----------|------|
| `max_bot` | Бот | 8002 |
| `aegisone-app` | Сервисный портал | 8000 |
| `aegisone-postgres` | PostgreSQL | 5432 |

### Порядок деплоя:

```bash
# 1. scp файлов на сервер
scp file.py angel@81.177.141.34:/home/angel/deploy/

# 2. docker cp в контейнер
# ВАЖНО: max_bot — путь /app/app/, НЕ /app/!
docker cp /home/angel/deploy/file.py max_bot:/app/app/file.py
docker cp /home/angel/deploy/file.py aegisone-app:/app/app/file.py

# 3. Очистка __pycache__
docker exec max_bot rm -rf /app/app/handlers/__pycache__ /app/app/__pycache__

# 4. Перезапуск
docker restart max_bot
docker restart aegisone-app

# 5. Проверка
docker ps
docker logs max_bot --tail 10
docker logs aegisone-app --tail 10
```

### Кодировка:

- Все файлы **UTF-8**
- `scp` / `docker cp` сохраняют кодировку
- **НЕ** использовать `sed` / `echo` для изменения файлов в контейнере

---

## 10. Код

- **ruff** — линтер для Python (запускать перед коммитом)
- **UTF-8** — кодировка всех файлов
- **Комментарии** — ОБЯЗАТЕЛЬНЫ (см. раздел 4)
- Следуй существующему стилю кода
- Удаляй неиспользуемый код при изменениях
- Не добавляй лишних зависимостей без необходимости