DScoder/DOCS.md

## DOCS.md

      
    Raw
  

              DOCS.md
            
          
    TaskBot Automation Suite - Полная техническая документация

Обзор проекта

TaskBot Automation Suite - система автоматизации выполнения микрозадач на биржах заданий с развитой архитектурой управления браузерными сессиями, интеллектуальным парсингом и автоматическим выполнением задач.
Версия и статус


Текущая версия: 1.0.0-MVP
Дата последнего обновления: 2025-07-07
Статус разработки: Активная разработка (MVP фаза)
Команда разработки: Ilia Vasilchenko

Архитектура системы

Структура директорий
Task Agent/
├── main.py                          # Точка входа приложения
├── docs.md                          # Документация проекта
├── data/                            # Данные приложения
│   ├── tasks.db                     # БД задач (SQLite)
│   ├── sessions.json                # Конфигурации сессий
│   └── backup/                      # Резервные копии
├── browser_profiles/                # Профили браузеров
│   ├── session_<id>/               # Профиль конкретной сессии
│   └── ...
├── config/                          # Конфигурационные файлы
│   ├── task_templates.json         # Шаблоны определения задач
│   ├── behavior_models.json        # Модели поведения
│   └── app_config.json             # Настройки приложения
└── src/                            # Исходный код
    ├── __init__.py
    ├── agents/                     # Пользовательские агенты
    │   ├── __init__.py
    │   ├── base_user_agent.py      # Базовый класс агента
    │   └── unu_bot.py              # Агент для UNU.im
    ├── core/                       # Ядро системы
    │   ├── __init__.py
    │   ├── session_manager.py      # Управление сессиями
    │   ├── session_process.py      # Процессы сессий
    │   ├── session_config.py       # Конфигурация сессий
    │   ├── task_manager.py         # Управление задачами
    │   ├── task_parser.py          # Парсинг задач
    │   ├── behavior_engine.py      # Движок поведения
    │   ├── template_manager.py     # Управление шаблонами
    │   ├── execution_manager.py    # Управление выполнением
    │   ├── webdriver_pool.py       # Пул WebDriver
    │   ├── webdriver_fix.py        # Исправления ChromeDriver
    │   ├── async_webdriver_monitor.py
    │   ├── session_profile_manager.py     # Управление профилями браузера
    │   ├── session_statistics.py          # Статистика и метрики сессий
    │   └── anti_detection.py              # Антидетект технологии
    ├── gui/                        # Графический интерфейс
    │   ├── __init__.py
    │   ├── main_window.py          # Главное окно
    │   ├── panels/                 # Панели интерфейса
    │   │   ├── __init__.py
    │   │   ├── sessions_panel.py   # Панель управления сессиями
    │   │   ├── tasks_panel.py      # Панель задач
    │   │   ├── statistics_panel.py # ❌ НЕ РЕАЛИЗОВАН - Панель статистики
    │   │   └── settings_panel.py   # ❌ НЕ РЕАЛИЗОВАН - Панель настроек
    │   ├── dialogs/                # Диалоговые окна
    │   │   ├── __init__.py
    │   │   ├── session_dialog.py   # Диалог создания сессии
    │   │   ├── task_detail_dialog.py      # Детальный просмотр задач
    │   │   └── session_create_dialog.py   # Создание сессии
    │   ├── utils/                  # Утилиты GUI
    │   │   ├── __init__.py
    │   │   ├── theme_manager.py           # ❌ НЕ РЕАЛИЗОВАН - Управление темами
    │   │   ├── widget_utils.py            # ❌ НЕ РЕАЛИЗОВАН - Утилиты виджетов
    │   │   └── notification_manager.py
    │   └── widgets/                        #Кастомные виджеты
    │       ├── __init__.py
    │       ├── task_widget.py
    │       └── session_widget.py
    ├── models/                     # Модели данных
    │   ├── __init__.py
    │   ├── task.py                 # Модель задачи
    │   ├── session.py              # Модель сессии
    │   ├── statistics.py           # Модель данных для статистики и аналитики
    │   ├── etection_template.py    # Модели для системы шаблонов определения задач
    │   └── behavior_model.py       # Модели поведения
    ├── parsers/                    # Парсеры контента
    │   ├── __init__.py
    │   ├── base_parser.py          # Базовый парсер
    │   └── unu_exchange_parser.py  # Парсер UNU.im
    ├── executors/                  # Исполнители задач
    │   ├── __init__.py
    │   └── base_executor.py        # Базовый исполнитель
    └── utils/                      # Утилиты
        ├── __init__.py
        ├── logger.py               # Система логирования
        ├── config.py               # Менеджер конфигурации
        ├── settings.py             # Конфигурационные настройки
        └── database.py             # Работа с БД

Компонентная диаграмма

TaskBot Automation Suite
├── GUI Layer (PySide6)
├── Core Business Logic
├── Data Access Layer (SQLite)
├── External Services (WebDriver, Parsers)
└── Utilities & Configuration

Детальная структура проекта

Корневая директория

TaskBot Automation Suite/
├── main.py                     # ✅ Точка входа приложения
├── README.md                   # ✅ Основная документация
├── requirements.txt            # ✅ Зависимости Python
├── .gitignore                  # ✅ Конфигурация Git
├── config/
│   └── settings.json          # ✅ Основная конфигурация
├── data/
│   ├── tasks.db              # ✅ База данных задач
│   ├── sessions.db           # ✅ База данных сессий  
│   └── backups/              # ✅ Резервные копии БД
├── logs/                     # ✅ Директория логов
├── temp/                     # ✅ Временные файлы
├── screenshots/              # ✅ Скриншоты процессов
└── browser_profiles/         # ✅ Профили браузеров

Модуль src/core/ (Основная бизнес-логика)

src/core/
├── __init__.py                    # ✅ Инициализация модуля
├── session_manager.py             # ✅ РЕАЛИЗОВАН - Центральный менеджер сессий
├── session_config.py              # ✅ РЕАЛИЗОВАН - Конфигурация сессий
├── session_process.py             # ✅ РЕАЛИЗОВАН - Процессы браузерных сессий
├── session_profile_manager.py     # ✅ РЕАЛИЗОВАН - Управление профилями браузера
├── session_statistics.py          # ✅ РЕАЛИЗОВАН - Статистика и метрики сессий
├── task_manager.py                # ✅ РЕАЛИЗОВАН - Управление жизненным циклом задач
├── anti_detection.py              # ✅ РЕАЛИЗОВАН - Антидетект технологии
├── user_agent_manager.py          # ❌ НЕ РЕАЛИЗОВАН - Управление User Agent'ами
└── behavior_engine.py             # ❌ НЕ РЕАЛИЗОВАН - Движок выполнения поведений

Ключевые классы в src/core/:
SessionManager (session_manager.py):

Управление множественными браузерными сессиями
Интеграция с WebDriver (Chrome/Firefox)
Методы: create_session(), start_session(), stop_session(), get_webdriver()

SessionProcess (session_process.py):

Управление отдельным процессом браузера
WebDriver инициализация и мониторинг
Антидетект настройки браузера

TaskManager (task_manager.py):

SQLite интеграция для задач
Методы: save_task(), get_all_tasks(), _row_to_task()
Автоматические миграции схемы БД

Модуль src/models/ (Модели данных)

src/models/
├── __init__.py                # ✅ Экспорт моделей
├── session.py                 # ✅ РЕАЛИЗОВАН - Модель браузерной сессии
├── task.py                    # ✅ РЕАЛИЗОВАН - Модель задачи с расширенными полями
├── user_agent.py              # ❌ НЕ РЕАЛИЗОВАН - Модель User Agent
├── behavior_model.py          # ❌ НЕ РЕАЛИЗОВАН - Модель поведения
└── detection_template.py      # ❌ НЕ РЕАЛИЗОВАН - Шаблоны определения

Ключевые модели:
Session (session.py):
@dataclass
class Session:
    session_id: str
    name: str
    status: SessionStatus
    browser_type: BrowserType
    platform_type: PlatformType
    created_at: datetime
    last_active: Optional[datetime]
    config: Optional[SessionConfig]
Task (task.py):
@dataclass  
class Task:
    task_id: str
    task_name: str
    task_type: str
    description: str
    reward: str
    status: TaskStatus
    source_url: str = ""
    target_links: List[str] = field(default_factory=list)
    # + дополнительные поля для аналитики
Модуль src/parsers/ (Парсеры бирж)

src/parsers/
├── __init__.py                # ✅ Экспорт парсеров
├── base_parser.py             # ✅ РЕАЛИЗОВАН - Базовый класс парсера
└── unu_exchange_parser.py     # ✅ РЕАЛИЗОВАН - Парсер биржи unu.im

UnuExchangeParser (unu_exchange_parser.py):

Специализированный парсер для unu.im
Поддержка кнопки "Показать ещё"
Извлечение детальной информации о задачах
Интеграция с SessionManager для WebDriver доступа

Модуль src/executors/ (Исполнители задач)

src/executors/
├── __init__.py                # ✅ Инициализация исполнителей
├── base_executor.py           # ✅ ЧАСТИЧНО - Базовый класс исполнителя
├── task_executor.py           # ✅ ЧАСТИЧНО - Основной исполнитель задач
├── platform_executors/       # ✅ Платформо-специфичные исполнители
│   ├── __init__.py
│   ├── telegram_executor.py  # ❌ НЕ РЕАЛИЗОВАН
│   ├── vk_executor.py         # ❌ НЕ РЕАЛИЗОВАН
│   └── youtube_executor.py    # ❌ НЕ РЕАЛИЗОВАН
└── behavior_executors/        # ❌ НЕ РЕАЛИЗОВАН - Исполнители поведений
    ├── subscribe_executor.py
    ├── like_executor.py
    └── comment_executor.py

Модуль src/gui/ (Графический интерфейс)

src/gui/
├── __init__.py                     # ✅ Инициализация GUI
├── main_window.py                  # ✅ РЕАЛИЗОВАН - Главное окно приложения
├── panels/                         # ✅ Панели интерфейса
│   ├── __init__.py                # ✅ Экспорт панелей
│   ├── sessions_panel.py          # ✅ РЕАЛИЗОВАН - Панель управления сессиями  
│   ├── tasks_panel.py             # ✅ РЕАЛИЗОВАН - Панель управления задачами
│   ├── statistics_panel.py        # ❌ НЕ РЕАЛИЗОВАН - Панель статистики
│   └── settings_panel.py          # ❌ НЕ РЕАЛИЗОВАН - Панель настроек
├── dialogs/                        # ✅ Диалоговые окна
│   ├── __init__.py                # ✅ Экспорт диалогов
│   ├── task_detail_dialog.py      # ✅ РЕАЛИЗОВАН - Детальный просмотр задач
│   ├── session_create_dialog.py   # ✅ ЧАСТИЧНО - Создание сессии
│   └── settings_dialog.py         # ❌ НЕ РЕАЛИЗОВАН - Настройки
├── utils/                          # ✅ Утилиты GUI
│   ├── __init__.py                # ✅ Инициализация утилит
│   ├── notification_manager.py    # ✅ РЕАЛИЗОВАН - Система уведомлений
│   ├── theme_manager.py           # ❌ НЕ РЕАЛИЗОВАН - Управление темами
│   └── widget_utils.py            # ❌ НЕ РЕАЛИЗОВАН - Утилиты виджетов
└── widgets/                        # ❌ НЕ РЕАЛИЗОВАН - Кастомные виджеты
    ├── __init__.py
    ├── task_widget.py
    └── session_widget.py

Ключевые GUI компоненты:
MainWindow (main_window.py):

Центральное окно с табами
Инициализация всех панелей
Обработка событий приложения
Интеграция с основными менеджерами

SessionsPanel (sessions_panel.py):

Таблица всех сессий с статусами
Кнопки управления: Создать, Запустить, Остановить, Удалить
Real-time обновление статусов
Интеграция с SessionManager

TasksPanel (tasks_panel.py):

Таблица спаршенных задач
Фильтрация по типу, платформе, статусу
Кнопки: Загрузить задачи, Запустить, Детали
Интеграция с TaskManager и парсерами

Модуль src/utils/ (Утилиты)

src/utils/
├── __init__.py                # ✅ Инициализация утилит
├── config.py                  # ✅ РЕАЛИЗОВАН - Менеджер конфигурации
├── database.py                # ✅ РЕАЛИЗОВАН - Менеджер базы данных (legacy)
├── logger.py                  # ✅ РЕАЛИЗОВАН - Система логирования
├── file_utils.py              # ❌ НЕ РЕАЛИЗОВАН - Файловые операции
└── validation.py              # ❌ НЕ РЕАЛИЗОВАН - Валидация данных

ConfigManager (config.py):

Чтение/запись JSON конфигурации
Методы: get(), set(), get_logging_config(), get_tasks_config()
Поддержка вложенных настроек

Logger (logger.py):

Структурированное логирование
Ротация файлов логов
Уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL

Технические детали компонентов

Система сессий

Жизненный цикл сессии:
CREATED → STARTING → ACTIVE → AUTHENTICATED → WORKING → STOPPED → ERROR

SessionConfig содержит:

Настройки браузера (User-Agent, viewport, языки)
Антидетект параметры
Профили и cookies
Прокси настройки

SessionStatistics отслеживает:

Временные метрики:

session_start_time - время запуска сессии
session_end_time - время остановки сессии
uptime_minutes - общее время работы
last_task_time - время последней выполненной задачи


Производительные метрики:

tasks_completed - количество успешно выполненных задач
tasks_failed - количество неудачных задач
tasks_total - общее количество обработанных задач
success_rate - процент успешности выполнения
average_task_time - среднее время выполнения задачи


Финансовые метрики:

total_earned - общий заработок
total_spent - общие расходы
net_profit - чистая прибыль
total_earnings - алиас для совместимости


Системные метрики:

pages_visited - количество посещенных страниц
errors_count - количество ошибок
warnings_count - количество предупреждений
execution_attempts - количество попыток выполнения


SessionManager (src/core/session_manager.py)

Назначение: Централизованное управление браузерными сессиями
Ключевые методы:

create_session() - создание новой сессии
start_session() - запуск сессии с браузером
stop_session() - остановка сессии
list_sessions() - получение списка сессий
get_profile_statistics() - статистика профилей

Зависимости:

Session модель из src/models/session.py
SessionConfig из src/core/session_config.py
SessionProcess из src/core/session_process.py

Session (src/models/session.py)

Назначение: Модель данных сессии браузера
Ключевые поля:

session_id - уникальный идентификатор
name - название сессии
status - текущий статус (CREATED, ACTIVE, STOPPED, etc.)
auth_status - статус авторизации
config - конфигурация сессии
process_id, browser_port - системная информация

Ключевые методы:

create() - класс-метод создания сессии
update_status() - обновление статуса
to_dict(), from_dict() - сериализация

SessionProcess (src/core/session_process.py)

Назначение: Управление процессом браузера для конкретной сессии
Функции:

Запуск Chrome с персистентным профилем
Мониторинг состояния процесса
Управление WebDriver соединением

Система управления задачами

TaskManager предоставляет полный жизненный цикл управления задачами:
Основные методы:
# Сохранение и получение
save_task(task: Task) -> bool
get_task(task_id: str) -> Optional[Task]
get_all_tasks() -> List[Task]

# Статистика
get_tasks_statistics() -> Dict[str, Any]

# Внутренние методы
_row_to_task(row: sqlite3.Row) -> Optional[Task]
_safe_json_loads(json_string: str) -> list
_safe_datetime_parse(datetime_string: str) -> datetime
Схема базы данных tasks:
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,
    source_url TEXT,
    task_type TEXT,
    task_name TEXT,
    description TEXT,
    report_requirements TEXT,
    reward TEXT,
    target_links TEXT,  -- JSON массив
    verification_time TEXT,
    start_execution_url TEXT,
    
    -- Обработанные данные
    reward_amount REAL,
    reward_currency TEXT,
    platform_detected TEXT,
    keywords TEXT,  -- JSON массив
    
    -- Управление системой
    status TEXT,
    priority_score REAL DEFAULT 0.0,
    pattern_match TEXT,
    validation_errors TEXT,  -- JSON массив
    
    -- Метаданные
    parsed_at TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    
    -- Выполнение
    assigned_session_id TEXT,
    execution_attempts INTEGER DEFAULT 0,
    last_execution_result TEXT
);
Индексы для оптимизации:

idx_tasks_status - по статусу задач
idx_tasks_type - по типу задач
idx_tasks_platform - по платформе
idx_tasks_priority - по приоритету

TaskManager (src/core/task_manager.py)

Назначение: Управление жизненным циклом задач
База данных: SQLite (data/tasks.db)
Ключевые методы:

save_task() - сохранение задачи
get_all_tasks() - получение всех задач
get_tasks_by_session() - задачи для конкретной сессии
update_task_status() - обновление статуса задачи
save_tasks_with_deduplication() - сохранение с дедупликацией

Схема БД задач:
CREATE TABLE tasks (
    task_id TEXT PRIMARY KEY,
    source_url TEXT,
    task_type TEXT,
    task_name TEXT,
    description TEXT,
    report_requirements TEXT,
    reward TEXT,
    target_links TEXT,
    verification_time TEXT,
    start_execution_url TEXT,
    reward_amount REAL,
    reward_currency TEXT,
    platform_detected TEXT,
    keywords TEXT,
    status TEXT,
    priority_score REAL DEFAULT 0.0,
    pattern_match TEXT,
    validation_errors TEXT,
    parsed_at TIMESTAMP,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    assigned_session_id TEXT,
    execution_attempts INTEGER DEFAULT 0,
    last_execution_result TEXT,
    detection_status TEXT DEFAULT "not_detected",
    lifecycle_status TEXT DEFAULT "parsed",
    behavior_model_id TEXT,
    template_match_results TEXT
);
Task (src/models/task.py)

Назначение: Модель данных задачи
Ключевые enum'ы:

TaskStatus - статусы задач (PARSED, IN_PROGRESS, COMPLETED, etc.)
TaskType - типы задач (подписка, лайк, репост, etc.)
TaskPriority - приоритеты (LOW, NORMAL, HIGH, URGENT)
Platform - платформы (TELEGRAM, VK, INSTAGRAM, etc.)

Система парсинга

UnuExchangeParser содержит специализированную логику для unu.im:
Основные возможности:

Извлечение списка задач с главной страницы
Автоматическое расширение списка через кнопку "Показать ещё"
Детальный парсинг каждой задачи
Определение типа задачи и целевой платформы
Извлечение финансовой информации

Селекторы CSS для unu.im:
TASK_CARD_SELECTOR = ".task-card"
LOAD_MORE_BUTTON = ".load-more-btn"
TASK_TITLE_SELECTOR = ".task-title"
TASK_REWARD_SELECTOR = ".reward-amount"
TASK_PLATFORM_SELECTOR = ".platform-icon"
Процесс парсинга:

Получение WebDriver из SessionManager
Переход на страницу задач
Прокрутка и клики "Показать ещё" (настраиваемое количество)
Извлечение HTML каждой задачи
Парсинг структурированных данных
Создание объектов Task
Возврат списка задач

UnuExchangeParser (src/parsers/unu_exchange_parser.py)

Назначение: Парсинг задач с биржи UNU.im
Ключевые возможности:

Расширение списка задач через кнопку "Показать ещё"
Дедупликация по task_id
Обязательная привязка задач к сессиям
Извлечение метаданных (тип задачи, платформа, награда)

Ключевые методы:

fetch_tasks_with_deduplication() - основной метод парсинга
parse_tasks_page() - парсинг HTML страницы
_assign_session_to_task() - привязка задачи к сессии

Система агентов

Архитектура агентов

Базовый класс: BaseUserAgent (src/agents/base_user_agent.py)
Реализация: UnuBot (src/agents/unu_bot.py)
Управление агентами (src/agents/__init__.py)

Функции:

get_available_agents() - список доступных агентов
get_available_agents_info() - детальная информация об агентах
create_user_agent() - создание экземпляра агента
Кэширование информации об агентах для производительности

Система GUI

MainWindow (src/gui/main_window.py):

Архитектура: QTabWidget с четырьмя основными вкладками
Инициализация панелей: Динамическая проверка зависимостей
Обработка ошибок: Fallback на placeholder панели при сбоях
Интеграция: Прямая связь с core компонентами через app_instance

SessionsPanel (src/gui/panels/sessions_panel.py):

Таблица сессий: QTableWidget с колонками [ID, Имя, Статус, Тип браузера, Создано, Активность]
Кнопки управления: Создать, Запустить, Остановить, Удалить, Обновить
Real-time обновление: QTimer каждые 5 секунд
Цветовая индикация: Статусы отображаются разными цветами

TasksPanel (src/gui/panels/tasks_panel.py):

Таблица задач: 10 колонок [ID, Тип, Название, Платформа, Награда, Сложность, Приоритет, Статус, Время, Действия]
Функции парсинга: Интеграция с UnuExchangeParser через TaskParsingWorker
Фильтрация: По типу, платформе, статусу, текстовый поиск
Контекстное меню: Запуск, детали, копирование ID
Настройки парсинга: Диалог конфигурации количества кликов "Показать ещё"

MainWindow (src/gui/main_window.py)

Назначение: Главное окно приложения с многовкладочным интерфейсом
SessionsPanel (src/gui/panels/sessions_panel.py)

Назначение: Панель управления сессиями
Функции:

Отображение списка сессий в таблице
Создание/редактирование/удаление сессий
Запуск/остановка/перезапуск сессий
Автообновление каждые 5 секунд
Контекстное меню для быстрых действий

TasksPanel (src/gui/panels/tasks_panel.py)

Назначение: Панель управления задачами
Функции:

Отображение задач в многовкладочном интерфейсе
Вкладка "Все задачи" и отдельные вкладки для каждой сессии
Парсинг задач для выбранной сессии
Система сигналов для обновления интерфейса

SessionDialog (src/gui/dialogs/session_dialog.py)

Назначение: Диалог создания/редактирования сессии
Вкладки:

Основные настройки (название, User Agent)
Настройки браузера
Антидетект настройки
Прокси настройки

API интерфейсы

Core API

SessionManager API:
# Управление жизненным циклом
create_session(name: str, config: SessionConfig) -> str
start_session(session_id: str) -> bool
stop_session(session_id: str) -> bool
delete_session(session_id: str, cleanup_profile: bool = None) -> bool

# Получение информации
list_sessions() -> List[Session]
get_session(session_id: str) -> Optional[Session]
get_session_status(session_id: str) -> Dict[str, Any]

# WebDriver доступ
get_webdriver(session_id: str) -> Optional[object]
get_webdriver_with_validation(session_id: str) -> Optional[object]
check_webdriver_availability(session_id: str) -> bool

# Диагностика
diagnose_session_issues(session_id: str) -> Dict[str, Any]
get_debug_info(session_id: str) -> Dict[str, Any]
TaskManager API:
# CRUD операции
save_task(task: Task) -> bool
get_task(task_id: str) -> Optional[Task]
get_all_tasks() -> List[Task]
delete_task(task_id: str) -> bool

# Массовые операции
save_tasks(tasks: List[Task]) -> int
get_tasks_by_status(status: TaskStatus) -> List[Task]
get_tasks_by_platform(platform: str) -> List[Task]

# Статистика и аналитика
get_tasks_statistics() -> Dict[str, Any]
get_platform_distribution() -> Dict[str, int]
get_status_distribution() -> Dict[str, int]

# Системные операции
_init_database() -> None
_migrate_database() -> None
debug_database_content() -> None
GUI Events API

Сигналы SessionsPanel:
session_selected = Signal(str)        # ID выбранной сессии
session_started = Signal(str)         # Сессия запущена
session_stopped = Signal(str)         # Сессия остановлена
session_created = Signal(str)         # Новая сессия создана
Сигналы TasksPanel:
task_selected = Signal(str)           # ID выбранной задачи
task_started = Signal(str)            # Задача запущена
task_completed = Signal(str)          # Задача завершена
tasks_parsed = Signal(list)           # Новые задачи спаршены
Конфигурация системы

Основной файл конфигурации (config/settings.json)

{
  "application": {
    "name": "TaskBot Automation Suite",
    "version": "1.0.0-MVP",
    "debug_mode": false,
    "auto_start_sessions": false
  },
  "logging": {
    "level": "INFO",
    "logs_dir": "logs",
    "max_file_size": "10MB",
    "backup_count": 5,
    "format": "%(asctime)s | %(levelname)s | %(message)s"
  },
  "database": {
    "tasks_db_path": "data/tasks.db",
    "backup_enabled": true,
    "backup_interval": 3600,
    "backup_retention_days": 30
  },
  "sessions": {
    "default_browser": "chrome",
    "headless": false,
    "profile_dir": "browser_profiles",
    "webdriver_timeout": 30,
    "page_load_timeout": 30,
    "implicit_wait": 10
  },
  "parsing": {
    "default_delay": 2.0,
    "max_retries": 3,
    "load_more_clicks": 3,
    "scroll_before_click": true,
    "request_timeout": 30
  },
  "gui": {
    "auto_refresh_interval": 30,
    "notification_duration": 5000,
    "window_geometry": {
      "width": 1200,
      "height": 800,
      "x": 100,
      "y": 100
    }
  },
  "anti_detection": {
    "rotate_user_agent": true,
    "random_delays": true,
    "human_like_behavior": true,
    "stealth_mode": true
  }
}
Переменные окружения

# Опциональные переменные окружения
TASKBOT_CONFIG_PATH=./config/settings.json
TASKBOT_LOG_LEVEL=INFO
TASKBOT_HEADLESS=false
TASKBOT_PROFILE_DIR=./browser_profiles
TASKBOT_DATA_DIR=./data
Установка и запуск

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

Минимальные требования:

ОС: Windows 10/11 (x64), macOS 10.15+, Ubuntu 18.04+
Python: 3.8+
RAM: 4GB минимум
Дисковое пространство: 2GB свободного места
Интернет: Постоянное подключение для WebDriver и парсинга

Рекомендуемые требования:

RAM: 8GB+
CPU: Многоядерный процессор
SSD: Для быстрой работы с базой данных

Пошаговая установка

1. Клонирование и подготовка проекта

# Создание рабочей директории
mkdir "TaskBot Automation Suite"
cd "TaskBot Automation Suite"

# Копирование файлов проекта
# (файлы должны быть скопированы в соответствии со структурой)
2. Установка зависимостей

# Установка основных зависимостей
pip install PySide6>=6.5.0
pip install selenium>=4.15.0
pip install webdriver-manager>=4.0.0
pip install beautifulsoup4>=4.12.0
pip install requests>=2.31.0

# Или из requirements.txt (если создан)
pip install -r requirements.txt
3. Подготовка конфигурации

# Создание необходимых директорий
mkdir -p config data logs browser_profiles temp screenshots backups

# Создание базового конфигурационного файла
# (config/settings.json должен быть создан с базовыми настройками)
4. Первый запуск

# Запуск приложения
python main.py

# Запуск в консольном режиме (если GUI недоступен)
python main.py --console
Верификация установки

После запуска должны выполняться следующие проверки:

Инициализация компонентов:

✅ PySide6 найден - GUI режим доступен
✅ Менеджер конфигурации инициализирован
✅ Система логирования инициализирована
✅ Менеджер сессий инициализирован
✅ Парсер задач инициализирован
✅ Система антидетект инициализирована


GUI интерфейс:

✅ GUI интерфейс инициализирован
✅ Функциональная панель сессий загружена
✅ Функциональная панель задач загружена


Базы данных:

✅ База данных задач инициализирована
✅ Схема базы данных актуальна

Примеры использования

Создание и запуск сессии

# Программный доступ к API
from src.core.session_manager import session_manager
from src.core.session_config import SessionConfig

# Создание конфигурации сессии
config = SessionConfig(
    browser_type=BrowserType.CHROME,
    headless=False,
    user_agent="custom_agent",
    viewport_width=1920,
    viewport_height=1080
)

# Создание сессии
session_id = session_manager.create_session("Тестовая сессия", config)

# Запуск сессии
success = session_manager.start_session(session_id)

if success:
    print(f"Сессия {session_id} успешно запущена")
    
    # Получение WebDriver для работы
    driver = session_manager.get_webdriver(session_id)
    if driver:
        driver.get("https://unu.im/tasks/search")
Парсинг задач

from src.parsers.unu_exchange_parser import UnuExchangeParser
from src.core.task_manager import task_manager

# Создание парсера
parser = UnuExchangeParser(session_manager)

# Парсинг задач из активной сессии
tasks = parser.fetch_tasks_from_session(session_id)

# Сохранение задач в базу данных
saved_count = 0
for task in tasks:
    if task_manager.save_task(task):
        saved_count += 1

print(f"Сохранено {saved_count} из {len(tasks)} задач")
Работа с GUI компонентами

# Программное управление GUI панелями
from src.gui.panels.tasks_panel import TasksPanel
from src.gui.panels.sessions_panel import SessionsPanel

# В контексте главного окна
class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        
        # Инициализация панелей
        self.sessions_panel = SessionsPanel(self, self)
        self.tasks_panel = TasksPanel(self, self)
        
        # Подключение сигналов
        self.sessions_panel.session_started.connect(self.on_session_started)
        self.tasks_panel.task_selected.connect(self.on_task_selected)
    
    def on_session_started(self, session_id: str):
        print(f"Сессия {session_id} запущена через GUI")
    
    def on_task_selected(self, task_id: str):
        print(f"Выбрана задача {task_id}")
Безопасность и антидетект

Встроенные функции защиты

AntiDetectionManager (src/core/anti_detection.py):

User-Agent ротация: Автоматическая смена отпечатков браузера
Viewport рандомизация: Случайные размеры окна браузера
Человекоподобное поведение: Имитация естественных движений мыши
Случайные задержки: Вариативные интервалы между действиями
Stealth режим: Скрытие автоматизации от детекторов

Настройки безопасности

# Конфигурация антидетект в SessionConfig
config = SessionConfig(
    # Основные настройки браузера
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
    viewport_width=random.randint(1200, 1920),
    viewport_height=random.randint(800, 1080),
    
    # Антидетект параметры
    disable_blink_features=True,
    disable_extensions=False,
    disable_default_apps=True,
    disable_component_update=True,
    
    # Прокси настройки (опционально)
    proxy_enabled=False,
    proxy_host="",
    proxy_port=0,
    
    # Профиль и cookies
    profile_path="browser_profiles/session_001",
    load_cookies=True,
    save_cookies=True
)
Рекомендации по безопасности


Интервалы между действиями:

Минимум 1-2 секунды между кликами
Случайные задержки от 0.5 до 5 секунд
Длительные паузы между сессиями работы


Ротация параметров:

Смена User-Agent каждые 24 часа
Изменение размеров viewport при каждом запуске
Использование разных профилей браузера


Ограничения активности:

Не более 100 задач в день на одну сессию
Перерывы между сессиями работы
Имитация человеческого режима работы


Мониторинг и диагностика

Система логирования

Структура логов:
logs/
├── app.log                    # Основной лог приложения
├── sessions.log               # Логи работы сессий
├── parsing.log                # Логи парсинга
├── gui.log                    # Логи GUI событий
└── errors.log                 # Критические ошибки

Уровни логирования:

DEBUG: Детальная отладочная информация
INFO: Информационные сообщения о работе
WARNING: Предупреждения о потенциальных проблемах
ERROR: Ошибки, не останавливающие работу
CRITICAL: Критические ошибки, требующие вмешательства

Метрики производительности

Ключевые метрики системы:
system_metrics = {
    # Общие метрики
    "uptime": "время работы приложения",
    "memory_usage": "использование оперативной памяти",
    "cpu_usage": "загрузка процессора",
    
    # Метрики сессий
    "active_sessions": "количество активных сессий",
    "total_sessions": "общее количество сессий",
    "session_success_rate": "процент успешных запусков",
    
    # Метрики задач
    "tasks_parsed_today": "задач спаршено сегодня",
    "tasks_completed_today": "задач выполнено сегодня",
    "parsing_success_rate": "процент успешного парсинга",
    
    # Метрики производительности
    "average_parsing_time": "среднее время парсинга",
    "average_task_time": "среднее время выполнения задачи",
    "error_rate": "частота ошибок"
}
Диагностические команды

# Диагностика состояния сессии
diagnosis = session_manager.diagnose_session_issues(session_id)
print(f"Статус сессии: {diagnosis['status']}")
print(f"Проблемы: {diagnosis['issues']}")
print(f"Рекомендации: {diagnosis['recommendations']}")

# Проверка базы данных задач
task_manager.debug_database_content()

# Получение статистики задач
stats = task_manager.get_tasks_statistics()
print(f"Всего задач: {stats['total_tasks']}")
print(f"По статусам: {stats['by_status']}")
print(f"По типам: {stats['by_type']}")

# Проверка состояния WebDriver
webdriver_status = session_process.get_webdriver_status()
print(f"WebDriver инициализирован: {webdriver_status['webdriver_initialized']}")
print(f"WebDriver отвечает: {webdriver_status['webdriver_responsive']}")
Расширение и кастомизация

Добавление новых парсеров

Создание парсера для новой биржи:

Наследование от BaseParser:

from src.parsers.base_parser import BaseParser

class NewExchangeParser(BaseParser):
    def __init__(self, session_manager):
        super().__init__(session_manager)
        self.exchange_name = "NewExchange"
        self.base_url = "https://newexchange.com"
    
    def fetch_tasks_from_session(self, session_id: str) -> List[Task]:
        # Реализация специфичной логики парсинга
        pass
    
    def parse_task_details(self, task_element) -> Dict[str, Any]:
        # Парсинг деталей задачи
        pass

Регистрация парсера:

# В инициализации приложения
from src.parsers.new_exchange_parser import NewExchangeParser

# Создание и регистрация парсера
new_parser = NewExchangeParser(session_manager)
parser_registry.register("new_exchange", new_parser)
Создание кастомных GUI панелей

Добавление новой панели:
from PySide6.QtWidgets import QWidget, QVBoxLayout, QLabel
from src.gui.panels.base_panel import BasePanel

class CustomPanel(BasePanel):
    def __init__(self, app_instance, parent=None):
        super().__init__(app_instance, parent)
        self.setup_ui()
    
    def setup_ui(self):
        layout = QVBoxLayout(self)
        title = QLabel("Кастомная панель")
        layout.addWidget(title)
        
        # Добавление специфичной функциональности
        self.setup_custom_widgets()
    
    def setup_custom_widgets(self):
        # Реализация кастомных виджетов
        pass
Интеграция с внешними системами

REST API для внешней интеграции:
from flask import Flask, jsonify, request
from src.core.session_manager import session_manager
from src.core.task_manager import task_manager

app = Flask(__name__)

@app.route('/api/sessions', methods=['GET'])
def get_sessions():
    sessions = session_manager.list_sessions()
    return jsonify([session.to_dict() for session in sessions])

@app.route('/api/sessions/<session_id>/start', methods=['POST'])
def start_session(session_id):
    success = session_manager.start_session(session_id)
    return jsonify({"success": success})

@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    tasks = task_manager.get_all_tasks()
    return jsonify([task.to_dict() for task in tasks])

if __name__ == '__main__':
    app.run(debug=True, port=5000)
Текущий статус разработки

Завершенные этапы

✅ Этап 1-2: Базовая инфраструктура


Многовкладочная панель задач с отдельными сессиями
Система шаблонов определения задач
Базовая система статусов и жизненного цикла
Интеграция с системой сигналов

✅ Этап 3: Улучшенный парсинг (частично)


Дедупликация задач по task_id
Обязательная привязка задач к сессиям
Расширенное расширение списка задач
Детальная статистика парсинга

Текущие нерешенные проблемы

🔴 Критические проблемы


Проблема запуска браузера

Ошибка: [WinError 5] Отказано в доступе при работе с ChromeDriver
Причина: WebDriverManager не может переместить файл драйвера
Статус: Требует реализации webdriver_fix.py


Ошибка импорта SessionConfig

Ошибка: Unresolved reference 'SessionConfig' в session_manager.py
Причина: Неправильный относительный импорт
Статус: Требует исправления импортов


Проблемы с диалогом сессий

Ошибка: Пустые диалоги при редактировании
Причина: Несовместимость методов SessionDialog
Статус: Требует добавления get_session_config()


🟡 Проблемы средней важности


Система BehaviorEngine

Статус: Частично работает, нужна доработка моделей поведения
Проблема: Ошибка при создании моделей по умолчанию (решена)


QPainter warnings

Проблема: Множественные предупреждения рендеринга GUI
Статус: Не критично, но влияет на стабильность


Планы по завершению текущего этапа

Немедленные действия (1-2 дня)


Исправление запуска браузера

Создать src/core/webdriver_fix.py
Реализовать FixedChromeDriverManager
Обновить SessionProcess для использования исправленного драйвера


Исправление импортов и совместимости

Исправить импорт SessionConfig в session_manager.py
Добавить метод get_session_config() в SessionDialog
Проверить все зависимости между компонентами


Стабилизация создания сессий

Исправить дублирование сессий
Обеспечить корректное сохранение в sessions.json
Проверить работу редактирования сессий


Доработка функционала (3-5 дней)


Завершение системы парсинга

Улучшить алгоритмы определения типов задач
Добавить поддержку различных платформ
Оптимизировать производительность парсинга


Улучшение GUI

Исправить QPainter warnings
Добавить прогресс-бары для длительных операций
Улучшить отзывчивость интерфейса


Известные проблемы и ограничения

Текущие ограничения


Поддержка бирж:

В данный момент поддерживается только unu.im
Требуется ручная адаптация для каждой новой биржи


Автоматическое выполнение:

Система исполнителей задач находится в разработке
Доступен только парсинг, выполнение - ручное


Масштабируемость:

SQLite ограничивает производительность при больших объемах
Рекомендуется не более 10,000 задач в базе


Антидетект:

Базовые функции реализованы
Требуется дополнительная настройка для каждой платформы


Известные проблемы


Циркулярный импорт session model:

Статус: Частично исправлен
Проявление: Предупреждение при запуске
Обходной путь: Добавить from __future__ import annotations


QPainter ошибки в GUI:

Статус: Косметическая проблема
Проявление: Сообщения в консоли, не влияет на функциональность
Обходной путь: Игнорировать или настроить инициализацию GUI


Потеря WebDriver соединения:

Статус: Редкие случаи
Проявление: Потеря связи с браузером
Обходной путь: Перезапуск сессии


Планы по устранению

Версия 1.0.1 (Исправления):

Устранение циркулярного импорта
Оптимизация GUI инициализации
Улучшение стабильности WebDriver

Версия 1.1.0 (Новая функциональность):

Система User Agent'ов
Модели поведения
Панель статистики

Версия 1.2.0 (Расширения):

Поддержка дополнительных бирж
REST API
Улучшенный антидетект

Планы дальнейшего развития

Этап 4: Модели поведения (приоритет: высокий)

Длительность: 5-6 дней
Зависимости: Этапы 1-3
Задачи:

Завершение разработки системы поведенческих моделей
Интеграция с системой определения задач
Разработка алгоритмов выбора подходящих моделей
Тестирование на различных типах задач

Этап 5: Система выполнения (приоритет: средний)

Длительность: 4-5 дней
Зависимости: Этапы 1-4
Задачи:

Разработка исполнителей для различных платформ
Система очередей выполнения
Мониторинг и отчетность выполнения
Обработка ошибок и повторных попыток

Этап 6: Интеграция и тестирование (приоритет: высокий)

Длительность: 3-4 дня
Зависимости: Все этапы
Задачи:

Комплексное тестирование всех компонентов
Оптимизация производительности
Документирование и финализация MVP
Подготовка к релизу

Инструкции по разработке

Добавление нового агента


Создать класс, наследующий от BaseUserAgent
Реализовать обязательные методы
Добавить в src/agents/__init__.py
Обновить метаданные в get_available_agents_info()

Добавление нового парсера


Создать класс, наследующий от BaseParser
Реализовать методы парсинга
Добавить в src/parsers/__init__.py
Интегрировать с TaskManager

Работа с базой данных


Все изменения схемы делать через миграции в TaskManager._migrate_database()
Обязательно добавлять новые поля в column_definitions
Тестировать миграции на копиях данных

Система логирования


Использовать get_logger(__name__) в каждом модуле
Уровни: DEBUG для отладки, INFO для важных событий, WARNING для проблем, ERROR для ошибок
Логи сохраняются в файлы с ротацией

Заключение

TaskBot Automation Suite находится на финальной стадии разработки MVP. Основная инфраструктура создана, требуется решение нескольких критических проблем и завершение интеграции компонентов. После устранения текущих проблем проект будет готов к переходу к следующим этапам развития.
Текущий приоритет: Устранение критических проблем с запуском браузера и стабилизация базового функционала.
Сообщество и поддержка

Контактная информация


Команда разработки: Ilia Vasilchenko
Email: viadesire@gmail.com
Документация: Данный файл DOCS.MD
Версия документации: 1.0.0 полная

Участие в разработке

Структура для контрибьюторов:

Форк репозитория
Создание feature branch
Следование code style
Написание тестов
Создание pull request

Code Style Guidelines:

Python PEP 8
Типизация с помощью typing
Docstrings для всех публичных методов
Комментарии на русском языке
Логирование всех важных событий

Лицензия

MIT License (предполагаемая)

Свободное использование
Модификация разрешена
Коммерческое использование разрешено
Без гарантий

Документация версии: 1.0.0 полная
Дата создания: 2025-07-07
Последнее обновление: 2025-07-07
Автор: Ilia Vasilchenko