112 lines
5.0 KiB
Plaintext
112 lines
5.0 KiB
Plaintext
# Правила разработки проекта 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`
|
||
|