From 0dd8457df170ac15b1f1fdfa48b176e5ce788a12 Mon Sep 17 00:00:00 2001 From: stalcke2288969 Date: Sun, 4 Oct 2026 02:00:32 +0000 Subject: [PATCH] =?UTF-8?q?GITBOOK-16:=20SignalR:=20=D0=BF=D1=80=D0=BE?= =?UTF-8?q?=D1=84=D0=B8=D0=BB=D1=8C,=20=D1=87=D0=BB=D0=B5=D0=BD=D1=81?= =?UTF-8?q?=D1=82=D0=B2=D0=BE=20=D0=B8=20=D0=BF=D1=80=D0=B0=D0=B2=D0=B0=20?= =?UTF-8?q?=D0=B3=D1=80=D1=83=D0=BF=D0=BF/=D0=BA=D0=B0=D0=BD=D0=B0=D0=BB?= =?UTF-8?q?=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture.md | 4 +++- docs/groups.md | 30 ++++++++++++++++++++++-- docs/signalr/chathub.md | 52 ++++++++++++++++++++++------------------- 3 files changed, 59 insertions(+), 27 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index afb4890..14d6b4c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -17,6 +17,8 @@ GroupManagementService сериализует изменения членств Соединения ChatsHub автоматически входят в группы сессий. SignalR-события направляются активным сессиям действующих участников из БД; заблокированные участники исключаются. ConnectionStore и OnlineUserStore остаются в памяти одного процесса; для нескольких экземпляров нужна общая инфраструктура SignalR/presence. -Сообщение и задача push сохраняются атомарно; ChatPushWorker повторяет неудачные доставки. SignalR-события не имеют долговременной очереди. Клиент восстанавливает историю, прочтение и версии реакций после reconnect через HTTP. Для реакций/политик push не отправляется; изменения группы пока восстанавливаются чтением профиля/участников. +Сообщение и задача push сохраняются атомарно; ChatPushWorker повторяет неудачные доставки. После успешного HTTP сохранения ChatNotificationService отправляет GroupProfileChanged и GroupMemberChanged через ChatsHub. Профиль перечитывается индивидуально через HTTP; статус/роль членства читаются после команды. При бане/выходе только событие собственного членства дополнительно доставляется пользователю, потерявшему доступ. Остальные события по-прежнему получают действующие участники. Отказ в правах/валидации не создаёт событий; сбой доставки не отменяет сохранение. + +SignalR-события не имеют долговременной очереди. Клиент восстанавливает историю, прочтение, версии реакций, свои группы, открытый профиль и участников после reconnect через HTTP. Для реакций/политик и изменений сообществ push не отправляется. При параллельных командах порядок событий не гарантирован, поэтому актуальные права берутся из HTTP состояния, а не из последнего полученного уведомления. [Группы и каналы](groups.md), [реакции](endpoints/reactions.md), [прочтение](endpoints/message-read.md) описывают текущую рабочую версию. E2EE, согласованное присутствие между инстансами и ключ идемпотентности отправки сообщений остаются отдельными задачами. diff --git a/docs/groups.md b/docs/groups.md index 2171708..9312c77 100644 --- a/docs/groups.md +++ b/docs/groups.md @@ -1,6 +1,6 @@ # Группы и каналы -Рабочий серверный API от 03.10.2026. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль. +Рабочий серверный API от 04.10.2026. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль. Публичные сообщества доступны поиску Govor и вступлению по ID. Приватные сообщества не появляются в поиске: вступление выполняется по действующей ссылке. История, участники, закрытые аватары и команды сообщений доступны только незаблокированным участникам, даже если само сообщество публично. @@ -96,7 +96,33 @@ validForDays — 1–365 (по умолчанию 7), maxParticipants — 0–1 В канале владелец/админ задаёт политику через PUT `/api/groups/{groupId}/reactions`: All=0, None=1, Selected=2 с reactionIds. GET возвращает текущую политику; изменения приходят как ChannelReactionPolicyChanged. Эмодзи, изображения/GIF, HTTP/SignalR установка реакции описаны в [реакциях](endpoints/reactions.md). Бан и снятие админа применяются к этим же сервисам. -Изменения профиля, членства и ролей пока не имеют отдельного SignalR-события. Обновляйте GroupResponse/список участников при открытии экрана, после своей команды и после отказа по правам. Обычные события сообщений, прочтения, удаления и реакций работают через ChatsHub. Старый пустой GroupsHub не используется. +## Обновления группы через SignalR + +С 04.10.2026 изменения сообщества приходят через тот же `/hubs/chats`. Нужны Bearer access token и активная сессия. Дополнительная подписка на группу не требуется: сервер доставляет события всем активным сессиям действующих участников, включая другие устройства автора команды. Старый пустой GroupsHub не используется; команды управления остаются HTTP API и подходят будущему боту. + +| Событие | Payload | Когда отправляется | +| ------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GroupProfileChanged | `{ groupId }` | Имя, описание, приватность, загрузка/удаление аватара, передача владения, настройка обязательного канала | +| GroupMemberChanged | `{ groupId, userId, status, role }` | Создание группы, вступление через поиск/ссылку, выход, назначение/снятие админа, бан/разбан, передача владения, автоматическое добавление нового аккаунта в обязательный канал | + +status: Active=0, Banned=1, Left=2. role: Member=0, Admin=1, Owner=2; null для заблокированного или вышедшего. Статус/роль читаются из БД после завершения команды. При передаче владения отправляются GroupProfileChanged и два GroupMemberChanged: прежний владелец становится Admin, новый — Owner. + +Заблокированный или вышедший пользователь получает GroupMemberChanged о **себе** на свои активные сессии вместе с оставшимися участниками. После этого ему не направляются изменения профиля, чужого членства и события сообщений. Остальные заблокированные, посторонние пользователи, отозванные и истёкшие сессии исключены. При разбане статус Active с ролью Member; автоматическое вступление при регистрации уведомляет уже подключённых участников обязательного канала. + +GroupProfileChanged — сигнал перечитать GET `/api/groups/{groupId}`. Он не содержит общий GroupResponse: myRole и canLeave зависят от конкретного пользователя. Клиент обновляет имя/описание, аватар, приватность, владельца, свои права и возможность выхода из полученного HTTP ответа. Смена обязательного канала уведомляет участников прежнего и нового канала; смена allowLeave — участников текущего. + +При GroupMemberChanged перечитайте профиль и видимую страницу участников; это обновляет memberCount и myRole. Если событие касается текущего пользователя, пересчитайте доступность кнопок отправки и модерации. Если профиль публичного сообщества вернул myRole=null, членство уже потеряно, даже при HTTP 200. Ответ 403/404 также означает потерю доступа: закройте экран сообщества, уберите его из локального списка и перечитайте `/api/groups/mine`. Обновляйте UI MAUI на главном потоке. Все серверные команды независимо проверяют действующие права в БД. + +Пример регистрации обработчиков в .NET-клиенте (Reload — методы приложения, выполняющие описанные HTTP запросы): + +```csharp +hub.On("GroupProfileChanged", + change => ReloadGroupAsync(change.GroupId)); +hub.On("GroupMemberChanged", + change => ReloadGroupAndMembersAsync(change.GroupId)); +``` + +Событие отправляется только после успешного сохранения, отказ в правах/валидации не создаёт события. Повтор успешной идемпотентной команды может повторить уведомление: обработчики должны быть идемпотентными. SignalR не хранит очередь и не гарантирует порядок между параллельными HTTP командами; payload членства — подсказка, актуальный HTTP ответ является источником прав. После reconnect перечитайте mine, открытый профиль и участников. Ошибка доставки логируется, но не отменяет уже сохранённое изменение и не превращает успешную команду в ошибку. Для этих событий push не отправляется. ## Обязательный канал сервера diff --git a/docs/signalr/chathub.md b/docs/signalr/chathub.md index 7d7bd6d..a2b67a5 100644 --- a/docs/signalr/chathub.md +++ b/docs/signalr/chathub.md @@ -1,18 +1,18 @@ # ChatsHub — сообщения -Подключение: `/hubs/chats`, Bearer access token и активная сессия. Команды возвращают `HubResult` (status, result, errorMessage); события приходят независимо от ответа команды. Этот раздел описывает рабочую копию с исправлениями от 03.10.2026. +Подключение: `/hubs/chats`, Bearer access token и активная сессия. Команды возвращают `HubResult` (status, result, errorMessage); события приходят независимо от ответа команды. Этот раздел описывает рабочую копию с исправлениями от 04.10.2026. ## Команды -| Имя | Аргументы | Успешный result | -| --- | --- | --- | -| Send | MessageRequest | UserMessageResponse | -| Read | `{ messageId }` | MessageReadResponse | -| ReadChat | chatId, ReadChatRequest | ChatReadResponse | -| Edit | `{ messageId, newEncryptedContent }` | MessageEditResponse | -| Remove | `{ messageId, requestType }` | MessageRemovedResponse | -| React | messageId, `{ reactionId }` | MessageReactionsChangedResponse | -| RemoveReaction | messageId | MessageReactionsChangedResponse | +| Имя | Аргументы | Успешный result | +| -------------- | ------------------------------------ | ------------------------------- | +| Send | MessageRequest | UserMessageResponse | +| Read | `{ messageId }` | MessageReadResponse | +| ReadChat | chatId, ReadChatRequest | ChatReadResponse | +| Edit | `{ messageId, newEncryptedContent }` | MessageEditResponse | +| Remove | `{ messageId, requestType }` | MessageRemovedResponse | +| React | messageId, `{ reactionId }` | MessageReactionsChangedResponse | +| RemoveReaction | messageId | MessageReactionsChangedResponse | ```json { @@ -32,27 +32,31 @@ Send/Read/React и чтение истории проверяют участие ## События -| Имя события (точно) | Payload | -| --- | --- | -| ReceiveMessage | UserMessageResponse | -| MessageSent | UserMessageResponse, подтверждение устройствам отправителя | -| MessageEdited | MessageEditResponse | -| MessageRemoved | MessageRemovedResponse | -| MessageReaded | MessageReadResponse | -| ChatRead | ChatReadResponse | -| MessageReactionsChanged | MessageReactionsChangedResponse | -| ChannelReactionPolicyChanged | ChannelReactionPolicyResponse | +| Имя события (точно) | Payload | +| ---------------------------- | --------------------------------------------------------------- | +| ReceiveMessage | UserMessageResponse | +| MessageSent | UserMessageResponse, подтверждение устройствам отправителя | +| MessageEdited | MessageEditResponse | +| MessageRemoved | MessageRemovedResponse | +| MessageReaded | MessageReadResponse | +| ChatRead | ChatReadResponse | +| MessageReactionsChanged | MessageReactionsChangedResponse | +| ChannelReactionPolicyChanged | ChannelReactionPolicyResponse | +| GroupProfileChanged | GroupProfileChangedResponse: `{ groupId }` | +| GroupMemberChanged | GroupMemberChangedResponse: `{ groupId, userId, status, role }` | Опечатка MessageReaded сохранена для совместимости. При подключении сервер автоматически добавляет соединение в группу его сессии. События чата направляются активным сессиям участников; заблокированные участники групп исключаются. Не требуется вручную подписываться на SignalR-группу чата. Отзыв сессии прекращает её участие в маршрутизации и проверяется для команд; истечение токена закрывает соединение. UserMessageResponse: messageId, senderId, recipientId, recipientType, encryptedContent, replyToMessageId, sentAt, isEdited, mediaAttachments. История через HTTP также содержит реакции и reactionsVersion. После получения сообщения загрузите снимок реакций при необходимости. -MessageEditResponse: messageId, editorId, recipientId, recipientType, newEncryptedContent, editedAt. -MessageReadResponse: viewId, messageId, readerId, recipientId, whenWas, recipientType. -MessageRemovedResponse: messageId, senderId, recipientId, requestType, recipientType. +MessageEditResponse: messageId, editorId, recipientId, recipientType, newEncryptedContent, editedAt. MessageReadResponse: viewId, messageId, readerId, recipientId, whenWas, recipientType. MessageRemovedResponse: messageId, senderId, recipientId, requestType, recipientType. ## Доставка и восстановление +GroupProfileChanged сообщает об изменении имени, описания, приватности, аватара, владельца и настроек обязательного канала. Загрузите GET `/api/groups/{groupId}`: myRole и canLeave индивидуальны, поэтому событие содержит только groupId. GroupMemberChanged сообщает о вступлении/выходе, бане/разбане и роли участника. status: Active=0, Banned=1, Left=2; role: Member=0, Admin=1, Owner=2, null без активного членства. Перечитайте профиль и видимых участников; при потере доступа удалите сообщество из локального списка. Передача владения обновляет профиль и роли обоих пользователей. + +Эти события доставляются после успешного HTTP сохранения. Заблокированный/вышедший пользователь получает только изменение собственного членства; последующие события сообщества ему не отправляются. Ошибочные команды не создают событий. Повтор успешной команды может повторить уведомление. [Группы и каналы](../groups.md) описывают все причины событий и клиентское восстановление. Порядок параллельных уведомлений не гарантирован; HTTP состояние определяет актуальные права. После reconnect обновите mine, профиль открытой группы и список участников. + Сохранение в БД и доставка события — разные этапы. После reconnect загрузите историю через HTTP; объединяйте ответ Send и ReceiveMessage по messageId. Для реакций принимайте более новую version и заменяйте counts целиком, затем восстанавливайте состояние видимых сообщений через GET. -SignalR-события не имеют долговременной очереди. Push сообщений использует серверную очередь и повторные попытки; для реакций и политик каналов push не отправляется. Реальный push требует корректной конфигурации Firebase и зарегистрированного FCM-токена активной сессии. Повтор Send после неоднозначного сетевого сбоя всё ещё может создать дубликат: clientMessageId/idempotency-key для сообщений не реализован. +SignalR-события не имеют долговременной очереди. Push сообщений использует серверную очередь и повторные попытки; для реакций, политик каналов и изменений сообществ push не отправляется. Реальный push требует корректной конфигурации Firebase и зарегистрированного FCM-токена активной сессии. Повтор Send после неоднозначного сетевого сбоя всё ещё может создать дубликат: clientMessageId/idempotency-key для сообщений не реализован.