Руководство по локальной установке FlowCraft

Это подробное руководство по локальной установке и запуску FlowCraft для разработки и тестирования. Следуя этим инструкциям, вы сможете настроить полноценную среду разработки на вашем локальном компьютере.

Предварительные требования

Перед началом установки убедитесь, что ваша система соответствует следующим требованиям:

Системные требования

Операционная система:
- Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
- macOS 11+
- Windows 10/11 с WSL2
Оперативная память: минимум 4 ГБ (рекомендуется 8+ ГБ)
Дисковое пространство: минимум 10 ГБ свободного места
Процессор: 2+ ядра

Необходимое программное обеспечение

Python: версия 3.10 или выше
Node.js: версия 16 или выше
npm: версия 7 или выше
Git: последняя стабильная версия
PostgreSQL: версия 13 или выше
Redis: версия 6 или выше

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

Linux (Ubuntu/Debian)

bash

# Обновление пакетов
sudo apt update
sudo apt upgrade -y

# Установка Python и инструментов разработки
sudo apt install -y python3 python3-pip python3-venv python3-dev

# Установка Node.js и npm
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs

# Установка Git
sudo apt install -y git

# Установка PostgreSQL
sudo apt install -y postgresql postgresql-contrib

# Установка Redis
sudo apt install -y redis-server

# Проверка установленных версий
python3 --version
node --version
npm --version
git --version
psql --version
redis-cli --version

macOS

Для macOS рекомендуется использовать Homebrew:

bash

# Установка Homebrew (если не установлен)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Установка Python
brew install python

# Установка Node.js и npm
brew install node

# Установка Git
brew install git

# Установка PostgreSQL
brew install postgresql
brew services start postgresql

# Установка Redis
brew install redis
brew services start redis

# Проверка установленных версий
python3 --version
node --version
npm --version
git --version
psql --version
redis-cli --version

Windows с WSL2

Установите WSL2, следуя официальной инструкции Microsoft
Установите Ubuntu 20.04 из Microsoft Store
Откройте терминал Ubuntu и выполните команды для Linux (Ubuntu/Debian), приведенные выше

Настройка базы данных PostgreSQL

bash

# Вход в консоль PostgreSQL
sudo -u postgres psql

# Создание пользователя и базы данных
CREATE USER flowcraft WITH PASSWORD 'your_secure_password';
CREATE DATABASE flowcraft OWNER flowcraft;
ALTER USER flowcraft CREATEDB;

# Выход из консоли PostgreSQL
\q

Клонирование репозитория

bash

# Клонирование репозитория
git clone https://github.com/your-organization/flowcraft.git
cd flowcraft

Настройка Python-окружения

bash

# Создание виртуального окружения
python3 -m venv venv

# Активация виртуального окружения
# Для Linux/macOS:
source venv/bin/activate
# Для Windows:
# venv\Scripts\activate

# Установка зависимостей Python
pip install -r requirements.txt
pip install -r requirements-dev.txt

Настройка переменных окружения

Создайте файл .env в корневой директории проекта:

# Основные настройки
DEBUG=True
SECRET_KEY=your_development_secret_key
ALLOWED_HOSTS=localhost,127.0.0.1

# База данных
DATABASE_URL=postgresql://flowcraft:your_secure_password@localhost:5432/flowcraft

# Redis
REDIS_URL=redis://localhost:6379/0

# Настройки для разработки
DEVELOPMENT_MODE=True
AUTO_RELOAD=True
LOG_LEVEL=DEBUG

Настройка фронтенда

bash

# Переход в директорию фронтенда
cd frontend

# Установка зависимостей Node.js
npm install

# Сборка фронтенда для разработки
npm run dev

# Вернуться в корневую директорию проекта
cd ..

Применение миграций базы данных

bash

# Применение миграций
python manage.py migrate

# Создание суперпользователя
python manage.py createsuperuser

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

Запуск бэкенда

bash

# Запуск сервера разработки
python manage.py runserver

Сервер будет доступен по адресу http://127.0.0.1:8000/

Запуск фоновых задач (Celery)

Откройте новый терминал, активируйте виртуальное окружение и выполните:

bash

# Запуск Celery Worker
celery -A flowcraft worker --loglevel=info

Откройте еще один терминал, активируйте виртуальное окружение и выполните:

bash

# Запуск Celery Beat для периодических задач
celery -A flowcraft beat --loglevel=info

Запуск фронтенда в режиме разработки

Откройте новый терминал и выполните:

bash

# Переход в директорию фронтенда
cd frontend

# Запуск сервера разработки фронтенда
npm run dev

Фронтенд будет доступен по адресу http://localhost:3000/

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

Ознакомьтесь с основной структурой проекта:

flowcraft/
├── api/                  # API приложение
│   ├── endpoints/        # Эндпоинты API
│   ├── models/           # Модели данных
│   └── serializers/      # Сериализаторы
├── core/                 # Ядро системы
│   ├── engine/           # Движок выполнения
│   ├── models/           # Основные модели
│   └── services/         # Сервисы
├── frontend/             # Фронтенд приложение
│   ├── public/           # Статические файлы
│   ├── src/              # Исходный код
│   └── package.json      # Зависимости фронтенда
├── integrations/         # Интеграции с внешними сервисами
│   ├── connectors/       # Коннекторы к API
│   └── nodes/            # Узлы для рабочих процессов
├── plugins/              # Система плагинов
│   ├── base/             # Базовые классы плагинов
│   └── registry/         # Реестр плагинов
├── workflows/            # Управление рабочими процессами
│   ├── models/           # Модели рабочих процессов
│   └── execution/        # Выполнение рабочих процессов
├── manage.py             # Скрипт управления Django
├── requirements.txt      # Зависимости Python
└── .env                  # Переменные окружения

Разработка и тестирование

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

bash

# Запуск всех тестов
pytest

# Запуск тестов с покрытием
pytest --cov=.

# Запуск конкретного теста
pytest tests/test_specific_file.py

Линтинг и форматирование кода

bash

# Проверка стиля кода Python
flake8

# Форматирование кода Python
black .

# Проверка типов
mypy .

# Линтинг JavaScript/TypeScript
cd frontend
npm run lint

# Форматирование JavaScript/TypeScript
cd frontend
npm run format

Создание миграций

После изменения моделей данных необходимо создать и применить миграции:

bash

# Создание миграций
python manage.py makemigrations

# Применение миграций
python manage.py migrate

Работа с API

Документация API

После запуска сервера разработки, документация API доступна по адресу:

Swagger UI: http://127.0.0.1:8000/api/docs/
ReDoc: http://127.0.0.1:8000/api/redoc/

Аутентификация в API

Для работы с API необходимо получить токен аутентификации:

bash

# Получение токена через curl
curl -X POST http://127.0.0.1:8000/api/v1/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "your_username", "password": "your_password"}'

Полученный токен необходимо использовать в заголовке Authorization при запросах к API:

bash

curl -X GET http://127.0.0.1:8000/api/v1/workflows/ \
  -H "Authorization: Bearer your_token_here"

Создание и запуск рабочих процессов

Создание рабочего процесса через API

bash

curl -X POST http://127.0.0.1:8000/api/v1/workflows/ \
  -H "Authorization: Bearer your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Workflow",
    "description": "My first workflow",
    "nodes": [
      {
        "id": "node1",
        "type": "start",
        "position": {"x": 100, "y": 100}
      },
      {
        "id": "node2",
        "type": "http_request",
        "position": {"x": 300, "y": 100},
        "parameters": {
          "url": "https://jsonplaceholder.typicode.com/posts/1",
          "method": "GET"
        }
      },
      {
        "id": "node3",
        "type": "end",
        "position": {"x": 500, "y": 100}
      }
    ],
    "connections": [
      {
        "source": "node1",
        "target": "node2"
      },
      {
        "source": "node2",
        "target": "node3"
      }
    ]
  }'

Запуск рабочего процесса через API

bash

curl -X POST http://127.0.0.1:8000/api/v1/workflows/1/execute/ \
  -H "Authorization: Bearer your_token_here"

Отладка

Отладка бэкенда

Для отладки бэкенда можно использовать встроенный отладчик Python:

python

import pdb; pdb.set_trace()

Или использовать более современный breakpoint():

python

breakpoint()

Отладка фронтенда

Для отладки фронтенда используйте инструменты разработчика в браузере (F12) и консоль JavaScript.

В коде можно использовать:

javascript

console.log('Debug message', variable);
debugger; // Установка точки останова

Логирование

Для логирования в Python используйте стандартный модуль logging:

python

import logging

logger = logging.getLogger(__name__)
logger.debug('Debug message')
logger.info('Info message')
logger.warning('Warning message')
logger.error('Error message')

Создание собственных узлов

Структура узла

Создайте новый файл в директории integrations/nodes/:

python

# integrations/nodes/my_custom_node.py
from core.nodes import BaseNode

class MyCustomNode(BaseNode):
    """
    Мой пользовательский узел для выполнения специфической операции.
    """
    
    # Метаданные узла
    type_name = 'my_custom_node'
    display_name = 'My Custom Node'
    description = 'Performs a custom operation'
    icon = 'custom-icon'
    category = 'Custom'
    
    # Определение входных параметров
    parameters_schema = {
        'type': 'object',
        'properties': {
            'input_param': {
                'type': 'string',
                'title': 'Input Parameter',
                'description': 'An input parameter for the node',
                'default': ''
            }
        },
        'required': ['input_param']
    }
    
    # Определение выходных данных
    output_schema = {
        'type': 'object',
        'properties': {
            'result': {
                'type': 'string',
                'title': 'Result',
                'description': 'The result of the operation'
            }
        }
    }
    
    async def execute(self, context):
        """
        Выполнение операции узла.
        
        Args:
            context: Контекст выполнения, содержащий входные параметры и данные.
            
        Returns:
            dict: Результат выполнения узла.
        """
        # Получение входных параметров
        input_param = context.parameters.get('input_param')
        
        # Выполнение операции
        result = f"Processed: {input_param}"
        
        # Возврат результата
        return {
            'result': result
        }

Регистрация узла

Добавьте узел в реестр узлов в файле integrations/nodes/__init__.py:

python

from .my_custom_node import MyCustomNode

# Регистрация узлов
NODE_REGISTRY = {
    # Существующие узлы...
    'my_custom_node': MyCustomNode,
}

Создание собственных интеграций

Структура интеграции

Создайте новую директорию в integrations/connectors/:

integrations/connectors/my_service/
├── __init__.py
├── connector.py
├── nodes/
│   ├── __init__.py
│   ├── actions.py
│   └── triggers.py
└── auth.py

Реализация коннектора

python

# integrations/connectors/my_service/connector.py
import aiohttp
from core.connectors import BaseConnector

class MyServiceConnector(BaseConnector):
    """
    Коннектор для интеграции с My Service API.
    """
    
    name = 'my_service'
    display_name = 'My Service'
    description = 'Integration with My Service API'
    
    def __init__(self, api_key=None, base_url=None):
        self.api_key = api_key or ''
        self.base_url = base_url or 'https://api.myservice.com/v1'
    
    async def request(self, method, endpoint, **kwargs):
        """
        Выполнение запроса к API.
        
        Args:
            method: HTTP метод (GET, POST, etc.)
            endpoint: Эндпоинт API
            **kwargs: Дополнительные параметры запроса
            
        Returns:
            dict: Ответ API
        """
        url = f"{self.base_url}/{endpoint}"
        headers = {
            'Authorization': f'Bearer {self.api_key}',
            'Content-Type': 'application/json',
            **kwargs.pop('headers', {})
        }
        
        async with aiohttp.ClientSession() as session:
            async with session.request(method, url, headers=headers, **kwargs) as response:
                response.raise_for_status()
                return await response.json()
    
    async def get_resources(self):
        """
        Получение списка ресурсов.
        
        Returns:
            list: Список ресурсов
        """
        return await self.request('GET', 'resources')
    
    async def create_resource(self, data):
        """
        Создание нового ресурса.
        
        Args:
            data: Данные ресурса
            
        Returns:
            dict: Созданный ресурс
        """
        return await self.request('POST', 'resources', json=data)

Реализация узлов для интеграции

python

# integrations/connectors/my_service/nodes/actions.py
from core.nodes import BaseNode

class GetResourcesNode(BaseNode):
    """
    Узел для получения списка ресурсов из My Service.
    """
    
    type_name = 'my_service_get_resources'
    display_name = 'Get Resources'
    description = 'Retrieves a list of resources from My Service'
    icon = 'my-service-icon'
    category = 'My Service'
    
    parameters_schema = {
        'type': 'object',
        'properties': {
            'limit': {
                'type': 'integer',
                'title': 'Limit',
                'description': 'Maximum number of resources to retrieve',
                'default': 10
            }
        }
    }
    
    output_schema = {
        'type': 'object',
        'properties': {
            'resources': {
                'type': 'array',
                'title': 'Resources',
                'description': 'List of resources'
            }
        }
    }
    
    async def execute(self, context):
        # Получение коннектора
        connector = context.get_connector('my_service')
        
        # Получение параметров
        limit = context.parameters.get('limit', 10)
        
        # Выполнение запроса
        resources = await connector.get_resources()
        
        # Ограничение количества ресурсов
        resources = resources[:limit]
        
        # Возврат результата
        return {
            'resources': resources
        }

Регистрация интеграции

Добавьте интеграцию в реестр интеграций в файле integrations/connectors/__init__.py:

python

from .my_service.connector import MyServiceConnector
from .my_service.nodes.actions import GetResourcesNode

# Регистрация коннекторов
CONNECTOR_REGISTRY = {
    # Существующие коннекторы...
    'my_service': MyServiceConnector,
}

# Регистрация узлов
NODE_REGISTRY.update({
    # Существующие узлы...
    'my_service_get_resources': GetResourcesNode,
})

Создание собственных плагинов

Структура плагина

Создайте новую директорию в plugins/:

plugins/my_plugin/
├── __init__.py
├── plugin.py
├── nodes/
│   ├── __init__.py
│   └── custom_nodes.py
└── static/
    ├── icon.svg
    └── styles.css

Реализация плагина

python

# plugins/my_plugin/plugin.py
from plugins.base import BasePlugin

class MyPlugin(BasePlugin):
    """
    Мой пользовательский плагин.
    """
    
    id = 'my_plugin'
    name = 'My Plugin'
    description = 'A custom plugin for FlowCraft'
    version = '1.0.0'
    author = 'Your Name'
    
    def initialize(self):
        """
        Инициализация плагина.
        """
        # Регистрация узлов
        from .nodes.custom_nodes import MyPluginNode
        self.register_node('my_plugin_node', MyPluginNode)
        
        # Регистрация статических файлов
        self.register_static_dir('static')
        
        # Регистрация хуков
        self.register_hook('workflow.before_execute', self.on_workflow_execute)
    
    async def on_workflow_execute(self, workflow):
        """
        Хук, вызываемый перед выполнением рабочего процесса.
        
        Args:
            workflow: Рабочий процесс
        """
        self.logger.info(f"Workflow {workflow.id} is about to execute")

Реализация узлов плагина

python

# plugins/my_plugin/nodes/custom_nodes.py
from core.nodes import BaseNode

class MyPluginNode(BaseNode):
    """
    Пользовательский узел, предоставляемый плагином.
    """
    
    type_name = 'my_plugin_node'
    display_name = 'My Plugin Node'
    description = 'A custom node provided by My Plugin'
    icon = 'my-plugin-icon'
    category = 'My Plugin'
    
    parameters_schema = {
        'type': 'object',
        'properties': {
            'message': {
                'type': 'string',
                'title': 'Message',
                'description': 'A message to process',
                'default': 'Hello, world!'
            }
        }
    }
    
    output_schema = {
        'type': 'object',
        'properties': {
            'processed_message': {
                'type': 'string',
                'title': 'Processed Message',
                'description': 'The processed message'
            }
        }
    }
    
    async def execute(self, context):
        # Получение параметров
        message = context.parameters.get('message', 'Hello, world!')
        
        # Обработка сообщения
        processed_message = message.upper()
        
        # Возврат результата
        return {
            'processed_message': processed_message
        }

Регистрация плагина

Добавьте плагин в реестр плагинов в файле plugins/__init__.py:

python

from .my_plugin.plugin import MyPlugin

# Регистрация плагинов
PLUGIN_REGISTRY = {
    # Существующие плагины...
    'my_plugin': MyPlugin,
}

Часто задаваемые вопросы

Как изменить порт сервера разработки?

bash

python manage.py runserver 8080

Как сбросить базу данных и начать с чистого листа?

bash

# Удаление базы данных
sudo -u postgres psql -c "DROP DATABASE flowcraft;"

# Создание новой базы данных
sudo -u postgres psql -c "CREATE DATABASE flowcraft OWNER flowcraft;"

# Применение миграций
python manage.py migrate

# Создание суперпользователя
python manage.py createsuperuser

Как создать дамп базы данных?

bash

pg_dump -U flowcraft flowcraft > flowcraft_dump.sql

Как восстановить базу данных из дампа?

bash

psql -U flowcraft flowcraft < flowcraft_dump.sql

Как обновить зависимости проекта?

bash

# Обновление зависимостей Python
pip install -r requirements.txt --upgrade

# Обновление зависимостей Node.js
cd frontend
npm update

Как запустить только определенные тесты?

bash

# Запуск тестов по маске имени
pytest -k "test_workflow"

# Запуск тестов из определенного модуля
pytest tests/test_workflows.py

# Запуск конкретного теста
pytest tests/test_workflows.py::test_workflow_execution

Устранение неполадок

Проблемы с базой данных

Проблема: Ошибка подключения к базе данных.

Решение:

Убедитесь, что PostgreSQL запущен:
bash
```
sudo systemctl status postgresql
```
Проверьте настройки подключения в файле .env

Убедитесь, что пользователь и база данных созданы:

bash

sudo -u postgres psql -c "\l"  # Список баз данных
sudo -u postgres psql -c "\du"  # Список пользователей

Проблемы с Redis

Проблема: Ошибка подключения к Redis.

Решение:

Убедитесь, что Redis запущен:
bash
```
sudo systemctl status redis
```
Проверьте настройки подключения в файле .env
Проверьте доступность Redis:
bash
```
redis-cli ping
```

Проблемы с фронтендом

Проблема: Ошибки сборки фронтенда.

Решение:

Убедитесь, что все зависимости установлены:
bash
```
cd frontend
npm install
```
Очистите кэш npm:
bash
```
npm cache clean --force
```
Удалите директорию node_modules и установите зависимости заново:
bash
```
rm -rf node_modules
npm install
```

Проблемы с миграциями

Проблема: Ошибки при применении миграций.

Решение:

Проверьте, какие миграции применены:
bash
```
python manage.py showmigrations
```
Попробуйте применить миграции по одной:
bash
```
python manage.py migrate app_name migration_name
```
В крайнем случае, сбросьте базу данных и начните с чистого листа.

Заключение

Это руководство предоставляет основную информацию для начала работы с FlowCraft в режиме разработки. Для получения более подробной информации обратитесь к официальной документации или исходному коду проекта.

Если у вас возникли вопросы или проблемы, не описанные в этом руководстве, обратитесь к команде разработчиков или создайте issue в репозитории проекта.

Руководство по локальной установке FlowCraft ​

Предварительные требования ​

Системные требования ​

Необходимое программное обеспечение ​

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

Linux (Ubuntu/Debian) ​

macOS ​

Windows с WSL2 ​

Настройка базы данных PostgreSQL ​

Клонирование репозитория ​

Настройка Python-окружения ​

Настройка переменных окружения ​

Настройка фронтенда ​

Применение миграций базы данных ​

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

Запуск бэкенда ​

Запуск фоновых задач (Celery) ​

Запуск фронтенда в режиме разработки ​

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

Разработка и тестирование ​

Запуск тестов ​

Линтинг и форматирование кода ​

Создание миграций ​

Работа с API ​

Документация API ​

Аутентификация в API ​

Создание и запуск рабочих процессов ​

Создание рабочего процесса через API ​

Запуск рабочего процесса через API ​

Отладка ​

Отладка бэкенда ​

Отладка фронтенда ​

Логирование ​

Создание собственных узлов ​

Структура узла ​

Регистрация узла ​

Создание собственных интеграций ​

Структура интеграции ​

Реализация коннектора ​

Реализация узлов для интеграции ​

Регистрация интеграции ​

Создание собственных плагинов ​

Структура плагина ​

Реализация плагина ​

Реализация узлов плагина ​

Регистрация плагина ​

Часто задаваемые вопросы ​

Как изменить порт сервера разработки? ​

Как сбросить базу данных и начать с чистого листа? ​

Как создать дамп базы данных? ​

Как восстановить базу данных из дампа? ​

Как обновить зависимости проекта? ​

Как запустить только определенные тесты? ​

Устранение неполадок ​

Проблемы с базой данных ​

Проблемы с Redis ​

Проблемы с фронтендом ​

Проблемы с миграциями ​

Заключение ​

Руководство по локальной установке FlowCraft

Предварительные требования

Системные требования

Необходимое программное обеспечение

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

Linux (Ubuntu/Debian)

macOS

Windows с WSL2

Настройка базы данных PostgreSQL

Клонирование репозитория

Настройка Python-окружения

Настройка переменных окружения

Настройка фронтенда

Применение миграций базы данных

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

Запуск бэкенда

Запуск фоновых задач (Celery)

Запуск фронтенда в режиме разработки

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

Разработка и тестирование

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

Линтинг и форматирование кода

Создание миграций

Работа с API

Документация API

Аутентификация в API

Создание и запуск рабочих процессов

Создание рабочего процесса через API

Запуск рабочего процесса через API

Отладка

Отладка бэкенда

Отладка фронтенда

Логирование

Создание собственных узлов

Структура узла

Регистрация узла

Создание собственных интеграций

Структура интеграции

Реализация коннектора

Реализация узлов для интеграции

Регистрация интеграции

Создание собственных плагинов

Структура плагина

Реализация плагина

Реализация узлов плагина

Регистрация плагина

Часто задаваемые вопросы

Как изменить порт сервера разработки?

Как сбросить базу данных и начать с чистого листа?

Как создать дамп базы данных?

Как восстановить базу данных из дампа?

Как обновить зависимости проекта?

Как запустить только определенные тесты?

Устранение неполадок

Проблемы с базой данных

Проблемы с Redis

Проблемы с фронтендом

Проблемы с миграциями

Заключение