👹

README.md

@@ -0,0 +1,323 @@
+**МИНИСТЕРСТВО НАУКИ И ВЫСШЕГО ОБРАЗОВАНИЯ РОССИЙСКОЙ ФЕДЕРАЦИИ**
+**Новгородский государственный университет имени Ярослава Мудрого**
+**Политехнический институт**
+**Кафедра Информационных Технологий и Систем**
+
+ОТЧЕТ ПО ЛАБОРАТОРНОЙ РАБОТЕ №14
+Разработка распределенной системы обмена сообщениями реального времени (аналог Discord) Minor для кафедры Программного Обеспечения и Вычислительной Техники НовГУ
+Версия v0.1
+
+**Выполнили:**
+* Студент Ильин Д.А. группы № 3093
+* Студент Распопов С.И. группы № 3093
+
+Великий Новгород 2026 г.
+
+---
+# Аннотация
+
+В данном документе представлено подробное руководство пользователя распределенной системы обмена сообщениями реального времени **«Minor»** (версия 0.1). Система разработана для оптимизации информационного обмена на кафедре Информационных Технологий и Систем (ИТИС) НовГУ. Она представляет собой суверенный аналог коммуникационных платформ Discord и Slack, функционирующий на базе микросервисной архитектуры с использованием технологий Go, Cassandra, PostgreSQL, Redis и NATS JetStream.
+
+Руководство пользователя составлено в строгом соответствии с требованиями межгосударственного стандарта **ГОСТ 19.502-90** (Единая система программной документации. Описание применения) и регламентирует структуру, системные требования, процессы установки, тестирования и повседневной эксплуатации системы как в десктопной (веб-клиент), так и в мобильной версиях.
+
+---
+
+# Содержание
+
+- [1. Введение](#1-введение)
+  - [1.1. Область применения](#11-область-применения)
+  - [1.2. Краткое описание возможностей](#12-краткое-описание-возможностей)
+  - [1.3. Уровень подготовки пользователя](#13-уровень-подготовки-пользователя)
+  - [1.4. Перечень эксплуатационной документации](#14-перечень-эксплуатационной-документации)
+- [2. Назначение и условия применения](#2-назначение-и-условия-применения)
+  - [2.1. Назначение программы](#21-назначение-программы)
+  - [2.2. Системные требования и условия применения](#22-системные-требования-и-условия-применения)
+- [3. Подготовка к работе](#3-подготовка-к-работе)
+  - [3.1. Состав и содержание дистрибутивного носителя](#31-состав-и-содержание-дистрибутивного-носителя)
+  - [3.2. Порядок загрузки данных и программ](#32-порядок-загрузки-данных-и-программ)
+  - [3.3. Порядок проверки работоспособности](#33-порядок-проверки-работоспособности)
+- [4. Описание операций](#4-описание-операций)
+  - [4.1. Регистрация и аутентификация пользователя](#41-регистрация-и-аутентификация-пользователя)
+  - [4.2. Главное меню программы](#42-главное-меню-программы)
+  - [4.3. Управление профилем и настройки](#43-управление-профилем-и-настройки)
+  - [4.4. Навигация по серверам и создание каналов](#44-навигация-по-серверам-и-создание-каналов)
+  - [4.5. Обмен сообщениями](#45-обмен-сообщениями)
+  - [4.6. Завершение работы с программой](#46-завершение-работы-с-программой)
+- [5. Аварийные ситуации](#5-аварийные-ситуации)
+- [6. Рекомендации по освоению](#6-рекомендации-по-освоению)
+- [7. Термины и сокращения](#7-термины-и-сокращения)
+- [Лист регистрации изменений](#лист-регистрации-изменений)
+
+---
+# 1. Введение
+
+## 1.1. Область применения
+
+Распределенная информационная система реального времени **Minor** предназначена для использования на кафедре Информационных Технологий и Систем НовГУ имени Ярослава Мудрого. Основными пользователями системы являются:
+
+- Студенты бакалавриата и магистратуры, координирующие выполнение групповых проектов и лабораторных работ.
+- Преподавательский состав кафедры, использующий систему для проведения консультаций, выдачи заданий и контроля успеваемости.
+- Администраторы кафедры, управляющие распределением прав и доступом к учебным ресурсам.
+
+Программа функционирует в корпоративной сети университета с возможностью внешнего доступа через защищенные каналы связи. Внедрение Minor позволяет исключить риски потери данных в облачных зарубежных сервисах и перевести внутреннее взаимодействие на суверенную инфраструктуру.
+
+## 1.2. Краткое описание возможностей
+
+Программный продукт предоставляет пользователям следующий набор функциональных возможностей:
+
+- **Аутентификация и авторизация:** безопасный вход в систему по корпоративным учетным записям, защита сессий при помощи токенов JWT (Access и Refresh).
+- **Управление серверами:** организация изолированных пространств для различных академических дисциплин, курсов или проектных групп.
+- **Каналы коммуникации:** деление серверов на текстовые каналы (для обсуждений, публикации учебных материалов и файлов) и голосовые каналы (для проведения онлайн-семинаров и аудиосвязи в реальном времени с минимальной задержкой).
+- **Обмен мгновенными сообщениями:** отправка текстовой информации (длиной до 2000 символов) по протоколу WebSocket с задержкой доставки менее 100 мс.
+- **Профили пользователей:** кастомизация личных данных (ФИО, академическая группа, аватар) и системных настроек (звуки, уведомления, выбор темы оформления).
+- **Уведомления и статусы:** автоматическое отслеживание статуса присутствия участников ("В сети" / "Не в сети") и индикация непрочитанных сообщений в каналах.
+
+## 1.3. Уровень подготовки пользователя
+
+Для работы с пользовательскими интерфейсами системы Minor (веб-клиент, мобильное приложение) от пользователя не требуется специальной технической подготовки. Достаточно обладать базовыми навыками работы на персональном компьютере или смартфоне под управлением Android/iOS и уметь использовать стандартные интернет-браузеры.
+
+Для администраторов системы, осуществляющих развертывание, конфигурацию и техническую поддержку серверной части, необходим следующий уровень квалификации:
+
+- Системное администрирование операционных систем семейства Linux (Ubuntu Server).
+- Навыки контейнеризации приложений с использованием Docker и оркестрации через Docker Compose.
+- Базовые знания языков запросов SQL (для PostgreSQL) и CQL (для Apache Cassandra).
+- Опыт конфигурирования брокеров сообщений (NATS) и шлюзов API (Traefik).
+
+## 1.4. Перечень эксплуатационной документации
+
+В состав пакета эксплуатационной документации программного продукта Minor входят следующие документы:
+
+- **Техническое задание** ([ТЗ-Minor.docx](file:///Users/odner/Desktop/morkin/ТЗ-Minor.docx)): определяет исходные цели разработки и технические рамки.
+- **Спецификация требований к программному обеспечению** ([LAB7-Minor.docx](file:///Users/odner/Desktop/morkin/LAB7-Minor.docx)): детально описывает логику работы микросервисов и схемы баз данных.
+- **Руководство пользователя** ([LR14-Minor.docx](file:///Users/odner/Desktop/morkin/LR14-Minor.docx)): текущий документ, содержащий руководство по установке и эксплуатации.
+
+---
+# 2. Назначение и условия применения
+
+## 2.1. Назначение программы
+
+Программа Minor предназначена для автоматизации процессов обмена сообщениями, координации совместной проектной деятельности студентов и проведения оперативных онлайн-консультаций преподавателями в рамках образовательного процесса кафедры ИТИС НовГУ.
+
+## 2.2. Системные требования и условия применения
+
+Для стабильного функционирования серверной части распределенной системы Minor в условиях средней нагрузки (до 500 активных WebSocket-соединений одновременно) должны быть обеспечены следующие минимальные параметры окружения:
+
+**Аппаратные требования к серверу:**
+- **Процессор:** x86_64 или ARM64 с тактовой частотой не менее 2.5 ГГц, количество ядер — не менее 4.
+- **Оперативная память:** не менее 8 Гб (рекомендуется 16 Гб для стабильной работы СУБД Cassandra в Java Virtual Machine).
+- **Дисковая подсистема:** твердотельный накопитель SSD объемом не менее 50 Гб со скоростью чтения/записи не ниже 500 Мб/с.
+- **Сетевой интерфейс:** гигабитный сетевой адаптер (1 Gbps Ethernet).
+
+**Программные требования к серверу:**
+- **Операционная система:** Ubuntu Server 22.04 LTS или аналогичный Linux-дистрибутив (ядро версии 5.15 и выше).
+- **Платформа контейнеризации:** Docker Engine версии 24.0.0 и выше.
+- **Инструмент оркестрации:** Docker Compose v2.20.0 и выше.
+
+**Требования к клиентским устройствам:**
+- **Персональный компьютер:** ОС Windows 10/11, macOS 12+ или Linux; установленный браузер Google Chrome 110+, Mozilla Firefox 100+, Apple Safari 15+ с поддержкой HTML5 и WebSockets.
+- **Мобильное устройство:** смартфон под управлением Android 10.0+ или iOS 15.0+; стабильное подключение к сети Интернет или интрасети НовГУ (Wi-Fi/4G).
+
+---
+# 3. Подготовка к работе
+
+## 3.1. Состав и содержание дистрибутивного носителя
+
+Программное обеспечение Minor поставляется в виде Git-репозитория. В соответствии со структурой проекта, состав дистрибутивного пакета содержит следующие компоненты:
+
+| Путь в репозитории | Описание | Тип |
+| :--- | :--- | :--- |
+| `/backend/` | Корневая директория бэкенд-компонентов системы. | Каталог |
+| `/backend/services/` | Каталог микросервисов системы (`api_gateway`, `auth_service`, `chat_service`, `gateway_service`, `guild_service`, `notification_service`, `presence_service`, `sfu_service`, `signal_service`, `upload_service`, `user_service`). | Каталог |
+| `/backend/shared/` | Общие библиотеки (`pkg`) и protobuf-определения API (`api`). | Каталог |
+| `/deploy/` | Скрипты и файлы для развертывания инфраструктуры. | Каталог |
+| `/deploy/docker-compose.yaml` | Конфигурация Docker Compose для запуска всех сервисов и баз данных. | YAML-файл |
+| `/docs/` | Техническая документация проекта. | Каталог |
+| `/frontend/` | Исходный код клиентской веб-панели (React/Vite). | Каталог |
+
+## 3.2. Порядок загрузки данных и программ
+
+Развертывание программного продукта на сервере производится в соответствии со следующим пошаговым алгоритмом:
+
+1. **Шаг 1. Получение дистрибутива:**  
+   Склонируйте репозиторий с исходным кодом в локальную директорию на сервере:
+   ```bash
+   git clone http://172.20.7.4:3000/minor-chat/minor.git /opt/minor
+   ```
+
+2. **Шаг 2. Конфигурирование системы:**  
+   Перейдите в каталог нужного сервиса бэкенда (например, `chat_service`) и создайте рабочий файл конфигурации окружения `.env` на основе шаблона:
+   ```bash
+   cd /opt/minor/backend/services/chat_service && cp .env.example .env
+   ```
+   Отредактируйте параметры подключения к БД, секретный ключ JWT для шифрования токенов и порты.
+
+3. **Шаг 3. Подготовка баз данных:**  
+   Перейдите в каталог развертывания `deploy`, запустите контейнеры баз данных (PostgreSQL и Cassandra) и примените файлы миграций схем данных:
+   ```bash
+   cd /opt/minor/deploy && docker-compose up -d postgres cassandra
+   ```
+   Убедитесь, что порты доступны, и выполните:
+   ```bash
+   migrate -path ../backend/services/chat_service/migrations -database "postgres://postgres:secret@localhost:5432/minor?sslmode=disable" up
+   ```
+
+4. **Шаг 4. Запуск всех компонентов:**  
+   Запустите сборку образов микросервисов и разверните всю распределенную систему Minor:
+   ```bash
+   cd /opt/minor/deploy && docker-compose up --build -d
+   ```
+
+## 3.3. Порядок проверки работоспособности
+
+Для верификации корректности развертывания распределенной системы выполните следующие действия:
+
+1. Выполните HTTP-запрос к эндпоинту проверки состояния микросервиса авторизации:
+   ```bash
+   curl -i http://localhost:8080/api/v1/auth/health
+   ```
+   Сервер должен вернуть статус `200 OK` и JSON-тело `{"status": "healthy"}`.
+
+2. Проверьте логи шлюза API Traefik на отсутствие критических ошибок маршрутизации:
+   ```bash
+   cd /opt/minor/deploy && docker-compose logs | grep -E "(ERROR|FATAL)"
+   ```
+
+3. Убедитесь в активности очередей в брокере сообщений NATS JetStream, выполнив команду в контейнере:
+   ```bash
+   cd /opt/minor/deploy && docker-compose exec nats nats stream info server_messages
+   ```
+
+4. Откройте веб-браузер на клиентском компьютере, перейдите по настроенному доменному адресу (например, `http://minor.novsu.ru`) и убедитесь в отображении стартовой страницы авторизации.
+
+---
+
+# 4. Описание операций
+
+## 4.1. Регистрация и аутентификация пользователя
+
+При первом обращении к системе пользователь видит экран авторизации.
+
+- Если учетная запись еще не создана, необходимо нажать на ссылку **«Регистрация»** и ввести адрес корпоративной почты, имя пользователя и надежный пароль.
+- Для входа в систему введите e-mail и пароль в соответствующие поля ввода формы (Рисунок 1).
+- После успешной аутентификации Auth Service сгенерирует токен, который запишется в защищенные cookie браузера, и клиент будет автоматически перенаправлен на главный рабочий экран.
+
+|           *Рисунок 1 – Авторизация*            |
+| :----------------------------------------------: |
+| ![Рисунок 4 – Главный экран](./media/image1.png) |
+
+## 4.2. Главное меню программы
+
+Главный интерфейс Minor разделен на несколько функциональных зон (Рисунок 2):
+
+- В нижней части мобильного приложения (или в левой части веб-версии) отображаются круглые иконки доступных серверов (гильдий), а также кнопка быстрого перехода к личным сообщениям.
+- В центральной области выводится текущий выбранный чат.
+- Панель поиска сверху позволяет выполнять полнотекстовый поиск по истории личных сообщений (Рисунок 3).
+
+|           *Рисунок 2 – Главный экран*            |           *Рисунок 3 – Поиск в главном меню*            |
+| :----------------------------------------------: | :-----------------------------------------------------: |
+| ![Рисунок 2 – Главный экран](./media/image2.png) | ![Рисунок 3 – Поиск в главном меню](./media/image3.png) |
+
+## 4.3. Управление профилем и настройки
+
+Нажав на иконку настроек профиля, пользователь попадает в меню конфигурации (Рисунок 4). В данном разделе доступны:
+
+- Настройка приватности и доступа.
+- Управление системными звуковыми уведомлениями.
+- Переключение цветового оформления интерфейса (Светлая тема / Темная тема).
+
+|           *Рисунок 4 – Настройки*            |
+| :----------------------------------------------: |
+| ![Рисунок 4 – Главный экран](./media/image4.png) |
+
+## 4.4. Навигация по серверам и создание каналов
+
+При переходе на один из серверов в левой панели отображается список доступных каналов (Рисунок 5):
+
+- **Текстовые каналы** (помечаются знаком `#`) используются для обмена сообщениями и учебными файлами.
+- **Голосовые каналы** (помечаются значком динамика) служат для мгновенного подключения к голосовой связи. Достаточно кликнуть на канал для начала аудиообщения.
+
+|           *Рисунок 5 – Экран сервера*            |
+| :----------------------------------------------: |
+| ![Рисунок 5 – Экран сервера](./media/image5.png) |
+
+## 4.5. Обмен сообщениями
+
+Для отправки сообщения выберите нужный текстовый канал, введите текст в поле ввода внизу экрана и нажмите клавишу **Enter** (или кнопку **«Отправить»**).
+
+- Для отправки файлов воспользуйтесь кнопкой со скрепкой.
+- Для записи голосового сообщения удерживайте кнопку с изображением микрофона.
+- Интерфейс личной переписки с другим пользователем представлен на Рисунке 6. Окно чата в текстовом канале сервера представлено на Рисунке 7.
+
+| *Рисунок 6 – Личная переписка* | *Рисунок 7 – Переписка в канале* |
+| :---: | :---: |
+| ![Рисунок 6 – Личная переписка](./media/image6.png) | ![Рисунок 7 – Переписка в канале](./media/image7.png) |
+
+## 4.6. Завершение работы с программой
+
+Для корректного выхода из системы и предотвращения несанкционированного доступа к аккаунту с текущего устройства откройте настройки профиля и нажмите на кнопку **«Logout»** (Рисунок 4). В результате сессия будет аннулирована, а авторизационные токены удалены из памяти устройства.
+
+---
+
+# 5. Аварийные ситуации
+
+В процессе эксплуатации распределенной системы Minor возможны сбои программного и аппаратного характера. Ниже представлены сценарии реагирования на нештатные ситуации:
+
+**Временная потеря сетевого соединения клиентом:**
+- *Поведение системы:* Пользовательский веб-клиент автоматически переходит в режим ожидания. На экране отображается сообщение *«Соединение потеряно. Попытка переподключения...»*.
+- *Действия пользователя:* Проверить физическое подключение к сети Интернет или интрасети НовГУ. При восстановлении связи клиентское приложение восстановит WebSocket-сессию автоматически без потери истории сообщений.
+
+**Отказ базы данных истории сообщений (Apache Cassandra):**
+- *Поведение системы:* При попытке отправки или получения старых сообщений интерфейс выдает ошибку *«Не удалось загрузить сообщения. Пожалуйста, попробуйте позже»* (HTTP-статус 500). Работа авторизации и голосовых каналов при этом сохраняется (отказоустойчивость).
+- *Действия администратора:* Подключиться к серверу по SSH, проверить логи контейнера базы данных:
+  ```bash
+  docker-compose logs cassandra
+  ```
+  В случае необходимости выполнить перезапуск службы:
+  ```bash
+  docker-compose restart cassandra
+  ```
+
+**Истечение времени действия сессии (JWT токена):**
+- *Поведение системы:* При выполнении любого действия (отправка сообщения, переход в канал) система перенаправляет пользователя на форму входа.
+- *Действия пользователя:* Повторно пройти процедуру авторизации, введя логин и пароль.
+
+**Сбой брокера сообщений NATS JetStream:**
+- *Поведение системы:* Сообщения сохраняются в БД, но перестают приходить другим участникам в реальном времени до момента ручного обновления страницы.
+- *Действия администратора:* Проверить статус контейнера NATS и очистить зависшие сообщения в очереди при переполнении диска.
+
+---
+
+# 6. Рекомендации по освоению
+
+Для быстрого и эффективного начала работы с системой Minor рекомендуется придерживаться следующих шагов:
+
+- **Изучение интерфейса:** Основное расположение элементов управления (серверы, каналы, настройки) аналогично популярным мессенджерам Discord и Slack. Освоение базового функционала занимает у среднего пользователя не более 10–15 минут.
+- **Групповая координация:** Рекомендуется создавать отдельные серверы для каждой учебной дисциплины, а внутри них группировать каналы по типам заданий (например, текстовые каналы `#лекции`, `#лабораторные` и голосовой канал `Консультации` для созвонов с преподавателем).
+
+---
+
+# 7. Термины и сокращения
+
+Таблица 2 – Термины и сокращения
+
+| Термин / Сокращение | Расшифровка | Описание |
+| :--- | :--- | :--- |
+| **БД** | База Данных | Организованная структура для хранения системной информации. |
+| **СУБД** | Система Управления Базами Данных | Специализированное ПО для управления реляционными и нереляционными данными. |
+| **JWT** | JSON Web Token | Стандарт токенов для безопасной передачи claims (утверждений) между сторонами. |
+| **NATS JetStream** | Брокер сообщений | Распределенная система обмена сообщениями, обеспечивающая доставку событий в реальном времени. |
+| **UUIDv7** | Universally Unique Identifier | Уникальный 128-битный идентификатор, генерируемый с использованием временной метки (timestamp-first). |
+| **API** | Application Programming Interface | Программный интерфейс взаимодействия между клиентами и бэкенд-службами. |
+| **gRPC** | Google Remote Procedure Call | Фреймворк для быстрого межсервисного взаимодействия с использованием Protocol Buffers. |
+| **WebSocket** | Протокол связи | Протокол двусторонней полнодуплексной связи поверх TCP-соединения для Real-time обмена. |
+| **Гильдия / Сервер** | Тематическое сообщество | Изолированное коммуникационное пространство внутри Minor, содержащее каналы и участников. |
+
+
+---
+
+# Лист регистрации изменений
+
+| Номер изменения |   Тип изменения    | Дата изменения | Описание внесенных изменений                                            | Автор изменения             |
+| :-------------: | :----------------: | :------------: | :---------------------------------------------------------------------- | :-------------------------- |
+|     **0.1**     | Создание документа |   20.05.2026   | Разработка первичной версии руководства пользователя по ГОСТ 19.502-90. | Ильин Д. А., Распопов С. И. |
+