# АРХИТЕКТУРА ЧАТ-БОТА ИТ-ПОДДЕРЖКИ
## Версия 2.0 — На базе Beeline AI Platform

---

## Документ для передачи в разработку

**Дата:** 24.06.2026  
**Версия:** 2.0  
**Статус:** Утверждена к разработке  
**Ответственный:** Архитектор решения  

---

## Оглавление

1. [Введение](#1-введение)
2. [Обзор решения](#2-обзор-решения)
3. [Проблема и целевая аудитория](#3-проблема-и-целевая-аудитория)
4. [Архитектурные принципы](#4-архитектурные-принципы)
5. [Архитектурные диаграммы](#5-архитектурные-диаграммы)
6. [Детальное описание компонентов](#6-детальное-описание-компонентов)
7. [Сценарии работы](#7-сценарии-работы)
8. [Интеграции](#8-интеграции)
9. [Синхронизация документов](#9-синхронизация-документов)
10. [Требования к разработке](#10-требования-к-разработке)
11. [Требования к инфраструктуре](#11-требования-к-инфраструктуре)
12. [Мониторинг и логирование](#12-мониторинг-и-логирование)
13. [Безопасность](#13-безопасность)
14. [Границы MVP](#14-границы-mvp)
15. [Метрики успеха](#15-метрики-успеха)
16. [План реализации](#16-план-реализации)
17. [Открытые вопросы](#17-открытые-вопросы)
18. [Приложения](#18-приложения)

---

## 1. Введение

### 1.1 Цель документа

Данный документ содержит полное архитектурное описание чат-бота ИТ-поддержки, интегрированного с порталом «ВКУС» и платформой ИИ Beeline. Документ предназначен для команд разработки, DevOps, тестирования и эксплуатации.

### 1.2 Обозначения и сокращения

| Сокращение | Расшифровка |
|------------|-------------|
| RAG | Retrieval-Augmented Generation |
| LLM | Large Language Model |
| API | Application Programming Interface |
| JWT | JSON Web Token |
| ITSM | IT Service Management |
| BPM | Business Process Management |
| MVP | Minimum Viable Product |
| SLA | Service Level Agreement |
| FQDN | Fully Qualified Domain Name |
| DB | Database |
| UI | User Interface |
| S3 | Simple Storage Service |

---

## 2. Обзор решения

### 2.1 Назначение

Корпоративный чат-бот для ИТ-поддержки, интегрированный в портал «ВКУС». Бот отвечает на вопросы сотрудников по 20 ИТ-системам, используя технологию RAG (Retrieval-Augmented Generation).

### 2.2 Ключевая ценность

- **24/7 поддержка** — сотрудники получают ответы в любое время
- **Быстрый поиск** — мгновенный доступ к инструкциям и документации
- **Снижение нагрузки** — автоматическая обработка типовых обращений

### 2.3 Основные компоненты

| Компонент | Назначение |
|-----------|------------|
| **ВКУС Frontend** | Виджет чата на портале ВКУС |
| **ВКУС Backend** | Бизнес-логика, управление диалогами, создание заявок |
| **API платформы ИИ** | Единый OpenAI‑совместимый API (apiai.sibur.local) |
| **RAG-слой** | Docling + BERT Inference Service + Векторная БД |
| **LLM** | gpt-oss-120b (генерация ответов) |
| **Документы / инструкции** | Корпоративная документация и инструкции |
| **Creatio BPM** | ITSM-система для создания заявок |
| **Мониторинг** | Grafana + VictoriaMetrics + OpenSearch |

### 2.4 Принципиальная схема
---

## 3. Проблема и целевая аудитория

### 3.1 Проблемы

| № | Проблема | Описание |
|---|----------|----------|
| 1 | Отсутствие поддержки 24/7 | ИТ-служба работает в ограниченные часы |
| 2 | Сложность поиска информации | Базы знаний разрознены, поиск неэффективен |
| 3 | Большое количество типовых обращений | Операторы тратят время на однотипные вопросы |

### 3.2 Целевая аудитория

| Группа | Роль | Потребности |
|--------|------|-------------|
| Все сотрудники компании | Пользователи чат-бота | Быстрое получение ответов по ИТ-вопросам |
| ИТ-операторы | Обработка заявок | Получение только сложных заявок (<70% уверенности) |
| Владельцы инструкций | Актуализация базы знаний | Регулярное обновление документации |

---

## 4. Архитектурные принципы

| Принцип | Описание | Обоснование |
|---------|----------|-------------|
| **API платформы ИИ — единая точка входа** | Все вызовы к LLM и эмбеддингам через apiai.sibur.local | Унификация, безопасность, управляемость |
| **Separation of concerns** | Бизнес-логика в ВКУС, генерация в AI-платформе | Чёткое разделение ответственности |
| **OpenAI‑совместимый API** | Единый стандарт для всех вызовов | Совместимость, легкость интеграции |
| **Stateless** | Каждый запрос независим | Масштабируемость, отказоустойчивость |
| **Единый источник данных** | Все инструкции из корпоративных документов | Актуальность, консистентность |
| **Secure-by-default** | Аутентификация через JWT + Keycloak | Безопасность с самого начала |

---

## 5. Архитектурные диаграммы

### 5.1 Контекстная диаграмма (C4 Level 1)

```mermaid
flowchart TB
    Employee([Сотрудник компании])
    
    subgraph VKUS["Портал ВКУС"]
        Frontend[ВКУС Frontend\nReact/Vue виджет\nВзаимодействие с пользователем]
        Backend[ВКУС Backend\nБизнес-логика портала\nУправление диалогами\nСоздание заявок в ITSM]
    end

    subgraph BeelineAI["Платформа ИИ Beeline"]
        APIPlatform["API платформы ИИ\napiai.sibur.local (10.204.128.14)\nЕдиный OpenAI‑совместимый API\nДоступ к LLM и эмбеддингам\nГенерация API-ключей"]
        
        subgraph RAG_Layer["RAG-слой"]
            Docling["Docling (uc-gpu-1, 10.204.128.13)\nСервис извлечения текста\nPDF / DOC / OCR → текст\nПодготовка данных для векторизации"]
            BERT["BERT Inference Service (uc-gpu-1, 10.204.128.13)\nМикросервис эмбеддингов\nГенерация векторных представлений\nМодель BERT (768-dim)"]
            VectorDB["Векторная БД (встроена в платформу)\nХранение векторных представлений\nБыстрый поиск похожих документов\nHNSW / IVF индексация"]
        end
        
        LLM["LLM (uc-gpu-1, 10.204.128.13)\ngpt-oss-120b (основная модель)\nГенерация текста\nИнтеграция с RAG-слоем\nОбработка запросов"]
    end

    subgraph DataSources["Документы / инструкции"]
        Documents["Документы\nКорпоративные документы\nИнструкции\nРуководства"]
    end

    subgraph ITSM["ITSM-система"]
        Creatio["Creatio BPM\nУправление заявками\nСоздание тикетов\nОбработка обращений"]
    end

    Employee -->|Задаёт вопрос через виджет| Frontend
    Frontend -->|Вызов API| Backend
    Backend -->|Запрос к /v1/chat/completions\n(JWT токен)| APIPlatform

    APIPlatform -->|Поиск релевантных чанков| RAG_Layer
    RAG_Layer --> Docling --> BERT --> VectorDB

    Documents -->|Синхронизация инструкций| Docling

    APIPlatform -->|Генерация ответа| LLM

    Backend -->|Создание заявки\n(при уверенности < 70%)| Creatio