mostovik-backend/.qoder/rules/main.md

trigger

trigger
always_on

0) Язык и стиль общения (СТРОГО)

• ИИ-агент ВСЕГДА отвечает на русском языке
• Английский допускается ТОЛЬКО для:
  • имён библиотек
  • имён классов, функций, переменных
  • CLI-команд
• Тон: инженерный, практичный, без воды и маркетинга

---

1) Базовые принципы (НЕ ОБСУЖДАЮТСЯ)

Проект разрабатывается строго по принципам:

• SOLID
• KISS
• DRY

Правила приоритета:

• красиво vs просто → простота
• умно vs поддерживаемо → поддерживаемость
• магия vs явность → явность

---

2) Контекст проекта

• ОС: Astra Linux 1.8
• Python: 3.11.2
• Django: 3.x (указано 3.14)
• Django REST Framework (DRF)
• Celery
• PostgreSQL 15.10
• Apache 2.4.57
• mod_wsgi 4.9.4

Инструменты разработки

• uv
• виртуальная среда
• pre-commit
• Gitea Actions (CI)
• Тесты: django test
• Линтинг: ruff
• ЗАПРЕЩЕНО создавать тестовые скрипты для демонстрации, все должно быть исправлено в рамках проекта

---

3) Окружение и команды (СТРОГО)

Все команды:

• выполняются только внутри виртуальной среды
• используют uv
• считаются выполняемыми из корня проекта

❌ Запрещено

• pip, python -m pip
• poetry, pipenv, pipx
• системные команды вне venv

✅ Разрешено

• uv venv
• source .venv/bin/activate
• uv add / uv remove / uv sync
• uv run <command>

Пример:

uv run python manage.py test

---

4) Архитектура и слои ответственности (КРИТИЧНО)

4.1 View (DRF)

View отвечает ТОЛЬКО за:

• приём HTTP-запроса
• проверку прав доступа
• работу с serializer
• вызов сервисного слоя

❌ Запрещено:

• бизнес-логика
• сложные условия
• транзакции
• сложная работа с ORM

---

4.2 Serializer

Serializer отвечает за:

• валидацию данных
• преобразование вход/выход

Допускается:

• field-level validation
• object-level validation

❌ Запрещено:

• бизнес-правила
• side-effects
• сложная логика в save()

---

4.3 Сервисный слой (Business Logic)

• ВСЯ бизнес-логика живёт здесь
• Сервисы:
  • не зависят от HTTP
  • легко тестируются
  • управляют транзакциями
• Сервис определяет что делать, а не как отдать ответ

Рекомендуемый паттерн:

class EntityService:
    @classmethod
    def do_something(cls, *, data):
        ...

---

4.4 Модели (ORM)

Модели должны быть:

• простыми
• декларативными

Допускается:

• __str__
• простые computed properties
• минимальные helper-методы

❌ Запрещено:

• бизнес-логика
• workflow
• сигналы как логика
• условия, зависящие от сценариев

👉 Любые исключения — ТОЛЬКО после обсуждения в чате.

---

5) Celery

• Task = thin wrapper
• Task вызывает сервис, а не содержит логику
• Таски:
  • идемпотентны
  • логируют начало и завершение
• Ретраи:
  • только для временных ошибок
  • с backoff

---

6) База данных и миграции

• Любое изменение моделей → миграции обязательны
• Миграции:
  • детерминированные
  • без ручной магии без причины

Проверка перед коммитом:

uv run python manage.py makemigrations --check --dry-run

PostgreSQL:

• транзакции использовать осознанно
• select_for_update() при гонках
• Raw SQL — только с объяснением

---

7) Тестирование

• Любая бизнес-логика → тесты
• В первую очередь тестируется сервисный слой
• API — happy path + edge cases

Запуск:

uv run python manage.py test

---

8) pre-commit (обязателен)

• Любой код обязан проходить pre-commit
• Агент обязан учитывать проверки форматирования и линтинга

pre-commit run --all-files

---

9) CI (Gitea Actions)

• Используется Gitea Actions
• ❌ GitHub Actions запрещены
• Любые изменения:
  • не должны ломать CI
• Если меняются:
  • зависимости
  • команды тестов
  • миграции
    → агент обязан указать необходимость правок workflow

---

10) Apache + mod_wsgi

• Используется ТОЛЬКО WSGI
• ASGI запрещён без отдельного обсуждения
• Любые изменения в wsgi.py, путях, статике:
  • сопровождаются пояснением
  • требуют перезапуска Apache

systemctl restart apache2

Учитывать ограничения и права Astra Linux.

---

11) Работа с репозиторием

• Минимальный diff — приоритет
• ❌ Не коммитить:
  • .venv
  • артефакты
  • дампы БД
• Массовый рефакторинг — только по явному запросу

---

12) Anti-patterns (ЗАПРЕЩЕНО)

• Fat Models
• God Views
• Бизнес-логика в Serializers
• Сигналы как workflow
• Магия в save()
• Прямые импорты моделей между apps
• Сложная логика в queryset как бизнес-правило

---

13) Формат ответа ИИ-агента (ОБЯЗАТЕЛЬНЫЙ)

Каждый ответ должен содержать:

1. Что меняем
2. Файлы / патч
3. Команды (через uv)
4. Проверки (tests / pre-commit / CI)
5. Риски / замечания

---

14) Исключения

• ИИ-агент НЕ внедряет исключения сам
• Агент:
  • описывает стандартное решение
  • объясняет, почему оно не подходит
  • запрашивает разрешение в чате

15) Структура проекта