# Правила проекта

## Общие принципы

### 1. Модульность
- Структурируй код по модулям
- Избегай жестких зависимостей между модулями
- Добавление новых функций не должно ломать существующие

### 2. Типизация
- **Запрещено** использовать `any` в TypeScript
- Все типы должны быть определены явно
- Все функции должны иметь явные типы параметров и возвращаемого значения
- Используй интерфейсы для сложных структур данных

### 3. Обработка ошибок
- Все API запросы должны обрабатывать ошибки сети
- Проверяй граничные случаи (деление на ноль, пустые значения и т.д.)
- Возвращай понятные сообщения об ошибках

### 4. Форматирование кода
- Используй ESLint правила проекта
- Код должен проходить `npm run lint` без ошибок
- Production build не должен падать из-за линтера

## Структура проекта

### Frontend (Next.js)
```
frontend/
  app/               # Next.js App Router страницы
  components/        # React компоненты
  lib/              # Утилиты и типы
  docs/             # Документация фронтенда
```

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

## Соглашения об именовании

### Файлы и папки:
- Компоненты: `PascalCase.tsx`
- Утилиты: `camelCase.ts`
- Константы: `UPPER_SNAKE_CASE.ts`
- Папки: `kebab-case`

### Переменные и функции:
- Переменные: `camelCase`
- Функции: `camelCase`
- Компоненты: `PascalCase`
- Константы: `UPPER_SNAKE_CASE`

## Работа с Git

### Ветки:
- `main` / `master` - продакшн (стабильная версия)
- `dev` - разработка (активная разработка)

### Стандартный Workflow разработки

#### 1. Разработка в `dev`
Все новые изменения разрабатываются в ветке `dev`:

```bash
# Переключиться на dev
git checkout dev

# Получить последние изменения с сервера
git pull origin dev

# После внесения изменений
git add .
git commit -m "описание изменений"
git push origin dev
```

#### 2. Тестирование на сервере
Перед слиянием в `main` обязательно тестируйте изменения на сервере:
- Залить изменения на сервер (из `dev`)
- Пересобрать фронтенд: `cd frontend && npm run build`
- Перезапустить процессы: `pm2 restart <app-name>-frontend <app-name>-backend`
- Проверить работу функционала

#### 3. Слияние в `main`
После успешного тестирования слить `dev` в `main`:

```bash
# Переключиться на main
git checkout main

# Обновить локальную main
git pull origin main

# Слить dev в main
git merge dev --no-ff -m "Merge dev: краткое описание изменений"

# Отправить на сервер
git push origin main
```

**Важно**: Используйте флаг `--no-ff` для создания merge commit - это сохраняет историю разработки.

#### 4. Feature-ветки (для больших изменений)
Для крупных изменений создавайте feature-ветки от `dev`:

```bash
git checkout dev
git checkout -b feature/new-feature
# Работаете в feature ветке
git push origin feature/new-feature
# Когда готово - мержите в dev
git checkout dev
git merge feature/new-feature
git push origin dev
```

### Коммиты:
- Используй понятные сообщения коммитов на русском или английском
- Один коммит = одно логическое изменение
- Формат: `тип: краткое описание`
  - `feat:` - новая функциональность
  - `fix:` - исправление ошибки
  - `docs:` - изменения в документации
  - `refactor:` - рефакторинг кода
  - `style:` - форматирование (без изменения логики)
  - `test:` - добавление тестов
  - `chore:` - обновление зависимостей, конфигов

### Перед коммитом:
1. Проверь линтер: `npm run lint`
2. Убедись, что сборка проходит: `npm run build`
3. Проверь типы: TypeScript должен компилироваться без ошибок

### Перед слиянием в main:
1. ✅ Все изменения протестированы на сервере в `dev`
2. ✅ Линтер не выдает ошибок
3. ✅ Production build собирается успешно
4. ✅ Функционал работает корректно
5. ✅ Нет критических ошибок в консоли браузера

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

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

**Важно учитывать:**
- В PowerShell команды с `&&` не работают, используйте `;` или отдельные команды
- Пути к файлам на Windows используют обратные слеши `\`, но в Git и конфигах используйте `/`
- При работе через SSH с Ubuntu используйте стандартные Linux команды

### Локальная разработка (Windows)
```powershell
# Frontend
cd frontend
npm install
npm run dev

# Backend (в отдельном терминале)
cd backend
npm install
node server.js
```

## Деплой на сервер

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

### Порядок действий:
1. Закоммитить изменения в ветку `dev`
2. Отправить на сервер: `git push origin dev`
3. Подключиться к серверу: `ssh user@server-ip`
4. На сервере (Ubuntu):
   ```bash
   cd ~/projects/<project-name>
   git pull origin dev
   cd frontend && npm run build
   pm2 restart <app-name>-frontend <app-name>-backend
   ```

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

### Локальная разработка:
- Frontend: `npm run dev` (порт 3000)
- Backend: `node server.js` (порт 3001)

### Проверка перед деплоем:
- [ ] Все функции работают корректно
- [ ] Нет ошибок в консоли браузера
- [ ] API запросы работают
- [ ] Production build успешно собирается
- [ ] Линтер не выдает ошибок

## Запрещенные практики

1. ❌ Использование `any` в TypeScript
2. ❌ Хардкод значений, которые должны быть в конфигурации
3. ❌ Коммит без проверки линтера и сборки
4. ❌ Прямые зависимости между несвязанными модулями
5. ❌ Игнорирование ошибок ESLint в production коде