Files
Govor/docs/messaging-and-benefits.md
T
Artemy 632ac04b56 Add forwarding, friend controls, and benefits
Add message forwarding and reply lookup, friend removal and blocking endpoints, and database-backed Govor+ privileges with customizable profile tags. Include migrations, integration tests, and updated API and operations documentation.
2026-10-31 18:29:40 +07:00

18 KiB
Raw Blame History

Ответы, пересылки, блокировки и Govor+

Все запросы требуют действующего access JWT. Для HTTP передавайте Authorization: Bearer <token>, для SignalR используйте существующую авторизацию хабов. Новые поля совместимы с прежними клиентами: идентификаторы связей nullable, у пользователей без назначенных прав privileges = 0.

Ответ на сообщение

Вызовите Send в /hubs/chats, указав replyToMessageId:

{
  "recipientId": "<chat-id>",
  "recipientType": 0,
  "encryptedContent": "<fresh E2EE envelope>",
  "replyToMessageId": "<original-message-id>",
  "mediaAttachments": []
}

recipientType: 0 — личный чат, 1 — группа/канал. Ответ должен ссылаться на существующее сообщение того же чата и типа. Сервер проверяет право отправки, включая блокировку в личном чате, бан в группе и роль администратора канала. Для E2EE replyToMessageId должен совпадать с replyTo подписанного конверта. В публичных группах допускается обычное содержимое согласно существующей политике.

Связь возвращается в результате Send, событиях сообщений и истории. Для превью ответа за пределами загруженной страницы используйте GET /api/messages/{messageId}. Ответ — MessageResponse с вложениями, реакциями и прочтениями. Отсутствующее сообщение и отсутствие доступа дают одинаковый 404, без раскрытия чужого чата. После удаления оригинала ссылка остаётся; клиент показывает «Сообщение удалено». Содержимое удалённого сообщения сервер не архивирует в ответе.

Пересылка

Используется тот же Send; добавьте forwardedFromMessageId, передайте новое содержимое и принадлежащие отправителю вложения для чата назначения:

{
  "recipientId": "<destination-chat-id>",
  "recipientType": 0,
  "encryptedContent": "<new envelope encrypted for destination devices>",
  "forwardedFromMessageId": "<source-message-id>",
  "mediaAttachments": []
}

Сервер проверяет доступ отправителя к исходному сообщению и право отправки в чат назначения. Несуществующий или недоступный источник отклоняется без записи сообщения и push. Автор и дата источника берутся из БД, клиент не может передать их сам:

Поле ответа/истории Значение
senderId Пользователь, выполнивший пересылку
forwardedFromMessageId ID непосредственно пересланного сообщения
forwardedFromUserId Автор непосредственно пересланного сообщения
forwardedFromSentAt Дата отправки источника, UTC

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

Для зашифрованных сообщений клиент расшифровывает оригинал локально, затем шифрует новое сообщение для актуального набора устройств назначения с новым messageId. Вложения нужно заново загрузить от текущего пользователя; для E2EE зашифровать их новыми ключами, а ключи поместить внутрь конверта. Прямая подстановка чужих media ID не даёт прав на файлы. Сервер не расшифровывает содержимое и не может проверить, что текст пересылки идентичен оригиналу; метаданные происхождения не являются подписью исходного автора под новым содержимым.

Повтор одного E2EE-запроса с тем же ID идемпотентен; изменение источника, адресата, содержимого, ответа или вложений с прежним ID отклоняется. В публичных чатах без E2EE каждый Send создаёт новое сообщение. Для массовой пересылки выполняйте отдельный вызов для каждого сообщения и адресата.

Удаление из друзей и блокировка

HTTP Действие
DELETE /api/friends/{userId} Удалить принятую дружбу
PUT /api/friends/{userId}/block Заблокировать пользователя
DELETE /api/friends/{userId}/block Снять собственную блокировку

Успех — 204. Идентификатор текущего пользователя всегда берётся из JWT. Пустой ID и действие на себя дают 400; блокировка несуществующего пользователя — 404; изменение чужой блокировки — 403.

Удаление идемпотентно, переводит принятую дружбу в Rejected, сохраняет историю чата и не снимает блокировку. Само удаление дружбы не запрещает отправку в ранее созданный чат: для этого нужна блокировка. Блокировка может создаваться без дружбы, исключает пользователя из друзей и запрещает новые сообщения в личном чате в обе стороны, а также новые заявки. Чтение истории и общие группы сохраняются.

Используется существующая модель FriendshipStatus.Blocked: у пары одна блокировка, её владелец записан как RequesterId. Только владелец может снять её; вторая сторона не может заменить владельца. Повтор собственной блокировки безопасен. Снятие блокировки не восстанавливает дружбу: требуется новая заявка и согласие получателя.

Привилегии и Govor+

Платёжная подписка не требуется: статус назначает администратор во время работы сервера. Права читаются из БД при каждой операции и не кешируются в JWT.

Бит privileges Право
0 Без специальных прав
1 Govor+: официальный статус и настройка тега
2 Настройка тега без статуса Govor+
3 Оба явно назначенных бита

PUT /api/admin/users/{userId}/privileges принимает {"privileges": 1}. Требуется роль Admin; endpoint заменяет весь набор прав. Для отзыва всех прав передайте 0. Неизвестные биты дают 400, неизвестный пользователь — 404, конкурентное создание записи прав — 409 (перечитайте состояние и повторите запрос). Govor+ не выдаёт административных ролей. Новые возможности добавляются отдельными битами с явной проверкой в соответствующем серверном сервисе.

GET /api/profile/{userId}/benefits возвращает:

{
  "privileges": 1,
  "isGovorPlus": true,
  "canCustomizeProfileTag": true,
  "tag": {
    "text": "Govor+",
    "textColor": "#FFFFFF",
    "textGradientEndColor": null,
    "backgroundColor": "#2455DD",
    "gradientEndColor": null,
    "gradientAngle": 90,
    "borderColor": "#6688FF",
    "borderGradientEndColor": null,
    "borderWidth": 1,
    "shadowColor": "#00000080",
    "shadowBlur": 4,
    "shadowOffsetX": 0,
    "shadowOffsetY": 1,
    "fontFamily": "Inter",
    "fontWeight": 600,
    "fontSize": 12
  },
  "revision": 1
}

Тот же объект benefits входит в GET /api/profile/download/me и GET /api/profile/download/{id}. Обычный пользователь получает tag: null. У Govor+ без своего оформления отображается стандартный тег. Официальный статус нужно определять по isGovorPlus, а не по произвольному тексту тега.

Настройка тега

У каждого пользователя один настраиваемый профильный тег. PUT /api/profile/tag заменяет оформление текущего пользователя объектом tag из примера выше; пропущенные поля получают стандартные значения. DELETE /api/profile/tag сбрасывает оформление к стандартному. Оба endpoint возвращают актуальный UserBenefitsView и требуют права настройки; иначе 403.

Параметр Допустимое значение
text 1–32 UTF-16 символа, не пробельная строка, без управляющих символов
Цвета #RRGGBB или #RRGGBBAA
gradientEndColor Конечный цвет градиента фона; null — сплошной фон
textGradientEndColor, borderGradientEndColor Конечные цвета градиентов текста и обводки; null — сплошной цвет
gradientAngle 0–360°, общий угол линейных градиентов
borderWidth 0–4
shadowBlur 0–20
shadowOffsetX, shadowOffsetY −10–10
fontFamily Inter, Roboto, Arial, Noto Sans, serif, sans-serif, monospace
fontWeight 100–900 с шагом 100
fontSize 10–24

Размеры заданы в логических пикселях. Угол соответствует CSS linear-gradient: 0° вверх, 90° вправо. Клиент обеспечивает наличие выбранного шрифта или безопасный fallback. Тег — структурированные данные: текст рендерится как plain text, а не HTML; URL шрифтов, произвольный CSS и внешние ресурсы не принимаются. Некорректное оформление даёт 400 и не изменяет сохранённый тег.

При отзыве прав сохранённое оформление остаётся в БД, но скрывается в API и не может редактироваться. При повторной выдаче права оформление восстанавливается.

Обновления в реальном времени

Подключите каждый клиент к /hubs/profiles и слушайте UserBenefitsUpdated:

connection.on("UserBenefitsUpdated", ({ userId, benefits }) => {
  const old = profileBenefits.get(userId);
  if (!old || benefits.revision > old.revision) {
    profileBenefits.set(userId, benefits);
    refreshVisibleUserTags(userId);
  }
});

Событие содержит полный объект, включая revision, и отправляется всем подключённым авторизованным клиентам этого хаба, включая владельца, после фиксации выдачи/отзыва прав, изменения или сброса тега. Дружба или подписка на конкретный профиль не требуется. Статус и тег — публичные данные для авторизованных пользователей. Обновляйте общий кеш профилей и все места отображения пользователя: чат, список участников, друзей и открытый профиль. HTTP-ответ содержит тот же формат.

Ревизия монотонно увеличивается на пользователя; игнорируйте события и HTTP-снимки с меньшей или равной ревизией. Это защищает от изменения порядка доставки при конкурентных запросах. Сначала зарегистрируйте обработчик, подключитесь, затем загрузите HTTP-снимки, также сравнивая ревизии.

SignalR не хранит историю событий: после восстановления соединения перечитайте видимые профили/benefits через HTTP. При сбое доставки сохранённый HTTP-запрос остаётся успешным, ошибка пишется в серверный лог; снимок в БД является источником истины. Перезапуск API для выдачи статуса или изменения оформления не нужен. При запуске нескольких экземпляров API необходим общий SignalR backplane/service для доставки между экземплярами; текущая конфигурация использует стандартный in-process SignalR.

Миграции и проверка

Перед запуском новой версии примените миграции обычным способом проекта (dotnet run --project Govor.API -- --migrate-only). Добавлены nullable-поля пересылки в Messages, таблица UserBenefits и её ревизия. Старые сообщения и пользователи сохраняются; существующим пользователям права автоматически не выдаются.

Проверки находятся в ReplyAndForwardTests, UserBenefitsTests, E2eeTests и ReadApiTests (UserBenefitsHttpTests.cs). Они проверяют SQL-хранение, отсутствие доступа к чужим сообщениям, шифрование пересылки для нового адресата, идемпотентность, права админа, валидацию оформления и доставку выдачи/изменения/сброса/отзыва статуса через реальные WebSocket-подключения трёх пользователей.

dotnet test Govor.Server.slnx --no-restore

Результат проверки 31.10.2026

На итоговом исходном коде dotnet test Govor.Server.slnx --no-restore -c Release с Coverlet завершился успешно: 771 тест, из них 36 новых. Использовались SQLite in-memory, HTTP TestServer и реальные SignalR WebSocket-соединения. Миграции проверены через has-pending-model-changes и генерацию PostgreSQL SQL-скрипта; применение к живой PostgreSQL в этом прогоне не выполнялось.

Для сравнения исходный коммит a3401ce проверен отдельной временной рабочей копией с теми же Release-настройками и штатным скриптом измерения покрытия:

Сборка Исходные строки / ветви Итоговые строки / ветви
Govor.Application 98,06% / 88,18% 98,10% / 88,80%
Govor.API, без generated sources 97,03% / 90,91% 97,05% / 91,06%

Пороги CI 98% строк и 92% ветвей не достигнуты в обеих версиях; они не снижались. Это остаётся ограничением общего покрытия репозитория. Новый UserBenefitsService, FriendManagementController, MessageLookupController, а также изменённые MessageSendingService и FriendshipService покрыты по строкам на 100%. UserBenefitsController — 20 из 21 исполняемой строки; непокрытым остаётся HTTP-ответ 409 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).