DosAi/DoSoapCalc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
DoSoapCalc/docs/PROJECT_RULES.md

7.9 KiB
Raw Permalink Blame History

Правила проекта 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:

import { myCalculatorConfig } from '@/calculators/my-calc/config';
registerCalculator(myCalculatorConfig);

Соглашения об именовании

Файлы и папки:

  • Калькуляторы: kebab-case (например: soap, candles)
  • Компоненты: PascalCase.tsx
  • Утилиты: camelCase.ts

ID полей и расчетов:

  • Используй camelCase для ID
  • Названия должны быть понятными и описательными

Работа с Git

Ветки:

  • main / master - продакшн (стабильная версия)
  • dev - разработка (активная разработка)

Стандартный Workflow разработки

1. Разработка в dev

Все новые изменения разрабатываются в ветке dev:

# Переключиться на dev
git checkout dev

# Получить последние изменения с сервера
git pull origin dev

# После внесения изменений
git add .
git commit -m "описание изменений"
git push origin dev

2. Тестирование на сервере

Перед слиянием в main обязательно тестируйте изменения на сервере:

  • Залить изменения на сервер (из dev)
  • Пересобрать фронтенд: cd frontend && npm run build
  • Перезапустить процессы: pm2 restart dosoap-frontend dosoap-backend
  • Проверить работу функционала

3. Слияние в main

После успешного тестирования слить dev в main:

# Переключиться на main
git checkout main

# Обновить локальную main
git pull origin main

# Слить dev в main
git merge dev --no-ff -m "Merge dev: краткое описание изменений"

# Отправить на сервер
git push origin main

Важно: Используйте флаг --no-ff для создания merge commit - это сохраняет историю разработки.

4. Feature-ветки (для больших изменений)

Для крупных изменений создавайте feature-ветки от dev:

git checkout dev
git checkout -b feature/new-calculator
# Работаете в feature ветке
git push origin feature/new-calculator
# Когда готово - мержите в dev
git checkout dev
git merge feature/new-calculator
git push origin dev

Коммиты:

  • Используй понятные сообщения коммитов на русском или английском
  • Один коммит = одно логическое изменение
  • Формат: тип: краткое описание
    • feat: - новая функциональность
    • fix: - исправление ошибки
    • docs: - изменения в документации
    • refactor: - рефакторинг кода
    • style: - форматирование (без изменения логики)

Перед коммитом:

  1. Проверь линтер: npm run lint
  2. Убедись, что сборка проходит: npm run build
  3. Проверь типы: TypeScript должен компилироваться без ошибок

Перед слиянием в main:

  1. ✅ Все изменения протестированы на сервере в dev
  2. ✅ Линтер не выдает ошибок
  3. ✅ Production build собирается успешно
  4. ✅ Функционал работает корректно
  5. ✅ Нет критических ошибок в консоли браузера

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

Платформы

  • Разработка: Windows с PowerShell
  • Хостинг: Ubuntu Linux сервер

Важно учитывать:

  • В PowerShell команды с && не работают, используйте ; или отдельные команды
  • Пути к файлам на Windows используют обратные слеши \, но в Git и конфигах используйте /
  • При работе через SSH с Ubuntu используйте стандартные Linux команды

Локальная разработка (Windows)

# Frontend
cd frontend
npm install
npm run dev

# Backend (в отдельном терминале)
cd backend
node bot.js

Деплой на сервер

Сервер информация:

  • ОС: Ubuntu Linux
  • Пользователь: dosai
  • Путь проекта: ~/projects/DoSoapCalc
  • Управление процессами: PM2

Порядок действий:

  1. Закоммитить изменения в ветку dev
  2. Отправить на сервер: git push origin dev
  3. Подключиться к серверу: ssh dosai@192.168.0.19
  4. На сервере (Ubuntu): 
    cd ~/projects/DoSoapCalc
git pull origin dev
cd frontend && npm run build
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. ❌ Коммит без проверки линтера и сборки