Добавить SA-support.md

2025-06-20 13:53:31 +00:00 · 2025-06-20 13:53:31 +00:00 · 35008198fb
commit 35008198fb
parent 8c75c7cf45
1 changed files with 154 additions and 0 deletions
--- a/SA-support.md
+++ b/SA-support.md
@ -0,0 +1,154 @@
+# Техническое задание  
+## Разработка 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)