DoSoapCalc/PROJECT_INFO.md

DoSoapCalc - Сводная информация о проекте

Быстрый обзор

DoSoapCalc - система для расчёта себестоимости изделий ручной работы с веб-интерфейсом и интеграцией Telegram-бота. Проект использует модульную архитектуру для легкого добавления новых калькуляторов.

Архитектура

Структура проекта

DoSoapCalc/
├── backend/                 # Node.js + Express + Telegram Bot
│   ├── bot.js              # Главный файл - запускает бота и сервер
│   ├── config/
│   │   └── env.js          # Загрузка переменных окружения (.env)
│   ├── calculators/        # Модули калькуляторов
│   │   ├── index.js        # Регистрация всех калькуляторов
│   │   ├── soap.js         # Калькулятор мыла
│   │   └── candle.js       # Пример: калькулятор свечей
│   ├── lib/
│   │   ├── telegram.js     # Отправка сообщений в Telegram
│   │   └── validator.js    # Валидация данных форм
│   ├── routes/
│   │   └── api.js           # API маршруты (/api/submit/:calculatorType)
│   └── .env                 # Переменные окружения (не в Git)
│
└── frontend/                # Next.js + React + TypeScript
    ├── app/
    │   ├── [calculator]/    # Динамический роут для калькуляторов
    │   │   └── page.tsx    # Страница калькулятора
    │   └── page.tsx         # Редирект на /soap
    ├── components/
    │   ├── DynamicCalculator.tsx  # Универсальный компонент формы
    │   └── FormField.tsx          # Переиспользуемые поля ввода
    ├── lib/
    │   ├── calculators/     # Модули калькуляторов (frontend)
    │   │   ├── index.ts     # Регистрация калькуляторов
    │   │   ├── soap.ts      # Калькулятор мыла
    │   │   └── candle.ts    # Пример: калькулятор свечей
    │   ├── api.ts           # Отправка данных на backend
    │   └── config.ts        # Конфигурация (API URL)
    └── types/
        └── calculator.ts     # TypeScript типы

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

Backend:

• Node.js + Express
• node-telegram-bot-api (Telegram Bot)
• multer (загрузка файлов)
• dotenv (переменные окружения)
• PM2 (менеджер процессов)

Frontend:

• Next.js 15 (App Router)
• React 19
• TypeScript
• Tailwind CSS 4
• Статический экспорт (output: 'export')

Ключевые концепции

Система калькуляторов

Каждый калькулятор состоит из двух модулей (backend + frontend):

Backend модуль (backend/calculators/[name].js):

• id - уникальный идентификатор
• name - название для пользователя
• fieldSchema - схема полей формы
• calculate(data) - функция расчёта
• formatMessage(data, result) - форматирование для Telegram
• getRequiredFields() - обязательные поля
• getNumericFields() - числовые поля

Frontend модуль (frontend/lib/calculators/[name].ts):

• Та же структура, синхронная с backend
• TypeScript типы

Регистрация калькуляторов

Backend: backend/calculators/index.js

const calculators = {
  soap: require('./soap'),
  candle: require('./candle'),
};

Frontend: frontend/lib/calculators/index.ts

const calculators: Record<string, Calculator> = {
  soap: soapCalculator,
  candle: candleCalculator,
};

API Endpoints

• POST /api/submit/:calculatorType - отправка расчёта
  • Параметры: calculatorType (soap, candle, etc.)
  • Body: FormData (поля формы + опционально photo)
  • Ответ: 200 OK или ошибка

Telegram Bot

• Команда /menu - открывает Web App с калькулятором
• URL формата: {WEBAPP_BASE_URL}/{calculatorType}?chat_id={chatId}
• Отправка результатов через sendMessage или sendPhoto

Переменные окружения

Backend (.env в /backend/):

BOT_TOKEN=your_telegram_bot_token
WEBAPP_BASE_URL=https://your-domain.com
API_BASE_URL=https://api.your-domain.com
HTTP_PORT=3001
CORS_ORIGINS=https://your-domain.com

Frontend (.env.local в /frontend/):

NEXT_PUBLIC_API_BASE_URL=https://api.your-domain.com

Запуск проекта

PM2 (Production)

# Production режим (через node)
pm2 start ecosystem.config.js --env production

# Development режим (через nodemon с автоперезагрузкой)
pm2 start ecosystem.config.js --env development

# Управление
pm2 restart ecosystem.config.js
pm2 stop ecosystem.config.js
pm2 logs dosoap-backend
pm2 logs dosoap-frontend

Ручной запуск

Backend:

cd backend
npm install
# Создать .env файл
node bot.js
# или с nodemon:
nodemon bot.js

Frontend:

cd frontend
npm install
npm run dev        # Development
npm run build      # Production build
npm run export     # Статический экспорт

Динамические роуты

• /soap - калькулятор мыла
• /candle - калькулятор свечей
• /[calculatorType] - любой зарегистрированный калькулятор

Добавление нового калькулятора

1. Создать backend/calculators/[name].js с модулем
2. Создать frontend/lib/calculators/[name].ts (синхронная структура)
3. Зарегистрировать в calculators/index.js (backend) и calculators/index.ts (frontend)
4. Перезапустить процессы

Подробное руководство: CALCULATOR_GUIDE.md

Файлы конфигурации

• ecosystem.config.js - PM2 конфигурация
• .gitignore - игнорирует .env, но не .env.example
• next.config.ts - Next.js конфигурация (static export)

Логи

PM2 логи находятся в:

• Backend: ~/.pm2/logs/dosoap-backend-*.log
• Frontend: ~/.pm2/logs/dosoap-frontend-*.log

Важные детали

1. Синхронизация схем: Frontend и backend схемы полей должны совпадать
2. Рабочая директория: Backend должен запускаться из /backend/ для загрузки .env
3. CORS: Настроен для конкретных доменов через CORS_ORIGINS
4. Статический экспорт: Frontend экспортируется статически (Next.js export)
5. Фото: Поддерживается загрузка фото, отправляется в Telegram как caption

Структура данных калькулятора

Поле схемы:

{
  id: string;          // Уникальный ID
  name: string;        // Имя поля в данных
  label: string;       // Метка для пользователя
  type: 'text' | 'number';
  required: boolean;
  group?: string;      // Группировка полей (опционально)
}

Результат расчёта:

{
  [key: string]: number;  // Промежуточные значения
  total: number;         // Итоговая себестоимость (обязательно)
}

Команды Telegram бота

• /menu - открыть калькулятор (по умолчанию мыло)

Порты

• Backend: 3001 (HTTP_PORT из .env)
• Frontend: 3000 (в development), статический экспорт (production)

Безопасность

• Токен бота в .env (не в Git)
• CORS настроен для конкретных доменов
• Валидация обязательных и числовых полей на backend
• HTML форматирование в Telegram сообщениях (parse_mode: 'HTML')