v1.8.2: AGENTS.md, consent revocation, delete bot users, dialogues fix, intent improvements, CI for max_bot
This commit is contained in:
@@ -0,0 +1,225 @@
|
||||
# Правила проекта 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)
|
||||
- Следуй существующему стилю кода
|
||||
- Удаляй неиспользуемый код при изменениях
|
||||
- Не добавляй лишних зависимостей без необходимости
|
||||
Reference in New Issue
Block a user