From def724e0ee5e1c968e800e1864f066b5efc95e3b Mon Sep 17 00:00:00 2001 From: Artemy <109195690+stalcker2288969@users.noreply.github.com> Date: Sat, 31 Oct 2026 18:35:50 +0700 Subject: [PATCH] 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. --- docs/SUMMARY.md | 5 +- docs/endpoints/friendshipcontroller.md | 14 ++ docs/endpoints/replies-and-forwards.md | 54 ++++++ docs/messaging-and-benefits.md | 256 ------------------------- docs/operations.md | 4 + docs/privileges/README.md | 57 ++++++ docs/privileges/profile-tags.md | 54 ++++++ docs/privileges/realtime.md | 38 ++++ docs/testing.md | 21 ++ 9 files changed, 246 insertions(+), 257 deletions(-) create mode 100644 docs/endpoints/replies-and-forwards.md delete mode 100644 docs/messaging-and-benefits.md create mode 100644 docs/privileges/README.md create mode 100644 docs/privileges/profile-tags.md create mode 100644 docs/privileges/realtime.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index cb40af8..ed6fa0d 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -19,16 +19,19 @@ * [Друзья и поиск](endpoints/friendshipcontroller.md) * [Списки заявок](endpoints/friendsrequestquerycontroller.md) * [Личные чаты](endpoints/private-chats.md) + * [Ответы и пересылки сообщений](endpoints/replies-and-forwards.md) * [История сообщений](endpoints/chatloadcontroller.md) * [Прочтение и счётчики](endpoints/message-read.md) * [Группы и каналы](groups.md) * [Реакции и паки](endpoints/reactions.md) * [Медиа и вложения](endpoints/mediacontroller.md) * [Профиль и аватар](endpoints/profile.md) - * [Ответы, пересылки, блокировки и Govor+](messaging-and-benefits.md) * [Присутствие через HTTP](endpoints/onlinepingingcontroller-ne-rabotaet.md) * [Push-уведомления](endpoints/push.md) * [Администрирование](endpoints/admin-and-groups.md) +* [Привилегии и Govor+](privileges/README.md) + * [Профильные теги](privileges/profile-tags.md) + * [Обновления статуса и тега](privileges/realtime.md) * [SignalR — команды и события](signalr/README.md) * [ChatsHub — сообщения и события чатов](signalr/chathub.md) * [FriendsHub — заявки](friendshub-zayavki.md) diff --git a/docs/endpoints/friendshipcontroller.md b/docs/endpoints/friendshipcontroller.md index b28527e..638d259 100644 --- a/docs/endpoints/friendshipcontroller.md +++ b/docs/endpoints/friendshipcontroller.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). + +## Удаление из друзей и блокировка + +| 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`. Только владелец может снять её; вторая сторона не может заменить владельца. Повтор собственной блокировки безопасен. Снятие блокировки не восстанавливает дружбу: требуется новая заявка и согласие получателя. diff --git a/docs/endpoints/replies-and-forwards.md b/docs/endpoints/replies-and-forwards.md new file mode 100644 index 0000000..af15bea --- /dev/null +++ b/docs/endpoints/replies-and-forwards.md @@ -0,0 +1,54 @@ +# Ответы и пересылки сообщений + +Сообщения отправляются через ChatsHub.Send в /hubs/chats. Требуется access JWT и право отправки в чат. Для личного чата recipientId — PrivateChat.Id, recipientType — 0. Те же механизмы поддерживаются в группах и каналах с recipientType — 1 и соответствующей проверкой членства/роли. + +## Ответ на сообщение + +Вызовите `Send` в `/hubs/chats`, указав `replyToMessageId`: + +```json +{ + "recipientId": "", + "recipientType": 0, + "encryptedContent": "", + "replyToMessageId": "", + "mediaAttachments": [] +} +``` + +`recipientType`: `0` — личный чат, `1` — группа/канал. Ответ должен ссылаться на существующее сообщение того же чата и типа. Сервер проверяет право отправки, включая блокировку в личном чате, бан в группе и роль администратора канала. Для E2EE `replyToMessageId` должен совпадать с `replyTo` подписанного конверта. В публичных группах допускается обычное содержимое согласно существующей политике. + +Связь возвращается в результате `Send`, событиях сообщений и истории. Для превью ответа за пределами загруженной страницы используйте `GET /api/messages/{messageId}`. Ответ — `MessageResponse` с вложениями, реакциями и прочтениями. Отсутствующее сообщение и отсутствие доступа дают одинаковый `404`, без раскрытия чужого чата. После удаления оригинала ссылка остаётся; клиент показывает «Сообщение удалено». Содержимое удалённого сообщения сервер не архивирует в ответе. + +## Пересылка + +Используется тот же `Send`; добавьте `forwardedFromMessageId`, передайте новое содержимое и принадлежащие отправителю вложения для чата назначения: + +```json +{ + "recipientId": "", + "recipientType": 0, + "encryptedContent": "", + "forwardedFromMessageId": "", + "mediaAttachments": [] +} +``` + +Сервер проверяет доступ отправителя к исходному сообщению и право отправки в чат назначения. Несуществующий или недоступный источник отклоняется без записи сообщения и push. Автор и дата источника берутся из БД, клиент не может передать их сам: + +| Поле ответа/истории | Значение | +| ------------------------ | -------------------------------------------- | +| `senderId` | Пользователь, выполнивший пересылку | +| `forwardedFromMessageId` | ID непосредственно пересланного сообщения | +| `forwardedFromUserId` | Автор непосредственно пересланного сообщения | +| `forwardedFromSentAt` | Дата отправки источника, UTC | + +Это снимок происхождения без внешнего ключа: удаление источника не удаляет пересылку. При повторной пересылке указывается непосредственный источник, цепочка автоматически не разворачивается. Получатель не получает доступ к исходному чату. + +Для зашифрованных сообщений клиент расшифровывает оригинал локально, затем шифрует новое сообщение для актуального набора устройств назначения с новым `messageId`. Вложения нужно заново загрузить от текущего пользователя; для E2EE зашифровать их новыми ключами, а ключи поместить внутрь конверта. Прямая подстановка чужих media ID не даёт прав на файлы. Сервер не расшифровывает содержимое и не может проверить, что текст пересылки идентичен оригиналу; метаданные происхождения не являются подписью исходного автора под новым содержимым. + +Повтор одного E2EE-запроса с тем же ID идемпотентен; изменение источника, адресата, содержимого, ответа или вложений с прежним ID отклоняется. В публичных чатах без E2EE каждый `Send` создаёт новое сообщение. Для массовой пересылки выполняйте отдельный вызов для каждого сообщения и адресата. + +## Установка + +Для полей происхождения пересылки требуется версия API с миграцией MessagingAndUserBenefits. [Порядок обновления](../operations.md). diff --git a/docs/messaging-and-benefits.md b/docs/messaging-and-benefits.md deleted file mode 100644 index 4671def..0000000 --- a/docs/messaging-and-benefits.md +++ /dev/null @@ -1,256 +0,0 @@ -# Ответы, пересылки, блокировки и Govor+ - -Все запросы требуют действующего access JWT. Для HTTP передавайте -`Authorization: Bearer `, для SignalR используйте существующую авторизацию -хабов. Новые поля совместимы с прежними клиентами: идентификаторы связей nullable, -у пользователей без назначенных прав `privileges = 0`. - -## Ответ на сообщение - -Вызовите `Send` в `/hubs/chats`, указав `replyToMessageId`: - -```json -{ - "recipientId": "", - "recipientType": 0, - "encryptedContent": "", - "replyToMessageId": "", - "mediaAttachments": [] -} -``` - -`recipientType`: `0` — личный чат, `1` — группа/канал. Ответ должен ссылаться -на существующее сообщение того же чата и типа. Сервер проверяет право отправки, -включая блокировку в личном чате, бан в группе и роль администратора канала. -Для E2EE `replyToMessageId` должен совпадать с `replyTo` подписанного конверта. -В публичных группах допускается обычное содержимое согласно существующей политике. - -Связь возвращается в результате `Send`, событиях сообщений и истории. Для превью -ответа за пределами загруженной страницы используйте `GET /api/messages/{messageId}`. -Ответ — `MessageResponse` с вложениями, реакциями и прочтениями. Отсутствующее -сообщение и отсутствие доступа дают одинаковый `404`, без раскрытия чужого чата. -После удаления оригинала ссылка остаётся; клиент показывает «Сообщение удалено». -Содержимое удалённого сообщения сервер не архивирует в ответе. - -## Пересылка - -Используется тот же `Send`; добавьте `forwardedFromMessageId`, передайте новое -содержимое и принадлежащие отправителю вложения для чата назначения: - -```json -{ - "recipientId": "", - "recipientType": 0, - "encryptedContent": "", - "forwardedFromMessageId": "", - "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 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса). diff --git a/docs/operations.md b/docs/operations.md index 64004a2..29a0e7b 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -42,3 +42,7 @@ VPS-скрипт сериализует деплои, но автоматиче ## Несколько экземпляров OnlineUserStore, ConnectionStore, SRP challenge и rate limiter локальны процессу. Несколько реплик требуют согласования SignalR/presence, маршрутизации/общего одноразового хранилища challenge и общих файлов. Одна только общая PostgreSQL не обеспечивает такую согласованность. + +## Миграции сообщений и привилегий + +Перед запуском версии с ответами/пересылками и Govor+ примените MessagingAndUserBenefits и UserBenefitsRevision обычным способом проекта: `dotnet run --project Govor.API -- --migrate-only`. Добавляются nullable-поля происхождения пересылки в Messages, таблица UserBenefits и её ревизия. Старые сообщения и пользователи сохраняются; специальные права автоматически не назначаются. diff --git a/docs/privileges/README.md b/docs/privileges/README.md new file mode 100644 index 0000000..d45f14d --- /dev/null +++ b/docs/privileges/README.md @@ -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). diff --git a/docs/privileges/profile-tags.md b/docs/privileges/profile-tags.md new file mode 100644 index 0000000..14258e7 --- /dev/null +++ b/docs/privileges/profile-tags.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. diff --git a/docs/privileges/realtime.md b/docs/privileges/realtime.md new file mode 100644 index 0000000..5da5106 --- /dev/null +++ b/docs/privileges/realtime.md @@ -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": "", + "benefits": { + "privileges": 0, + "isGovorPlus": false, + "canCustomizeProfileTag": false, + "tag": null, + "revision": 4 + } +} +``` + +Операции записи выполняются через HTTP. Команд SetTag или SetPrivileges на ProfileHub нет. [Модель привилегий](README.md). diff --git a/docs/testing.md b/docs/testing.md index d7b62a9..9b3a5ec 100644 --- a/docs/testing.md +++ b/docs/testing.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` — исторические измерения; после добавления тестов восстановления они не пересчитывались в текущем запуске. Перед релизом дополнительно проверьте 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 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).