core/docs/README.md

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

## Модули

### Аутентификация и авторизация

Подробная документация: [auth.md](auth.md)

Основные возможности:
- Гибкая система аутентификации с использованием локальной БД и Redis
- Система ролей и разрешений (RBAC)
- OAuth интеграция (Google, Facebook, GitHub)
- Защита от брутфорс атак
- Управление сессиями через Redis
- Мультиязычные email уведомления
- Страница авторизации для админ-панели

Конфигурация:
```python
# settings.py
JWT_SECRET_KEY = "your-secret-key"  # секретный ключ для JWT токенов
SESSION_TOKEN_LIFE_SPAN = 60 * 60 * 24 * 30  # время жизни сессии (30 дней)
```

### Authentication & Security
- [Security System](security.md) - Password and email management
- [OAuth Token Management](oauth.md) - OAuth provider token storage in Redis
- [Following System](follower.md) - User subscription system

### Реакции и комментарии

Модуль обработки пользовательских реакций и комментариев.

Основные возможности:
- Создание, обновление и удаление реакций (лайки, дизлайки, комментарии)
- Иерархические комментарии с пагинацией корневых и дочерних
- Расчет статистики (счетчик комментариев, рейтинг)
- Автоматическое добавление/снятие статуса "featured" для публикаций
- Оптимизация запросов с использованием distinct() для предотвращения дублирования

Особенности реализации:
- Физическое удаление рейтинговых реакций и логическое удаление комментариев (поле deleted_at)
- Использование distinct() для предотвращения дублирования результатов при JOIN с eager loading
- Эффективная обработка иерархических данных с помощью специализированных GraphQL запросов

Ключевые функции:
- `get_reactions_with_stat(q, limit, offset)` - получение реакций со статистикой
- `load_comments_branch(shout, parent_id, limit, offset, sort, children_limit, children_offset)` - загрузка иерархических комментариев с пагинацией

### Административный интерфейс

Основные возможности:
- Защищенный доступ только для авторизованных пользователей с ролью admin
- Автоматическая проверка прав пользователя
- Отдельная страница входа для неавторизованных пользователей
- Проверка доступа по email или правам в системе RBAC

Маршруты:
- `/admin` - административная панель с проверкой прав доступа

## Запуск сервера

### Стандартный запуск
```bash
python main.py
```

### Запуск с поддержкой HTTPS
Для локальной разработки с HTTPS используйте скрипт `run.py` с инструментом mkcert:

```bash
# Установите mkcert
# macOS:
brew install mkcert
# Linux:
# sudo apt install mkcert (или эквивалент для вашего дистрибутива)
# Windows:
# choco install mkcert

# Установите локальный CA
mkcert -install

# Запуск с HTTPS на порту 8000 через Granian
python run.py --https

# Запуск с HTTPS на другом порту
python run.py --https --port 8443

# Запуск с несколькими рабочими процессами
python run.py --https --workers 4

# Запуск с указанием домена для сертификата
python run.py --https --domain "localhost.localdomain"
```

При первом запуске будут автоматически сгенерированы доверенные локальные сертификаты с помощью mkcert.

**Преимущества mkcert:**
- Сертификаты распознаются браузером как доверенные (нет предупреждений)
- Работает на всех платформах (macOS, Linux, Windows)
- Простая установка и настройка