# База знаний проекта

## Назначение шаблона

Это шаблон проекта для быстрого старта новых проектов с:
- Next.js фронтендом (App Router)
- Express.js бэкендом
- TypeScript
- Tailwind CSS
- Модульной архитектурой

## Архитектура системы

### Frontend (Next.js)

**Структура:**
```
frontend/
  app/               # Next.js App Router страницы
    page.tsx         # Главная страница
    layout.tsx       # Общий layout
  components/        # React компоненты
  lib/               # Утилиты и типы
  docs/              # Документация фронтенда
```

**Технологии:**
- Next.js 15.3.3 с App Router
- React 19
- TypeScript 5
- Tailwind CSS 4
- Статический экспорт (`output: 'export'`)

### Backend (Express)

**Структура:**
```
backend/
  server.js          # Основной файл сервера
  routes/            # API маршруты (создавать по мере необходимости)
```

**Технологии:**
- Express.js 5
- body-parser для обработки запросов

## Типы данных

Все типы должны быть определены явно. Используй интерфейсы для сложных структур:

```typescript
// Пример: frontend/lib/types.ts
export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

export interface User {
  id: string;
  name: string;
  email: string;
}
```

## API интеграция

### Определение URL

Фронтенд автоматически определяет URL API:
```typescript
const isLocalhost = typeof window !== 'undefined' && window.location.hostname === 'localhost';
const apiUrl = isLocalhost
  ? 'http://localhost:3001/api'
  : 'https://your-api-domain.com/api';
```

### Пример запроса

```typescript
async function fetchData() {
  try {
    const response = await fetch(`${apiUrl}/endpoint`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ data: 'value' }),
    });
    
    if (!response.ok) {
      throw new Error('Server error');
    }
    
    const result = await response.json();
    return result;
  } catch (err) {
    console.error('API Error:', err);
    throw err;
  }
}
```

## Добавление новых функций

### Frontend компонент

1. Создать компонент в `frontend/components/`:
```typescript
// components/MyComponent.tsx
export default function MyComponent() {
  return <div>Content</div>;
}
```

2. Использовать в странице:
```typescript
// app/page.tsx
import MyComponent from '@/components/MyComponent';
```

### Backend endpoint

1. Добавить маршрут в `backend/server.js` или создать отдельный файл в `backend/routes/`:

```javascript
// backend/server.js
app.post('/api/my-endpoint', (req, res) => {
  try {
    const { data } = req.body;
    // Обработка данных
    res.json({ success: true, result: data });
  } catch (err) {
    res.status(500).json({ success: false, error: err.message });
  }
});
```

## Окружение разработки

### Платформы
- **Разработка**: Windows с PowerShell
- **Хостинг**: Ubuntu Linux

### Особенности разработки на Windows
- PowerShell не поддерживает оператор `&&` для цепочки команд
- Используйте `;` или выполняйте команды отдельно
- Пути в Git и конфигах всегда используют `/`, даже на Windows
- При работе через SSH используйте Linux команды

### Локальная разработка (Windows + PowerShell)
```powershell
# Frontend - один терминал
cd frontend
npm install
npm run dev

# Backend - отдельный терминал
cd backend
npm install
node server.js
```

## Деплой

### Сервер
- **ОС**: Ubuntu Linux
- **IP**: (настройте под себя)
- **Пользователь**: (настройте под себя)
- **Путь**: ~/projects/<project-name>
- **Управление процессами**: PM2

### Процессы PM2
- `<app-name>-frontend` - Next.js приложение (статические файлы через serve или nginx)
- `<app-name>-backend` - Express сервер

### Команды деплоя
**С локального Windows (PowerShell):**
```powershell
# Отправить изменения
git push origin dev

# Подключиться и обновить сервер (Ubuntu команды через SSH)
ssh user@server-ip "cd ~/projects/<project-name> && git pull origin dev && cd frontend && npm run build && pm2 restart <app-name>-frontend <app-name>-backend"
```

**Или на сервере напрямую (Ubuntu):**
```bash
cd ~/projects/<project-name>
git pull origin dev
cd frontend && npm run build
pm2 restart <app-name>-frontend <app-name>-backend
```

### Настройка PM2

Создайте `ecosystem.config.js` в корне проекта:

```javascript
module.exports = {
  apps: [
    {
      name: 'my-app-frontend',
      script: 'serve',
      args: '-s frontend/out -p 3000',
      cwd: './',
      env: {
        NODE_ENV: 'production'
      }
    },
    {
      name: 'my-app-backend',
      script: 'server.js',
      cwd: './backend',
      env: {
        NODE_ENV: 'production',
        PORT: 3001
      }
    }
  ]
};
```

Запуск: `pm2 start ecosystem.config.js`

## Обработка ошибок

### API запросы
```typescript
try {
  const response = await fetch(apiUrl, { method: 'POST', body: formData });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  const data = await response.json();
  return data;
} catch (err) {
  console.error('API Error:', err);
  // Показать сообщение пользователю
  throw err;
}
```

### Backend
```javascript
app.post('/api/endpoint', (req, res) => {
  try {
    // Обработка
    res.json({ success: true, data: result });
  } catch (err) {
    console.error('Error:', err);
    res.status(500).json({ success: false, error: err.message });
  }
});
```

## Известные особенности

1. **Статический экспорт**: Next.js собирается в статические файлы, нет серверного рендеринга
2. **CORS**: Настроен для разработки, адаптируйте под продакшн
3. **Порты**: Frontend 3000, Backend 3001 по умолчанию