NextNodeTemplate/docs/PROJECT_RULES.md

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

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

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:

# Переключиться на 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:

# Переключиться на 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:

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)

# 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):

   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 коде