nakama/WIND.md

# 🪟 Инструкция по развертыванию Nakama на Windows

## 📋 Содержание

1. [Предварительные требования](#предварительные-требования)
2. [Установка зависимостей](#установка-зависимостей)
3. [Настройка окружения](#настройка-окружения)
4. [Запуск MongoDB](#запуск-mongodb)
5. [Запуск приложения](#запуск-приложения)
6. [Отключение проверки initData для разработки](#отключение-проверки-initdata-для-разработки)
7. [Тестирование без Telegram](#тестирование-без-telegram)
8. [Полезные команды](#полезные-команды)
9. [Устранение проблем](#устранение-проблем)

---

## 🔧 Предварительные требования

### 1. Node.js
Установите Node.js версии 18 или выше:
- Скачайте с [nodejs.org](https://nodejs.org/)
- Проверьте установку:
```cmd
node --version
npm --version
```

### 2. MongoDB
Установите MongoDB Community Edition:
- Скачайте с [mongodb.com/try/download/community](https://www.mongodb.com/try/download/community)
- Или используйте MongoDB в Docker (см. ниже)

### 3. Git (опционально)
Для работы с репозиторием:
- Скачайте с [git-scm.com](https://git-scm.com/)

---

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

### 1. Клонируйте репозиторий (если еще не клонирован)
```cmd
git clone <repository-url>
cd nakama
```

### 2. Установите зависимости для backend
```cmd
npm install
```

### 3. Установите дополнительные пакеты для музыкального модуля
```cmd
npm install adm-zip music-metadata
```

### 4. Установите зависимости для frontend
```cmd
cd frontend
npm install
cd ..
```

---

## ⚙️ Настройка окружения

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

```cmd
REM Скопируйте пример
copy ENV_EXAMPLE.txt .env
```

**Для PowerShell:**
```powershell
# Скопируйте пример
Copy-Item ENV_EXAMPLE.txt .env
```

### 2. Минимальная конфигурация для локальной разработки

Откройте `.env` в текстовом редакторе и настройте:

```env
# Режим разработки
NODE_ENV=development
PORT=3000

# MongoDB (локальная база)
MONGODB_URI=mongodb://localhost:27017/nakama-dev

# JWT Secrets (можно использовать любые строки для разработки)
JWT_SECRET=dev_jwt_secret_change_me_in_production_32chars
JWT_ACCESS_SECRET=dev_access_secret_32chars_minimum_length
JWT_REFRESH_SECRET=dev_refresh_secret_32chars_minimum_length

# Telegram Bot Configuration
# ⚠️ Для разработки без Telegram оставьте пустыми или используйте тестовый токен
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
MODERATION_BOT_TOKEN=

# API ключи для поиска (опционально)
GELBOORU_API_KEY=
GELBOORU_USER_ID=
E621_USERNAME=
E621_API_KEY=

# Frontend URL
FRONTEND_URL=http://localhost:5173
VITE_API_URL=http://localhost:3000/api

# CORS (разрешить все для разработки)
CORS_ORIGIN=*

# Redis (опционально, можно оставить пустым)
REDIS_URL=

# MinIO (отключить для локальной разработки)
MINIO_ENABLED=false

# Rate Limiting (мягкие лимиты для разработки)
RATE_LIMIT_GENERAL=1000
RATE_LIMIT_POSTS=100
RATE_LIMIT_INTERACTIONS=200

# Email (отключить для локальной разработки)
EMAIL_PROVIDER=
```

### 3. Создайте `.env` для frontend

```cmd
cd frontend
echo VITE_API_URL=http://localhost:3000/api > .env
cd ..
```

**Для PowerShell:**
```powershell
cd frontend
"VITE_API_URL=http://localhost:3000/api" | Out-File -Encoding UTF8 .env
cd ..
```

---

## 🗄️ Запуск MongoDB

### Вариант 1: MongoDB как сервис Windows

1. Запустите MongoDB из меню Пуск или через службы:
```cmd
net start MongoDB
```

2. Проверьте подключение:
```cmd
mongosh
REM Должно подключиться к mongodb://localhost:27017
```

### Вариант 2: MongoDB в Docker

```cmd
docker run -d -p 27017:27017 --name mongodb-nakama mongo:latest
```

### Вариант 3: MongoDB вручную

Если MongoDB не установлен как сервис:

```cmd
REM Перейдите в папку MongoDB
cd "C:\Program Files\MongoDB\Server\7.0\bin"

REM Создайте папку для данных (если не существует)
if not exist C:\data\db mkdir C:\data\db

REM Запустите MongoDB
mongod --dbpath C:\data\db
```

---

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

### 1. Запуск Backend

В корневой папке проекта:

```cmd
npm run server
```

Или для автоматической перезагрузки при изменениях:

```cmd
npm run dev
```

Backend будет доступен на `http://localhost:3000`

### 2. Запуск Frontend

Откройте **новое окно Command Prompt** (Win+R → `cmd`):

```cmd
cd C:\путь\к\проекту\nakama\frontend
npm run dev
```

Frontend будет доступен на `http://localhost:5173`

### 3. Запуск обоих одновременно

Из корневой папки:

```cmd
npm run dev
```

Эта команда запустит и backend, и frontend одновременно.

---

## 🔓 Отключение проверки initData для разработки

Для тестирования без Telegram Mini App нужно временно отключить проверку initData.

### Метод 1: Переменная окружения (Рекомендуется)

1. Добавьте в `.env`:
```env
DISABLE_TELEGRAM_AUTH=true
DEV_USER_ID=123456789
```

2. Создайте файл `backend/middleware/devAuth.js`:

```javascript
// Middleware для разработки без Telegram
const User = require('../models/User');

const devAuthenticate = async (req, res, next) => {
  // Включено только если DISABLE_TELEGRAM_AUTH=true
  if (process.env.DISABLE_TELEGRAM_AUTH !== 'true') {
    return require('./auth').authenticate(req, res, next);
  }

  console.log('⚠️  DEV MODE: Telegram auth disabled');

  try {
    const devUserId = process.env.DEV_USER_ID || '123456789';
    
    // Найти или создать тестового пользователя
    let user = await User.findOne({ telegramId: devUserId });

    if (!user) {
      user = new User({
        telegramId: devUserId,
        username: 'DevUser',
        firstName: 'Dev',
        lastName: 'User',
        photoUrl: null
      });
      await user.save();
      console.log('✅ Created dev user:', user.username);
    }

    // Инициализировать настройки
    if (!user.settings) {
      user.settings = {
        searchPreference: 'furry',
        whitelist: { noNSFW: false, noHomo: false }
      };
      await user.save();
    }

    req.user = user;
    req.telegramUser = {
      id: user.telegramId,
      username: user.username,
      firstName: user.firstName,
      lastName: user.lastName
    };

    next();
  } catch (error) {
    console.error('❌ Dev auth error:', error);
    res.status(500).json({ error: 'Dev auth error' });
  }
};

module.exports = { devAuthenticate };
```

3. Обновите `backend/routes/*.js` (все роуты с авторизацией):

```javascript
// Было:
const { authenticate } = require('../middleware/auth');

// Стало:
const { authenticate } = require('../middleware/auth');
const { devAuthenticate } = require('../middleware/devAuth');

// Используйте devAuthenticate вместо authenticate:
const authMiddleware = process.env.DISABLE_TELEGRAM_AUTH === 'true' 
  ? devAuthenticate 
  : authenticate;

router.get('/', authMiddleware, async (req, res) => {
  // ...
});
```

### Метод 2: Модификация auth.js (Быстрый способ)

Отредактируйте `backend/middleware/auth.js`:

```javascript
const authenticate = async (req, res, next) => {
  // 🔥 DEV MODE: Skip Telegram validation
  if (process.env.DISABLE_TELEGRAM_AUTH === 'true') {
    console.log('⚠️  DEV MODE: Skipping Telegram auth');
    
    const devUserId = process.env.DEV_USER_ID || '123456789';
    let user = await User.findOne({ telegramId: devUserId });

    if (!user) {
      user = new User({
        telegramId: devUserId,
        username: 'DevUser',
        firstName: 'Dev',
        lastName: 'User'
      });
      await user.save();
    }

    req.user = user;
    req.telegramUser = {
      id: user.telegramId,
      username: user.username,
      firstName: user.firstName,
      lastName: user.lastName
    };

    return next();
  }

  // Остальной код без изменений...
  try {
    const authHeader = req.headers.authorization || '';
    // ... существующий код ...
```

### Метод 3: Mock Telegram WebApp

Для фронтенда создайте файл `frontend\src\utils\mockTelegram.js`:

```javascript
// Mock Telegram WebApp для разработки
export const mockTelegram = () => {
  if (window.Telegram?.WebApp) return; // Уже есть

  const mockInitData = 'query_id=mock&user=%7B%22id%22%3A123456789%2C%22first_name%22%3A%22Dev%22%2C%22last_name%22%3A%22User%22%2C%22username%22%3A%22devuser%22%7D&auth_date=1234567890&hash=mockhash';

  window.Telegram = {
    WebApp: {
      initData: mockInitData,
      initDataUnsafe: {
        query_id: 'mock',
        user: {
          id: 123456789,
          first_name: 'Dev',
          last_name: 'User',
          username: 'devuser'
        },
        auth_date: 1234567890,
        hash: 'mockhash'
      },
      version: '6.0',
      platform: 'web',
      colorScheme: 'light',
      themeParams: {},
      isExpanded: true,
      viewportHeight: 600,
      viewportStableHeight: 600,
      isClosingConfirmationEnabled: false,
      headerColor: '#ffffff',
      backgroundColor: '#ffffff',
      BackButton: { isVisible: false },
      MainButton: { isVisible: false },
      ready: () => console.log('Mock Telegram ready'),
      expand: () => console.log('Mock Telegram expand'),
      close: () => console.log('Mock Telegram close'),
      disableVerticalSwipes: () => {},
      enableClosingConfirmation: () => {},
      disableClosingConfirmation: () => {}
    }
  };

  console.log('✅ Mock Telegram WebApp initialized');
};
```

Импортируйте и используйте в `frontend/src/App.jsx`:

```javascript
// В начале файла
import { mockTelegram } from './utils/mockTelegram'

// В useEffect перед initTelegramApp()
useEffect(() => {
  // Mock Telegram для разработки
  if (import.meta.env.DEV && !window.Telegram?.WebApp) {
    mockTelegram()
  }

  initTheme()
  // ...
}, [])
```

---

## 🧪 Тестирование без Telegram

### 1. Настройте среду разработки

В `.env`:
```env
DISABLE_TELEGRAM_AUTH=true
DEV_USER_ID=123456789
NODE_ENV=development
```

### 2. Запустите приложение

**Окно CMD 1 - Backend:**
```cmd
npm run server
```

**Окно CMD 2 - Frontend:**
```cmd
cd frontend
npm run dev
```

### 3. Откройте браузер

Перейдите на `http://localhost:5173`

Приложение должно работать без Telegram Mini App!

### 4. Тестирование API напрямую

Используйте **Postman**, **Thunder Client** или **curl** (если установлен):

```cmd
REM Получить посты
curl http://localhost:3000/api/posts

REM Создать пост (с mock auth) - для PowerShell
```

**Для PowerShell:**
```powershell
# Получить посты
Invoke-RestMethod -Uri http://localhost:3000/api/posts -Method Get

# Создать пост
$body = @{
    content = "Test post"
    tags = @("furry", "art")
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:3000/api/posts -Method Post -Body $body -ContentType "application/json"
```

**Рекомендуется использовать Postman или Thunder Client для удобства.**

---

## 📝 Полезные команды

### npm скрипты

```cmd
REM Backend
npm run server          & REM Запустить backend
npm run dev            & REM Backend + Frontend одновременно

REM Frontend
cd frontend
npm run dev            & REM Запустить frontend dev server
npm run build          & REM Собрать production build
npm run preview        & REM Preview production build
```

### MongoDB

```cmd
REM Подключиться к базе
mongosh mongodb://localhost:27017/nakama-dev
```

Внутри mongosh:
```javascript
// Показать базы
show dbs

// Использовать базу
use nakama-dev

// Показать коллекции
show collections

// Найти пользователей
db.users.find().pretty()

// Очистить посты
db.posts.deleteMany({})
```

### Остановка процессов

```cmd
REM Найти процесс на порту
netstat -ano | findstr :3000
netstat -ano | findstr :5173

REM Убить процесс по PID (замените <PID> на номер процесса)
taskkill /PID <PID> /F

REM Пример:
taskkill /PID 12345 /F
```

---

## 🔧 Устранение проблем

### Ошибка: "MongoDB connection failed"

**Решение:**
1. Проверьте, что MongoDB запущен:
```cmd
net start MongoDB
```
или
```cmd
mongosh
```

2. Проверьте `MONGODB_URI` в `.env`:
```env
MONGODB_URI=mongodb://localhost:27017/nakama-dev
```

### Ошибка: "Port 3000 already in use"

**Решение:**
```cmd
REM Найти процесс
netstat -ano | findstr :3000

REM Убить процесс (замените <PID> на номер из вывода выше)
taskkill /PID <PID> /F

REM Или измените порт в .env
REM PORT=3001
```

### Ошибка: "Cannot find module 'adm-zip'" или "Cannot find module 'music-metadata'"

**Решение:**
```cmd
npm install adm-zip music-metadata
```

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

**Решение:**
1. Проверьте `VITE_API_URL` в `frontend\.env`:
```env
VITE_API_URL=http://localhost:3000/api
```

2. Проверьте CORS в backend `.env`:
```env
CORS_ORIGIN=*
```

3. Перезапустите frontend:
```cmd
cd frontend
npm run dev
```

### Ошибка: "Требуется авторизация"

**Решение:**
1. Убедитесь, что `DISABLE_TELEGRAM_AUTH=true` в `.env`
2. Реализуйте devAuth middleware (см. выше)
3. Перезапустите backend

### Медленная работа на Windows

**Решение:**
1. Добавьте папки в исключения антивируса:
   - `node_modules`
   - Папка проекта целиком

2. Используйте WSL2 (Windows Subsystem for Linux) для лучшей производительности:
```cmd
wsl --install
```
Перезагрузите компьютер после установки, затем установите проект в WSL.

3. Очистите кеш npm:
```cmd
npm cache clean --force
```

---

## 🎯 Чек-лист запуска

- [ ] Node.js установлен (v18+)
- [ ] MongoDB запущен
- [ ] `.env` создан и настроен
- [ ] `npm install` выполнен в корне проекта
- [ ] `npm install` выполнен в `frontend\`
- [ ] `npm install adm-zip music-metadata` выполнен
- [ ] `DISABLE_TELEGRAM_AUTH=true` в `.env` (для разработки)
- [ ] Backend запущен (`npm run server`)
- [ ] Frontend запущен (`cd frontend && npm run dev`)
- [ ] Браузер открыт на `http://localhost:5173`
- [ ] Приложение работает!

---

## 📚 Дополнительные ресурсы

- [Node.js документация](https://nodejs.org/docs/)
- [MongoDB документация](https://www.mongodb.com/docs/)
- [Vite документация](https://vitejs.dev/)
- [React документация](https://react.dev/)
- [Express.js документация](https://expressjs.com/)

---

## 🆘 Поддержка

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

1. Проверьте логи в консоли backend и frontend
2. Проверьте `.env` файлы
3. Очистите `node_modules` и переустановите:
   ```cmd
   REM Удалить node_modules
   rmdir /s /q node_modules
   rmdir /s /q frontend\node_modules
   
   REM Переустановить зависимости
   npm install
   cd frontend
   npm install
   cd ..
   ```
4. Создайте issue в репозитории

---

**Удачной разработки! 🚀**