Skip to content

Development

Jump to bottom
mrSaT13 edited this page Mar 24, 2026 · 1 revision

🔧 Разработка KumaFlow

Руководство для контрибьюторов

📋 Требования

Зависимость Версия Установка
Node.js ≥18.x nvm
pnpm ≥8.x npm install -g pnpm
Git ≥2.30 git-scm.com

🚀 Локальная разработка

1. Клонирование

git clone https://github.com/mrSaT13/kumaflow.git
cd kumaflow

2. Установка зависимостей

pnpm install

3. Запуск в режиме разработки

# Основной процесс + рендерер с hot-reload
pnpm run electron:dev

# Только фронтенд (быстрее для тестов)
pnpm run dev:web

4. Сборка

# Все платформы
pnpm run build

# Конкретная ОС
pnpm run build:win    # Windows (.exe)
pnpm run build:mac    # macOS (.dmg)
pnpm run build:linux  # Linux (.deb + AppImage)

🏗️ Архитектура проекта

kumaflow/
├── electron/           # Main процесс (Node.js)
│   ├── main.ts        # Точка входа Electron
│   ├── ipc/           # IPC-обработчики
│   └── services/      # Фоновые сервисы
│
├── src/               # Renderer процесс (React + Vite)
│   ├── components/    # UI-компоненты
│   ├── pages/         # Страницы приложения
│   ├── hooks/         # React-хуки
│   ├── lib/           # Утилиты, API-клиенты
│   └── styles/        # Глобальные стили, темы
│
├── resources/         # Статические ресурсы
├── cypress/           # E2E-тесты
└── build/             # Скрипты сборки

Ключевые технологии

🔷 Frontend: React 18 + TypeScript + Vite + TailwindCSS
🔷 Backend: Electron (Node.js) + IPC
🔷 ML: Python-микросервис + ONNX Runtime
🔷 State: Zustand + React Query
🔷 Testing: Cypress (E2E) + Vitest (unit)

🧪 Тестирование

# Unit-тесты
pnpm run test:unit

# E2E-тесты
pnpm run test:e2e

# Линтинг и форматирование
pnpm run lint
pnpm run format

# Проверка типов
pnpm run typecheck

📐 Стиль кода

TypeScript

  • ✅ Строгий режим (strict: true)
  • ✅ Явные типы для функций и пропсов
  • ✅ Избегать any, использовать unknown

React

  • ✅ Функциональные компоненты + хуки
  • ✅ Мемоизация через React.memo, useMemo
  • ✅ Разделение логики: компоненты ↔ хуки ↔ утилиты

Коммиты

Используйте Conventional Commits:

feat(ml): добавить анализ энергии в Vibe Similarity
fix(ui): исправить отображение прогресса на мобильных
docs(wiki): обновить руководство по настройке
chore(deps): обновить Electron до 40.1.2

🤝 Процесс Pull Request

  1. Создайте issue с описанием изменения
  2. Форкните репозиторий и создайте ветку: 
    git checkout -b feat/your-feature-name
  3. Внесите изменения, добавьте тесты
  4. Убедитесь, что все проверки проходят: 
    pnpm run lint && pnpm run typecheck && pnpm run test:unit
  5. Откройте PR с описанием:
    • 🔗 Ссылка на issue
    • 📝 Что изменено
    • 🧪 Как протестировать
    • 📸 Скриншоты (для UI)

⏱️ Мы стараемся ревьювить PR в течение 3-5 дней.

🐛 Отладка

Логи приложения

Пути к логам:
• Windows: %APPDATA%\kumaflow\logs\
• macOS: ~/Library/Logs/kumaflow/
• Linux: ~/.config/kumaflow/logs/

Режим отладки Electron

# Запуск с открытыми DevTools
pnpm run electron:dev -- --remote-debugging-port=9222

# Включение подробных логов
export DEBUG=kumaflow:*
pnpm run electron:dev

Нужна помощь? Откройте Discussion или Issue

Clone this wiki locally