nakama/SETUP.md

NakamaSpace - Инструкция по установке и запуску

📋 Требования

• Node.js 16+ и npm
• MongoDB 5+
• Telegram Bot Token (получить у @BotFather)

🚀 Установка

1. Установить зависимости

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

# Установка зависимостей frontend
cd frontend
npm install
cd ..

2. Настроить переменные окружения

Создайте файл .env в корне проекта:

cp .env.example .env

Отредактируйте .env:

MONGODB_URI=mongodb://localhost:27017/nakama
PORT=3000
JWT_SECRET=your_secret_key_here
TELEGRAM_BOT_TOKEN=your_bot_token_here
NODE_ENV=development

Создайте файл frontend/.env:

cp frontend/.env.example frontend/.env

3. Запустить MongoDB

# macOS с Homebrew
brew services start mongodb-community

# Linux
sudo systemctl start mongod

# Или запустите вручную
mongod --dbpath /path/to/data/directory

4. Создать Telegram бота

1. Откройте @BotFather в Telegram
2. Отправьте /newbot и следуйте инструкциям
3. Получите токен бота и добавьте в .env
4. Настройте Web App:
   • /mybots → выберите бота → Bot Settings → Menu Button
   • Укажите URL вашего приложения

🏃 Запуск приложения

Режим разработки

# Запустить backend и frontend одновременно
npm run dev

# Или запустить по отдельности:

# Backend (http://localhost:3000)
npm run server

# Frontend (http://localhost:5173)
npm run client

Production

# Собрать frontend
npm run build

# Запустить production сервер
npm start

🔧 Настройка Telegram Mini App

Локальная разработка

Для тестирования локально:

1. Используйте ngrok или подобный туннель:

ngrok http 5173

2. Скопируйте HTTPS URL от ngrok

3. Настройте Menu Button в BotFather с этим URL

Production деплой

Рекомендуемые платформы:

• Backend: Railway, Render, Heroku
• Frontend: Vercel, Netlify
• MongoDB: MongoDB Atlas

Пример деплоя на Railway:

# Установить Railway CLI
npm i -g @railway/cli

# Войти
railway login

# Создать проект
railway init

# Деплой
railway up

📱 Тестирование

1. Откройте бота в Telegram
2. Нажмите на кнопку меню или отправьте команду
3. Приложение откроется как Mini App

🛠️ Структура проекта

nakama/
├── backend/              # Backend сервер
│   ├── models/           # MongoDB модели
│   ├── routes/           # API endpoints
│   ├── middleware/       # Middleware (auth, etc)
│   └── server.js         # Точка входа
├── frontend/             # Frontend React приложение
│   ├── src/
│   │   ├── components/   # React компоненты
│   │   ├── pages/        # Страницы-вкладки
│   │   ├── utils/        # Утилиты (API, Telegram)
│   │   └── styles/       # CSS стили
│   └── index.html
└── package.json

🎨 Дизайн-система

Проект использует минималистичный iOS-стиль с палитрой:

• Фон: #F2F3F5
• Карточки: #FFFFFF
• Текст: #1C1C1E
• Furry теги: #FF8A33
• Anime теги: #4A90E2
• Other теги: #A0A0A0

🔐 Модерация

Для назначения модераторов/админов:

// Подключиться к MongoDB
mongo nakama

// Обновить роль пользователя
db.users.updateOne(
  { telegramId: "YOUR_TELEGRAM_ID" },
  { $set: { role: "admin" } }
)

Роли:

• user - обычный пользователь
• moderator - может модерировать контент
• admin - полные права

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

Основные endpoints:

Авторизация

• POST /api/auth/verify - Верификация Telegram Init Data

Посты

• GET /api/posts - Получить ленту постов
• POST /api/posts - Создать пост
• POST /api/posts/:id/like - Лайкнуть пост
• POST /api/posts/:id/comment - Добавить комментарий
• POST /api/posts/:id/repost - Репостнуть
• DELETE /api/posts/:id - Удалить пост

Пользователи

• GET /api/users/:id - Получить профиль
• GET /api/users/:id/posts - Получить посты пользователя
• POST /api/users/:id/follow - Подписаться/отписаться
• PUT /api/users/profile - Обновить профиль
• GET /api/users/search/:query - Поиск пользователей

Уведомления

• GET /api/notifications - Получить уведомления
• PUT /api/notifications/:id/read - Отметить как прочитанное
• PUT /api/notifications/read-all - Прочитать все

Поиск

• GET /api/search/furry?query=tags - Поиск в e621
• GET /api/search/anime?query=tags - Поиск в gelbooru
• GET /api/search/furry/tags?query=tag - Автокомплит тегов e621
• GET /api/search/anime/tags?query=tag - Автокомплит тегов gelbooru
• GET /api/search/proxy/:encodedUrl - Проксирование изображений с e621/gelbooru (для доступа из РФ)

Модерация

• POST /api/moderation/report - Создать жалобу
• GET /api/moderation/reports - Получить жалобы (модераторы)
• PUT /api/moderation/reports/:id - Обработать жалобу
• PUT /api/moderation/posts/:id/nsfw - Установить NSFW флаг
• PUT /api/moderation/users/:id/ban - Заблокировать пользователя

⚠️ Troubleshooting

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

# Проверить статус
brew services list  # macOS
sudo systemctl status mongod  # Linux

# Проверить порт
lsof -i :27017

CORS ошибки

Убедитесь что VITE_API_URL в frontend/.env указывает на правильный адрес backend

Telegram Init Data invalid

В dev режиме проверка отключена, но для production нужен валидный TELEGRAM_BOT_TOKEN

📞 Поддержка

Если возникли проблемы:

1. Проверьте логи: npm run server
2. Откройте DevTools в браузере
3. Проверьте MongoDB подключение
4. Убедитесь что все переменные окружения установлены

🎉 Готово!

Приложение должно работать! Откройте бота в Telegram и начните использовать NakamaSpace.