HyperPlatform — Руководство пользователя

1. Основные термины и сокращения

2. Назначение документа

Настоящий документ предназначен для пользователей, администраторов и операторов программного обеспечения «HyperPlatform». Документ содержит подробные инструкции по установке, настройке и использованию ПО, описание интерфейса, описание действий для каждой роли пользователя, а также способы решения типовых проблем.

Предполагается, что пользователи обладают базовыми навыками работы с персональным компьютером и веб-браузером.

3. Назначение ПО

3.1. Функциональное назначение ПО

Программное обеспечение «HyperPlatform» предназначено для:

1. Обмена текстовыми сообщениями между пользователями и ботами в реальном времени;
2. Отправки и получения файлов (изображения, видео, аудио, документы);
3. Использования интерактивных форм для сбора структурированных данных;
4. Использования кнопок быстрого действия (inline-клавиатура) для callback-взаимодействия;
5. Управления пользователями, ботами и чатами через API;
6. Автоматизации бизнес-процессов с помощью ботов.

3.2. Эксплуатационное назначение ПО

ПО может эксплуатироваться в организациях любого профиля для:

• Внутренней корпоративной коммуникации;
• Автоматизации процессов обработки заявок и уведомлений;
• Создания и управления корпоративными чат-ботами;
• Централизованного управления пользователями и доступом.

4. Условия функционирования ПО

4.1. Требования к аппаратному обеспечению (сервер)

4.2. Требования к программному обеспечению (сервер)

4.3. Требования к персоналу

К работе с ПО допускаются:

• Конечные пользователи — сотрудники организации, прошедшие инструктаж по работе с системой;
• Администраторы — специалисты, обладающие навыками работы с Linux, Docker и REST API;
• Операторы — сотрудники, прошедшие обучение по управлению ботами и чатами.

5. Установка ПО

Установка ПО осуществляется согласно отдельному документу «HyperPlatform — Инструкция по установке». Краткий порядок установки:

1. Убедиться, что сервер соответствует требованиям (раздел 4);
2. Проверить наличие Docker и Docker Compose;
3. Скопировать архив с ПО на сервер;
4. Распаковать архив командой: tar -xzf HyperPlatform-1.0.0.tar.gz;
5. Перейти в папку: cd HyperPlatform-1.0.0;
6. Отредактировать файл .env.example;
7. Отредактировать файл .env.frontend.example — указать IP-адрес или домен сервера;
8. Запустить скрипт установки: ./install.sh;
9. При первом запуске ввести email администратора (первого пользователя платформы);
10. Сохранить токены доступа, отображаемые в конце установки.

6. Запуск ПО

6.1. Запуск серверной части

Запуск производится автоматически скриптом install.sh. Проверка работоспособности:

docker ps

Должны отображаться 7 контейнеров:

6.2. Вход в систему

1. Открыть браузер;
2. В адресной строке ввести http://<IP-адрес-сервера>/bot/;
3. Откроется экран входа в систему.

7. Интерфейс программы

7.1. Экран входа

Экран входа содержит следующие элементы:

• Заголовок с названием платформы;
• Поле «Email» — для ввода адреса электронной почты;
• Кнопка «Получить код» — отправляет PIN-код на указанную почту;
• Поле «Код подтверждения» — появляется после отправки PIN-кода;
• Кнопка «Войти» — выполняет вход в систему.

7.2. Главный экран

После успешного входа пользователь попадает на главный экран, который состоит из трёх областей:

Левая панель (список чатов)

• Отображает список доступных чатов;
• Каждый чат содержит название бота и аватар;
• Активный чат подсвечивается;
• В верхней части — поле поиска ботов и кнопка выхода.

Центральная область (окно переписки)

• Отображает историю сообщений в выбранном чате;
• Сообщения пользователя выравниваются по правому краю, бота — по левому;
• Вложения отображаются в виде превью;
• Кнопки и формы отображаются внутри сообщений.

7.3. Окно чата

В нижней части центральной области находится поле ввода сообщения и кнопки:

7.4. Типы сообщений

8. Работа в ПО

8.1. Роль: Конечный пользователь

8.1.1. Авторизация

1. Открыть браузер и перейти по адресу http://<IP-адрес-сервера>/bot/;
2. На экране входа ввести адрес электронной почты;
3. Нажать кнопку «Получить код»;
4. Проверить почтовый ящик (включая папку «Спам»);
5. Ввести полученный PIN-код в поле «Код подтверждения»;
6. Нажать кнопку «Войти»;
7. При успешном входе отобразится главный экран со списком чатов.

8.1.2. Работа с чатами

Выбор чата: щёлкнуть левой кнопкой мыши по названию чата в левой панели — в центральной области отобразится история сообщений.

Отправка текстового сообщения: выбрать чат → ввести текст в поле ввода → нажать Enter или кнопку отправки → сообщение отобразится в чате.

Отправка файла: выбрать чат → нажать кнопку 📎 → выбрать файл на компьютере → файл загрузится и отобразится с превью.

Просмотр истории: история загружается автоматически при выборе чата; при прокрутке вверх подгружаются более ранние сообщения.

Очистка чата: производится нажатием на кнопку в правом верхнем углу (история очищается, чат перезапускается).

8.1.3. Взаимодействие с кнопками

Если сообщение бота содержит кнопки: нажать на кнопку → данные кнопки (callback_data) отправляются боту → бот обрабатывает нажатие и может изменить сообщение или отправить новое.

8.1.4. Заполнение форм

Если сообщение бота содержит форму: заполнить поля (текстовые поля, выпадающие списки, радиокнопки, даты и т.д.) → нажать кнопку «Отправить» внизу формы → данные будут отправлены боту для обработки.

8.1.5. WebSocket-уведомления

При открытой странице чата устанавливается WebSocket-соединение, благодаря чему:

• Новые сообщения отображаются мгновенно без обновления страницы;
• При получении нового сообщения в неактивном чате счётчик непрочитанных увеличивается;
• Отображаются push-уведомления.

8.2. Роль: Администратор

Администратор взаимодействует с системой через REST API. Все запросы выполняются с использованием токена компании (COMPANY_TOKEN), который передаётся в заголовке Authorization: Bearer <token>. Для удобного взаимодействия со всеми элементами платформы создан главный бот BotBrother, через интерфейс которого можно управлять остальными ботами, чатами и пользователями.

8.2.1. Управление пользователями

8.2.2. Управление ботами

8.2.3. Управление чатами

8.3. Роль: Оператор

Оператор взаимодействует с платформой через главного бота BotBrother, который предоставляет возможности по управлению пользователями и созданию ботов непосредственно из интерфейса чата. Возможности оператора: приглашение новых пользователей, создание новых ботов, создание чатов между пользователями и ботами.

8.3.1. Начало работы

8.3.2. Приглашение пользователей

Отправить боту команду для приглашения нового пользователя. Пользователь получит уведомление и сможет войти в систему, используя свой email.

8.3.3. Создание нового бота

Отправить боту команду создания бота. Потребуется указать название бота, описание (опционально) и список команд (опционально). После создания бот получит уникальный токен доступа, который будет отображён в ответном сообщении.

8.3.4. Создание чатов

Оператор может создать чат между любым пользователем и любым ботом своей компании. Бот запросит необходимые данные и создаст чат.

9. Завершение работы ПО

9.1. Завершение сеанса пользователя

• Нажать кнопку закрытия в интерфейсе;
• Или закрыть вкладку браузера;
• Для выхода из сессии нажать кнопку в левом верхнем углу.

9.2. Остановка серверной части

cd <папка-установки>/HyperPlatform-1.0.0

# Полная остановка всех сервисов
docker compose down

# Временная остановка без удаления
docker compose stop

10. Удаление ПО

Для полного удаления ПО с сервера выполните следующие команды:

cd <папка-установки>/HyperPlatform-1.0.0

# Остановить и удалить все контейнеры, тома и сети
docker compose down --volumes

# Удалить все данные
rm -rf data/postgres data/redis Files Previews Static

# Удалить конфигурационные файлы
rm .env .env.frontend

# Перейти выше и удалить папку с ПО
cd ..
rm -rf HyperPlatform-1.0.0
rm HyperPlatform-1.0.0.tar.gz

11. Решение типовых проблем