docs: Add knowledge base, project rules and organize documentation
- Created .cursorrules for development context - Added KNOWLEDGE_BASE.md with architecture details - Added PROJECT_RULES.md with coding standards - Updated README.md with project overview - Moved CHANGELOG.md and PLAN.md to docs/ folder - Updated CHANGELOG.md with latest changes
This commit is contained in:
parent
8d5ecd401d
commit
88ed4b3580
83
.cursorrules
Normal file
83
.cursorrules
Normal file
@ -0,0 +1,83 @@
|
||||
# Правила разработки проекта 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`
|
||||
|
||||
109
README.md
Normal file
109
README.md
Normal file
@ -0,0 +1,109 @@
|
||||
# DoSoap - Модульная система калькуляторов себестоимости
|
||||
|
||||
Веб-приложение для расчета себестоимости продукции ручной работы (мыло, свечи и др.) с интеграцией Telegram-бота.
|
||||
|
||||
## 🚀 Возможности
|
||||
|
||||
- **Модульная архитектура**: Легкое добавление новых калькуляторов
|
||||
- **Универсальный движок**: Один компонент для всех калькуляторов
|
||||
- **Telegram интеграция**: Автоматическая отправка расчетов в Telegram
|
||||
- **Динамические формы**: Поля и расчеты определяются конфигурацией
|
||||
- **Группировка полей**: Правильное расположение блоков расчета
|
||||
|
||||
## 📁 Структура проекта
|
||||
|
||||
```
|
||||
DoSoap/
|
||||
├── frontend/ # Next.js приложение
|
||||
│ ├── app/ # App Router страницы
|
||||
│ ├── calculators/ # Модули калькуляторов
|
||||
│ │ ├── soap/ # Калькулятор мыла
|
||||
│ │ └── candles/ # Калькулятор свечей
|
||||
│ ├── components/ # React компоненты
|
||||
│ ├── lib/ # Утилиты и типы
|
||||
│ └── docs/ # Документация
|
||||
├── backend/ # Express + Telegram Bot
|
||||
└── docs/ # Документация проекта
|
||||
```
|
||||
|
||||
## 🛠️ Технологический стек
|
||||
|
||||
**Frontend:**
|
||||
- Next.js 15.3.3 (App Router)
|
||||
- React 19
|
||||
- TypeScript 5
|
||||
- Tailwind CSS 4
|
||||
|
||||
**Backend:**
|
||||
- Express.js 5
|
||||
- node-telegram-bot-api
|
||||
- multer (загрузка файлов)
|
||||
|
||||
## 📦 Установка и запуск
|
||||
|
||||
### Локальная разработка
|
||||
|
||||
```bash
|
||||
# Frontend
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
# Открыть http://localhost:3000
|
||||
|
||||
# Backend
|
||||
cd backend
|
||||
npm install
|
||||
node bot.js
|
||||
# Сервер запустится на http://localhost:3001
|
||||
```
|
||||
|
||||
### Production сборка
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run build
|
||||
# Статические файлы в frontend/out/
|
||||
```
|
||||
|
||||
## 🎯 Добавление нового калькулятора
|
||||
|
||||
1. Создать папку `frontend/calculators/[название]/`
|
||||
2. Создать `config.ts` с конфигурацией
|
||||
3. Опционально создать `calc.ts` для сложных расчетов
|
||||
4. Зарегистрировать в `frontend/lib/calculator-registry.ts`
|
||||
|
||||
Подробные инструкции: [`docs/calculator-creation-guide.md`](docs/calculator-creation-guide.md)
|
||||
|
||||
## 📚 Документация
|
||||
|
||||
- **[Руководство по созданию калькуляторов](frontend/docs/calculator-creation-guide.md)** - Подробная инструкция
|
||||
- **[База знаний](docs/KNOWLEDGE_BASE.md)** - Архитектура и технические детали
|
||||
- **[Правила проекта](docs/PROJECT_RULES.md)** - Стандарты кодирования
|
||||
- **[История изменений](CHANGELOG.md)** - Changelog проекта
|
||||
- **[План работ](PLAN.md)** - Отслеживание задач
|
||||
|
||||
## 🔧 Деплой
|
||||
|
||||
Проект деплоится на сервер через PM2:
|
||||
|
||||
```bash
|
||||
# На сервере
|
||||
cd ~/projects/DoSoapCalc
|
||||
git pull origin dev
|
||||
cd frontend && npm run build
|
||||
pm2 restart dosoap-frontend dosoap-backend
|
||||
```
|
||||
|
||||
## 🧪 Доступные калькуляторы
|
||||
|
||||
- **Калькулятор мыла** 🧼 - Расчет себестоимости мыла ручной работы
|
||||
- **Калькулятор свечей** 🕯️ - Расчет себестоимости свечей
|
||||
|
||||
## 📝 Лицензия
|
||||
|
||||
ISC
|
||||
|
||||
## 👤 Автор
|
||||
|
||||
DosAi
|
||||
|
||||
@ -46,4 +46,7 @@
|
||||
## Добавлено после первоначального релиза
|
||||
|
||||
- **Калькулятор свечей**: Добавлен полнофункциональный пример калькулятора для свечей (`frontend/calculators/candles/`) с демонстрацией всех возможностей системы
|
||||
- **Исправления для production build**: Устранены ошибки ESLint (удален `any`, добавлен комментарий для `<img>`)
|
||||
- **База знаний и правила проекта**: Создана документация для контекста разработки (`.cursorrules`, `docs/KNOWLEDGE_BASE.md`, `docs/PROJECT_RULES.md`)
|
||||
- **Организация документации**: Вся документация собрана в папке `docs/`
|
||||
|
||||
247
docs/KNOWLEDGE_BASE.md
Normal file
247
docs/KNOWLEDGE_BASE.md
Normal file
@ -0,0 +1,247 @@
|
||||
# База знаний проекта DoSoap
|
||||
|
||||
## Назначение проекта
|
||||
|
||||
DoSoap - это веб-приложение для расчета себестоимости продукции ручной работы. Пользователи могут:
|
||||
1. Выбрать калькулятор (мыло, свечи и т.д.)
|
||||
2. Ввести параметры продукта
|
||||
3. Получить автоматический расчет себестоимости
|
||||
4. Отправить результат в Telegram-бота
|
||||
|
||||
## Архитектура системы
|
||||
|
||||
### Frontend (Next.js)
|
||||
|
||||
**Структура:**
|
||||
```
|
||||
frontend/
|
||||
app/ # Next.js App Router
|
||||
page.tsx # Главная страница с меню
|
||||
layout.tsx # Общий layout
|
||||
calculators/ # Модули калькуляторов
|
||||
soap/ # Калькулятор мыла
|
||||
config.ts # Конфигурация
|
||||
calc.ts # Функции расчета
|
||||
candles/ # Калькулятор свечей
|
||||
config.ts
|
||||
calc.ts
|
||||
components/ # React компоненты
|
||||
CalculatorEngine.tsx # Универсальный движок
|
||||
CalculatorMenu.tsx # Меню выбора
|
||||
lib/ # Утилиты и типы
|
||||
calculator-types.ts # TypeScript типы
|
||||
calculator-registry.ts # Реестр калькуляторов
|
||||
docs/ # Документация
|
||||
calculator-creation-guide.md
|
||||
```
|
||||
|
||||
**Технологии:**
|
||||
- Next.js 15.3.3 с App Router
|
||||
- React 19
|
||||
- TypeScript 5
|
||||
- Tailwind CSS 4
|
||||
- Статический экспорт (`output: 'export'`)
|
||||
|
||||
### Backend (Express + Telegram)
|
||||
|
||||
**Файлы:**
|
||||
- `backend/bot.js` - основной файл бэкенда
|
||||
|
||||
**Функционал:**
|
||||
- Обработка POST запросов от фронтенда
|
||||
- Интеграция с Telegram Bot API
|
||||
- Загрузка и отправка фотографий
|
||||
- Форматирование сообщений для Telegram
|
||||
|
||||
**API:**
|
||||
- `POST /api/submit` - принимает данные расчета и отправляет в Telegram
|
||||
- Команда `/myid` - возвращает chat_id пользователя
|
||||
|
||||
## Типы данных
|
||||
|
||||
### FieldConfig
|
||||
Определяет поле ввода в калькуляторе:
|
||||
```typescript
|
||||
{
|
||||
id: string; // Уникальный ID
|
||||
type: 'text' | 'number' | 'file';
|
||||
label: string; // Название поля
|
||||
defaultValue?: string;
|
||||
gridCols?: 1 | 2; // Ширина в grid
|
||||
required?: boolean;
|
||||
accept?: string; // Для файлов
|
||||
groupName?: string; // Группа для группировки
|
||||
showStepAfter?: string; // ID расчета после группы
|
||||
}
|
||||
```
|
||||
|
||||
### CalculationStep
|
||||
Шаг расчета (например, "Себестоимость основы"):
|
||||
```typescript
|
||||
{
|
||||
id: string;
|
||||
name: string;
|
||||
formula: (values: Record<string, number>) => number;
|
||||
formulaDescription?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### SubtotalConfig
|
||||
Подитог (например, "Итого себестоимость"):
|
||||
```typescript
|
||||
{
|
||||
id: string;
|
||||
name: string;
|
||||
formula: (values, steps) => number;
|
||||
highlight?: boolean; // Выделить визуально
|
||||
formulaDescription?: string;
|
||||
}
|
||||
```
|
||||
|
||||
### AdditionalCalculation
|
||||
Дополнительный расчет (например, "Цена за 100г"):
|
||||
```typescript
|
||||
{
|
||||
id: string;
|
||||
name: string;
|
||||
formula: (values, steps, subtotals, additional?) => number;
|
||||
formulaDescription?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Поток работы калькулятора
|
||||
|
||||
1. **Выбор калькулятора**: Пользователь выбирает калькулятор в меню
|
||||
2. **Загрузка конфигурации**: `CalculatorEngine` получает конфигурацию из реестра
|
||||
3. **Рендеринг полей**: Динамически создаются поля на основе `fields` из конфигурации
|
||||
4. **Ввод данных**: Пользователь заполняет поля
|
||||
5. **Расчет**: При изменении полей автоматически пересчитываются все шаги, подитоги и дополнительные расчеты
|
||||
6. **Отправка**: Данные отправляются на бэкенд через `/api/submit`
|
||||
7. **Telegram**: Бэкенд отправляет форматированное сообщение в Telegram
|
||||
|
||||
## Группировка полей
|
||||
|
||||
Поля можно группировать для правильного расположения блоков расчета:
|
||||
|
||||
```typescript
|
||||
{
|
||||
id: 'weight',
|
||||
groupName: 'base', // Группа "base"
|
||||
showStepAfter: 'base', // После группы показать расчет "base"
|
||||
}
|
||||
{
|
||||
id: 'price',
|
||||
groupName: 'base', // Тот же группа
|
||||
}
|
||||
// Блок расчета "Себестоимость основы" появится здесь
|
||||
```
|
||||
|
||||
## Форматирование Telegram сообщений
|
||||
|
||||
Каждый калькулятор может иметь функцию `formatTelegramMessage`:
|
||||
|
||||
```typescript
|
||||
formatTelegramMessage: (values, steps, subtotals, additional) => {
|
||||
let text = `🧼 <b>Расчёт мыла:</b>\n\n`;
|
||||
text += `💵 Себестоимость: ${subtotals.total.toFixed(1)} ₽\n`;
|
||||
return text;
|
||||
}
|
||||
```
|
||||
|
||||
Если функция не указана, используется универсальное форматирование.
|
||||
|
||||
## API интеграция
|
||||
|
||||
### Определение URL
|
||||
|
||||
Фронтенд автоматически определяет URL API:
|
||||
```typescript
|
||||
const isLocalhost = window.location.hostname === 'localhost';
|
||||
const apiUrl = isLocalhost
|
||||
? 'http://localhost:3001/api/submit'
|
||||
: 'https://api-dosoap.duckdns.org/api/submit';
|
||||
```
|
||||
|
||||
### Формат запроса
|
||||
|
||||
```typescript
|
||||
FormData {
|
||||
chat_id: string;
|
||||
calculator_id: string;
|
||||
calculator_name: string;
|
||||
telegram_message: string; // Готовое сообщение
|
||||
photo?: File; // Опциональное фото
|
||||
// ... остальные поля
|
||||
}
|
||||
```
|
||||
|
||||
## Добавление нового калькулятора
|
||||
|
||||
### Шаг 1: Создать модуль
|
||||
```bash
|
||||
mkdir frontend/calculators/my-calc
|
||||
touch frontend/calculators/my-calc/config.ts
|
||||
touch frontend/calculators/my-calc/calc.ts # опционально
|
||||
```
|
||||
|
||||
### Шаг 2: Создать конфигурацию
|
||||
См. `frontend/docs/calculator-creation-guide.md`
|
||||
|
||||
### Шаг 3: Зарегистрировать
|
||||
В `frontend/lib/calculator-registry.ts`:
|
||||
```typescript
|
||||
import { myCalcConfig } from '@/calculators/my-calc/config';
|
||||
registerCalculator(myCalcConfig);
|
||||
```
|
||||
|
||||
## Деплой
|
||||
|
||||
### Сервер
|
||||
- IP: 192.168.0.19
|
||||
- Пользователь: dosai
|
||||
- Путь: ~/projects/DoSoapCalc
|
||||
|
||||
### Процессы PM2
|
||||
- `dosoap-frontend` - Next.js приложение
|
||||
- `dosoap-backend` - Express сервер
|
||||
|
||||
### Команды деплоя
|
||||
```bash
|
||||
# На сервере
|
||||
cd ~/projects/DoSoapCalc
|
||||
git pull origin dev
|
||||
cd frontend && npm run build
|
||||
pm2 restart dosoap-frontend dosoap-backend
|
||||
```
|
||||
|
||||
## Обработка ошибок
|
||||
|
||||
### Расчеты
|
||||
Все формулы должны проверять:
|
||||
- Деление на ноль → вернуть 0
|
||||
- Пустые значения → вернуть 0
|
||||
- NaN → вернуть 0
|
||||
|
||||
Пример:
|
||||
```typescript
|
||||
if (weight <= 0 || price <= 0) return 0;
|
||||
return (weight / 1000) * price;
|
||||
```
|
||||
|
||||
### API запросы
|
||||
```typescript
|
||||
try {
|
||||
const res = await fetch(apiUrl, { method: 'POST', body: formData });
|
||||
if (!res.ok) throw new Error('Server error');
|
||||
} catch (err) {
|
||||
alert('Ошибка сети при отправке расчёта');
|
||||
}
|
||||
```
|
||||
|
||||
## Известные особенности
|
||||
|
||||
1. **Статический экспорт**: Next.js собирается в статические файлы, нет серверного рендеринга
|
||||
2. **Telegram Bot Token**: Хранится в переменных окружения на сервере
|
||||
3. **Chat ID**: Передается через URL параметр `?chat_id=...` или через Telegram бота
|
||||
4. **Фото**: Отправляются через FormData, обрабатываются multer на бэкенде
|
||||
|
||||
93
docs/PROJECT_RULES.md
Normal file
93
docs/PROJECT_RULES.md
Normal file
@ -0,0 +1,93 @@
|
||||
# Правила проекта 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` - разработка
|
||||
|
||||
### Коммиты:
|
||||
- Используй понятные сообщения коммитов
|
||||
- Один коммит = одно логическое изменение
|
||||
|
||||
### Перед коммитом:
|
||||
1. Проверь линтер: `npm run lint`
|
||||
2. Убедись, что сборка проходит: `npm run build`
|
||||
3. Проверь типы: TypeScript должен компилироваться без ошибок
|
||||
|
||||
## Деплой на сервер
|
||||
|
||||
### Порядок действий:
|
||||
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. ❌ Коммит без проверки линтера и сборки
|
||||
|
||||
@ -13,8 +13,8 @@ const geistMono = Geist_Mono({
|
||||
});
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: "Create Next App",
|
||||
description: "Generated by create next app",
|
||||
title: "Калькулятор DoSoap",
|
||||
description: "Калькулятор себестоимости ручных изделий",
|
||||
};
|
||||
|
||||
export default function RootLayout({
|
||||
|
||||
Loading…
Reference in New Issue
Block a user