# Модуль Связей (Relations Module) — Knot Messager

Модуль Связей (Relations) является архитектурным фундаментом для управления социальным графом и разграничения прав доступа между узлами (пользователями) в Knot Messager. Он аккумулирует в себе все типы взаимодействий: от контактов и подписок до блокировок и федеративных связей.

---

## 🏗 Архитектура и Назначение

Модуль Relations отделен от модуля аутентификации ([Auth](file:///e:/GIT/forkmessager/backend/src/Modules/Auth/Domain/AuthErrors.cs#5-15)) и модуля сообщений (`Messaging`), что позволяет ему выступать **Единым источником истины (SSOT)** для ответов на вопросы:
1.  Является ли Пользователь Б контактом Пользователя А?
2.  Может ли Пользователь А видеть истории или статус Presence Пользователя Б?
3.  Находится ли отправитель в черном списке получателя?

---

## ⚡ Репликация данных (UserReplica Ecosystem)

Для обеспечения высокой скорости работы и соблюдения принципов **Clean Architecture**, модуль Relations оперирует локальными репликами данных:
*   **UserReplica**: Содержит базовую информацию о пользователе (Id, Username, DisplayName, Avatar).
*   **Federation Metadata**: Хранит признаки внешнего пользователя (`IsExternal`, [Domain](file:///e:/GIT/forkmessager/backend/src/Modules/Federation/Application/Federation/Events/FederatedMessageActionsHandler.cs#86-97)).
*   **Автономия**: Все запросы на получение списков контактов и статусов связей выполняются внутри схемы `relations`, что исключает межмодульные Joins и повышает производительность системы.

---

## 📂 Типы связей: Контакты (Contacts)

В текущей версии мессенджера основной реализацией связей являются **Контакты**:
*   **Contact Request**: Модель взаимодействия, требующая явного подтверждения (Accept).
*   **Status Management**: Сущность [Contact](file:///e:/GIT/forkmessager/backend/src/Modules/Relations/Domain/Contact.cs#21-22) поддерживает полный жизненный цикл связи: `Pending` ➡ `Accepted` ➡ `Blocked/Removed`.

### Статусы взаимодействия:
| Статус | Описание |
| :--- | :--- |
| `Pending` | Запрос на связь отправлен, ожидает решения получателя. |
| `Accepted` | Двусторонняя связь установлена. Разрешены: сообщения, истории, Presence. |
| `Blocked` | Черный список. Полная блокировка любых входящих сигналов от данного узла. |
| `Declined` | Запрос отклонен пользователем. |

---

## 📡 API и Эндпоинты

Системный путь: `/api/contacts` (в рамках модуля Relations).

*   `GET /api/contacts` — Получить список активных контактов.
*   `POST /api/contacts/request` — Создать новую связь (запрос).
*   `POST /api/contacts/{id}/accept` — Подтвердить входящую связь.
*   `DELETE /api/contacts/{id}` — Разорвать связь (удалить контакт).

---

## 🌍 Федерация и Масштабируемость

Модуль Relations спроектирован с учетом **Federation-First**:
1.  **Cross-Server Identity**: При создании связи с внешним пользователем (например, `bob@knot.cloud`), модуль Relations автоматически создает запись в [UserReplica](file:///e:/GIT/forkmessager/backend/src/Modules/Relations/Domain/UserReplica.cs#3-12) с пометкой `IsExternal = true`.
2.  **Privacy Control**: Перед любой передачей данных через `Federation Gateway`, система проверяет статус связи в модуле [Relations](file:///e:/GIT/forkmessager/backend/src/Modules/Relations/Infrastructure/Persistence/RelationsDbContext.cs#13-71), обеспечивая приватность данных пользователей.

---

## 🧩 Интеграция с другими модулями

*   **Stories Module**: Использует [Relations](file:///e:/GIT/forkmessager/backend/src/Modules/Relations/Infrastructure/Persistence/RelationsDbContext.cs#13-71), чтобы определить круг лиц, имеющих право на просмотр ленты историй.
*   **Messaging Module**: Запрашивает статус связи для фильтрации спама и применения настроек приватности.
*   **Admin Module**: Позволяет администраторам видеть анонимизированную статистику связей в системе.

---

> [!IMPORTANT]
> Модуль Relations использует схему `relations` в БД. Любые расширения социального графа (подписки на каналы, групповые связи) должны реализовываться именно здесь для сохранения архитектурной чистоты.
