Документация

Путеводитель разработчика Crisis Monitor

Введение

Цель этого документа – обеспечить быструю и безболезненную адаптацию новых разработчиков, а также установить единые стандарты и архитектурные правила для проекта. Следование этому руководству обязательно для всех, кто вносит изменения в кодовую базу. Это поможет нам избежать повторения критических ошибок, которые были допущены на ранних этапах разработки.

1. Настройка окружения

1.1. Зависимости Python

  • Версия Python: Проект использует Python 3.11+. Рекомендуется использовать pyenv для управления версиями.
  • Виртуальное окружение: Всегда работайте в активированном виртуальном окружении (venv).
  • Установка зависимостей:
    • Для основной работы: pip install -r requirements.txt
    • Для разработки (включая инструменты тестирования и линтинга): pip install -r requirements-dev.txt

1.2. Зависимости для Machine Learning (PyTorch)

Важно: В проекте используется PyTorch. Файлы зависимостей (requirements.txt) настроены для кросс-платформенной установки. В них не указаны специфичные для NVIDIA CUDA пакеты.

При выполнении pip install -r requirements.txt менеджер пакетов pip автоматически определит вашу ОС и архитектуру и установит подходящую версию PyTorch: - На macOS с Apple Silicon (M1/M2/M3/M4) будет установлена версия, использующая технологию Apple MPS для GPU-ускорения. - На Linux/Windows с GPU от NVIDIA будет установлена версия с поддержкой CUDA.

Ошибка No matching distribution found for nvidia-cublas-cu12...: Если вы столкнулись с этой ошибкой, это значит, что в вашем requirements.txt оказались платформо-зависимые пакеты. Убедитесь, что ваш файл соответствует версии из репозитория, где эти пакеты удалены.

1.3. База данных

Проект использует PostgreSQL. Убедитесь, что у вас установлен psycopg2-binary (он есть в requirements.txt) и что у вас есть доступ к работающему серверу PostgreSQL. Параметры подключения настраиваются в файле .env (см. config.py).

2. Ключевые архитектурные принципы

2.1. Единый источник истины для расширений Flask

Все глобальные объекты и расширения Flask (db, cache, migrate и т.д.) инициализируются только один раз в файле app/__init__.py.

Правило: Любой модуль должен импортировать эти объекты из пакета app.

# Правильно
from app.database import db
from app import cache

# НЕПРАВИЛЬНО! Запрещено создавать новые экземпляры в других файлах.
# from flask_sqlalchemy import SQLAlchemy
# db = SQLAlchemy()

Объект db находится в модуле app.database. Нарушение этого правила в прошлом привело к созданию "раздвоенного" объекта db и полной неработоспособности миграций базы данных.

2.2. Строгое направление зависимостей

Это самый важный архитектурный принцип в проекте для избежания циклических импортов.

Золотое правило: Низкоуровневые, переиспользуемые модули НИКОГДА не должны импортировать высокоуровневые модули на уровне всего файла. - Высокоуровневые модули: app, app/models, app/auth.py (любые Flask Blueprints). - Низкоуровневые модули: services/, utils/.

Пример нарушения:

# В файле services/some_service.py
from app.models import User # НЕПРАВИЛЬНО! Это создает цикл.

Правильное решение: Используйте защитный блок if TYPE_CHECKING: для аннотаций типов и локальные импорты внутри функций для реального использования.

# services/some_service.py

from __future__ import annotations
from typing import TYPE_CHECKING

# Импорты для аннотаций типов находятся здесь
if TYPE_CHECKING:
    from app.models import User, Ticket  # noqa: F401

class SomeService:
    def get_user_by_ticket(self, ticket: 'Ticket') -> 'User' | None:
        # Локальный импорт для реального использования объекта
        from app.models import User

        user = User.query.get(ticket.reporter_id)
        return user

3. Стандарты качества кода

3.1. Линтинг и форматирование

  • Линтер и форматирование: проект использует Ruff с конфигурацией из pyproject.toml. Проверка всего репозитория: .venv/bin/ruff check ..
  • Типизация: стабильная типизированная граница проверяется командой bash scripts/typecheck.sh.
  • Pre-commit: локальные хуки повторяют основной quality gate. Установите их командой .venv/bin/pre-commit install.

3.2. Обработка предупреждений Ruff

  • F401 (unused import): Удаляйте неиспользуемые импорты. Если импорт нужен для TYPE_CHECKING, добавьте в конце строки комментарий # noqa: F401.
  • E501 (line too long): разбивайте выражение на читаемые строки в пределах настроенного лимита.
  • F821 (undefined name): Эта ошибка почти всегда указывает на нарушение правила о направлении зависимостей. Убедитесь, что вы добавили локальный импорт внутри функции, которая использует данный объект.