<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

# Система очереди AI запросов

## Обзор

Система очереди AI запросов предназначена для управления нагрузкой на Ollama и обеспечения стабильной работы AI ассистента. Она предотвращает перегрузку модели, обеспечивает приоритизацию запросов и предоставляет мониторинг производительности.

## Архитектура

### Компоненты

1. **AIQueueService** (`backend/services/ai-queue.js`) - основной сервис очереди
2. **AI Queue Routes** (`backend/routes/ai-queue.js`) - API маршруты для управления очередью
3. **AIQueueMonitor** (`frontend/src/components/AIQueueMonitor.vue`) - компонент мониторинга
4. **Обновленный Chat Route** - поддержка очереди в чате

### Технологии

- **better-queue** - библиотека для управления очередью
- **Node.js** - серверная часть
- **Vue.js** - клиентская часть
- **Chart.js** - визуализация статистики

## Конфигурация очереди

### Основные параметры

```javascript
{
  concurrent: 2,           // Количество одновременных запросов
  maxTimeout: 180000,      // Максимальное время выполнения (3 мин)
  afterProcessDelay: 1000, // Задержка между задачами (1 сек)
  maxRetries: 2,           // Максимальное количество повторных попыток
  retryDelay: 5000         // Задержка между повторными попытками (5 сек)
}
```

### Приоритизация

Система автоматически определяет приоритет задач:

- **Администраторы**: +10 к приоритету
- **Срочные запросы**: +20 к приоритету
- **Чат**: +5 к приоритету
- **Анализ**: +3 к приоритету
- **Генерация**: +1 к приоритету
- **Короткие запросы** (<100 символов): +2 к приоритету
- **Долгое ожидание** (>30 сек): +5 к приоритету

## API Endpoints

### Получение статистики
```http
GET /api/ai-queue/stats
```

### Добавление задачи в очередь
```http
POST /api/ai-queue/task
Content-Type: application/json

{
  "message": "Текст сообщения",
  "language": "ru",
  "history": [...],
  "systemPrompt": "...",
  "rules": {...},
  "type": "chat"
}
```

### Получение статуса задачи
```http
GET /api/ai-queue/task/:taskId
```

### Управление очередью (только для админов)
```http
POST /api/ai-queue/control
Content-Type: application/json

{
  "action": "pause|resume|clear"
}
```

### Информация о производительности
```http
GET /api/ai-queue/performance
```

## Использование в чате

### Обычный режим (без очереди)
```http
POST /api/chat/message
```

### Режим с очередью
```http
POST /api/chat/message-queued
```

## Мониторинг

### Компонент AIQueueMonitor

Компонент предоставляет:

- **Статус очереди**: активна, ожидает, пуста, ошибка
- **Количество задач**: в очереди и выполняющихся
- **Производительность**: успешность, среднее время обработки
- **Детальная статистика**: общее количество, ошибки, время
- **Управление**: пауза, возобновление, очистка (для админов)
- **График производительности**: реальное время

### Интеграция в интерфейс

```vue
<template>
  <AIQueueMonitor :isAdmin="userIsAdmin" />
</template>

<script>
import AIQueueMonitor from '@/components/AIQueueMonitor.vue'

export default {
  components: {
    AIQueueMonitor
  }
}
</script>
```

## Ограничения и защита

### Rate Limiting

- **Ограничение по пользователю**: 10 запросов в минуту
- **Размер сообщения**: максимум 10,000 символов
- **Валидация**: проверка обязательных полей

### Фильтрация

- Проверка формата сообщения
- Валидация ID запроса
- Проверка размера сообщения
- Контроль частоты запросов

### Слияние задач

- Объединение одинаковых запросов от одного пользователя
- Обновление метаданных при повторных запросах

## Производительность

### Оптимизации

1. **Кэширование**: ответы кэшируются на 5 минут
2. **Проверка здоровья**: мониторинг состояния модели
3. **Ограничение ресурсов**: Docker контейнер с лимитами
4. **Таймауты**: защита от зависших запросов

### Мониторинг

- Время обработки запросов
- Успешность выполнения
- Размер очереди
- Количество ошибок
- Статистика по пользователям

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

### Частые проблемы

1. **Медленные ответы**
   - Проверить размер очереди
   - Увеличить количество concurrent задач
   - Проверить ресурсы Ollama

2. **Ошибки таймаута**
   - Увеличить maxTimeout
   - Проверить состояние модели
   - Очистить очередь

3. **Высокая нагрузка**
   - Уменьшить concurrent задачи
   - Включить rate limiting
   - Добавить задержки между задачами

### Логи

```bash
# Просмотр логов очереди
docker logs dapp-backend | grep AIQueue

# Статистика очереди
curl http://localhost:8000/api/ai-queue/stats

# Проверка здоровья
curl http://localhost:8000/api/health
```

## Настройка для продакшена

### Рекомендуемые параметры

```javascript
{
  concurrent: 1,           // Один запрос за раз для стабильности
  maxTimeout: 300000,      // 5 минут таймаут
  afterProcessDelay: 2000, // 2 секунды между запросами
  maxRetries: 1,           // Одна повторная попытка
  retryDelay: 10000        // 10 секунд между попытками
}
```

### Мониторинг

- Настройка алертов при высокой нагрузке
- Логирование всех операций
- Метрики производительности
- Автоматическое масштабирование

### Безопасность

- Аутентификация для всех endpoints
- Авторизация для управления очередью
- Валидация всех входных данных
- Защита от DDoS атак

## Разработка

### Добавление новых типов задач

1. Обновить функцию `getTaskPriority`
2. Добавить обработку в `processTask`
3. Обновить документацию

### Расширение мониторинга

1. Добавить новые метрики в `getStats`
2. Обновить компонент `AIQueueMonitor`
3. Добавить новые API endpoints

### Интеграция с другими сервисами

1. Подключение к Redis для персистентности
2. Интеграция с системами мониторинга
3. Подключение к лог-агрегаторам