199 lines
7.9 KiB
Markdown
199 lines
7.9 KiB
Markdown
# Правила проекта DoSoap
|
||
|
||
## Общие принципы
|
||
|
||
### 1. Модульность
|
||
- Каждый калькулятор должен быть независимым модулем
|
||
- Не должно быть жестких зависимостей между калькуляторами
|
||
- Добавление нового калькулятора не должно ломать существующие
|
||
|
||
### 2. Типизация
|
||
- **Запрещено** использовать `any` в TypeScript
|
||
- Все типы должны быть определены в `calculator-types.ts`
|
||
- Все функции должны иметь явные типы параметров и возвращаемого значения
|
||
|
||
### 3. Обработка ошибок
|
||
- Все расчеты должны проверять деление на ноль
|
||
- Пустые значения должны возвращать 0, а не NaN
|
||
- API запросы должны обрабатывать ошибки сети
|
||
|
||
### 4. Форматирование кода
|
||
- Используй ESLint правила проекта
|
||
- Код должен проходить `npm run lint` без ошибок
|
||
- Production build не должен падать из-за линтера
|
||
|
||
## Структура модуля калькулятора
|
||
|
||
### Обязательные файлы:
|
||
1. `config.ts` - конфигурация калькулятора (обязательно)
|
||
2. `calc.ts` - функции расчета (опционально, только для сложной логики)
|
||
|
||
### Регистрация:
|
||
Каждый новый калькулятор должен быть зарегистрирован в `frontend/lib/calculator-registry.ts`:
|
||
```typescript
|
||
import { myCalculatorConfig } from '@/calculators/my-calc/config';
|
||
registerCalculator(myCalculatorConfig);
|
||
```
|
||
|
||
## Соглашения об именовании
|
||
|
||
### Файлы и папки:
|
||
- Калькуляторы: `kebab-case` (например: `soap`, `candles`)
|
||
- Компоненты: `PascalCase.tsx`
|
||
- Утилиты: `camelCase.ts`
|
||
|
||
### ID полей и расчетов:
|
||
- Используй `camelCase` для ID
|
||
- Названия должны быть понятными и описательными
|
||
|
||
## Работа с 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 dosoap-frontend dosoap-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-calculator
|
||
# Работаете в feature ветке
|
||
git push origin feature/new-calculator
|
||
# Когда готово - мержите в dev
|
||
git checkout dev
|
||
git merge feature/new-calculator
|
||
git push origin dev
|
||
```
|
||
|
||
### Коммиты:
|
||
- Используй понятные сообщения коммитов на русском или английском
|
||
- Один коммит = одно логическое изменение
|
||
- Формат: `тип: краткое описание`
|
||
- `feat:` - новая функциональность
|
||
- `fix:` - исправление ошибки
|
||
- `docs:` - изменения в документации
|
||
- `refactor:` - рефакторинг кода
|
||
- `style:` - форматирование (без изменения логики)
|
||
|
||
### Перед коммитом:
|
||
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
|
||
node bot.js
|
||
```
|
||
|
||
## Деплой на сервер
|
||
|
||
### Сервер информация:
|
||
- **ОС**: Ubuntu Linux
|
||
- **Пользователь**: dosai
|
||
- **Путь проекта**: `~/projects/DoSoapCalc`
|
||
- **Управление процессами**: PM2
|
||
|
||
### Порядок действий:
|
||
1. Закоммитить изменения в ветку `dev`
|
||
2. Отправить на сервер: `git push origin dev`
|
||
3. Подключиться к серверу: `ssh dosai@192.168.0.19`
|
||
4. На сервере (Ubuntu):
|
||
```bash
|
||
cd ~/projects/DoSoapCalc
|
||
git pull origin dev
|
||
cd frontend && npm run build
|
||
pm2 restart dosoap-frontend dosoap-backend
|
||
```
|
||
|
||
## Тестирование
|
||
|
||
### Локальная разработка:
|
||
- Frontend: `npm run dev` (порт 3000)
|
||
- Backend: `node bot.js` (порт 3001)
|
||
|
||
### Проверка перед деплоем:
|
||
- [ ] Все расчеты работают корректно
|
||
- [ ] Нет ошибок в консоли браузера
|
||
- [ ] Отправка в Telegram работает
|
||
- [ ] Production build успешно собирается
|
||
- [ ] Линтер не выдает ошибок
|
||
|
||
## Запрещенные практики
|
||
|
||
1. ❌ Использование `any` в TypeScript
|
||
2. ❌ Прямые импорты между калькуляторами
|
||
3. ❌ Изменение `CalculatorEngine` без обновления документации
|
||
4. ❌ Хардкод значений, которые должны быть в конфигурации
|
||
5. ❌ Коммит без проверки линтера и сборки
|
||
|