mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-21 14:28:20 +00:00
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.
This commit is contained in:
@@ -0,0 +1,256 @@
|
||||
# Ответы, пересылки, блокировки и 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 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).
|
||||
Reference in New Issue
Block a user