Структура, доп модули, федерация, документация

backend/src/Docs/conversations_module_documentation.md

@@ -0,0 +1,84 @@
+# Документация модуля диалогов (Conversations Module)
+
+Модуль Conversations является центральным узлом Knot Messager, обеспечивающим взаимодействие пользователей через чаты, управление сообщениями и организацию рабочего пространства с помощью папок.
+
+## Основные сущности
+
+### 1. Чат (Chat)
+Основная единица общения. Бывает трех типов:
+*   **Personal**: Диалог между двумя пользователями.
+*   **Group**: Групповой чат с неограниченным (или лимитированным админом) количеством участников.
+*   **Favorites**: Спец-чат "Избранное" (заметки для самого себя).
+
+### 2. Участник (Member)
+Связующее звено между пользователем и чатом. Хранит:
+*   Роль (Admin, Moderator, Member).
+*   **Cursors**: Указатели на последнее прочитанное и последнее доставленное сообщение для синхронизации статусов.
+
+### 3. Папка (Folder)
+Инструмент группировки чатов.
+*   **Системные папки**: "Все чаты", "Новые" (с непрочитанными), "Без звука".
+*   **Пользовательские папки**: Создаются пользователем вручную по имени и иконке.
+*   *Особенность*: Один чат может находиться одновременно в нескольких папках.
+
+## Функциональные возможности
+
+### Управление чатами
+*   Создание личных и групповых чатов.
+*   Редактирование названия, описания и аватара группы (с поддержкой обрезки изображения).
+*   Управление участниками (добавление, удаление, выход из чата).
+*   Закрепление чатов (Pin) для быстрого доступа.
+*   Очистка истории сообщений для конкретного пользователя.
+
+### Работа с сообщениями
+Модуль предоставляет высокоуровневый API для отправки контента:
+*   **Текстовые сообщения**: С поддержкой цитирования и ответов.
+*   **Медиа-сообщения**: Фото, видео, файлы, голосовые сообщения.
+*   **Опросы**: Анонимные или публичные, с выбором одного или нескольких вариантов.
+*   **Истории**: Ответы на истории и реакции (пересылаются в чат как спец-сообщения).
+*   **Пересылка (Forwarding)**: Отправка существующих сообщений в другие чаты.
+
+### Синхронизация и поиск
+*   **Курсоры чтения**: Позволяют клиенту точно знать, какие сообщения новы для пользователя.
+*   **Shared Media**: Быстрый доступ ко всем файлам, ссылкам или фото, когда-либо отправленным в конкретном чате.
+*   **Глобальный поиск**: Поиск по тексту сообщений во всех доступных чатах.
+
+---
+
+## API Эндпоинты
+
+### Чаты (`api/chats`)
+*   `GET /` — Получение списка всех чатов пользователя.
+*   `POST /personal` — Создание диалога с пользователем.
+*   `POST /group` — Создание группы.
+*   `PUT /{id}` — Обновление информации о чате.
+*   `POST /{id}/pin` — Закрепить/открепить чат.
+*   `POST /{id}/avatar` — Загрузка аватара группы.
+
+## Зависимость от глобальных настроек (Admin Module)
+
+Логика модуля Conversations напрямую зависит от конфигурации, установленной администратором в `Admin Module`:
+
+1.  **Медиа-сообщения**: Перед отправкой фото, видео или файлов проверяется флаг `AllowMedia`. Если он выключен, сервер возвращает ошибку `Media.Disabled`.
+2.  **Опросы**: Создание опросов возможно только при включенном флаге `AllowPolls`. В противном случае возвращается `Polls.Disabled`.
+3.  **Папки**: Функционал группировки чатов по папкам контролируется флагом `EnableFolders`. При его отключении команды добавления в папку ([AddToFolder](file:///e:/GIT/forkmessager/backend/src/Modules/Conversations/Domain/Folder.cs#67-71)) блокируются с ошибкой `Folders.Disabled`.
+4.  **Групповые чаты**: Лимит на количество участников в группе (`MaxGroupParticipants`) проверяется при создании чата и добавлении новых членов.
+
+## Сообщения (`api/messages`)
+*   `POST /chat/{chatId}` — Отправка сообщения.
+*   `GET /chat/{chatId}` — Получение истории (поддерживает пагинацию через курсоры).
+*   `POST /upload` — Предварительная загрузка файла в хранилище.
+*   `GET /search` — Поиск сообщений.
+
+### Папки (`api/folders`)
+*   `POST /add` — Добавление чата в папку.
+*   `POST /remove` — Удаление из папки.
+
+---
+
+## Интеграция и Real-time
+
+Модуль тесно интегрирован с:
+*   **Messaging**: Для фактического хранения и доставки тел сообщений (в MongoDB).
+*   **Storage**: Для обработки вложений и аватаров.
+*   **SignalR (ChatHub)**: Для мгновенной доставки уведомлений о новых сообщениях, статусах прочтения (`message_read`) и обновлении состава участников.