nakama/moderation/backend-py/README.md

# Nakama Moderation Backend - Python

Бэкенд модерации на Python с FastAPI, портированный с Node.js.

## Преимущества Python версии

- ✅ **Лучшая работа с email** - нативная поддержка SMTP без проблем с AWS SDK
- ✅ **Простота настройки** - меньше зависимостей и конфликтов
- ✅ **Производительность** - async/await с uvicorn
- ✅ **Типизация** - Pydantic для валидации данных
- ✅ **Совместимость** - использует ту же MongoDB и те же данные

## Установка

### 1. Установите Python 3.11+

```bash
python3 --version  # Должно быть >= 3.11
```

### 2. Создайте виртуальное окружение

```bash
cd moderation/backend-py
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows
```

### 3. Установите зависимости

```bash
pip install -r requirements.txt
```

### 4. Настройте .env

Используется корневой `.env` файл проекта (в `nakama/.env`).

Обязательные переменные для email:

```env
EMAIL_PROVIDER=yandex

YANDEX_SMTP_HOST=smtp.yandex.ru
YANDEX_SMTP_PORT=465
YANDEX_SMTP_SECURE=true
YANDEX_SMTP_USER=ваш_email@yandex.ru
YANDEX_SMTP_PASSWORD=ваш_пароль_приложения

EMAIL_FROM=noreply@nakama.guru
OWNER_EMAIL=admin@example.com
```

**Важно:** Для Yandex используйте пароль приложения (https://id.yandex.ru/security), не основной пароль!

## Запуск

### Development режим

```bash
cd moderation/backend-py
source venv/bin/activate
python main.py
```

Или через uvicorn с auto-reload:

```bash
uvicorn main:app --reload --host 0.0.0.0 --port 3001
```

### Production режим

```bash
uvicorn main:app --host 0.0.0.0 --port 3001 --workers 4
```

### Docker

```bash
# Сборка
docker build -t nakama-moderation-py -f moderation/backend-py/Dockerfile moderation/backend-py

# Запуск
docker run -d \
  --name nakama-moderation-py \
  -p 3001:3001 \
  --env-file ../../.env \
  nakama-moderation-py
```

## API Endpoints

### Authentication (`/api/moderation-auth`)

- `POST /send-code` - Отправить код на email
- `POST /register` - Регистрация с кодом
- `POST /login` - Вход по email/паролю
- `POST /telegram-widget` - Вход через Telegram виджет
- `POST /logout` - Выход
- `GET /config` - Получить конфигурацию
- `GET /me` - Текущий пользователь

### Moderation (`/api/mod-app`)

- `GET /users` - Список пользователей
- `PUT /users/{id}/ban` - Забанить пользователя
- `GET /posts` - Список постов
- `GET /posts/{id}` - Получить пост
- `PUT /posts/{id}` - Обновить пост
- `DELETE /posts/{id}` - Удалить пост
- `GET /reports` - Список репортов
- `PUT /reports/{id}` - Обновить статус репорта
- `GET /admins` - Список админов
- `POST /auth/verify` - Верификация авторизации

### WebSocket (`/socket.io`)

- `join_moderation_chat` - Присоединиться к чату
- `leave_moderation_chat` - Покинуть чат
- `moderation_message` - Отправить сообщение
- `typing` - Индикатор печати

## Структура проекта

```
moderation/backend-py/
├── main.py                 # Главный файл приложения
├── config.py               # Конфигурация
├── database.py             # MongoDB подключение
├── models.py               # Pydantic модели
├── middleware.py           # Middleware (logging, security)
├── websocket_server.py     # WebSocket сервер
├── requirements.txt        # Python зависимости
├── Dockerfile              # Docker образ
├── routes/
│   ├── __init__.py
│   ├── mod_app.py         # Роуты модерации
│   └── moderation_auth.py # Роуты аутентификации
└── utils/
    ├── __init__.py
    ├── auth.py            # JWT и авторизация
    ├── email_service.py   # Отправка email
    └── minio_client.py    # MinIO клиент
```

## Миграция с Node.js

Для переключения с Node.js версии на Python:

1. Остановите Node.js бэкенд модерации
2. Запустите Python версию на том же порту (3001)
3. Фронтенд будет работать без изменений (API совместимо)

## Отладка

### Проверка email настроек

```python
python -c "from config import settings; print(f'Email: {settings.EMAIL_PROVIDER}, User: {settings.YANDEX_SMTP_USER}')"
```

### Проверка MongoDB подключения

```python
python -c "import asyncio; from database import connect_db; asyncio.run(connect_db())"
```

### Логи

Все логи выводятся в stdout с префиксами:
- `[Email]` - email операции
- `[ModerationAuth]` - аутентификация
- `[ModApp]` - модерация
- `[WebSocket]` - WebSocket события

## Troubleshooting

### Email не отправляется

1. Проверьте переменные в `.env`:
   ```bash
   grep YANDEX_SMTP ../../.env
   ```

2. Убедитесь, что используете пароль приложения Yandex

3. Проверьте логи при запуске - должно быть:
   ```
   [Email] Настройка SMTP: {provider: 'yandex', host: 'smtp.yandex.ru', ...}
   ```

### 401 Unauthorized

Проверьте JWT токены в cookies или Authorization header.

### WebSocket не подключается

Убедитесь, что фронтенд подключается к правильному URL:
- Development: `http://localhost:3001`
- Production: ваш домен с правильным портом

## Production Deployment

См. `moderation/DEPLOY.md` для инструкций по развертыванию.