# Документация API Meander Backend

Это полная, техническая документация API бэкенда Meander (Express.js), предназначенная для разработчиков клиентских приложений и библиотек.

## Базовые настройки

- **Базовый URL:** `https://backend.meander.sbs` (или ваш локальный URL для разработки)
- **Формат данных:** `application/json` (если не указано `multipart/form-data`)
- **Аутентификация:** Большинство роутов требуют JWT токен, передаваемый в заголовке `Authorization`.
  - Формат: `Authorization: Bearer <TOKEN>`

---

## 1. Аутентификация (Auth)

Аутентификация работает только через Google OAuth 2.0. Вы не можете выпустить токен без реального аккаунта Google. Лимит: 100 запросов в час с одного IP.

### Обмен токена Google на токен API
\`POST /auth/google/token\`
*   **Body:** \`{ "idToken": "google_oauth_id_token_here" }\`
*   **Возвращает:** \`{ "token": "jwt_token_string", "user": { ...profile_data } }\`

---

## 2. Профили пользователей (Profiles)

### Получение чужого профиля
\`GET /profiles/:id\`
*   **Возвращает:** Статистику пользователя, никнейм, роль, дату регистрации и статус онлайна.

### Редактирование своего профиля
\`POST /profiles/me\`
*   **Auth:** Требуется
*   **Body (multipart/form-data):** 
    *   \`full_name\` (строка, опционально)
    *   \`bio\` (строка, опционально)
    *   \`avatar\` (файл, опционально)

### Подписка / Отписка
\`POST /profiles/:id/follow\`
*   **Auth:** Требуется
*   **Возвращает:** \`{ "following": true|false }\`

### Получение достижений (Ачивок)
\`GET /profiles/:id/achievements\`
*   **Возвращает:** Массив полученных достижений.

### Ежедневный Стрик (Streak)
\`POST /profiles/update-streak\`
*   **Auth:** Требуется
*   **Возвращает:** \`{ "streak": N, "last_active_at": "...", "rewardClaimed": true|false }\`

### Настройки
\`GET /profiles/sync-settings\` — Настройки облачных сохранений.
\`POST /profiles/sync-settings\` — Обновление настроек (body: \`{ "auto_sync": boolean, "sync_on_cellular": boolean }\`).
\`GET /profiles/author-notifs-settings\` — Настройки уведомлений.
\`POST /profiles/author-notifs-settings\` — Обновление уведомлений (body: \`{ "muted_authors": ["id1"] }\`).

---

## 3. Квесты (Quests)

### Список квестов (Каталог)
\`GET /quests\`
*   **Параметры (Query):** 
    *   \`page\` (по умолчанию: 1)
    *   \`limit\` (по умолчанию: 10)
    *   \`search\` (поиск по названию/тегам)
    *   \`genre\` (фильтр по жанру)
    *   \`sort\` (\`newest\`, \`popular\`, \`downloads\`, \`rating\`)
*   **Возвращает:** \`{ "quests": [...], "totalPages": N, "currentPage": N }\`

### Подборки
\`GET /quests/featured\` — Рекомендованные квесты.
\`GET /quests/activity/recent\` — Недавняя активность (отзывы).
\`GET /quests/liked-genres\` — Квесты по любимым жанрам пользователя.

### Детали квеста
\`GET /quests/:id\`
*   **Возвращает:** Полную информацию о квесте (описание, рейтинг, автор, теги).
\`GET /quests/:id/screenshots\` — Скриншоты.

### Взаимодействие
\`POST /quests/:id/vote\` — Поставить/убрать лайк (Body: \`{ "vote": 1 | 0 }\`).
\`POST /quests/:id/download\` — Скачать квест (Инкрементирует счетчик, возвращает подписанную ссылку).
\`POST /quests/:id/review\` — Написать отзыв (Body: \`{ "rating": 5, "textContent": "..." }\`).

---

## 4. Облачные сохранения (Cloud Sync)

Синхронизация игрового прогресса (файлов) с сервером.

### Получение квоты
\`GET /cloud-sync/quota\`
*   **Auth:** Требуется
*   **Возвращает:** Использованное место и лимит (базовый 50 МБ, VIP 200 МБ).

### Список сохранений
\`GET /cloud-sync/quests\`
*   **Auth:** Требуется
*   **Возвращает:** Список квестов, для которых есть сохранения на сервере.

### Проверка актуальности сохранения
\`POST /cloud-sync/quests/:questId/check\`
*   **Auth:** Требуется
*   **Body:** \`{ "localUpdatedAt": "ISOString" }\`
*   **Возвращает:** Какое сохранение новее (\`server\`, \`local\`, \`conflict\`).

### Загрузка сохранения (Upload)
\`PUT /cloud-sync/quests/:questId\`
*   **Auth:** Требуется
*   **Body (multipart/form-data):** Файл сохранения под ключом \`file\`.

### Скачивание сохранения (Download)
\`GET /cloud-sync/quests/:questId\`
*   **Auth:** Требуется
*   **Возвращает:** Бинарный файл сохранения.

### Удаление сохранения
\`DELETE /cloud-sync/quests/:questId\`
*   **Auth:** Требуется

---

## 5. Стена автора (Author Wall)

Каждый автор имеет свою "стену" для новостей, как в соцсетях.

### Загрузка картинок для постов
\`POST /api/author-walls/upload-media\`
*   **Auth:** Требуется
*   **Body (multipart/form-data):** \`file\`
*   **Возвращает:** URL картинки на CDN.

### Лента постов автора
\`GET /api/author-walls/:authorId/posts\`
*   **Параметры (Query):** \`limit\`, \`offset\`, \`viewer_id\`
*   **Возвращает:** Массив постов.

### Получение одного поста
\`GET /api/author-walls/posts/:postId\`
*   **Возвращает:** Детальную информацию по посту.

### Управление постами
\`POST /api/author-walls/:authorId/posts\` — Создать пост (Body: \`{ "content": "Текст", "media_urls": [] }\`).
\`PUT /api/author-walls/posts/:postId\` — Изменить пост.
\`DELETE /api/author-walls/posts/:postId\` — Удалить пост.
\`POST /api/author-walls/posts/:postId/view\` — Зарегистрировать просмотр (инкремент счетчика).

### Комментарии к постам
\`GET /api/author-walls/posts/:postId/comments\` — Список комментариев.
\`POST /api/author-walls/posts/:postId/comments\` — Написать комментарий (Body: \`{ "content": "Текст", "parentId": "optional_reply_id" }\`).

---

## 6. Глобальное сообщество (Community)

### Глобальная лента
\`GET /api/community/feed\`
*   **Параметры (Query):** \`limit\`, \`offset\`, \`viewer_id\`, \`tab\` ("all" или "following")
*   **Возвращает:** Единую ленту постов от всех авторов или только подписок.

### Топ авторы
\`GET /api/community/top\`
*   **Возвращает:** Массив самых популярных профилей.

---

## 7. Уведомления (Notifications)

\`GET /notifications\` — Список уведомлений (Query: \`archived=true|false\`).
\`GET /notifications/unread-count\` — Количество непрочитанных.
\`POST /notifications/:id/read\` — Пометить как прочитанное.
\`POST /notifications/:id/archive\` — Отправить в архив.

---

## 8. ИИ Функции (AI)

Возможности AI доступны за токены (выдаются бесплатно или через донат).

\`GET /ai/token-balance\` — Текущий баланс ИИ-токенов.
\`POST /ai/refresh-tokens\` — Обновить ежедневные бесплатные токены.

### Генерация и исправление
Все POST-запросы требуют передачи \`{ "text": "..." }\` в Body.
*   \`POST /ai/fix-text\` — Исправление текста (доп. \`mode\`: "grammar", "style", "expand").
*   \`POST /ai/translate\` — Перевод (доп. \`targetLanguage\`).
*   \`POST /ai/suggest-continuation\` — Продолжить абзац текста.
*   \`POST /ai/suggest-button-text\` — Сгенерировать текст для кнопок-ответов игрока.
*   \`POST /ai/generate-keywords\` — Генерация тегов для квеста по описанию.

---

## 9. Жалобы и Админ-панель (Reports & Admin)

### Создать жалобу на контент
\`POST /reports\`
*   **Auth:** Требуется
*   **Body:** 
    *   \`targetType\`: "quest" | "profile" | "review" | "wall_post" | "wall_comment"
    *   \`targetId\`: UUID
    *   \`reason\`: Категория (SPAM, NSFW, SCAM, и т.д.)
    *   \`details\`: Комментарий к жалобе

### Админ-панель (Только role='admin')
\`GET /admin/stats\` — Общая статистика по платформе.
\`GET /reports/admin\` — Очередь жалоб на модерацию.
\`POST /reports/admin/:id/resolve\` — Вынести решение по жалобе (Удалить / Игнорировать).