# Документация модуля диалогов (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`) и обновлении состава участников.