mirror of
https://github.com/Govor-team/Govor.git
synced 2026-11-18 13:24:59 +00:00
docs: split messaging and privileges guides
Organize reply/forward and friendship guidance into focused endpoint docs, add Govor+ privilege, profile-tag, and realtime guides, and document migrations and verification results.
This commit is contained in:
+4
-1
@@ -19,16 +19,19 @@
|
|||||||
* [Друзья и поиск](endpoints/friendshipcontroller.md)
|
* [Друзья и поиск](endpoints/friendshipcontroller.md)
|
||||||
* [Списки заявок](endpoints/friendsrequestquerycontroller.md)
|
* [Списки заявок](endpoints/friendsrequestquerycontroller.md)
|
||||||
* [Личные чаты](endpoints/private-chats.md)
|
* [Личные чаты](endpoints/private-chats.md)
|
||||||
|
* [Ответы и пересылки сообщений](endpoints/replies-and-forwards.md)
|
||||||
* [История сообщений](endpoints/chatloadcontroller.md)
|
* [История сообщений](endpoints/chatloadcontroller.md)
|
||||||
* [Прочтение и счётчики](endpoints/message-read.md)
|
* [Прочтение и счётчики](endpoints/message-read.md)
|
||||||
* [Группы и каналы](groups.md)
|
* [Группы и каналы](groups.md)
|
||||||
* [Реакции и паки](endpoints/reactions.md)
|
* [Реакции и паки](endpoints/reactions.md)
|
||||||
* [Медиа и вложения](endpoints/mediacontroller.md)
|
* [Медиа и вложения](endpoints/mediacontroller.md)
|
||||||
* [Профиль и аватар](endpoints/profile.md)
|
* [Профиль и аватар](endpoints/profile.md)
|
||||||
* [Ответы, пересылки, блокировки и Govor+](messaging-and-benefits.md)
|
|
||||||
* [Присутствие через HTTP](endpoints/onlinepingingcontroller-ne-rabotaet.md)
|
* [Присутствие через HTTP](endpoints/onlinepingingcontroller-ne-rabotaet.md)
|
||||||
* [Push-уведомления](endpoints/push.md)
|
* [Push-уведомления](endpoints/push.md)
|
||||||
* [Администрирование](endpoints/admin-and-groups.md)
|
* [Администрирование](endpoints/admin-and-groups.md)
|
||||||
|
* [Привилегии и Govor+](privileges/README.md)
|
||||||
|
* [Профильные теги](privileges/profile-tags.md)
|
||||||
|
* [Обновления статуса и тега](privileges/realtime.md)
|
||||||
* [SignalR — команды и события](signalr/README.md)
|
* [SignalR — команды и события](signalr/README.md)
|
||||||
* [ChatsHub — сообщения и события чатов](signalr/chathub.md)
|
* [ChatsHub — сообщения и события чатов](signalr/chathub.md)
|
||||||
* [FriendsHub — заявки](friendshub-zayavki.md)
|
* [FriendsHub — заявки](friendshub-zayavki.md)
|
||||||
|
|||||||
@@ -26,3 +26,17 @@ Bearer token обязателен; отдельная роль в атрибут
|
|||||||
|
|
||||||
|
|
||||||
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendshipController.cs).
|
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendshipController.cs).
|
||||||
|
|
||||||
|
## Удаление из друзей и блокировка
|
||||||
|
|
||||||
|
| 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`. Только владелец может снять её; вторая сторона не может заменить владельца. Повтор собственной блокировки безопасен. Снятие блокировки не восстанавливает дружбу: требуется новая заявка и согласие получателя.
|
||||||
|
|||||||
@@ -0,0 +1,54 @@
|
|||||||
|
# Ответы и пересылки сообщений
|
||||||
|
|
||||||
|
Сообщения отправляются через ChatsHub.Send в /hubs/chats. Требуется access JWT и право отправки в чат. Для личного чата recipientId — PrivateChat.Id, recipientType — 0. Те же механизмы поддерживаются в группах и каналах с recipientType — 1 и соответствующей проверкой членства/роли.
|
||||||
|
|
||||||
|
## Ответ на сообщение
|
||||||
|
|
||||||
|
Вызовите `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` создаёт новое сообщение. Для массовой пересылки выполняйте отдельный вызов для каждого сообщения и адресата.
|
||||||
|
|
||||||
|
## Установка
|
||||||
|
|
||||||
|
Для полей происхождения пересылки требуется версия API с миграцией MessagingAndUserBenefits. [Порядок обновления](../operations.md).
|
||||||
@@ -1,256 +0,0 @@
|
|||||||
# Ответы, пересылки, блокировки и 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 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).
|
|
||||||
@@ -42,3 +42,7 @@ VPS-скрипт сериализует деплои, но автоматиче
|
|||||||
## Несколько экземпляров
|
## Несколько экземпляров
|
||||||
|
|
||||||
OnlineUserStore, ConnectionStore, SRP challenge и rate limiter локальны процессу. Несколько реплик требуют согласования SignalR/presence, маршрутизации/общего одноразового хранилища challenge и общих файлов. Одна только общая PostgreSQL не обеспечивает такую согласованность.
|
OnlineUserStore, ConnectionStore, SRP challenge и rate limiter локальны процессу. Несколько реплик требуют согласования SignalR/presence, маршрутизации/общего одноразового хранилища challenge и общих файлов. Одна только общая PostgreSQL не обеспечивает такую согласованность.
|
||||||
|
|
||||||
|
## Миграции сообщений и привилегий
|
||||||
|
|
||||||
|
Перед запуском версии с ответами/пересылками и Govor+ примените MessagingAndUserBenefits и UserBenefitsRevision обычным способом проекта: `dotnet run --project Govor.API -- --migrate-only`. Добавляются nullable-поля происхождения пересылки в Messages, таблица UserBenefits и её ревизия. Старые сообщения и пользователи сохраняются; специальные права автоматически не назначаются.
|
||||||
|
|||||||
@@ -0,0 +1,57 @@
|
|||||||
|
# Привилегии и Govor+
|
||||||
|
|
||||||
|
Govor+ — назначаемый администратором специальный статус пользователя. Платёжная подписка пока не требуется. Права хранятся в БД и проверяются при каждой операции: выдача и отзыв работают во время работы API, без перезапуска и обновления JWT. Govor+ не выдаёт административных ролей.
|
||||||
|
|
||||||
|
## Набор прав
|
||||||
|
|
||||||
|
| Значение privileges | Права |
|
||||||
|
| ------------------- | ------------------------------------------------------- |
|
||||||
|
| 0 | Без специальных прав |
|
||||||
|
| 1 | Govor+: официальный статус и настройка профильного тега |
|
||||||
|
| 2 | Настройка профильного тега без статуса Govor+ |
|
||||||
|
| 3 | Оба явно назначенных бита |
|
||||||
|
|
||||||
|
Это битовая маска: GovorPlus = 1, CustomProfileTag = 2. Неизвестные биты сервер отклоняет. Новые возможности добавляются отдельными битами с проверкой в соответствующем сервисе.
|
||||||
|
|
||||||
|
## Выдача и отзыв
|
||||||
|
|
||||||
|
`PUT /api/admin/users/{userId}/privileges` требует access JWT с ролью Admin. Запрос заменяет весь набор прав пользователя.
|
||||||
|
|
||||||
|
Выдать Govor+:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "privileges": 1 }
|
||||||
|
```
|
||||||
|
|
||||||
|
Отозвать все специальные права:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "privileges": 0 }
|
||||||
|
```
|
||||||
|
|
||||||
|
Успех — 200 с UserBenefitsView. Ошибки: 400 — неизвестные биты; 404 — пользователь не найден; 409 — конкурентное первое создание прав, перечитайте состояние и повторите запрос. Без JWT — 401, без роли Admin — 403.
|
||||||
|
|
||||||
|
## Чтение состояния
|
||||||
|
|
||||||
|
`GET /api/profile/{userId}/benefits` требует действующего access JWT. Тот же объект benefits входит в `GET /api/profile/download/me` и `GET /api/profile/download/{id}`.
|
||||||
|
|
||||||
|
| Поле | Назначение |
|
||||||
|
| ---------------------- | ------------------------------------------------------- |
|
||||||
|
| privileges | Явно назначенная битовая маска |
|
||||||
|
| isGovorPlus | Наличие официального статуса Govor+ |
|
||||||
|
| canCustomizeProfileTag | Право изменять оформление тега, включая право от Govor+ |
|
||||||
|
| tag | Текущее доступное оформление или null |
|
||||||
|
| revision | Монотонная ревизия состояния пользователя |
|
||||||
|
|
||||||
|
Официальный статус определяйте по isGovorPlus, а доступность редактора — по canCustomizeProfileTag. Текст тега произволен и не доказывает наличие статуса.
|
||||||
|
|
||||||
|
Обычный пользователь получает tag: null. У Govor+ без собственного оформления отображается стандартный тег. При отзыве всех прав настройки сохранённое оформление скрывается и перестаёт редактироваться; при повторной выдаче восстанавливается.
|
||||||
|
|
||||||
|
## Разделы
|
||||||
|
|
||||||
|
* [Профильные теги: HTTP-контракт и оформление](profile-tags.md).
|
||||||
|
* [Обновления статуса и тега: SignalR и ревизии](realtime.md).
|
||||||
|
|
||||||
|
## Установка
|
||||||
|
|
||||||
|
Контракт реализован в дополнениях от 31.10.2026. Перед запуском версии примените миграции `MessagingAndUserBenefits` и `UserBenefitsRevision`; существующим пользователям права автоматически не назначаются. [Порядок обновления сервера](../operations.md).
|
||||||
@@ -0,0 +1,54 @@
|
|||||||
|
# Профильные теги
|
||||||
|
|
||||||
|
У каждого пользователя один настраиваемый профильный тег. Изменение доступно при Govor+ или отдельном праве CustomProfileTag. [Назначение и проверка прав](README.md).
|
||||||
|
|
||||||
|
## Изменение и сброс
|
||||||
|
|
||||||
|
`PUT /api/profile/tag` заменяет оформление текущего пользователя. Текущий пользователь берётся из access JWT. Передайте непосредственно объект оформления:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"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
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Пропущенные поля получают стандартные значения. `DELETE /api/profile/tag` сбрасывает оформление к стандартному. Оба endpoint возвращают 200 с актуальным UserBenefitsView. Без права настройки — 403; некорректное оформление — 400 без изменения сохранённого тега.
|
||||||
|
|
||||||
|
## Параметры оформления
|
||||||
|
|
||||||
|
| Параметр | Допустимое значение |
|
||||||
|
| ------------------------------------------------ | --------------------------------------------------------------------------- |
|
||||||
|
| `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 и не может редактироваться. При повторной выдаче права оформление восстанавливается.
|
||||||
|
|
||||||
|
## Отображение
|
||||||
|
|
||||||
|
Официальный статус определяйте по benefits.isGovorPlus, а не по тексту тега. Текущий стиль доступен в benefits.tag при чтении профиля или `GET /api/profile/{userId}/benefits`. После изменения или сброса сервер отправляет UserBenefitsUpdated в /hubs/profiles.
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
# Обновления статуса и тега
|
||||||
|
|
||||||
|
Подключите каждый клиент к `/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.
|
||||||
|
|
||||||
|
## Формат события
|
||||||
|
|
||||||
|
Имя события: `UserBenefitsUpdated`. Payload — `{ userId, benefits }`, где benefits содержит privileges, isGovorPlus, canCustomizeProfileTag, tag и revision. Например, отзыв всех прав:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"userId": "<user-id>",
|
||||||
|
"benefits": {
|
||||||
|
"privileges": 0,
|
||||||
|
"isGovorPlus": false,
|
||||||
|
"canCustomizeProfileTag": false,
|
||||||
|
"tag": null,
|
||||||
|
"revision": 4
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Операции записи выполняются через HTTP. Команд SetTag или SetPrivileges на ProfileHub нет. [Модель привилегий](README.md).
|
||||||
@@ -50,3 +50,24 @@ dotnet test Govor.Server.slnx --no-build --no-restore -c Release --collect 'XPla
|
|||||||
CI проверяет пороги 98% строк и 92% ветвей для Application и исходников API. Проценты из разных проектов нельзя складывать: они покрывают пересекающиеся сборки. Отчёты от 24.10.2026 в `tests/APPLICATION-COVERAGE.md` и `tests/API-COVERAGE.md` — исторические измерения; после добавления тестов восстановления они не пересчитывались в текущем запуске.
|
CI проверяет пороги 98% строк и 92% ветвей для Application и исходников API. Проценты из разных проектов нельзя складывать: они покрывают пересекающиеся сборки. Отчёты от 24.10.2026 в `tests/APPLICATION-COVERAGE.md` и `tests/API-COVERAGE.md` — исторические измерения; после добавления тестов восстановления они не пересчитывались в текущем запуске.
|
||||||
|
|
||||||
Перед релизом дополнительно проверьте HTTPS/WSS, доставку на физические устройства, восстановление архива на чистом устройстве, старые вложения после деплоя и восстановление резервной копии. [Порядок обновления](operations.md).
|
Перед релизом дополнительно проверьте HTTPS/WSS, доставку на физические устройства, восстановление архива на чистом устройстве, старые вложения после деплоя и восстановление резервной копии. [Порядок обновления](operations.md).
|
||||||
|
|
||||||
|
## Проверка расширений API от 31.10.2026
|
||||||
|
|
||||||
|
Проверки находятся в `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