From ebd6cb59be550062426d2f3d009a6316a08bd16d Mon Sep 17 00:00:00 2001 From: stalcke2288969 Date: Sat, 3 Oct 2026 13:54:10 +0000 Subject: [PATCH 1/2] =?UTF-8?q?GITBOOK-15:=20=D0=93=D1=80=D1=83=D0=BF?= =?UTF-8?q?=D0=BF=D1=8B=20=D0=B8=20=D0=BA=D0=B0=D0=BD=D0=B0=D0=BB=D1=8B:?= =?UTF-8?q?=20=D0=BF=D1=80=D0=B8=D0=B3=D0=BB=D0=B0=D1=88=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F,=20=D1=80=D0=BE=D0=BB=D0=B8,=20=D0=BC=D0=BE=D0=B4=D0=B5?= =?UTF-8?q?=D1=80=D0=B0=D1=86=D0=B8=D1=8F=20=D0=B8=20=D0=BE=D0=B1=D1=8F?= =?UTF-8?q?=D0=B7=D0=B0=D1=82=D0=B5=D0=BB=D1=8C=D0=BD=D1=8B=D0=B9=20=D0=BA?= =?UTF-8?q?=D0=B0=D0=BD=D0=B0=D0=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 31 +++--- docs/SUMMARY.md | 11 ++- docs/architecture.md | 45 +++------ docs/endpoints/admin-and-groups.md | 45 +++------ docs/friendshub-zayavki.md | 9 ++ docs/groups.md | 130 ++++++++++++++++++++++++++ docs/klient-signalr-na-c-dlya-maui.md | 10 ++ docs/server-fixes.md | 6 +- 8 files changed, 202 insertions(+), 85 deletions(-) create mode 100644 docs/friendshub-zayavki.md create mode 100644 docs/groups.md create mode 100644 docs/klient-signalr-na-c-dlya-maui.md diff --git a/docs/README.md b/docs/README.md index a3131dd..dc255ea 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,19 +6,19 @@ Govor — мессенджер на ASP.NET Core и .NET MAUI. Эта докум Изменения рабочей копии сервера описаны в [исправлениях](server-fixes.md), включая [API прочтения](endpoints/message-read.md). Страницы со ссылками на commit `4603be9` описывают исходную версию до этих исправлений. -| Область | Состояние по коду | -| --- | --- | -| Регистрация и вход | Регистрация по приглашению, BCrypt, открытие сессии и пара токенов | -| Сессии | Список, отзыв одной или всех сессий, обновление токенов | -| Друзья | Поиск, списки, отправка/принятие/отклонение заявок через SignalR | -| Личные чаты | Создание между друзьями, история, отправка и редактирование | -| Прочтение и удаление | HTTP/SignalR, видимые сообщения/граница/весь чат, квитанции и счётчики; удаление с проверкой прав | -| Реакции | [HTTP/SignalR, базовые эмодзи, общие паки картинок/GIF, административный API и выбор разрешённых реакций канала](endpoints/reactions.md) | -| Профиль | Описание, аватар, загрузка профиля и события изменений | -| Присутствие | События подключения/отключения; исправлены зависимости HTTP status | -| Медиа и push | Доступ к вложениям, привязка FCM к сессии, очередь и повторные попытки | -| Группы | Модели и часть сервисов сообщений; полноценный сценарий управления не завершён | -| Шифрование | Есть хранение публичных ключей, но готового E2EE нет | +| Область | Состояние по коду | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Регистрация и вход | Регистрация по приглашению, BCrypt, открытие сессии и пара токенов | +| Сессии | Список, отзыв одной или всех сессий, обновление токенов | +| Друзья | Поиск, списки, отправка/принятие/отклонение заявок через SignalR | +| Личные чаты | Создание между друзьями, история, отправка и редактирование | +| Прочтение и удаление | HTTP/SignalR, видимые сообщения/граница/весь чат, квитанции и счётчики; удаление с проверкой прав | +| Реакции | [HTTP/SignalR, базовые эмодзи, общие паки картинок/GIF, административный API и выбор разрешённых реакций канала](endpoints/reactions.md) | +| Профиль | Описание, аватар, загрузка профиля и события изменений | +| Присутствие | События подключения/отключения; исправлены зависимости HTTP status | +| Медиа и push | Доступ к вложениям, привязка FCM к сессии, очередь и повторные попытки | +| Группы и каналы | [Публичный поиск, приватные приглашения, владелец/админы/участники, баны, модерация и обязательный канал](groups.md) | +| Шифрование | Есть хранение публичных ключей, но готового E2EE нет | ## Как читать @@ -28,13 +28,14 @@ Govor — мессенджер на ASP.NET Core и .NET MAUI. Эта докум ## Границы готовности -Текущая версия не готова к открытому развёртыванию: обнаружены критичные ошибки авторизации и доступа к личным чатам. Контракты ниже полезны для разработки, но не являются подтверждением безопасности. +Документация новых групп и реакций описывает рабочую серверную копию с исправлениями доступа. Проверки HTTP/JWT, SQL и прав выполняются автоматическими тестами; реальная доставка на устройства и производственное развёртывание требуют отдельной проверки. Страницы с commit `4603be9` фиксируют старую диагностику и не описывают все текущие исправления. Эффект стекла относится к MAUI-интерфейсу. API передаёт данные и события; производительность размытия, контрастность и анимации нужно проверять отдельно на устройствах. Регистрация сейчас требует код приглашения. Обещание отключить приглашения после релиза является продуктовым планом, а не поведением текущего кода. ---- +*** + Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера. Источник: [Govor.API/Program.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Program.cs). diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4702310..78157e2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,7 +1,7 @@ -# Оглавление +# Table of contents * [Govor.API — обзор](README.md) -* [Исправления серверной части](server-fixes.md) +* [Исправления серверной части — 03.10.2026](server-fixes.md) * [Запуск и конфигурация](getting-started.md) * [Архитектура и границы](architecture.md) * [Аутентификация](endpoints/authentication/README.md) @@ -14,16 +14,17 @@ * [История сообщений](endpoints/chatloadcontroller.md) * [Прочтение сообщений и счётчики](endpoints/message-read.md) * [Реакции, паки и настройки каналов](endpoints/reactions.md) +* [Группы и каналы](groups.md) * [Медиа](endpoints/mediacontroller.md) * [Профиль и аватар](endpoints/profile.md) * [Push-уведомления](endpoints/push.md) * [HTTP-присутствие — ограничения](endpoints/onlinepingingcontroller-ne-rabotaet.md) * [Ключи сессий — экспериментальный API](endpoints/session-keys.md) -* [Администрирование и незавершённые группы](endpoints/admin-and-groups.md) +* [Администрирование сервера](endpoints/admin-and-groups.md) * [ChatsHub — сообщения](signalr/chathub.md) * [PresenceHub — online и offline](signalr/presencehub.md) -* [FriendsHub — заявки](friendshub/README.md) -* [Клиент SignalR на C# для MAUI](friendshub/friendshub-client-java.md) +* [FriendsHub — заявки](friendshub-zayavki.md) +* [Клиент SignalR на C# для MAUI](klient-signalr-na-c-dlya-maui.md) * [ProfileHub — изменения профиля](signalr/profilehub.md) * [Ответы, ошибки и сериализация](code-docs/hubresult-less-than-t-greater-than.md) * [Диагностика и порядок исправлений](diagnostics.md) diff --git a/docs/architecture.md b/docs/architecture.md index 637b7a3..afb4890 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,41 +1,22 @@ # Архитектура и границы -## Поток запроса +MAUI → HTTP Controller / SignalR Hub → Application service → GovorDbContext → PostgreSQL. Бинарные файлы хранятся через IStorageService; транспорт событий и push вынесен в ChatNotificationService. -MAUI → HTTP Controller / SignalR Hub → Application service → GovorDbContext → PostgreSQL. Медиа-сервис сохраняет бинарные данные через LocalStorageService; ChatNotificationService отправляет SignalR-события и push через Firebase. +| Проект | Ответственность | +| ----------------- | --------------------------------------------------------------------- | +| Govor.API | Маршруты, хабы, активные access-сессии, DI, ошибки, DTO и уведомления | +| Govor.Application | Пользователи, группы/каналы, права, сообщения, реакции, медиа и push | +| Govor.Contracts | HTTP/SignalR запросы и ответы | +| Govor.Domain | Сущности, DbContext, EF-конфигурации и миграции | -| Проект | Ответственность сейчас | -| --- | --- | -| Govor.API | Маршруты, хабы, авторизация, DI, преобразование ошибок и DTO | -| Govor.Application | Сценарии пользователей, друзей, сообщений, медиа и push | -| Govor.Contracts | HTTP/SignalR запросы, ответы и DTO | -| Govor.Domain | Сущности, DbContext, EF-конфигурации и миграции | +Domain зависит от EF Core и содержит инфраструктуру БД. PrivateChat связывает двух пользователей; Message.RecipientId указывает на PrivateChat при RecipientType.User=0 либо ChatGroup при Group=1. Это ID чата, а не получателя-пользователя. -Это многослойное приложение, но Domain уже зависит от EF Core и содержит инфраструктуру БД. Не следует описывать его как полностью независимую доменную модель. +Роль сервера в JWT берётся из Invitation.IsAdmin. Роль группы вычисляется отдельно: ChatGroup.OwnerUserId — владелец, GroupAdmins — админы, активная GroupMembership — участники. GroupAccess объединяет права владельца/админа с незаблокированным членством; ChatAccess проверяет доступ к конкретному чату. Уникальные индексы запрещают дубли членства и административных ролей. -## Хранение и идентификаторы +GroupManagementService сериализует изменения членства, ролей и ссылок на строке группы. Публикации, редактура, удаление, реакции и настройки канала используют тот же порядок блокировки. GroupAvatarService меняет аватар только для действующего владельца. Регистрация атомарно создаёт пользователя, расходует приглашение и добавляет членство в обязательном канале из ServerCommunitySettings; изменение этой настройки сериализуется с регистрацией. -PrivateChat связывает UserAId и UserBId. Message хранит SenderId и полиморфный RecipientId: ID PrivateChat для RecipientType.User или ID ChatGroup для RecipientType.Group. Ошибки возникают там, где этот ID сравнивают с ID пользователя. +Соединения ChatsHub автоматически входят в группы сессий. SignalR-события направляются активным сессиям действующих участников из БД; заблокированные участники исключаются. ConnectionStore и OnlineUserStore остаются в памяти одного процесса; для нескольких экземпляров нужна общая инфраструктура SignalR/presence. -Роль access token получается из приглашения пользователя (`Invite.IsAdmin`), хотя есть отдельная сущность Admin. Нужен один источник истины для ролей. - -## Состояние соединений - -ConnectionStore и OnlineUserStore — singleton в памяти одного процесса. Подключения автоматически вступают в группы пользователя, его чатов и групп. Перезапуск очищает это состояние; несколько инстансов без общего решения для SignalR и presence не имеют согласованного состояния. - -## Рекомендуемые решения - -1. Ввести общую проверку участия в конкретном чате и применять её к истории, Send, Read, медиа и событиям. -2. Разделить команды и чтение: создание чата и смена пароля не должны выполняться GET-запросами. -3. Возвращать только DTO, особенно для криптосессий и медиа. -4. Описать ошибки единым контрактом, сохранив совместимость с MAUI. -5. Для доставки отделить сохранение сообщения от внешних уведомлений: outbox и повторная доставка с дедупликацией. -6. Принять отдельное решение о E2EE: протокол, проверка ключей, несколько устройств, восстановление и миграция существующих сообщений. - -Это предложения, они не внедрены в рамках переписывания документации. - ---- -Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера. - -Источник: [Govor.Domain/GovorDbContext.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Domain/GovorDbContext.cs). +Сообщение и задача push сохраняются атомарно; ChatPushWorker повторяет неудачные доставки. SignalR-события не имеют долговременной очереди. Клиент восстанавливает историю, прочтение и версии реакций после reconnect через HTTP. Для реакций/политик push не отправляется; изменения группы пока восстанавливаются чтением профиля/участников. +[Группы и каналы](groups.md), [реакции](endpoints/reactions.md), [прочтение](endpoints/message-read.md) описывают текущую рабочую версию. E2EE, согласованное присутствие между инстансами и ключ идемпотентности отправки сообщений остаются отдельными задачами. diff --git a/docs/endpoints/admin-and-groups.md b/docs/endpoints/admin-and-groups.md index 791865e..16232ee 100644 --- a/docs/endpoints/admin-and-groups.md +++ b/docs/endpoints/admin-and-groups.md @@ -1,35 +1,20 @@ -# Администрирование и незавершённые группы +# Администрирование сервера -## Административные маршруты +Серверные административные маршруты требуют роль Admin и активную access-сессию. Администратор сервера и админ группы — разные права: роль в группе не открывает маршруты `/api/admin`. -Следующая таблица показывает фактические атрибуты, а не требуемую безопасную политику. +| Метод | Маршрут | Назначение | +| --------- | ----------------------------------------------- | ----------------------------------------------------------------------- | +| POST | `/api/admin/InviteUser/Invitation` | Приглашение регистрации: endDate, maxParticipants, isAdmin, description | +| GET | `/api/admin/InviteUser` | Список приглашений | +| GET | `/api/admin/InviteUser/GetAllActiveInvitations` | Активные приглашения | +| GET | `/api/admin/InviteUser/{id}` | Приглашение по ID | +| GET | `/api/admin/Users/all` | До 50 пользователей | +| GET | `/api/admin/Users/{id}` | Пользователь по ID | +| POST | `/api/admin/Users/user/{id}/password` | `{ "password": "..." }`; 204, отзыв сессий и push-токенов | +| GET / PUT | `/api/admin/required-channel` | Канал для всех новых пользователей, право выхода | -| Метод | Маршрут | Защита сейчас | -| --- | --- | --- | -| POST | /api/admin/InviteUser/Invitation | Без Authorize | -| GET | /api/admin/InviteUser | Без Authorize | -| GET | /api/admin/InviteUser/GetAllActiveInvitations | Без Authorize | -| GET | /api/admin/InviteUser/{id} | Без Authorize | -| GET | /api/admin/Users/all | Любой аутентифицированный пользователь | -| GET | /api/admin/Users/{id} | Любой аутентифицированный пользователь | -| GET | /api/admin/Users/user/{id}/setpassword/{password} | Любой аутентифицированный пользователь | +UserResponse не содержит passwordHash. Старый GET смены пароля с паролем в URL удалён. JWT роль Admin формируется по Invitation.IsAdmin пользователя. Настройки обязательного канала и изменения паков реакций дополнительно проверяют это право в БД. -CreateInvitationRequest: endDate, maxParticipants, isAdmin, description. Генератор возвращает строковый код в JSON (200). Списки приглашений возвращают id, description, isAdmin, maxParticipants, code, createdAt, endAt, isActive, participantCount. - -Users/all фактически ограничен 50 записями без стабильной пагинации. Ответ UserResponse включает passwordHash, что недопустимо для клиентского контракта. Смена пароля выполняется GET и кладёт пароль в URL. - -Эти маршруты нужно закрыть ролью Admin до публичного использования. Создание административного приглашения вместе с регистрацией позволяет получить роль Admin. Не подключайте их к пользовательскому интерфейсу. - -## Группы - -GET /invite/{code} задуман как вход в группу и требует Authorize. IGroupService не зарегистрирован в AddServices, а _currentUser не присваивается. Маршрут не является рабочим сценарием вступления. - -GroupsHub пуст и не подключён MapHub. Административный FriendshipsController содержит только закомментированные действия, поэтому рабочих endpoints у него нет. - -Наличие моделей ChatGroup/GroupMembership/GroupInvitation и проверки участия в групповом Send не подтверждает готовый продуктовый сценарий групп и каналов. - ---- -Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера. - -Источник: [Govor.API/Controllers/AdminStuff/UsersController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/AdminStuff/UsersController.cs). +Паки: [административный API реакций](reactions.md). Обязательный канал, владелец/админы, приглашения и модерация: [группы и каналы](../groups.md). +Создание административных приглашений выдаёт возможность зарегистрировать серверного администратора, поэтому этот API предназначен только для доверенных администраторов сервера. Административный FriendshipsController и пустой GroupsHub остаются неиспользуемыми заготовками. diff --git a/docs/friendshub-zayavki.md b/docs/friendshub-zayavki.md new file mode 100644 index 0000000..bff9c1e --- /dev/null +++ b/docs/friendshub-zayavki.md @@ -0,0 +1,9 @@ +--- +description: >- + Description: SignalR hub for managing real-time friend request operations, + including sending, accepting, and rejecting friend requests. +icon: wifi +--- + +# FriendsHub — заявки + diff --git a/docs/groups.md b/docs/groups.md new file mode 100644 index 0000000..2171708 --- /dev/null +++ b/docs/groups.md @@ -0,0 +1,130 @@ +# Группы и каналы + +Рабочий серверный API от 03.10.2026. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль. + +Публичные сообщества доступны поиску Govor и вступлению по ID. Приватные сообщества не появляются в поиске: вступление выполняется по действующей ссылке. История, участники, закрытые аватары и команды сообщений доступны только незаблокированным участникам, даже если само сообщество публично. + +## Создание, поиск и профиль + +| Метод | Маршрут | Тело / результат | +| ------ | ----------------------------------------- | ------------------------------------------------------ | +| POST | `/api/groups` | name, description, isPrivate, isChannel; GroupResponse | +| GET | `/api/groups/search?q=...&skip=0&take=50` | Публичные группы и каналы, поиск по имени/описанию | +| GET | `/api/groups/mine?skip=0&take=50` | Сообщества текущего пользователя без банов | +| GET | `/api/groups/{groupId}` | Профиль; приватный профиль только участникам | +| PUT | `/api/groups/{groupId}` | name, description, isPrivate; только владелец | +| POST | `/api/groups/{groupId}/join` | Вступить в публичное сообщество | +| DELETE | `/api/groups/{groupId}/members/me` | Выйти; HTTP 204 | +| POST | `/api/groups/{groupId}/avatar` | multipart/form-data с file; только владелец | +| DELETE | `/api/groups/{groupId}/avatar` | Убрать текущий аватар; только владелец, 204 | + +```json +{ + "name": "Новости Govor", + "description": "Обновления проекта", + "isPrivate": false, + "isChannel": true +} +``` + +POST/PUT/Join возвращают 200, остальные успешные команды без DTO — 204. name — 1–100 символов, description — до 500; q — до 100. skip >= 0, take — 1–100. По умолчанию новое сообщество приватное; создатель автоматически становится участником и владельцем. + +GroupResponse: id, name, description, imageId, imageUrl, isPrivate, isChannel, ownerUserId, createdAt, memberCount, myRole, isRequiredChannel, canLeave. myRole: Member=0, Admin=1, Owner=2, null — не участник. memberCount не включает заблокированных. canLeave учитывает владение и запрет выхода из обязательного канала. + +Аватар: статичный PNG/JPEG/WebP, исходный файл до 2 МиБ и сторон до 2048 px; после обработки PNG до 128×128 и 256 КиБ. GIF не принимается. Загрузка возвращает imageId и mediaUrl. Скачать можно через `/api/media/download/{imageId}` с Bearer token. Текущий публичный аватар доступен всем авторизованным незаблокированным пользователям; приватный — только активным участникам. Старые файлы не удаляются автоматически, но не выдаются посторонним как публичный аватар. + +## Роли и модерация + +| Возможность | Владелец | Админ | Участник | +| ----------------------------------------------- | -------- | ----- | -------- | +| Читать и реагировать | Да | Да | Да | +| Писать в обычную группу | Да | Да | Да | +| Публиковать/редактировать свои сообщения канала | Да | Да | Нет | +| Менять имя, описание, приватность, аватар | Да | Нет | Нет | +| Назначать/снимать админов | Да | Нет | Нет | +| Выпускать/отзывать ссылки | Да | Да | Нет | +| Банить/разбанивать участников | Да | Да | Нет | +| Банить других админов | Да | Нет | Нет | +| Удалять сообщения других участников | Да | Да | Нет | +| Выбирать реакции канала | Да | Да | Нет | +| Передавать владение | Да | Нет | Нет | + +Глобальная роль серверного Admin не заменяет роль в группе. Владельца и самого себя банить нельзя. Назначение админа требует активного участника. Бан админа владельцем снимает его административную роль; после разбана он возвращается как участник. При выходе роль админа снимается. + +| Метод | Маршрут | Назначение | +| ------ | --------------------------------------------------------------- | ------------------------------------------------------------- | +| GET | `/api/groups/{groupId}/members?bannedOnly=false&skip=0&take=50` | Активные участники; список bannedOnly=true только модераторам | +| PUT | `/api/groups/{groupId}/members/{userId}/administrator` | Назначить админа, только владелец | +| DELETE | `/api/groups/{groupId}/members/{userId}/administrator` | Снять админа, только владелец | +| PUT | `/api/groups/{groupId}/members/{userId}/ban` | Заблокировать | +| DELETE | `/api/groups/{groupId}/members/{userId}/ban` | Разблокировать | +| DELETE | `/api/groups/{groupId}/messages/{messageId}` | Удалить сообщение для всех; автор либо модератор | +| POST | `/api/groups/{groupId}/ownership/{userId}` | Передать владение активному участнику | + +Участник в списке: userId, username, role, isBanned, memberSince. Пароли/токены и сущности User не возвращаются. Удаление сообщения проверяет его принадлежность именно указанной группе и отправляет существующее событие MessageRemoved. + +Бан сохраняет запись участника, поэтому повторное вступление через поиск или другую ссылку его не обходит. Он блокирует историю, чтение, отправку, редактуру, реакции и файлы сообщества. События и push фильтруются по действующим участникам. Разбан возвращает членство; автоматического удаления старых сообщений при бане нет — модератор удаляет их отдельными командами. + +Владелец не может выйти, пока не передаст владение. При передаче прежний владелец становится админом и затем может выйти. Владение всегда у одного пользователя. + +## Приглашение по ссылке + +```http +POST /api/groups/{groupId}/invitations +Authorization: Bearer +Content-Type: application/json + +{ "validForDays": 7, "maxParticipants": 100, "description": "Приглашение" } +``` + +Ответ GroupInvitationResponse содержит id, groupId, invitationCode, sharePath, previewPath, joinPath, description, endDate, maxParticipants, usedCount, isRevoked. sharePath имеет вид `/invite/{code}`; добавьте доверенный API base URL, чтобы передать полную ссылку. Клиент, открывший ссылку, извлекает code, показывает preview и выполняет POST join после действия пользователя. Все запросы используют его access token; ссылка не является токеном авторизации аккаунта. + +| Метод | Маршрут | Назначение | +| ------ | -------------------------------------------------- | --------------------------------------------------- | +| GET | `/api/groups/{groupId}/invitations` | До 100 последних ссылок, только модераторы | +| DELETE | `/api/groups/{groupId}/invitations/{invitationId}` | Отозвать ссылку, 204 | +| GET | `/api/group-invites/{code}` | Превью профиля по действующему коду, без вступления | +| POST | `/api/group-invites/{code}/join` | Вступление, GroupResponse | + +Совместимые пути: GET `/invite/{code}` — только превью, POST `/invite/{code}/join` — вступление. Старый побочный эффект вступления через GET устранён: сканеры ссылок и предварительная загрузка не добавляют участников. + +validForDays — 1–365 (по умолчанию 7), maxParticipants — 0–1 000 000; 0 означает без лимита. usedCount — число успешных вступлений по ссылке, а не текущий размер группы. Повтор POST уже вступившего пользователя не расходует лимит; выход не освобождает использованный слот. Просроченная или отозванная ссылка не работает. Отзыв не удаляет ранее вступивших участников. + +## Сообщения и реакции + +Используйте `/hubs/chats`: Send с recipientType=1 и recipientId=groupId. История — GET `/api/groups/{groupId}/messages`; прочтение — [существующий API](endpoints/message-read.md). Публичность сообщества не даёт доступ к его истории без вступления. + +В канале владелец/админ задаёт политику через PUT `/api/groups/{groupId}/reactions`: All=0, None=1, Selected=2 с reactionIds. GET возвращает текущую политику; изменения приходят как ChannelReactionPolicyChanged. Эмодзи, изображения/GIF, HTTP/SignalR установка реакции описаны в [реакциях](endpoints/reactions.md). Бан и снятие админа применяются к этим же сервисам. + +Изменения профиля, членства и ролей пока не имеют отдельного SignalR-события. Обновляйте GroupResponse/список участников при открытии экрана, после своей команды и после отказа по правам. Обычные события сообщений, прочтения, удаления и реакций работают через ChatsHub. Старый пустой GroupsHub не используется. + +## Обязательный канал сервера + +Требуется серверная роль Admin; сервис дополнительно проверяет Invite.IsAdmin пользователя в БД. + +```http +PUT /api/admin/required-channel +Content-Type: application/json +Authorization: Bearer + +{ "channelId": "", "allowLeave": false } +``` + +GET `/api/admin/required-channel` возвращает channelId и allowLeave. PUT принимает существующий канал с владельцем; обычная группа не подходит. Канал может быть приватным. `{ "channelId": null, "allowLeave": true }` отключает автоматическое добавление. + +После включения все новые зарегистрированные пользователи становятся обычными участниками выбранного канала, без расходования приглашения группы. Создание аккаунта, расходование приглашения регистрации и членство сохраняются одной транзакцией; сбой записи не оставляет частичную регистрацию. allowLeave=false запрещает выход из текущего обязательного канала, true разрешает выход обычным участникам/админам. Владелец сначала передаёт владение независимо от этой настройки. + +Существующие пользователи автоматически не добавляются. Настройка выхода действует на всех текущих участников выбранного канала. Смена канала не удаляет старое членство, а ограничение выхода относится только к новому выбранному каналу. Статус обязательного канала не выдаёт административных прав и не отменяет модерацию. + +## Миграция и проверка + +```powershell +dotnet ef database update --project Govor.Domain --startup-project Govor.API +dotnet test Govor.Server.Tests/Govor.Server.Tests.csproj -c Release +``` + +Миграция `20261003131521_PrimitiveGroupsAndRequiredChannel` добавляет владельца, время создания, настройки сервера, лимиты/отзыв ссылок и уникальные индексы членства/админов/кодов. Старые дубли членства объединяются с сохранением бана; удаляются ссылки на отсутствующих пользователей и роли неактивных участников. Неоднозначные старые коды приглашений отзываются. Известное использование старых ссылок восстанавливается по сохранённым членствам; сведения о ранее вышедших пользователях в старой модели отсутствовали. + +Для существующей группы владельцем выбирается самый ранний активный админ, а при его отсутствии — самый ранний активный участник. Пустые сообщества без активных участников остаются без владельца; для них миграция не назначает владельца произвольно. Новые сообщества всегда создаются с владельцем. Исправляется лишняя связь членства с теневым ChatGroupId; основной GroupId сохраняется. + +Удаление сообщества, заявки на вступление, тонкие разрешения админов и UI MAUI в этот примитивный серверный сценарий не входят. Миграция подготовлена, но к рабочей пользовательской БД автоматически не применялась. Локально проверяются SQLite, реальные HTTP/JWT запросы и обработка файлов; PostgreSQL тестируется в существующем CI при его запуске. diff --git a/docs/klient-signalr-na-c-dlya-maui.md b/docs/klient-signalr-na-c-dlya-maui.md new file mode 100644 index 0000000..f89cf5c --- /dev/null +++ b/docs/klient-signalr-na-c-dlya-maui.md @@ -0,0 +1,10 @@ +--- +description: >- + Description: This sub-documentation provides example Java client code for + interacting with the FriendsHub SignalR hub using the microsoft/signalr + library. It covers connecting to the hub, handling con +icon: java +--- + +# Клиент SignalR на C# для MAUI + diff --git a/docs/server-fixes.md b/docs/server-fixes.md index 1899968..38d4ef9 100644 --- a/docs/server-fixes.md +++ b/docs/server-fixes.md @@ -45,10 +45,10 @@ Dockerfile обновлён до .NET 10 и текущих проектов; с ## Проверка и ограничения -Release-сборка Govor.Server.slnx завершилась без ошибок (88 предупреждений). Все 31 локальных серверных теста прошли; пропущенных тестов нет. EF не обнаружил расхождений модели с последней миграцией. +Исходный набор этих исправлений был проверен Release-сборкой и 31 серверным тестом. Новые проверки реакций и групп добавлены в ту же suite Govor.Server.Tests. EF не обнаружил расхождений модели с последней миграцией. Локальные тесты выполняют реальную SQL-запись в SQLite, тестируют HTTP pipeline с JWT и маршруты доставки с mock SignalR/Firebase. Покрыты чужие/забаненные участники, редактура/удаление, media/reply, три режима прочтения, повторения и конкурирующая запись/удаление, очередь/retry, перенос push-токена и отзыв access-сессии. Отдельно проверяется перевод границы в SQL Npgsql и соответствие модели миграции. -CI запускает эту же серверную suite на SQLite и PostgreSQL 16. Для самостоятельного PostgreSQL запуска задайте TEST_POSTGRES_CONNECTION на отдельную БД с именем, заканчивающимся `_tests`; каждый тест применяет миграции в отдельной временной схеме. Локально PostgreSQL и реальная доставка Firebase/MAUI не запускались. +CI запускает эту же серверную suite на SQLite и PostgreSQL 16. Для самостоятельного PostgreSQL запуска задайте TEST\_POSTGRES\_CONNECTION на отдельную БД с именем, заканчивающимся `_tests`; каждый тест применяет миграции в отдельной временной схеме. Локально PostgreSQL и реальная доставка Firebase/MAUI не запускались. -Групповой InviteController/IGroupService остаются незавершёнными; это не реализация управления группами. PresenceStore остаётся локальным процессу; для нескольких экземпляров понадобится общая инфраструктура SignalR/presence. Старые журналы с чувствительными SQL-параметрами и уже выданные права нужно оценивать отдельно от этих изменений. +Примитивное управление группами и каналами, приглашениями, ролями и обязательным каналом добавлено отдельным этапом: [контракт групп](groups.md). PresenceStore остаётся локальным процессу; для нескольких экземпляров понадобится общая инфраструктура SignalR/presence. Старые журналы с чувствительными SQL-параметрами и уже выданные права нужно оценивать отдельно от этих изменений. From 0dd8457df170ac15b1f1fdfa48b176e5ce788a12 Mon Sep 17 00:00:00 2001 From: stalcke2288969 Date: Sun, 4 Oct 2026 02:00:32 +0000 Subject: [PATCH 2/2] =?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 для сообщений не реализован.