# Техническое задание  
## Разработка Telegram-бота технической поддержки SmartAgro

### 1. Общие сведения

#### 1.1 Наименование проекта  
Telegram-бот технической поддержки SmartAgro.

#### 1.2 Заказчик  
ООО "СмартАгро" (SmartAgro)

#### 1.3 Цель создания  
Разработка автоматизированной системы технической поддержки через Telegram, предоставляющей пользователям информацию о продукте «Агроаналитика» (smartagro.ru) на основе данных из базы знаний (Confluence), с применением RAG и моделей сервиса Maker-GPT.

#### 1.4 Назначение  
Бот предназначен для оказания квалифицированной технической помощи в режиме реального времени по вопросам использования сервиса Агроаналитика, а также для снижения нагрузки на службу поддержки за счет автоматизации ответов на часто задаваемые вопросы.

---

### 2. Требования к функциональности

#### 2.1 Основные функции бота:
- Прием текстовых сообщений от пользователей.
- Поиск наиболее релевантных документов/фрагментов в базе знаний (Confluence).
- Формирование контекста запроса с использованием RAG (Retrieval-Augmented Generation).
- Генерация понятного и точного ответа на основе контекста и API Maker-GPT.
- Вывод ответа пользователю в чате Telegram.

#### 2.2 Дополнительные функции:
- Приветственное сообщение при старте.
- Возможность уточнения запроса, если он неоднозначен.
- Отправка ссылок на соответствующие статьи из Confluence.
- Логирование обращений пользователей (не персональные данные).
- Работа как с новыми, так и с зарегистрированными пользователями (по желанию).

---

### 3. Структура и источники данных

#### 3.1 Источник информации
- База знаний: **Confluence (https://doc.smartagro.ru/)**.
- Статьи из Confluence индексируются периодически или по запросу.

#### 3.2 Индексация и хранение
- Контент из Confluence загружается и предобрабатывается (очистка, токенизация, деление на чанки).
- Тексты преобразуются в эмбеддинги с помощью модели (например, `paraphrase-multilingual-MiniLM-L12-v2`).
- Векторы хранятся в **PostgreSQL + расширение pgvector**.
- Индексация может выполняться:
  - Периодически (ежедневно/еженедельно).
  - По требованию (через админ-панель или API).

#### 3.3 Метод поиска
- Для входящего запроса формируется вектор.
- Выполняется поиск ближайших векторов (ближайшие фрагменты статей) в PostgreSQL.
- Полученные фрагменты используются как контекст для генерации ответа.
- Необходимо рассмотреть возможности объединения результатов поиска - векторного, семантического, через API Confluence

---

### 4. Архитектура решения

#### 4.1 Компоненты системы:
| Компонент | Описание |
|----------|----------|
| **Telegram Bot** | Интерфейс взаимодействия с пользователем |
| **API Gateway / Backend** | Обработка запросов, логика работы с данными |
| **Confluence Parser** | Модуль сбора и обработки данных из Confluence |
| **Vector DB (PostgreSQL + pgvector)** | Хранилище эмбеддингов и текстовых фрагментов |
| **Maker-GPT API** | Генерация ответов на основе контекста |
| **Scheduler** | Планировщик регулярной синхронизации с Confluence |

#### 4.2 Технологии:
- Язык программирования: **JavaScript (Node.js)**
- Telegram-библиотека: **node-telegram-bot-api**
- Maker-GPT API: GPT-4.1/GigaChat/YandexGPT
- База данных: **PostgreSQL + pgvector**
- Парсер Confluence: использование официального REST API Confluence
- Упаковка и запуск: Docker, PM2

---

### 5. Требования к интерфейсу

#### 5.1 Telegram-бот
- Поддержка команд:
  - `/start` — приветствие и описание возможностей
  - `/help` — справка
  - `/search <запрос>` — принудительный поиск по базе знаний
- Автоматическая обработка свободного текста.
- Ответы — в виде простого текста, возможно с кнопками и ссылками.

#### 5.2 Административный интерфейс (по желанию)
- Веб-панель управления:
  - Запуск ручной синхронизации с Confluence
  - Просмотр истории обращений
  - Ручная проверка ответов
  - Управление доступом

---

### 6. Требования к безопасности

- Все данные, передаваемые между компонентами, должны быть защищены (HTTPS).
- Ключи API (Maker-GPT, Telegram, Confluence) хранятся в переменных окружения или секрет-менеджере (например, dotenv).
- Конфиденциальные данные пользователей не сохраняются без согласия.

---

### 7. Производительность и надёжность

- Ответ на запрос должен формироваться в течение **не более 5 секунд**.
- Бот должен работать **24/7** с минимальным временем простоя.
- Должны быть предусмотрены резервные пути (fallback) на случай недоступности OpenAI API или Confluence.

---

### 8. Этапы реализации

| Этап | Описание | Срок |
|------|----------|------|
| 1. Анализ требований | Уточнение деталей, подготовка документации | 3 дня |
| 2. Настройка доступа | Telegram-бот, Confluence, OpenAI, PostgreSQL | 3 дня |
| 3. Парсер Confluence | Сбор и обработка данных | 5 дней |
| 4. Индексация и поиск | Реализация RAG | 5 дней |
| 5. Backend | Логика обработки запросов | 5 дней |
| 6. Тестирование | Юнит-тесты, тестирование в Telegram | 3 дня |
| 7. Деплой | Запуск на сервере, настройка CI/CD | 2 дня |
| 8. Поддержка | Исправление ошибок, доработки | после запуска |

---

### 9. Дополнительные требования

- Поддержка русского языка во всех интерфейсах.
- Возможность дальнейшего расширения: добавление новых источников знаний, модернизация под другие LLM.
- Документация по API и внутренней архитектуре.

---

### 10. Пример диалога

**Пользователь:**  
> Как настроить датчики температуры?

**Бот:**  
> Чтобы настроить датчики температуры в системе Агроаналитика, выполните следующие шаги:  
> 1. Перейдите в раздел "Оборудование".  
> 2. Выберите нужную площадку...  
> [далее — подробная инструкция]  
> Также вы можете ознакомиться с полной инструкцией здесь: [ссылка на статью в Confluence]

---

![Схема системы](https://maker-gpt.pro/uploads/bot-shema.png)