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

## Общая информация о проекте

DoSoap - это модульная система калькуляторов себестоимости для ручной работы (мыло, свечи и др.). Проект состоит из фронтенда (Next.js) и бэкенда (Express + Telegram Bot API).

### Архитектура

Проект использует модульную архитектуру, где каждый калькулятор - это отдельный модуль в папке `frontend/calculators/[название]/`. Каждый модуль содержит:
- `config.ts` - конфигурация калькулятора (поля, формулы, подитоги)
- `calc.ts` - опциональные функции расчета для сложной логики

### Ключевые компоненты

- `CalculatorEngine.tsx` - универсальный компонент для рендеринга любого калькулятора
- `CalculatorMenu.tsx` - меню выбора калькулятора
- `calculator-registry.ts` - реестр всех калькуляторов
- `calculator-types.ts` - типы TypeScript для системы

### Технологический стек

**Frontend:**
- Next.js 15.3.3 (App Router)
- React 19
- TypeScript 5
- Tailwind CSS 4
- ESLint

**Backend:**
- Express.js 5
- node-telegram-bot-api
- multer (для загрузки файлов)

### Важные правила кодирования

1. **Всегда используй TypeScript типы** - не используй `any`, используй строгую типизацию
2. **Модульность** - новый калькулятор = новая папка в `calculators/` с минимум 2 файлами (config.ts и опционально calc.ts)
3. **Регистрация** - каждый новый калькулятор должен быть зарегистрирован в `calculator-registry.ts`
4. **Группировка полей** - используй `groupName` и `showStepAfter` для правильного расположения блоков расчета
5. **Обработка ошибок** - все формулы должны проверять деление на ноль и пустые значения, возвращать 0 вместо NaN
6. **ESLint** - код должен проходить линтер без ошибок (особенно важно для production build)

### Структура калькулятора

```typescript
// config.ts
export const myCalculatorConfig: CalculatorConfig = {
  id: 'unique-id',
  name: 'Название',
  description: 'Описание',
  icon: '🎯',
  fields: [...], // Поля ввода
  calculationSteps: [...], // Шаги расчета
  subtotals: [...], // Подитоги
  additionalCalculations: [...], // Дополнительные расчеты
  formatTelegramMessage: (...) => string // Форматирование для Telegram
};
```

### API Endpoints

**Backend:**
- `POST /api/submit` - отправка расчета в Telegram
- Команда `/myid` - получение chat_id пользователя

**Frontend:**
- API URL определяется автоматически: localhost для разработки, продакшн для деплоя

### Деплой

Проект деплоится на сервер через:
1. `git pull` на сервере
2. `npm run build` в папке frontend
3. `pm2 restart` для перезапуска процессов

### Файлы и пути

- Документация: `docs/` (корень проекта)
- Калькуляторы: `frontend/calculators/`
- Компоненты: `frontend/components/`
- Типы и утилиты: `frontend/lib/`
- Бэкенд: `backend/bot.js`

### Git Workflow

**Стандартный процесс разработки:**
1. Все изменения разрабатываются в ветке `dev`
2. Тестирование на сервере происходит из `dev`
3. После проверки `dev` мержится в `main`
4. Используй `--no-ff` при слиянии для сохранения истории

**Перед слиянием в main обязательно:**
- Протестировать на сервере
- Проверить линтер и сборку
- Убедиться что всё работает

Подробнее: `docs/PROJECT_RULES.md`

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

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

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

Подробнее: `docs/PROJECT_RULES.md` и `docs/KNOWLEDGE_BASE.md`