211 lines
8.1 KiB
Markdown
211 lines
8.1 KiB
Markdown
# Правила проекта
|
||
|
||
## Общие принципы
|
||
|
||
### 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 коде
|
||
|