Files
Govor/docs/groups.md
T

18 KiB
Raw Blame History

Группы и каналы

Рабочий серверный 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
{
  "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 фильтруются по действующим участникам. Разбан возвращает членство; автоматического удаления старых сообщений при бане нет — модератор удаляет их отдельными командами.

Владелец не может выйти, пока не передаст владение. При передаче прежний владелец становится админом и затем может выйти. Владение всегда у одного пользователя.

Приглашение по ссылке

POST /api/groups/{groupId}/invitations
Authorization: Bearer <access-token>
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. Публичность сообщества не даёт доступ к его истории без вступления.

В канале владелец/админ задаёт политику через PUT /api/groups/{groupId}/reactions: All=0, None=1, Selected=2 с reactionIds. GET возвращает текущую политику; изменения приходят как ChannelReactionPolicyChanged. Эмодзи, изображения/GIF, HTTP/SignalR установка реакции описаны в реакциях. Бан и снятие админа применяются к этим же сервисам.

Изменения профиля, членства и ролей пока не имеют отдельного SignalR-события. Обновляйте GroupResponse/список участников при открытии экрана, после своей команды и после отказа по правам. Обычные события сообщений, прочтения, удаления и реакций работают через ChatsHub. Старый пустой GroupsHub не используется.

Обязательный канал сервера

Требуется серверная роль Admin; сервис дополнительно проверяет Invite.IsAdmin пользователя в БД.

PUT /api/admin/required-channel
Content-Type: application/json
Authorization: Bearer <admin-access-token>

{ "channelId": "<GUID канала>", "allowLeave": false }

GET /api/admin/required-channel возвращает channelId и allowLeave. PUT принимает существующий канал с владельцем; обычная группа не подходит. Канал может быть приватным. { "channelId": null, "allowLeave": true } отключает автоматическое добавление.

После включения все новые зарегистрированные пользователи становятся обычными участниками выбранного канала, без расходования приглашения группы. Создание аккаунта, расходование приглашения регистрации и членство сохраняются одной транзакцией; сбой записи не оставляет частичную регистрацию. allowLeave=false запрещает выход из текущего обязательного канала, true разрешает выход обычным участникам/админам. Владелец сначала передаёт владение независимо от этой настройки.

Существующие пользователи автоматически не добавляются. Настройка выхода действует на всех текущих участников выбранного канала. Смена канала не удаляет старое членство, а ограничение выхода относится только к новому выбранному каналу. Статус обязательного канала не выдаёт административных прав и не отменяет модерацию.

Миграция и проверка

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 при его запуске.