# Группы и каналы Рабочий серверный API от 04.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 С 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 не отправляется. ## Обязательный канал сервера Требуется серверная роль 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 tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release ``` Миграция `20261003131521_PrimitiveGroupsAndRequiredChannel` добавляет владельца, время создания, настройки сервера, лимиты/отзыв ссылок и уникальные индексы членства/админов/кодов. Старые дубли членства объединяются с сохранением бана; удаляются ссылки на отсутствующих пользователей и роли неактивных участников. Неоднозначные старые коды приглашений отзываются. Известное использование старых ссылок восстанавливается по сохранённым членствам; сведения о ранее вышедших пользователях в старой модели отсутствовали. Для существующей группы владельцем выбирается самый ранний активный админ, а при его отсутствии — самый ранний активный участник. Пустые сообщества без активных участников остаются без владельца; для них миграция не назначает владельца произвольно. Новые сообщества всегда создаются с владельцем. Исправляется лишняя связь членства с теневым ChatGroupId; основной GroupId сохраняется. Удаление сообщества, заявки на вступление, тонкие разрешения админов и UI MAUI в этот примитивный серверный сценарий не входят. Миграция подготовлена, но к рабочей пользовательской БД автоматически не применялась. Локально проверяются SQLite, реальные HTTP/JWT запросы и обработка файлов; PostgreSQL тестируется в существующем CI при его запуске.