# Правила проекта 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. ✅ Нет критических ошибок в консоли браузера

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

### Порядок действий:
1. Закоммитить изменения в ветку `dev`
2. Отправить на сервер: `git push origin dev`
3. На сервере: `git pull origin dev`
4. Пересобрать фронтенд: `cd frontend && npm run build`
5. Перезапустить процессы: `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. ❌ Коммит без проверки линтера и сборки