18 KiB
Группы и каналы
Рабочий серверный 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 при его запуске.