From 88ed4b3580f0d25185755eaebdc2ec52be6245af Mon Sep 17 00:00:00 2001 From: DosAi Date: Sun, 2 Nov 2025 16:09:30 +0300 Subject: [PATCH] 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 --- .cursorrules | 83 ++++++++++ README.md | 109 +++++++++++++ CHANGELOG.md => docs/CHANGELOG.md | 3 + docs/KNOWLEDGE_BASE.md | 247 ++++++++++++++++++++++++++++++ PLAN.md => docs/PLAN.md | 0 docs/PROJECT_RULES.md | 93 +++++++++++ frontend/app/layout.tsx | 4 +- 7 files changed, 537 insertions(+), 2 deletions(-) create mode 100644 .cursorrules create mode 100644 README.md rename CHANGELOG.md => docs/CHANGELOG.md (91%) create mode 100644 docs/KNOWLEDGE_BASE.md rename PLAN.md => docs/PLAN.md (100%) create mode 100644 docs/PROJECT_RULES.md diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..670fd8f --- /dev/null +++ b/.cursorrules @@ -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` + diff --git a/README.md b/README.md new file mode 100644 index 0000000..46875bf --- /dev/null +++ b/README.md @@ -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 + diff --git a/CHANGELOG.md b/docs/CHANGELOG.md similarity index 91% rename from CHANGELOG.md rename to docs/CHANGELOG.md index b27ee9f..448a400 100644 --- a/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -46,4 +46,7 @@ ## Добавлено после первоначального релиза - **Калькулятор свечей**: Добавлен полнофункциональный пример калькулятора для свечей (`frontend/calculators/candles/`) с демонстрацией всех возможностей системы +- **Исправления для production build**: Устранены ошибки ESLint (удален `any`, добавлен комментарий для ``) +- **База знаний и правила проекта**: Создана документация для контекста разработки (`.cursorrules`, `docs/KNOWLEDGE_BASE.md`, `docs/PROJECT_RULES.md`) +- **Организация документации**: Вся документация собрана в папке `docs/` diff --git a/docs/KNOWLEDGE_BASE.md b/docs/KNOWLEDGE_BASE.md new file mode 100644 index 0000000..9ab5464 --- /dev/null +++ b/docs/KNOWLEDGE_BASE.md @@ -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) => 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 = `🧼 Расчёт мыла:\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 на бэкенде + diff --git a/PLAN.md b/docs/PLAN.md similarity index 100% rename from PLAN.md rename to docs/PLAN.md diff --git a/docs/PROJECT_RULES.md b/docs/PROJECT_RULES.md new file mode 100644 index 0000000..9c11217 --- /dev/null +++ b/docs/PROJECT_RULES.md @@ -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. ❌ Коммит без проверки линтера и сборки + diff --git a/frontend/app/layout.tsx b/frontend/app/layout.tsx index 1e6f515..e946f82 100644 --- a/frontend/app/layout.tsx +++ b/frontend/app/layout.tsx @@ -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({