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

257 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Ответы, пересылки, блокировки и Govor+
Все запросы требуют действующего access JWT. Для HTTP передавайте
`Authorization: Bearer <token>`, для SignalR используйте существующую авторизацию
хабов. Новые поля совместимы с прежними клиентами: идентификаторы связей nullable,
у пользователей без назначенных прав `privileges = 0`.
## Ответ на сообщение
Вызовите `Send` в `/hubs/chats`, указав `replyToMessageId`:
```json
{
"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`, передайте новое
содержимое и принадлежащие отправителю вложения для чата назначения:
```json
{
"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` возвращает:
```json
{
"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`:
```javascript
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-подключения трёх пользователей.
```powershell
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 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).