nakama/MUSIC_SETUP.md

# Настройка музыкального модуля Nakama

## Установка зависимостей

Для работы музыкального модуля требуется установить дополнительный пакет:

```bash
npm install adm-zip
```

Этот пакет используется для распаковки ZIP-архивов при загрузке альбомов.

## Структура файлов

### Backend

**Модели:**
- `backend/models/Artist.js` - Исполнители
- `backend/models/Album.js` - Альбомы
- `backend/models/Track.js` - Треки
- `backend/models/FavoriteTrack.js` - Избранные треки пользователей

**Routes:**
- `backend/routes/music.js` - API для музыки (загрузка, поиск, избранное)
- `backend/routes/bot.js` - Обновлен для отправки треков в Telegram
- `backend/routes/posts.js` - Обновлен для поддержки музыкальных вложений

**Бот:**
- `backend/bot.js` - Добавлена функция `sendAudioToUser()` для отправки треков

### Frontend

**Страницы:**
- `frontend/src/pages/Media.jsx` - Главная страница Media с категориями
- `frontend/src/pages/MediaFurry.jsx` - Поиск Furry контента
- `frontend/src/pages/MediaAnime.jsx` - Поиск Anime контента
- `frontend/src/pages/MediaMusic.jsx` - Музыкальный сервис

**Компоненты:**
- `frontend/src/components/MiniPlayer.jsx` - Мини-плеер (внизу экрана)
- `frontend/src/components/FullPlayer.jsx` - Полный плеер
- `frontend/src/components/MusicAttachment.jsx` - Отображение музыки в постах

**Контекст:**
- `frontend/src/contexts/MusicPlayerContext.jsx` - Управление состоянием плеера

**API:**
- `frontend/src/utils/musicApi.js` - API функции для работы с музыкой

## Функционал

### 1. Media Hub
- Главная страница с тремя категориями: Furry, Anime, Music
- Квадратные кнопки-карточки с цветовой кодировкой
- Анимации и состояния как в остальном приложении

### 2. Furry / Anime
- Отдельные страницы для каждой категории
- Поиск по тегам (e621 / gelbooru)
- Автокомплит тегов
- Просмотр изображений
- Добавление в посты
- Отправка в Telegram
- Режим выбора нескольких изображений

### 3. Music Service

**Загрузка:**
- Загрузка отдельных треков
- Загрузка альбомов из ZIP архива
- Автоматическое создание исполнителей и альбомов

**Поиск:**
- Поиск по трекам, исполнителям, альбомам
- Фильтрация результатов

**Плеер:**
- Мини-плеер (закреплен внизу)
- Полный плеер (открывается по клику)
- Управление воспроизведением (play/pause/next/prev)
- Прогресс-бар с перемоткой
- Регулировка громкости
- Очередь воспроизведения

**Избранное:**
- Добавление треков в избранное
- Просмотр избранных треков

**Telegram интеграция:**
- Отправка треков в личные сообщения
- Треки отправляются как аудио файлы с метаданными

### 4. Музыка в постах
- Прикрепление треков к постам
- Воспроизведение через общий плеер
- Отображение в ленте

## API Endpoints

### Music

**GET** `/api/music/search?q=query&type=all` - Поиск музыки

**GET** `/api/music/tracks?limit=50&page=1` - Список треков

**GET** `/api/music/tracks/:trackId` - Получить трек

**GET** `/api/music/albums/:albumId` - Получить альбом с треками

**POST** `/api/music/upload-track` - Загрузить трек
- FormData: track (file), title, artistName, albumTitle, trackNumber, year, genre

**POST** `/api/music/upload-album` - Загрузить альбом (ZIP)
- FormData: album (zip), artistName, albumTitle, year, genre

**POST** `/api/music/favorites/:trackId` - Добавить в избранное

**DELETE** `/api/music/favorites/:trackId` - Удалить из избранного

**GET** `/api/music/favorites` - Получить избранные треки

**POST** `/api/music/tracks/:trackId/play` - Отметить прослушивание

### Bot

**POST** `/api/bot/send-track` - Отправить трек в Telegram
```json
{
  "userId": 123456789,
  "trackId": "track_id"
}
```

## Навигация

Вкладка "Search" переименована в "Media" с иконкой Layers.

## Цветовая схема

- **Furry:** `var(--tag-furry)` - оранжевый (#FF8A33)
- **Anime:** `var(--tag-anime)` - синий (#4A90E2)
- **Music:** `#9b59b6` - фиолетовый

## Примечания

1. Музыкальные файлы хранятся в `backend/uploads/music/`
2. Поддерживаемые форматы: MP3, WAV, OGG, M4A
3. Максимальный размер файла: 50MB
4. ZIP архивы автоматически распаковываются и создают альбом
5. Плеер работает глобально - музыка продолжает играть при навигации
6. Треки в постах воспроизводятся через общий плеер