Add forwarding, friend controls, and benefits

Add message forwarding and reply lookup, friend removal and blocking endpoints, and database-backed Govor+ privileges with customizable profile tags. Include migrations, integration tests, and updated API and operations documentation.
This commit is contained in:
Artemy
2026-10-31 18:29:40 +07:00
parent a3401ceedf
commit 632ac04b56
78 changed files with 5284 additions and 720 deletions
+27 -29
View File
@@ -1,41 +1,39 @@
# Govor.API — обзор
# Govor — документация сервера
Govor — мессенджер на ASP.NET Core и .NET MAUI. Эта документация описывает сервер Govor.API и его контракт с клиентом. Стек сервера: .NET 10, EF Core, PostgreSQL, JWT, SignalR, Firebase и локальное хранилище файлов.
Govor — мессенджер с сервером ASP.NET Core и отдельным клиентом .NET MAUI. Здесь описаны запуск сервера, HTTP API, SignalR, шифрование, восстановление доступа и эксплуатация.
## Что реализовано
Документация сверена с серверным `master`, коммит `a3401ce`, 30 октября 2026 года. Описанное поведение относится к этой версии; установленный сервер может быть старше. Адреса и секреты в примерах условные.
Изменения рабочей копии сервера описаны в [исправлениях](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 к сессии, очередь и повторные попытки |
| Группы и каналы | [Публичный поиск, приватные приглашения, владелец/админы/участники, баны, модерация и обязательный канал](groups.md) |
| Шифрование | Есть хранение публичных ключей, но готового E2EE нет |
| Задача | Раздел |
| --- | --- |
| Запустить API локально | [Быстрый старт](getting-started.md) |
| Подключить собственный клиент | [Путь интеграции](client-integration.md), [карта HTTP API](api-reference.md) |
| Разобраться с входом и токенами | [Аутентификация](endpoints/authentication/README.md) |
| Восстановить историю или сменить пароль | [Пароли и восстановление](password-recovery.md) |
| Понять шифрование | [E2EE](e2ee.md), [API устройств и архивов](endpoints/e2ee.md) |
| Настроить сервер на Timeweb | [VPS](vps-deployment.md) или [App Platform](timeweb-deployment.md) |
| Найти причину ошибки | [Диагностика](diagnostics.md), [частые вопросы](faq.md) |
| Проверить изменения | [Тестирование](testing.md) |
## Как читать
## Возможности
Начните с «Запуск и конфигурация» и «Аутентификация». Для чатов используйте HTTP для истории и SignalR для команд и событий. Раздел «Диагностика» описывает ограничения, которые нельзя считать рабочими гарантиями API.
- Регистрация по приглашению, вход с доказательством пароля SRP, access/refresh токены и управление сессиями.
- Друзья, заявки, личные чаты, группы и каналы с отдельными ролями, приглашениями и модерацией.
- История, отправка и редактирование сообщений, прочтение, удаление, реакции и паки.
- E2EE сообщений и вложений, сертификаты устройств, ротация ключей, зашифрованный архив и восстановление по паролю/коду.
- Профили, аватары, присутствие, SignalR-события и очередь push через Firebase.
- PostgreSQL, миграции, Docker и GitHub Actions для развёртывания.
Имена `userId`, `friendId`, `chatId` обозначают разные сущности. В сообщениях личного чата `recipientId` — ID записи PrivateChat, а не ID собеседника.
## Что важно знать до интеграции
## Границы готовности
`userId` — пользователь, `sessionId` — сеанс входа, `chatId` — чат. Для личного сообщения `recipientId` означает **PrivateChat.Id**, а не ID собеседника. `recipientType`: `0` — личный чат, `1` — группа/канал.
Документация новых групп и реакций описывает рабочую серверную копию с исправлениями доступа. Проверки HTTP/JWT, SQL и прав выполняются автоматическими тестами; реальная доставка на устройства и производственное развёртывание требуют отдельной проверки. Страницы с commit `4603be9` фиксируют старую диагностику и не описывают все текущие исправления.
HTTP загружает состояние, SignalR передаёт команды и события. После переподключения клиент перечитывает состояние через HTTP. События могут повторяться или пропускаться; push не подтверждает прочтение.
Эффект стекла относится к MAUI-интерфейсу. API передаёт данные и события; производительность размытия, контрастность и анимации нужно проверять отдельно на устройствах.
E2EE реализовано прикладным протоколом JOSE. Он не предоставляет forward secrecy, post-compromise security и прозрачность ключей; первая встреча и состав групп доверяют серверу. [Модель доверия](e2ee.md) обязательна к прочтению перед реализацией другого клиента.
Регистрация сейчас требует код приглашения. Обещание отключить приглашения после релиза является продуктовым планом, а не поведением текущего кода.
В проверке этой ревизии прошли 735 серверных тестов на SQLite. Это не подтверждение доставки Firebase на устройство или состояния production-инсталляции. [Ограничения проверки](testing.md).
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Program.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Program.cs).
Исходный код: [Govor, a3401ce](https://github.com/stalcker2288969/Govor/tree/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2).
+42 -28
View File
@@ -1,30 +1,44 @@
# Table of contents
# Оглавление
* [Govor.API — обзор](README.md)
* [Исправления серверной части — 03.10.2026](server-fixes.md)
* [Запуск и конфигурация](getting-started.md)
* [Архитектура и границы](architecture.md)
* [Govor — документация сервера](README.md)
* [Начало работы](getting-started.md)
* [Конфигурация](configuration.md)
* [Путь интеграции клиента](client-integration.md)
* [Архитектура и границы](architecture.md)
* [Частые вопросы](faq.md)
* [Аутентификация](endpoints/authentication/README.md)
* [Регистрация и вход](endpoints/authentication/authcontroller.md)
* [Обновление токенов](endpoints/authentication/refreshcontroller.md)
* [Сессии](endpoints/sessioncontroller.md)
* [Друзья и поиск](endpoints/friendshipcontroller.md)
* [Списки заявок в друзья](endpoints/friendsrequestquerycontroller.md)
* [Личные чаты](endpoints/private-chats.md)
* [История сообщений](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)
* [ChatsHub — сообщения](signalr/chathub.md)
* [PresenceHub — online и offline](signalr/presencehub.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)
* [Регистрация и вход](endpoints/authentication/authcontroller.md)
* [Обновление токенов](endpoints/authentication/refreshcontroller.md)
* [Сессии и выход](endpoints/sessioncontroller.md)
* [Пароли и восстановление истории](password-recovery.md)
* [E2EE и модель доверия](e2ee.md)
* [Устройства, ключи и архивы — HTTP API](endpoints/e2ee.md)
* [Старый API prekeys](endpoints/session-keys.md)
* [HTTP API — карта маршрутов](api-reference.md)
* [Ответы, ошибки и сериализация](code-docs/hubresult-less-than-t-greater-than.md)
* [Друзья и поиск](endpoints/friendshipcontroller.md)
* [Списки заявок](endpoints/friendsrequestquerycontroller.md)
* [Личные чаты](endpoints/private-chats.md)
* [История сообщений](endpoints/chatloadcontroller.md)
* [Прочтение и счётчики](endpoints/message-read.md)
* [Группы и каналы](groups.md)
* [Реакции и паки](endpoints/reactions.md)
* [Медиа и вложения](endpoints/mediacontroller.md)
* [Профиль и аватар](endpoints/profile.md)
* [Ответы, пересылки, блокировки и Govor+](messaging-and-benefits.md)
* [Присутствие через HTTP](endpoints/onlinepingingcontroller-ne-rabotaet.md)
* [Push-уведомления](endpoints/push.md)
* [Администрирование](endpoints/admin-and-groups.md)
* [SignalR — команды и события](signalr/README.md)
* [ChatsHub — сообщения и события чатов](signalr/chathub.md)
* [FriendsHub — заявки](friendshub-zayavki.md)
* [PresenceHub — online и offline](signalr/presencehub.md)
* [ProfileHub — изменения профиля](signalr/profilehub.md)
* [Пример клиента на C# для MAUI](klient-signalr-na-c-dlya-maui.md)
* [Развёртывание и сопровождение](deployment.md)
* [Timeweb VPS и GitHub Actions](vps-deployment.md)
* [Timeweb App Platform](timeweb-deployment.md)
* [Обновления, резервные копии и восстановление](operations.md)
* [Тестирование](testing.md)
* [Диагностика](diagnostics.md)
* [Актуальность документации и история](server-fixes.md)
+281
View File
@@ -0,0 +1,281 @@
# Карта HTTP API
Карта составлена по действующим атрибутам контроллеров ревизии `a3401ce`. Закомментированные методы не включены. Тела запросов, ответы и права описаны в связанных разделах; точную runtime-схему DTO также показывает `/swagger/v1/swagger.json` установленного сервера. Swagger может быть ограничен оператором.
По умолчанию нужен Bearer access token и активная сессия. Без JWT доступны register/login/challenge/login, refresh, проверки server и InvitationWithKey (последний требует adminKey). Остальные методы не становятся публичными от наличия ссылки-приглашения. `purpose` в маршрутах пароля — только `change` или `reset`. Числовые типы чата: 0 — личный, 1 — группа.
Для методов без тела успех может быть 204; не пытайтесь всегда разбирать JSON. Форматы ошибок — [общий контракт](code-docs/hubresult-less-than-t-greater-than.md).
## Доступность
| Метод | Маршрут | Назначение |
| --- | --- | --- |
| GET | `/server/ping` | Процесс доступен |
| GET | `/server/ready` | БД доступна и миграции применены |
## InviteUserController
[Подробное описание](endpoints/admin-and-groups.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/AdminStuff/InviteUserController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/admin/InviteUser/Invitation` |
| POST | `/api/admin/InviteUser/InvitationWithKey` |
| GET | `/api/admin/InviteUser/GetAllActiveInvitations` |
| GET | `/api/admin/InviteUser` |
| GET | `/api/admin/InviteUser/{id}` |
## ReactionPacksAdminController
[Подробное описание](endpoints/reactions.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/AdminStuff/ReactionPacksAdminController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/admin/reaction-packs` |
| GET | `/api/admin/reaction-packs/{packId}` |
| POST | `/api/admin/reaction-packs` |
| PUT | `/api/admin/reaction-packs/{packId}` |
| DELETE | `/api/admin/reaction-packs/{packId}` |
| POST | `/api/admin/reaction-packs/{packId}/reactions/emoji` |
| POST | `/api/admin/reaction-packs/{packId}/reactions/media` |
| DELETE | `/api/admin/reaction-packs/{packId}/reactions/{reactionId}` |
## RequiredChannelController
[Подробное описание](endpoints/admin-and-groups.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/AdminStuff/RequiredChannelController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/admin/required-channel` |
| PUT | `/api/admin/required-channel` |
## UsersController
[Подробное описание](endpoints/admin-and-groups.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/AdminStuff/UsersController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/admin/Users/all` |
| GET | `/api/admin/Users/{id}` |
| POST | `/api/admin/Users/user/{id}/password` |
## AuthController
[Подробное описание](endpoints/authentication/authcontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Authentication/AuthController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/Auth/register` |
| POST | `/api/Auth/login` |
| POST | `/api/Auth/password/challenge` |
| POST | `/api/Auth/password/login` |
| GET | `/api/Auth/password` |
| PUT | `/api/Auth/password/enrollment` |
| PUT | `/api/Auth/password/recovery` |
| POST | `/api/Auth/password/{purpose}/challenge` |
| POST | `/api/Auth/password/{purpose}/authorize` |
| POST | `/api/Auth/password/change` |
| POST | `/api/Auth/password/reset-encryption` |
## RefreshController
[Подробное описание](endpoints/authentication/refreshcontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Authentication/RefreshController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/auth/token/refresh` |
## SessionKeysController
[Подробное описание](endpoints/session-keys.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Authentication/SessionKeysController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/session/keys` |
| GET | `/api/session/users/{userId}/keys` |
| POST | `/api/session/keys/rotate` |
| GET | `/api/session/keys/remaining` |
| POST | `/api/session/keys/{preKeyId}/used` |
## ChannelReactionsController
[Подробное описание](endpoints/reactions.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ChannelReactionsController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/groups/{groupId}/reactions` |
| PUT | `/api/groups/{groupId}/reactions` |
## ChatLoadController
[Подробное описание](endpoints/chatloadcontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ChatLoadController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/groups/{groupId}/messages` |
| GET | `/api/user/{userId}/messages` |
## E2eeController
[Подробное описание](endpoints/e2ee.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/E2eeController.cs)
| Метод | Маршрут |
| --- | --- |
| PUT | `/api/e2ee/device` |
| GET | `/api/e2ee/recovery` |
| GET | `/api/e2ee/identities/{peer}/changes` |
| GET | `/api/e2ee/devices` |
| PUT | `/api/e2ee/devices/certificate` |
| GET | `/api/e2ee/conversations/{type}/{conversationId}/signers/{deviceSession}` |
| PUT | `/api/e2ee/recovery` |
| GET | `/api/e2ee/conversations/{type}/{conversationId}/keys` |
## FriendshipController
[Подробное описание](endpoints/friendshipcontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendshipController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/friends/search` |
| GET | `/api/friends` |
## FriendsRequestQueryController
[Подробное описание](endpoints/friendsrequestquerycontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/friends/requests` |
| GET | `/api/friends/responses` |
## GroupsController
[Подробное описание](groups.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/GroupsController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/groups` |
| GET | `/api/groups/search` |
| GET | `/api/groups/mine` |
| GET | `/api/groups/{groupId}` |
| PUT | `/api/groups/{groupId}` |
| POST | `/api/groups/{groupId}/join` |
| POST | `/api/groups/{groupId}/avatar` |
| DELETE | `/api/groups/{groupId}/avatar` |
| DELETE | `/api/groups/{groupId}/members/me` |
| GET | `/api/groups/{groupId}/members` |
| 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` |
| POST | `/api/groups/{groupId}/ownership/{userId}` |
| POST | `/api/groups/{groupId}/invitations` |
| GET | `/api/groups/{groupId}/invitations` |
| DELETE | `/api/groups/{groupId}/invitations/{invitationId}` |
| DELETE | `/api/groups/{groupId}/messages/{messageId}` |
## InviteController
[Подробное описание](groups.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/InviteController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/group-invites/{code}` |
| GET | `/invite/{code}` |
| POST | `/api/group-invites/{code}/join` |
| POST | `/invite/{code}/join` |
## MediaController
[Подробное описание](endpoints/mediacontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/MediaController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/media/upload` |
| GET | `/api/media/download/{id}` |
## MessageReactionsController
[Подробное описание](endpoints/reactions.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/MessageReactionsController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/messages/{messageId}/reactions` |
| PUT | `/api/messages/{messageId}/reactions/me` |
| DELETE | `/api/messages/{messageId}/reactions/me` |
## MessageReadController
[Подробное описание](endpoints/message-read.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/MessageReadController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/chats/{chatId}/read` |
| GET | `/api/chats/{chatId}/unread-count` |
## OnlinePingingController
[Подробное описание](endpoints/onlinepingingcontroller-ne-rabotaet.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/OnlinePingingController.cs)
| Метод | Маршрут |
| --- | --- |
| PATCH | `/api/online/ping` |
| GET | `/api/online/status/{userId}` |
## PrivateChatController
[Подробное описание](endpoints/private-chats.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/PrivateChatController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/user/{friendId}/private-chat` |
| GET | `/api/user/private-chats` |
## ProfileController
[Подробное описание](endpoints/profile.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ProfileController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/profile/avatar` |
| GET | `/api/profile/download/me` |
| GET | `/api/profile/download/{id}` |
## PushTokensController
[Подробное описание](endpoints/push.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/PushTokensController.cs)
| Метод | Маршрут |
| --- | --- |
| POST | `/api/pushes/token/register` |
| DELETE | `/api/pushes/token` |
## ReactionPacksController
[Подробное описание](endpoints/reactions.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ReactionPacksController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/reaction-packs` |
| GET | `/api/reaction-packs/mine` |
| GET | `/api/reaction-packs/{packId}` |
| GET | `/api/reaction-packs/shared/{shareCode}` |
| GET | `/api/reactions/{reactionId}` |
| PUT | `/api/reaction-packs/{packId}/subscription` |
| DELETE | `/api/reaction-packs/{packId}/subscription` |
| GET | `/api/reaction-packs/limits` |
## SessionController
[Подробное описание](endpoints/sessioncontroller.md) · [Исходник](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/SessionController.cs)
| Метод | Маршрут |
| --- | --- |
| GET | `/api/Session/all` |
| DELETE | `/api/Session/close/{sessionId}` |
| DELETE | `/api/Session/close` |
| DELETE | `/api/Session/close/all` |
## SignalR
Команды сообщений находятся в [ChatsHub](signalr/chathub.md), заявки — в [FriendsHub](friendshub-zayavki.md). Подключения: `/hubs/chats`, `/hubs/friends`, `/hubs/presence`, `/hubs/profiles`. Пустой GroupsHub не опубликован как рабочий endpoint.
+1 -1
View File
@@ -21,4 +21,4 @@ GroupManagementService сериализует изменения членств
SignalR-события не имеют долговременной очереди. Клиент восстанавливает историю, прочтение, версии реакций, свои группы, открытый профиль и участников после reconnect через HTTP. Для реакций/политик и изменений сообществ push не отправляется. При параллельных командах порядок событий не гарантирован, поэтому актуальные права берутся из HTTP состояния, а не из последнего полученного уведомления.
[Группы и каналы](groups.md), [реакции](endpoints/reactions.md), [прочтение](endpoints/message-read.md) описывают текущую рабочую версию. E2EE, согласованное присутствие между инстансами и ключ идемпотентности отправки сообщений остаются отдельными задачами.
[Группы и каналы](groups.md), [реакции](endpoints/reactions.md), [прочтение](endpoints/message-read.md) описывают текущую рабочую версию. E2EE сообщений и архивов реализовано; [модель доверия](e2ee.md) и [восстановление по паролю](password-recovery.md) описаны отдельно. Для E2EE повтор той же отправки распознаётся по подписанному messageId и контексту. Согласованное присутствие между инстансами и общий ключ идемпотентности всех команд не реализованы.
+51
View File
@@ -0,0 +1,51 @@
# Путь интеграции клиента
Этот сценарий соединяет отдельные справочные страницы в рабочую последовательность. Используйте базовый HTTPS-адрес сервера без `/api` на конце.
## 1. Войти и подготовить устройство
1. Проверьте `/server/ping`; при необходимости `/server/ready`.
2. [Зарегистрируйтесь по приглашению или выполните SRP-вход](endpoints/authentication/authcontroller.md), проверьте серверное доказательство.
3. Сохраните токены в защищённом хранилище. Организуйте один общий последовательный [refresh](endpoints/authentication/refreshcontroller.md).
4. Загрузите свой профиль `/api/profile/download/me`. ID пользователя отличается от `sid` JWT.
5. Восстановите архив истории по паролю/резервному коду либо создайте первый архив. Зарегистрируйте публичные ключи текущей сессии через [E2EE API](endpoints/e2ee.md). Секреты храните раздельно по серверу и аккаунту.
Повторный вход создаёт новую сессию. Один только access token не позволяет расшифровать историю. Не перезаписывайте локальные ключи при временной ошибке сети или конфликте ревизии архива.
## 2. Загрузить состояние и подключить события
Прочитайте друзей, входящие/исходящие заявки, личные чаты и `/api/groups/mine`. Подпишитесь на события **до** запуска нужных хабов:
| Хаб | Для чего |
| --- | --- |
| `/hubs/chats` | Сообщения, прочтение, реакции, изменения групп |
| `/hubs/friends` | Заявки и их результаты |
| `/hubs/presence` | Online/offline |
| `/hubs/profiles` | Изменение описания и аватара |
SignalR использует протокол SignalR, а не произвольный JSON WebSocket. Для C# — [пример клиента](klient-signalr-na-c-dlya-maui.md). `AccessTokenProvider` возвращает действующий access token. Первоначальный StartAsync требует собственной обработки сбоев; automatic reconnect применяется к потере уже установленного соединения.
Между HTTP-снимком и подпиской возможна гонка. Подключите события, загрузите состояние повторно при необходимости и объединяйте по ID, не добавляйте записи вслепую.
## 3. Открыть чат и отправить сообщение
1. Для собеседника получите `GET /api/user/{friendId}/private-chat`. Ответ — GUID **чата**. Для группы используйте её groupId.
2. Загрузите [историю](endpoints/chatloadcontroller.md). Для пагинации используйте ID якоря, удаляя дубли из-за включения самого якоря.
3. Получите актуальный каталог E2EE участников/устройств. Для файлов сначала зашифруйте содержимое и [загрузите медиа](endpoints/mediacontroller.md).
4. Создайте подписанный E2EE-конверт с messageId, chatId/type, получателями, reply и mediaIds; ключи/имя/MIME вложений поместите внутрь ciphertext.
5. Вызовите ChatsHub.Send. Проверяйте `HubResult.status`; транспортный успех не означает успех бизнес-команды.
6. Объедините ответ Send, MessageSent, ReceiveMessage и историю по ID сообщения. HTTP использует `id`, SignalR — `messageId`.
Повтор **того же** E2EE-конверта с тем же ID и контекстом распознаётся сервисом отправки; создание нового ID при повторе может породить дубликат. Ответ уже сохранённого сообщения может повторить события. Не распространяйте эту гарантию на все команды API.
## 4. Прочтение, редактирование и восстановление
[Прочтение](endpoints/message-read.md) отправляйте, когда пользователь действительно увидел сообщения. Push/получение по сети не равно прочтению. Для редактирования сформируйте новый подписанный конверт с прежним messageId и признаком edit; соблюдайте окно редактирования.
После reconnect перечитайте историю, счётчики, реакции видимых сообщений, группы/права, заявки и открытые профили. HTTP определяет актуальное состояние. Не считайте порядок событий порядком транзакций. При `403` обновите права; при `409` обновите соответствующую ревизию/каталог; при `401` проверьте refresh/вход.
FCM-токен регистрируется для текущей сессии отдельно. [Push](endpoints/push.md) может повторяться и не заменяет загрузку истории.
## 5. Выход
Отмените циклы reconnect, остановите и освободите соединения, отзовите [сессию](endpoints/sessioncontroller.md), очистите её токены по политике приложения. Не удаляйте единственную копию ключей истории без подтверждённого архива/кода. На новом устройстве проверьте восстановление до отказа от старого.
@@ -11,7 +11,8 @@ ResultExtensions преобразует Result<T, Error>: успешный T →
| Conflict | 409 |
| Unauthorized | 401 |
| Forbidden | 403 |
| Остальные, включая ServerError | 400 (текущий дефект mapping) |
| ServerError | 500 |
| Прочие Failure | 400 |
Сервисная ошибка:
@@ -21,7 +22,7 @@ ResultExtensions преобразует Result<T, Error>: успешный T →
errors добавляется при наличии. Автоматическая MVC-валидация, middleware авторизации и ручные BadRequest/StatusCode могут возвращать другую форму. Единого тела ошибки для всех маршрутов сейчас нет.
В контроллерах встречается Forbid(ex.Message): строка трактуется как authentication scheme, а не тело ответа; результат может быть 500 вместо 403.
Ручной Forbid возвращает отказ без гарантированного JSON-тела. SRP/E2EE-контроллеры также возвращают строки и пустые ответы. Обрабатывайте статус и Content-Type до разбора тела.
## SignalR HubResult<T>
@@ -29,11 +30,11 @@ errors добавляется при наличии. Автоматическа
{"status":200,"result":null,"errorMessage":null}
```
status — число внутри ответа команды, не HTTP-статус соединения. Значения: 200 Success, 201 Created, 204 NoContent, 400 BadRequest, 401 Unauthorized, 404 NotFound, 409 Conflict, 422 UnprocessableEntity, 500 ServerError.
status — число внутри ответа команды, не HTTP-статус соединения. Значения: 200 Success, 201 Created, 204 NoContent, 400 BadRequest, 401 Unauthorized, 403 Forbidden, 404 NotFound, 409 Conflict, 422 UnprocessableEntity, 500 ServerError.
Static factories: Ok(result), Created(result), NoContent(), BadRequest(message, details), NotFound(message, details), Unauthorized(message), Conflict(message), UnprocessableEntity(message), Error(message).
Каждый хаб сам преобразует бизнес-ошибки; наличие enum не гарантирует точный status для каждого Failure. HubExceptionFilter возвращает Task.FromResult(errorResult) вместо объекта результата из InvokeMethodAsync; исключения вне локальных catch требуют исправления и проверки сериализации.
Каждый хаб преобразует бизнес-ошибки; сверяйтесь с контрактом конкретной команды. HubExceptionFilter проверяет активную сессию перед вызовом и преобразует необработанные исключения в сериализуемый HubResult нужного типа. status 401 может завершить соединение.
## JSON-контракт
@@ -41,7 +42,5 @@ Static factories: Ok(result), Created(result), NoContent(), BadRequest(message,
HTTP MessageResponse.id и SignalR UserMessageResponse.messageId отличаются. HTTP и SignalR вложения также имеют разные структуры. Клиент должен иметь явное преобразование; не подменяйте один DTO другим.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Common/Extensions/ResultExtensions.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Common/Extensions/ResultExtensions.cs).
Источник: [Govor.API/Common/Extensions/ResultExtensions.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Common/Extensions/ResultExtensions.cs).
+41
View File
@@ -0,0 +1,41 @@
# Конфигурация
Настройки загружаются стандартными провайдерами ASP.NET Core: `appsettings.json`, файл окружения, переменные окружения и аргументы командной строки. В переменных окружения вложенность обозначается двойным подчёркиванием: `JwtAccessOption:SecretKey` → `JwtAccessOption__SecretKey`.
Дополнительно загружается обязательный `configs/ban_usernames.json` из ContentRoot. Он предназначен для `UsernameModeration`; не размещайте в нём другие параметры, перекрывающие runtime-конфигурацию. Файлы `secrets/` исключены из публикации и предоставляются отдельно.
## Параметры
| Переменная окружения | Назначение / значение по умолчанию |
| --- | --- |
| `ASPNETCORE_ENVIRONMENT` | Локально `Development`, на сервере `Production` |
| `ConnectionStrings__GovorDbContext` | Подключение PostgreSQL; в Git пустое |
| `JwtAccessOption__SecretKey` | Секрет HS256; вне Development минимум 32 байта UTF-8 |
| `JwtAccessOption__Minutes` | Access token: 10 минут |
| `JwtRefreshOption__RefreshTokenLifetimeDays` | Refresh-сессия: 30 дней; продлевается при refresh |
| `InvitationAdmin__Key` | Необязательный секрет создания приглашений без JWT; без значения endpoint отключён (503) |
| `EncryptionOption__Secret` | Секрет хеширования refresh-токенов; в Git пустой |
| `MessageEditingOptions__Enabled` | Ограничение времени редактирования: `true` |
| `MessageEditingOptions__MaxEditTimeMinutes` | Окно редактирования: 15 минут |
| `Firebase__Enabled` | Отправка push; в поставляемом JSON `false` |
| `Firebase__CredentialsJson` | JSON service account; приоритетнее пути |
| `Firebase__CredentialsPath` | Путь к service account; относительно ContentRoot |
| `GOOGLE_APPLICATION_CREDENTIALS` | Путь, если `Firebase:CredentialsPath` не задан |
| `Cors__AllowedOrigins__0` | Разрешённый browser-origin, например `https://client.example.org`; следующие — `__1`, `__2` |
| `ASPNETCORE_HTTP_PORTS` | HTTP-порт контейнера, например `8080` |
Без явного пути Firebase используется `secrets/firebase-adminsdk.json`. Неправильные credentials при включённом Firebase останавливают запуск. Если ключ `Firebase:Enabled` отсутствует вообще, код использует `true`; штатный JSON явно задаёт `false`.
Вне Development нужны строка подключения, секрет JWT и `EncryptionOption:Secret`. `--migrate-only` требует подключение, но пропускает проверку секретов JWT/refresh и создание Firebase. Не используйте Development для обхода production-проверок.
## Хранилище и сеть
`uploads/` хранится относительно каталога API. В контейнере вынесите его в постоянный bind mount. Потеря файлов означает потерю вложений даже при сохранённой БД. Согласованно копируйте БД и файлы; [эксплуатация](operations.md).
API не включает HTTPS redirection. Внешний TLS обычно завершает reverse proxy. Для браузерного клиента настройте точные CORS origins. CORS не заменяет авторизацию и не ограничивает нативный MAUI-клиент.
Ограничитель `password-auth` считает `RemoteIpAddress`. В `Program.cs` нет настроенного `UseForwardedHeaders`: за прокси адресом может оказаться сам прокси, а `[RequireHttps]` старого API ключей может не распознать внешний HTTPS. TLS у прокси не настраивает forwarded headers в приложении автоматически.
Swagger middleware включён во всех окружениях. Для закрытого API ограничьте `/swagger` на прокси: поздний `MapSwagger().RequireAuthorization()` не защищает все пути, уже обслуженные `UseSwagger()`.
Секреты, тома и журналы для [VPS](vps-deployment.md) и [App Platform](timeweb-deployment.md) настраиваются по-разному.
+25
View File
@@ -0,0 +1,25 @@
# Выбор способа развёртывания
Оба варианта используют корневой Dockerfile .NET 10 и внешнюю PostgreSQL. Это альтернативные схемы, а не последовательные этапы.
| Вариант | Что настраивает оператор | Руководство |
| --- | --- | --- |
| VPS + GitHub Actions | Linux, Docker/Compose, SSH, домен, Caddy, постоянные каталоги, резервные копии | [VPS](vps-deployment.md) |
| Timeweb App Platform | Docker-сборка, runtime-переменные, БД, домен/TLS, постоянное хранилище средствами платформы | [App Platform](timeweb-deployment.md) |
## Общие условия
1. Отдельно подготовить PostgreSQL и сетевой доступ к ней.
2. Задать production-секреты через runtime, не через Docker build args.
3. Обеспечить постоянный `uploads` и резервное копирование БД/файлов.
4. Применить миграции командой `--migrate-only` до запуска обновлённого API.
5. Проверить `/server/ready`, авторизацию, сообщения, старые/новые вложения и SignalR по внешнему HTTPS.
6. Включить Firebase только с правильными credentials и проверить устройство отдельно.
Нормальный запуск API не мигрирует БД. Образ может успешно собраться и при этом не стартовать из-за отсутствующей runtime-конфигурации. Готовность процесса не доказывает работоспособность Firebase.
## Что делает workflow
Push в `master` и PR запускают тесты. Публикация образа/деплой включаются только при `VPS_DEPLOY_ENABLED=true`; PR не публикует production. Включённый VPS workflow собирает GHCR-образ, запускает миграции и обновляет контейнеры с проверкой ready. Проверка переменной в файле workflow не подтверждает, что она включена в вашем GitHub.
После применения миграции возврат к старому образу безопасен только при совместимой схеме. [Обновления и восстановление](operations.md).
+40 -61
View File
@@ -1,77 +1,56 @@
# Диагностика и порядок исправлений
# Диагностика
## Основание и пределы проверки
Сначала установите commit/digest сервера, версию клиента и окружение. Эта документация описывает `a3401ce`; симптомы старой версии не следует автоматически переносить на новую. Локальные тесты и опубликованный production — разные среды.
Проверен master Govor-team/Govor, commit 4603be9f714135e0af72d505d17f3d1709834bea (GitHub и локальный checkout совпали). Изучены контроллеры, хабы, сервисы, DTO, EF-модели, DI, запуск и часть MAUI-интеграции. Старый опубликованный GitBook оставался на ревизии 18.12.2025 и расходился с кодом.
## Запуск и доступность
При исходной диагностике сборка API на SDK 10.0.400 прошла с 90 предупреждениями, но тесты .NET 8 не восстанавливались из-за NU1201. Обновление 24.10.2026: серверные тесты перенесены в `tests`, обновлены до .NET 10; Release-сборка и 710 тестов проходят на SQLite и изолированной PostgreSQL. Покрытие Application: 98,88% строк и 93,53% ветвей. Инструкции и ограничения проверки — в [tests/README.md](../tests/README.md). Production, Firebase и UI на устройствах не проверялись.
| Симптом | Что проверить |
| --- | --- |
| SDK не найден | .NET SDK 10 и правила global.json |
| Нет configs/ban_usernames.json | ContentRoot, файл в publish/образе, регистр пути Linux |
| Ошибка обязательного секрета | Runtime-переменные нужного приложения, двойные подчёркивания, значение не пустое |
| Firebase ломает запуск | Enabled, service account JSON/путь и права; для разработки выключить |
| ping=200, ready=503 | Доступ к БД, TLS/CA, ожидающие миграции |
| Connection refused/502 | Порт приложения, состояние контейнера, reverse proxy и его журналы |
| После деплоя пропали файлы | Постоянный uploads, mount, права и прежняя структура путей |
| Browser CORS error | Точный origin включая схему/порт в Cors:AllowedOrigins |
Ниже «подтверждено» означает выявлено по конкретному коду или диагностике сборки, а не воспроизведено атакой на живой сервис.
[Запуск](getting-started.md), [конфигурация](configuration.md), [VPS](vps-deployment.md), [App Platform](timeweb-deployment.md).
## P0 — закрыть до публичного доступа
## HTTP и команды
| Проблема | Доказательство | Последствие | Исправление |
| --- | --- | --- | --- |
| Административные приглашения доступны анонимно | InviteUserController: Authorize закомментирован; isAdmin принимается из запроса | Получение административной роли через собственное приглашение | Admin policy и серверная проверка права выдавать роль |
| Смена чужого пароля и выдача passwordHash обычному пользователю | UsersController: только Authorize; GET setpassword; BuildUserDtos включает PasswordHash | Захват аккаунтов, раскрытие хешей, пароль в URL | Admin policy, убрать hash из DTO, POST-команда, аудит и отзыв сессий |
| Чужая история и отправка в чужой личный чат | MessagesLoader игнорирует currentUser; Send проверяет только существование PrivateChat | Чтение и запись по чужому chatId | Общая проверка участия в конкретном чате |
| Неправильная авторизация Read | CanReadMessage проверяет любой PrivateChat пользователя | Отметки чужих сообщений прочитанными | Привязать проверку к message.RecipientId |
| Криптосессия выдаётся как EF-сущность с UserSession | SessionKeysReader Include(UserSession), контроллер Ok(keys) | Риск раскрытия внутренних полей и циклов JSON | PublicSessionKeysDto, проекция только публичных полей |
| Ответ | Действие |
| --- | --- |
| 400 | Проверить DTO, enum, длины, errorCode и контекст E2EE; refresh тоже может вернуть 400 |
| 401 | Проверить access/refresh, sid, срок/отзыв и серверное время; сериализовать refresh |
| 403 | Проверить участие/бан, автора, роль и владельца файла; смена токена не выдаёт права |
| 404 | Проверить тип ID: пользователь, чат, заявка и сообщение не взаимозаменяемы |
| 409 | Перечитать ревизию/поколение/состояние и повторить согласованную операцию |
| 413 | Учесть лимит хоста/прокси, multipart-overhead и размер ciphertext |
| 429 | Остановить частые повторы входа; за прокси проверить RemoteIpAddress |
| 500 | Сопоставить время, маршрут и журнал; не показывать внутреннее исключение пользователю |
## P1 — восстановить корректность
Тело ошибки бывает ProblemDetails, строкой или пустым. У SignalR status находится внутри HubResult; успешное соединение не означает успешную команду. [Форматы](code-docs/hubresult-less-than-t-greater-than.md).
| Проблема | Где | Действие |
| --- | --- | --- |
| rotate/used всегда обращаются к null | SessionKeysController._oneTimePreKeysRotator | Передать зависимость конструктору |
| online/status всегда падает | OnlinePingingController, две зависимости не присвоены | Исправить DI и проверку поведения |
| Вступление в группу неработоспособно | InviteController._currentUser и незарегистрированный IGroupService | Завершить сервис и инъекцию |
| HideForMe физически удаляет сообщение автора | MessageRemovingService игнорирует ForceRemove | Реализовать отдельную запись скрытия |
| Удаление группового сообщения сравнивает userId с groupId | MessageRemovingService | Проверять автора/администратора и участие |
| Собеседнику не приходят Edit/Remove/Read | NotifyParticipantsAsync адресует ID чата как группу пользователя | Определять обоих участников чата |
| Личные вложения недоступны получателю | AccesserToDownloadMediaService сравнивает RecipientId с userId | Проверять участников PrivateChat |
| Нет владения вложениями и аватаром | Send; ProfileHub.SetAvatar; OwnerType от клиента | Серверная политика ownership, лимиты и whitelist |
| EncryptedKey теряется | MediaService и MessageSendingService не сохраняют ключ | Выбрать и реализовать контракт хранения/доставки |
| Отзыв сессии не отзывает access/соединение | Program.cs; UserSessionRevoker | Проверять sid и закрывать соединения по политике |
| Refresh может повторяться/конфликтовать | JwtService без jti/sid; hash unique; неатомарная ротация | Случайный refresh, атомарная ротация и replay-политика |
| Ошибки превращаются в ложные статусы | ResultExtensions, Forbid(text), хабы, фильтр | Единый mapping, 500 для server errors, корректный объект из фильтра |
| Тестовая инфраструктура отстала | API.Tests net8, API net10; устаревшие проекты | Выровнять TFM/EF и восстановить CI |
| Контейнер не соответствует проекту | Dockerfile .NET 8, ссылки Core/Data | Обновить слои сборки и зависимости |
## Сообщения и шифрование
## P2 — надёжность и сопровождение
- Нет истории: проверьте chatId и recipientType, доступ, якорь и параметры пагинации.
- Файл загружен, но Send отклонён: проверьте uploader/OwnerType, MIME, пустой открытый encryptedKey и совпадение mediaIds в конверте.
- `E2EE_DEVICES_CHANGED`: перечитайте каталог и согласуйте получателей заново.
- Новое устройство не читает старое: проверьте восстановление архива и наличие прежних ключей; не генерируйте новый корень поверх старого архива автоматически.
- Ошибка времени конверта: E2EE проверяет отклонение CreatedAt до пяти минут; синхронизируйте часы.
- Повтор сообщения в UI: объединяйте HTTP, ответ Send и события по ID.
- Конкурентные регистрации могут превысить лимит приглашения; IsActive не проверяется. Нужна атомарная квота.
- Повторный Read конфликтует при гонке по unique(MessageId, UserId); требуется идемпотентная запись.
- Нет clientMessageId/outbox: после сохранения уведомление может упасть, а повторная отправка создаст дубль.
- Пагинация только по SentAt пропускает одинаковые timestamps; нужен стабильный курсор.
- Состояние соединений локально процессу; для нескольких инстансов требуется общее решение.
- CORS принимает любой origin с credentials; sensitive EF logging включён без ограничения окружения.
- Firebase обязателен даже для локального старта; внешние зависимости должны включаться явно.
- global.json содержит некорректную sdk/version; solution зависит от внешнего SmartRes, а API — от DLL в libs.
- Дубликат маппинга UserProfileDto, nullable выключен в API, а предупреждения CS0649 уже указывают реальные дефекты.
- Приглашение определяет роль одновременно с отдельной таблицей Admin; выбрать один источник.
- PrivacyUserSettings и Blocked-модель не означают, что приватность и блокировка покрывают все сценарии.
[Клиентский сценарий](client-integration.md), [E2EE](e2ee.md), [восстановление](password-recovery.md).
NuGet сообщил NU1903 для AutoMapper 16.0.0. [GHSA-rvv3-g6hj-g44x](https://github.com/advisories/GHSA-rvv3-g6hj-g44x) описывает DoS от рекурсивного mapping; исправленная версия ветки 16 — 16.1.1. Это подтверждение уязвимости зависимости; доступность конкретного exploit-пути в Govor отдельно не доказана.
## SignalR и push
## MAUI и стеклянный интерфейс
Проверьте правильный `/hubs/...`, актуальный access token, регистрацию обработчиков до StartAsync и поддержку WebSocket прокси. После reconnect перечитайте HTTP-состояние. При logout остановите автоматические повторы.
MessagesListController присваивает EncryptedContent = text; mapping читает его прямо в Text, а репозиторий редактирует как NewEncryptedContent = newText. Следовательно, в проверенном пути сообщения передаются обычным текстом. Хранение ключей на сервере не делает этот путь E2EE.
Для push проверьте Enabled, актуальный FCM-токен **текущей сессии**, разрешения ОС, Android channel `chat_messages`, APNs для iOS и журнал worker. Активный SignalR не подавляет push сам по себе; прочитавшие исключаются. Принятие FCM не гарантирует отображение. [Диагностика доставки](endpoints/push.md).
ChatHub клиента отбрасывает сообщения с пустым текстом, даже если есть вложение. Клиент подписан на MessageSent, которое сервер не отправляет. Перезапуск из Closed может конфликтовать с logout; refresh на любом HTTP-сбое очищает токены. MessagesListController.SendAsync возвращает Success(true), не проверяя результат SendMessageAsync; экран может считать неуспешную отправку успешной. Эти проблемы важнее полировки оформления.
## Что известно о качестве
В ChatPage.xaml есть слои с Opacity и Shadow. Визуально подтвердить эффект, FPS и поведение blur без запуска приложения нельзя. Рекомендуется отдельно измерить скролл длинного чата, работу клавиатуры, контраст текста на светлом/тёмном фоне и отключение тяжёлых эффектов. Полный UI-аудит не проводился.
735 тестов SQLite прошли на проверенной ревизии; сборка выдаёт предупреждения, в том числе уязвимости ImageSharp 3.1.12. Текущий прогон не подтверждает production, PostgreSQL, реальные устройства и Firebase. [Проверки и ограничения](testing.md).
## Последовательность работ
1. Закрыть P0, добавить проверки «пользователь C не может читать/писать/читать ключи чата A–B; User не управляет Admin».
2. Выровнять .NET и тесты; проверить реальные PostgreSQL-запросы и DI через старт приложения.
3. Исправить P1: события двух участников, HideForMe, медиа, ключи, logout.
4. Закрепить API контрактами и интеграционными тестами HTTP/SignalR, включая повторные и параллельные операции.
5. Решить E2EE и доставку; после этого расширять группы и оптимизировать визуальные эффекты.
Критерий готовности: воспроизводимый запуск, зелёные проверки доступа, согласованный MAUI-контракт и отсутствие известных неработающих методов. Архитектурная переработка должна опираться на эти проверки, а не начинаться с переписывания всего приложения.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Program.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Program.cs).
Старый отчёт от 03.10.2026 описывал дефекты исходной версии, многие из которых уже устранены. Его утверждения об отсутствии E2EE, сломанном HTTP presence, отсутствии проверки sid и неправильном SDK не являются текущими ограничениями.
+25 -2
View File
@@ -1,10 +1,11 @@
# Администрирование сервера
Серверные административные маршруты требуют роль Admin и активную access-сессию. Администратор сервера и админ группы — разные права: роль в группе не открывает маршруты `/api/admin`.
Обычные административные маршруты требуют роль Admin и активную access-сессию. Исключение — InvitationWithKey, проверяющий отдельный runtime-секрет вместо JWT. Администратор сервера и админ группы — разные права: роль в группе не открывает маршруты `/api/admin`.
| Метод | Маршрут | Назначение |
| --- | --- | --- |
| POST | `/api/admin/InviteUser/Invitation` | Приглашение регистрации: endDate, maxParticipants, isAdmin, description |
| POST | `/api/admin/InviteUser/InvitationWithKey` | Без JWT, с секретом adminKey; первоначальное приглашение |
| GET | `/api/admin/InviteUser` | Список приглашений |
| GET | `/api/admin/InviteUser/GetAllActiveInvitations` | Активные приглашения |
| GET | `/api/admin/InviteUser/{id}` | Приглашение по ID |
@@ -15,6 +16,28 @@
UserResponse не содержит passwordHash. Старый GET смены пароля с паролем в URL удалён. JWT роль Admin формируется по Invitation.IsAdmin пользователя. Настройки обязательного канала и изменения паков реакций дополнительно проверяют это право в БД.
Паки: [административный API реакций](reactions.md). Обязательный канал, владелец/админы, приглашения и модерация: [группы и каналы](groups.md).
Паки: [административный API реакций](reactions.md). Обязательный канал, владелец/админы, приглашения и модерация: [группы и каналы](../groups.md).
Создание административных приглашений выдаёт возможность зарегистрировать серверного администратора, поэтому этот API предназначен только для доверенных администраторов сервера. Административный FriendshipsController и пустой GroupsHub остаются неиспользуемыми заготовками.
## Первый администратор и InvitationWithKey
Оператор задаёт `InvitationAdmin__Key` в runtime и перезапускает API. Метод `POST /api/admin/InviteUser/InvitationWithKey` помечен AllowAnonymous: это альтернативная авторизация по секрету, а не открытая выдача ролей. Он принимает `adminKey`, `endDate`, `maxParticipants`, `isAdmin`, `description`. Без настроенного ключа возвращает 503, с неверным — 401, при успешной генерации — 200 со строкой кода. Для административного приглашения задайте isAdmin=true, небольшой срок и maxParticipants=1.
```powershell
# Секрет задайте отдельно; не сохраняйте его в репозитории.
$invitation = @{
adminKey = $env:InvitationAdmin__Key
endDate = [DateTime]::UtcNow.AddHours(1).ToString("o")
maxParticipants = 1
isAdmin = $true
description = "Initial administrator"
} | ConvertTo-Json
$code = Invoke-RestMethod -Method Post -Uri "https://YOUR_API/api/admin/InviteUser/InvitationWithKey" -ContentType "application/json" -Body $invitation
```
Зарегистрируйтесь с inviteLink=$code через обычный `/api/auth/register` (SRP-параметры вычисляет клиент). Роль берётся из приглашения. После создания администратора уберите runtime-ключ и перезапустите API, если этот способ больше не нужен. Этот endpoint не использует password-auth rate limiter; ограничьте доступ к нему на инфраструктуре. Никогда не встраивайте adminKey в мобильное приложение.
## Сброс пароля пользователю
POST `/api/admin/Users/user/{id}/password` меняет доступ и отзывает сессии/FCM-токены. Сброс очищает SRP/парольную копию восстановления, но сохраняет основной зашифрованный архив. Администратор не получает ключи истории. Пользователь после входа задаёт новый пароль и восстанавливает архив резервным кодом либо с доверенного устройства. [Полный сценарий](../password-recovery.md).
+15 -14
View File
@@ -2,25 +2,26 @@
## Последовательность
1. `POST /api/auth/register` либо `POST /api/auth/login` возвращает `{ refreshToken, accessToken }`.
2. HTTP-запросы передают `Authorization: Bearer <accessToken>`.
3. Для SignalR задайте AccessTokenProvider, который возвращает актуальный access token. Program.cs также принимает query `access_token` на путях /hubs.
4. `POST /api/auth/token/refresh` возвращает новую пару; клиент сохраняет новый refresh token.
5. Отзыв сессий выполняется методами /api/Session/close.
1. Новый клиент регистрирует SRP-параметры через `POST /api/auth/register`. Для входа использует `POST /api/auth/password/challenge`, затем `/password/login` с доказательством.
2. Проверяет серверное доказательство и сохраняет пару access/refresh. Точный формат — [регистрация и вход](authcontroller.md).
3. HTTP передаёт `Authorization: Bearer <accessToken>`. Для SignalR задаётся `AccessTokenProvider`; query `access_token` принимается только на путях `/hubs`.
4. [Refresh](refreshcontroller.md) последовательно заменяет оба токена. [Сессии](../sessioncontroller.md) позволяют отозвать отдельное устройство или все сеансы.
5. [Восстановление](../../password-recovery.md) открывает зашифрованный архив истории. Успешный вход и наличие ключей старой истории — разные состояния.
Access token содержит `userId`, `sid` и роль User/Admin. Подпись HS256 проверяется, срок проверяется, issuer и audience не проверяются. Токены возвращаются JSON; сервер не устанавливает HttpOnly-cookie.
## Токены и отзыв
## Ограничения реализации
Access JWT содержит `userId`, `sid`, `tokenType: access` и роль `User`/`Admin`. Подпись HS256 и срок проверяются; issuer/audience не проверяются. JSON-ответы не устанавливают HttpOnly-cookie. Значения по умолчанию: access 10 минут, refresh-сессия 30 дней.
Отзыв сессии блокирует refresh, но Program.cs не проверяет IsRevoked при каждом использовании access token. Уже открытые SignalR-соединения явно не разрываются. Немедленный logout на всех устройствах не гарантирован.
Bearer middleware проверяет по БД владельца `sid`, срок и отсутствие отзыва. Refresh JWT не принимается как access. SignalR-фильтр заново проверяет сессию при каждой команде и прерывает соединение при отказе. Отзыв не следует трактовать как гарантированное мгновенное физическое закрытие всех соединений: у разных хабов разная маршрутизация событий. ChatsHub направляет события активным сессиям.
Refresh JWT содержит userId и tokenType, но не случайный jti или sid. При выпуске одному пользователю в одну секунду возможны одинаковые токены, конфликтующие с уникальным RefreshTokenHash. Ротация не защищена атомарным compare-and-swap от параллельных запросов.
Refresh содержит случайный `jti`; замена хеша выполняется условным атомарным обновлением. Из двух конкурирующих запросов со старым refresh только один может заменить хеш. Это не долговременный журнал replay и не отзыв всей семьи токенов.
Не используйте refresh token как access token. В bearer-валидации нет явного требования tokenType=access; методы с одним Authorize требуют исправления разделения типов токенов.
## Старые аккаунты
На MAUI рекомендовано хранить refresh token в SecureStorage и выполнять обновление последовательно. Это рекомендация клиенту, а не свойство сервера.
`POST /api/auth/login` с открытым паролем оставлен для bcrypt-аккаунтов. После настройки SRP он возвращает `401 Auth.PasswordProofRequired`. Новый клиент не должен автоматически откатываться на старый вход; [процедура перехода](../../password-recovery.md) требует явной смены пароля.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
## Ограничения и хранение
Источник: [Govor.Application/Authentication/JWT/JwtService.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Authentication/JWT/JwtService.cs).
Регистрация, старый login, SRP challenge/login и challenge/authorize действий имеют общий лимит `30 запросов/минуту` на `RemoteIpAddress`, без очереди; превышение — `429`. Challenge одноразовый и действует две минуты. Хранилище challenge находится в памяти процесса, поэтому несколько инстансов требуют отдельной схемы маршрутизации/общего хранилища.
На клиенте храните секреты в защищённом хранилище, сериализуйте refresh и сохраняйте новую пару до следующего запроса. Временная сеть/`5xx` не означает необходимость стирать ключи истории. На внешней сети обязателен HTTPS; [параметры proxy](../../configuration.md).
+39 -23
View File
@@ -1,45 +1,61 @@
# Регистрация и вход
Оба метода доступны анонимно, Content-Type: application/json.
`Content-Type: application/json`. Регистрация и методы входа анонимные, но ограничены политикой `password-auth`. Смена пароля, миграция и восстановление описаны в [отдельном руководстве](../../password-recovery.md).
## POST /api/auth/register
Для нового клиента передайте `name`, `inviteLink`, `deviceInfo` и **все три** поля `srpSalt`, `srpIdentity`, `srpVerifier`, без `password`. Параметры вычисляются клиентом по `PasswordProtocol`: SRP-6a, группа 4096 бит, SHA-512; сериализация должна точно соответствовать реализации. Не подставляйте произвольные Base64-строки вместо verifier.
Совместимый старый формат принимает `password` (минимум 8 символов) без SRP-полей. Смешанный или неполный SRP-запрос отклоняется. Новая интеграция должна реализовывать доказательство пароля, а не строиться на старом формате.
Имя: 4–44 символа, кириллица и цифры, начинается с буквы. Модерация проверяет зарезервированные имена, запрещённые совпадения/подстроки и пять одинаковых символов подряд. `deviceInfo` описывает устройство, в БД до 256 символов.
`inviteLink` — код приглашения, не URL. Генератор использует GUID в формате `N` (32 символа без дефисов). При регистрации проверяются активность, срок и лимит приглашения. Резервирование места, аккаунт, административная роль и членство в обязательном канале сохраняются транзакционно.
Успех `200`:
```json
{"refreshToken":"<refresh>","accessToken":"<access>"}
```
Открытие сессии выполняется после регистрации. Если оно не удалось, аккаунт уже мог быть создан: сначала попробуйте вход, не повторяйте регистрацию бесконечно. Конфликт имени — `409`, отсутствующее приглашение — `404`, ошибка валидации/недоступное приглашение — `400`. Ошибки сервиса используют [ProblemDetails](../../code-docs/hubresult-less-than-t-greater-than.md).
## Контракт SRP-обмена
| Шаг | JSON-поля запроса | Поля успешного ответа |
| --- | --- | --- |
| `password/challenge` | name, publicEphemeral, deviceInfo | challengeId, salt, identity, publicEphemeral, credentialVersion, legacy |
| `password/login` | challengeId, proof | refreshToken, accessToken, serverProof, credentialVersion |
publicEphemeral/proof создаёт SRP-библиотека с параметрами PasswordProtocol. salt/identity/verifier регистрации создаются PasswordProtocol.Create на стороне клиента; salt и identity — случайные значения в hex. `legacy=true` требует явного сценария перехода старого аккаунта, не автоматической отправки открытого пароля.
Пример формы новой регистрации (значения SRP нужно вычислить):
```json
{
"name": "Артём",
"password": "example-password",
"srpSalt": "<salt из PasswordProtocol.Create>",
"srpIdentity": "<identity из PasswordProtocol.Create>",
"srpVerifier": "<verifier из PasswordProtocol.Create>",
"inviteLink": "<код приглашения>",
"deviceInfo": "Android test device"
}
```
Имя: 4–44 символа, только кириллица и цифры, первый символ — буква. Модерация запрещает зарезервированные имена, совпадения/подстроки из конфигурации и пять одинаковых символов подряд. Пароль: минимум 8 символов. DeviceInfo необязателен в запросе, но в БД ограничен 256 символами.
## Вход SRP
Код создаётся как Guid.ToString("N"): 32 символа без дефисов. Поиск кода — по строковому равенству. InviteLink — код, а не URL.
1. `POST /api/auth/password/challenge` начинает обмен и возвращает серверные параметры/challenge.
2. Клиент вычисляет доказательство и отправляет `POST /api/auth/password/login`.
3. Ответ содержит токены и серверное доказательство. Клиент проверяет доказательство до принятия результата.
Проверяется существование приглашения, срок и число участников. Проверка IsActive отсутствует, лимит участников не защищён от конкурентной регистрации.
Challenge действует две минуты и расходуется один раз. Неверное/истёкшее доказательство — `401`, некорректные протокольные данные — `400`, конфликт состояния — `409`, превышение лимита — `429`. Для повторной попытки начните новый обмен.
Успех 200:
Точные DTO, правила кодирования и криптографические операции заданы в [PasswordProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Authentication/PasswordProtocol.cs) и [PasswordAccountService.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Authentication/PasswordAccountService.cs). Их следует переносить согласованно с клиентом, не реализовывать обмен по одному схематическому JSON-примеру.
```json
{"refreshToken":"<token>","accessToken":"<token>"}
```
Конфликт имени — 409; ошибки валидации — 400; отсутствующее приглашение — 404. Тело сервисных ошибок — ProblemDetails с errorCode. Регистрация и открытие сессии — отдельные сохранения: ошибка открытия сессии не откатывает созданного пользователя.
## POST /api/auth/login
## POST /api/auth/login — совместимость
```json
{"name":"Артём","password":"example-password","deviceInfo":"Android test device"}
```
Успех 200 с той же парой токенов. Пользователь не найден — 404 (UserNotRegisteredException); неверный пароль — 400 (InvalidOperationException). Это текущее поведение, а не рекомендуемая политика ошибок входа: разные ответы раскрывают существование аккаунта.
## Ограничения
Rate limiting и блокировка перебора в Program.cs не настроены. Для публичного запуска нужны единая ошибка входа, ограничение частоты и защита административных приглашений.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Authentication/AuthController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/AuthController.cs).
Для bcrypt-аккаунта успех — та же пара токенов. Неизвестное имя — `404`, неверный пароль — `400`, SRP-аккаунт — `401 Auth.PasswordProofRequired`. Различающиеся ответы старого входа позволяют определить существование имени; не переносите это поведение в пользовательские тексты ошибок.
@@ -8,29 +8,24 @@
{"refreshToken":"<последний сохранённый refresh token>"}
```
Сервис хеширует переданную строку и ищет UserSession по RefreshTokenHash. Проверяет IsRevoked и ExpiresAt, выпускает новую пару, заменяет хеш и продлевает ExpiresAt. CreatedAt также перезаписывается, поэтому после refresh это не исходная дата открытия сессии.
Сервис ищет сессию по хешу строки, проверяет отзыв и срок, создаёт новую пару и условно заменяет хеш только если старый ещё актуален. `ExpiresAt` продлевается, `CreatedAt` сохраняет исходную дату открытия сессии.
Успех 200:
Успех `200`:
```json
{"refreshToken":"<new token>","accessToken":"<new token>"}
{"refreshToken":"<new refresh>","accessToken":"<new access>"}
```
| Случай | Текущий ответ |
| Случай | Ответ |
| --- | --- |
| Пустая строка | 400, errorCode Auth.EmptyToken |
| Хеш не найден | 400, errorCode Auth.InvalidToken |
| Истекшая/отозванная сессия | 400, errorCode Auth.InvalidToken |
| Пустая строка | 400, `Auth.EmptyToken` |
| Неизвестный, истёкший или отозванный refresh | 400, `Auth.InvalidToken` |
| Сессия изменилась между чтением и условной заменой | 401, `Auth.InvalidToken` |
Не документируйте неверный refresh как гарантированный 401: текущий Error.Failure преобразуется в 400.
Повтор старого токена после успешной ротации не является штатным способом повторить запрос. Различие 400/401 зависит от момента обнаружения конфликта; не привязывайте восстановление клиента только к одному из статусов.
## Клиент
## Поведение клиента
Сохраните оба новых токена и сериализуйте refresh-запросы. Ошибка сети не должна автоматически удалять авторизацию пользователя. При подтверждённо недействительном refresh требуется повторный вход.
Выполняйте один refresh за раз для всех параллельных HTTP-запросов и хабов. Сохраняйте оба новых токена вместе. Если ответ потерялся после серверного сохранения, старая строка уже может быть недействительна и потребуется новый вход.
Ротация сейчас не имеет защиты от конкурентного использования и истории повторного применения. Детали — в разделе «Аутентификация».
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.Application/Users/UserSessions/UserSessionRefresher.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Users/UserSessions/UserSessionRefresher.cs).
Сетевой сбой или `5xx` не подтверждает недействительность токена. Повторный вход не должен удалять приватные ключи истории. [Пароль и восстановление](../../password-recovery.md).
+2 -32
View File
@@ -1,33 +1,3 @@
# Ключи сессий — экспериментальный API
# Старый API prekeys
RequireHttps и роль User/Admin обязательны.
| Метод | Маршрут | Назначение |
| ----- | --------------------------------- | ---------------------------------------- |
| POST | /api/session/keys | Привязать публичные ключи текущей сессии |
| GET | /api/session/users/{userId}/keys | Получить ключи друга |
| POST | /api/session/keys/rotate | Пополнить одноразовые ключи |
| GET | /api/session/keys/remaining | { remaining: число } |
| POST | /api/session/keys/{preKeyId}/used | Пометить собственный ключ использованным |
byte\[] в JSON передаются строкой base64. UploadKeysRequest содержит identityKey, signedPreKey, signedPreKeySignature и oneTimePreKeys (массив base64). За запрос допускается максимум 100 одноразовых ключей. Сервис запрещает повторную привязку ключей к сессии и проверяет владельца.
RotateOneTimePreKeysRequest содержит newOneTimePreKeys. В реализации ротация удаляет использованные записи и добавляет новые, не ограничивая общий размер набора.
## Неработающие и небезопасные части
\_oneTimePreKeysRotator не передан в конструктор SessionKeysController: rotate и used падают при обращении к null.
remaining считает все записи, включая IsUsed. Reader выдаёт все OneTimePreKeys и возвращает EF-сущности UserCryptoSession вместо PublicSessionKeysDto. Include(UserSession) может включить внутренние поля, а двусторонние навигации могут привести к циклу сериализации. SignedPreKey не включён явным Include.
Доступ к чужим ключам ограничен дружбой, но Forbid("текст") ошибочно используется как имя authentication scheme. Атомарной выдачи одного неиспользованного prekey потребителю нет: endpoint used относится к текущей сессии владельца.
## Статус E2EE
Это заготовка хранения ключей, не законченный криптографический протокол. Нет доказанной реализации обмена/проверки подписей, одноразового потребления, ratchet и поддержки шифрования на клиенте. Не используйте этот раздел как обещание сквозного шифрования.
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Authentication/SessionKeysController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/SessionKeysController.cs).
Актуальное описание: [совместимый API prekeys](../session-keys.md). Для нового клиента используйте [E2EE API](../e2ee.md).
+5 -6
View File
@@ -26,19 +26,18 @@ Query: StartMessageId (Guid?, необязателен), Before=20, After=2. Bef
"replyToMessageId":null,
"mediaAttachments":[],
"reactions":[],
"reactionsVersion":0,
"messageViews":[]
}]
```
У HTTP-ответа поле id; у SignalR UserMessageResponse — messageId. Вложения HTTP имеют id, messageId, mediaFileId.
## Известные проблемы
## Доступ и пагинация
Личный загрузчик принимает currentUser, но не проверяет участие в указанном чате. Это критичная ошибка доступа. Для группы участие проверяется; неучастнику возвращается [].
Оба загрузчика проверяют доступ к конкретному чату: неучастник/заблокированный участник получает 403. Реакции, прочтения и вложения загружаются явно. Порядок стабилен по паре (SentAt, Id), включая одинаковое время отправки.
Пагинация сравнивает только SentAt: сообщения с одинаковой датой могут выпадать вокруг якоря. Reactions и MessageViews не включаются явным Include, поэтому эти массивы не являются надёжным источником состояния. Нужны проверки доступа и стабильный курсор (SentAt, Id).
Якорь включается в результат; при объединении страниц удаляйте дубли по id. Пустой массив может означать пустую историю или неизвестный якорь. encryptedContent возвращается как сохранённый конверт и расшифровывается клиентом.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.Application/Messages/MessagesLoader.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.Application/Messages/MessagesLoader.cs).
Источник: [Govor.Application/Messages/MessagesLoader.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/Messages/MessagesLoader.cs).
+37
View File
@@ -0,0 +1,37 @@
# Устройства, ключи и архивы — HTTP API
Все маршруты `/api/e2ee` требуют access token, роль User/Admin и активную сессию. `type`: `0` — PrivateChat, `1` — ChatGroup. Приватные ключи устройства, пароль и резервный код серверу не передаются. [Модель доверия и жизненный цикл](../e2ee.md).
## Маршруты
| Метод | Маршрут | Результат |
| --- | --- | --- |
| PUT | `/api/e2ee/device` | Регистрация/ротация ключа текущей сессии; `{ registered: true }` |
| GET | `/api/e2ee/devices` | Собственные устройства |
| PUT | `/api/e2ee/devices/certificate` | Сертификация исторического устройства; `{ certified: true }` |
| GET | `/api/e2ee/conversations/{type}/{conversationId}/keys` | `ConversationKeys` для доступного чата |
| GET | `/api/e2ee/conversations/{type}/{conversationId}/signers/{deviceSession}?identityKey=...` | Исторический подписант; `404`, если не найден |
| GET | `/api/e2ee/recovery` | `RecoveryState`: `{ vault: ... }`, без архива `vault: null` |
| PUT | `/api/e2ee/recovery` | Сохранение подписанного архива с ожидаемой ревизией |
| GET | `/api/e2ee/identities/{userId}/changes` | Журнал явной смены корневого ключа |
## Контракты
`DeviceKey`: `userId`, `sessionId`, `identityKey`, `encryptionKey`, `signature`, `accountIdentityKey`, `accountSignature`, `generation`, `previousFingerprint`. `fingerprint` вычисляется из публичных ключей. Идентификаторы обязаны совпасть с владельцем JWT и текущей сессией.
`ConversationKeys`: `conversationId`, `recipientType`, `members` (ID пользователей), `devices` (DeviceKey). Не путайте список участников с устройствами: у одного пользователя может быть несколько устройств. Лимит — 500 устройств на чат. Истёкшая, но не отозванная сертифицированная сессия может оставаться получателем офлайн-сообщений; для авторизации команд срок сессии всё равно проверяется.
`SaveRecoveryVault`: `expectedRevision`, `identityKey`, `ciphertext`, `signature`. `RecoveryVault`: `userId`, `revision`, `identityKey`, `ciphertext`, `signature`. Предел ciphertext архива — 4 000 000 символов, HTTP-запроса сохранения — 4 100 000 байт.
При конфликте ревизии перечитайте архив, расшифруйте и объедините ключи локально, затем подпишите следующую версию. Простая замена expectedRevision без объединения может потерять историю другого устройства.
## Ошибки и повторы
- `400`: неверный тип/контекст, ключи, подпись или данные архива.
- `403`: нет доступа к чату, чужая сессия/устройство или неподходящий ключ аккаунта.
- `404`: не найден исторический подписант.
- `409`: изменилось поколение/ревизия либо не у всех участников есть подходящие ключи.
Перед отправкой получите каталог устройств, зашифруйте сообщение всем получателям и подпишите. При `E2EE_DEVICES_CHANGED` перечитайте каталог и создайте согласованный конверт; не переходите на plaintext. Для личных и приватных чатов сервер требует E2EE; публичные группы допускают старый формат, хотя актуальный клиент шифрует и их.
Точный формат JOSE, подписи и кодирование заданы в [E2eeProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/E2ee/E2eeProtocol.cs) и [E2eeRecoveryProtocol.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.Application/E2ee/E2eeRecoveryProtocol.cs). HTTP camelCase не означает, что можно переименовывать поля внутри подписанного JOSE-содержимого.
+1 -3
View File
@@ -24,7 +24,5 @@ Bearer token обязателен; отдельная роль в атрибут
Статус isOnline зависит от состояния процесса и подключения к presence. Он не является гарантией доставки сообщений или фоновой доступности устройства.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendshipController.cs).
Источник: [Govor.API/Controllers/Friends/FriendshipController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendshipController.cs).
@@ -20,7 +20,5 @@ FriendshipStatus сериализуется числом: Pending=0, Accepted=1,
При отсутствии записей — пустой массив. Ошибки контроллера — 500 с {"error":"Internal server error."}. Для восстановления после reconnect перечитайте списки: события не являются журналом гарантированной доставки.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Friends/FriendsRequestQueryController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs).
Источник: [Govor.API/Controllers/Friends/FriendsRequestQueryController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/Friends/FriendsRequestQueryController.cs).
+1 -154
View File
@@ -1,156 +1,3 @@
# Группы и каналы
Рабочий серверный 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 <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](message-read.md). Публичность сообщества не даёт доступ к его истории без вступления.
В канале владелец/админ задаёт политику через PUT `/api/groups/{groupId}/reactions`: All=0, None=1, Selected=2 с reactionIds. GET возвращает текущую политику; изменения приходят как ChannelReactionPolicyChanged. Эмодзи, изображения/GIF, HTTP/SignalR установка реакции описаны в [реакциях](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<GroupProfileChangedResponse>("GroupProfileChanged",
change => ReloadGroupAsync(change.GroupId));
hub.On<GroupMemberChangedResponse>("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 <admin-access-token>
{ "channelId": "<GUID канала>", "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 при его запуске.
Единый актуальный контракт: [группы и каналы](../groups.md).
+20 -25
View File
@@ -1,42 +1,37 @@
# Медиа
# Медиа и вложения
Требуется роль User/Admin.
Требуются access token и роль User/Admin. Загрузка файла и отправка сообщения — отдельные операции.
## POST /api/media/upload
Content-Type: multipart/form-data. Поля:
`multipart/form-data`:
| Поле | Тип | Назначение |
| --- | --- | --- |
| FromFile | файл | Непустое содержимое |
| Type | число | Image=0, Video=1, Audio=2, File=3, Voice=4 |
| MimeType | строка ≤255 | MIME типа файла |
| EncryptedKey | строка | Обязательное поле запроса; сохранение ключа не реализовано |
| OwnerType | число | Message=0, Avatar=1, GroupAvatar=2, System=3 |
| Поле | Назначение |
| --- | --- |
| `FromFile` | Непустой бинарный файл |
| `Type` | Число: Image=0, Video=1, Audio=2, File=3, Voice=4 |
| `MimeType` | Обязательная строка до 128 символов |
| `OwnerType` | Здесь разрешены только Message=0 и Avatar=1 |
| `EncryptedKey` | Для сообщения отсутствует или пустая строка; ключ расшифровки передавать нельзя |
Ограничение запроса — 20 000 000 байт, включая multipart; проверка файла также ≤20 000 000. Не следует обещать загрузку файла ровно этого размера: overhead тоже входит в лимит.
Для `OwnerType=Message` клиент **сначала шифрует файл**. `MimeType` должен совпадать с `E2eeProtocol.EncryptedMimeType`; сервер сохраняет случайное имя `.bin` и тип File. Оригинальные имя, MIME и ключ содержатся внутри зашифрованного сообщения, не в открытых полях upload.
Успех 200:
Лимит всего запроса и multipart — `20 000 000` байт; такой же предел проверяется для файла. Overhead формы и шифрования тоже занимает место: нельзя обещать загрузку исходного файла ровно 20 MB. Аватары не являются E2EE-вложениями; доступ к ним и профильный upload описаны отдельно.
Успех `200`:
```json
{"mediaId":"11111111-1111-1111-1111-111111111111","url":"2026/10/<имя файла>"}
{"mediaId":"11111111-1111-1111-1111-111111111111","url":"<путь в хранилище>"}
```
url — относительный путь хранилища, не публичный URL. Для скачивания используйте endpoint.
`url` — внутренний путь, не публичная ссылка. Для сообщения используйте `mediaId` в списке вложений и метаданных зашифрованного конверта. Send проверяет загрузчика, тип владения, уникальность ID и соответствие вложений подписанному конверту. Чужой файл прикрепить нельзя.
## GET /api/media/download/{id}
Проверяет HasAccessAsync, затем возвращает бинарный файл с MIME и Content-Disposition. Если доступа нет или запись не найдена — 403, потому что проверка доступа выполняется первой. Сервисные ошибки — через ResultExtensions.
Возвращает бинарный файл после проверки доступа. Для вложений учитывается участие в личном чате/группе и бан; непривязанная к сообщению загрузка не получает доступ к download только по признаку uploader. Отсутствие доступа или неизвестный ID могут дать `403`, поскольку доступ проверяется до чтения.
Ответ имеет `Cache-Control: no-store` и `X-Content-Type-Options: nosniff`. Клиент расшифровывает содержимое и проверяет целостность перед отображением. Не используйте серверное имя/MIME зашифрованного файла как оригинальные пользовательские метаданные.
## Ограничения
Для личного сообщения accesser сравнивает Message.RecipientId с userId, хотя там ID чата: получатель может получить 403. При Send принадлежность вложения загрузившему пользователю не проверяется. OwnerType задаёт клиент, включая публично доступный System, — нужна серверная политика владения.
EncryptedKey не хранится ни в MediaFile, ни в MediaAttachments. Нельзя обещать восстановление ключа из истории.
Файлы целиком буферизуются в памяти, MIME принимается от клиента. Запись файла и БД не атомарна: возможны файлы без записи. Очистка неиспользуемых загрузок и stream-based выдача требуют реализации.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/MediaController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/MediaController.cs).
Файлы буферизуются в памяти; запись в файловую систему и БД не образует единую транзакцию. Возможны неиспользованные файлы после сбоя/отмены отправки. Не удаляйте их по одному признаку возраста без проверки ссылок. [Хранение и резервные копии](../operations.md).
+1 -1
View File
@@ -1,6 +1,6 @@
# Прочтение сообщений
Контракт реализован в рабочей копии сервера от 03.10.2026. Требуются access token, роль User/Admin и участие именно в запрошенном чате. `chatId` — ID PrivateChat либо ChatGroup, а не ID собеседника. `recipientType`: 0 — личный чат, 1 — группа.
Контракт текущей серверной ревизии из обзора. Требуются access token, роль User/Admin и участие именно в запрошенном чате. `chatId` — ID PrivateChat либо ChatGroup, а не ID собеседника. `recipientType`: 0 — личный чат, 1 — группа.
## POST /api/chats/{chatId}/read
@@ -1,19 +1,12 @@
# HTTP-присутствие — ограничения
# Присутствие через HTTP
Требуется роль User/Admin.
Требуются access token и роль User/Admin. Историческое имя файла сохранено для совместимости ссылок; endpoint status работает в текущей версии.
| Метод | Маршрут | Текущее поведение |
| Метод | Маршрут | Ответ |
| --- | --- | --- |
| PATCH | /api/online/ping | Вызывает PingHandlerService, успех 200 без тела |
| GET | /api/online/status/{userId} | Неработоспособен: 500 |
| PATCH | `/api/online/ping` | Обновить lastSeen текущего пользователя; 200 без тела |
| GET | `/api/online/status/{userId}` | 200, `{ isOnline, lastSeen }` |
В конструкторе не присваиваются _userOnlineStore и _presenceReader. GetStatus обращается к null; catch возвращает 500 "Internal server error.".
isOnline определяется OnlineUserStore, lastSeen читается из сохранённого пользовательского состояния. Отсутствующие ранее зависимости конструктора исправлены. Исключение сервиса даёт 500, это не штатный ответ status.
Задуманное тело status — { isOnline, lastSeen }, но сейчас его нельзя считать рабочим контрактом.
Для событий online/offline подключайтесь к /hubs/presence. Ping и наличие SignalR-подключения — разные механизмы; требуется единая политика lastSeen/TTL. Не считайте HTTP ping подтверждением активного presence-соединения.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/OnlinePingingController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/OnlinePingingController.cs).
Для событий подключайтесь к [PresenceHub](../signalr/presencehub.md). HTTP ping и наличие presence-соединения — разные механизмы: ping не создаёт SignalR online. OnlineUserStore находится в памяти одного процесса; после перезапуска и на нескольких экземплярах состояние не является общим.
+3 -5
View File
@@ -16,14 +16,12 @@
}]
```
При принятии заявки FriendRequestCommandService также создаёт личный чат и добавляет текущие соединения участников в SignalR-группу.
При принятии заявки FriendRequestCommandService также создаёт личный чат. ChatsHub использует группы сессий; ручная подписка клиента на чат не требуется.
Используйте chatId в Send.recipientId и в /api/user/{userId}/messages. Несмотря на имя параметра userId, загрузчик ожидает ID PrivateChat.
Ошибки дружбы передаются через Forbid(ex.Message), что ошибочно трактует сообщение как имя схемы аутентификации и может дать 500. Параллельное создание и повторное присоединение после частичного сбоя требуют отдельной проверки.
Отсутствие дружбы/доступа возвращает 403 без обещания тела ProblemDetails. Некорректный аргумент — 400. При последовательном вызове существующий чат возвращается повторно. Сервис сначала ищет пару, затем создаёт запись; полную гарантию идемпотентности при конкурентном создании этот маршрут не обещает.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/PrivateChatController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/PrivateChatController.cs).
Источник: [Govor.API/Controllers/PrivateChatController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/PrivateChatController.cs).
+3 -5
View File
@@ -16,14 +16,12 @@ UserProfileDto: id, username, description (nullable), iconId (nullable), isOnlin
## Ограничения
REST UploadAvatar не рассылает AvatarUpdated. Клиентам может потребоваться отдельное обновление данных. В ProfileHub.SetAvatar проверяется существование файла, но не его загрузчик/тип/владелец.
REST UploadAvatar не рассылает AvatarUpdated. Клиентам может потребоваться отдельное обновление данных. ProfileHub.SetAvatar и ProfileService проверяют, что файл загружен текущим пользователем с OwnerType.Avatar. Чужое вложение нельзя назначить аватаром.
Хаб игнорирует Result от SetDescription и SetNewIcon, поэтому успех true не всегда подтверждает изменение. MappingProfile дважды регистрирует UserProfile → UserProfileDto; это нужно устранить и проверить isOnline.
Хаб проверяет Result от SetDescription и SetNewIcon: при сервисной ошибке возвращает ошибку HubResult и не рассылает успешное изменение.
Чтение чужого профиля не применяет PrivacyUserSettings. Наличие моделей приватности не означает действующую политику доступа.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/ProfileController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/ProfileController.cs).
Источник: [Govor.API/Controllers/ProfileController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/ProfileController.cs).
+2 -2
View File
@@ -1,6 +1,6 @@
# Реакции, паки и настройки каналов
Контракт рабочей версии сервера от 03.10.2026. Все маршруты требуют Bearer **access** token и активную сессию. JSON использует camelCase, перечисления передаются числами. HTTP и SignalR вызывают один сервис с одинаковыми проверками доступа.
Контракт текущей серверной ревизии из обзора. Все маршруты требуют Bearer **access** token и активную сессию. JSON использует camelCase, перечисления передаются числами. HTTP и SignalR вызывают один сервис с одинаковыми проверками доступа.
## Реакции сообщения
@@ -130,4 +130,4 @@ dotnet ef database update --project Govor.Domain --startup-project Govor.API
dotnet test tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
```
Миграция `20261003101700_ReactionPacksAndChannelPolicies` создаёт каталог, установки, разрешения канала, версии и базовый пак; старые реакции сохраняются. Она подготовлена, но к вашей рабочей БД автоматически не применялась. Локальные тесты используют SQLite и HTTP pipeline с JWT; SignalR-доставка проверяется через mock транспорта. CI также настроен на PostgreSQL. Реальные устройства/сокеты и PostgreSQL локально не проверены.
Миграция `20261003101700_ReactionPacksAndChannelPolicies` создаёт каталог, установки, разрешения канала, версии и базовый пак; старые реакции сохраняются. Применение к конкретной установке проверяется отдельно через миграции и /server/ready. [Тестирование и границы проверки](../testing.md).
+12 -26
View File
@@ -1,33 +1,19 @@
# Ключи сессий — экспериментальный API
# Старый API prekeys
RequireHttps и роль User/Admin обязательны.
Эти маршруты сохранены для совместимости и отличаются от действующего [API E2EE устройств](e2ee.md). Они сами по себе не реализуют Signal Protocol, ratchet или архив истории.
Требуются HTTPS, access token и роль User/Admin.
| Метод | Маршрут | Назначение |
| --- | --- | --- |
| POST | /api/session/keys | Привязать публичные ключи текущей сессии |
| GET | /api/session/users/{userId}/keys | Получить ключи друга |
| POST | /api/session/keys/rotate | Пополнить одноразовые ключи |
| GET | /api/session/keys/remaining | { remaining: число } |
| POST | /api/session/keys/{preKeyId}/used | Пометить собственный ключ использованным |
| POST | `/api/session/keys` | Привязать ключи текущей сессии |
| GET | `/api/session/users/{userId}/keys` | Публичные ключи друга |
| POST | `/api/session/keys/rotate` | Пополнить одноразовые ключи |
| GET | `/api/session/keys/remaining` | `{ remaining }` |
| POST | `/api/session/keys/{preKeyId}/used` | Пометить собственный ключ использованным |
byte[] в JSON передаются строкой base64. UploadKeysRequest содержит identityKey, signedPreKey, signedPreKeySignature и oneTimePreKeys (массив base64). За запрос допускается максимум 100 одноразовых ключей. Сервис запрещает повторную привязку ключей к сессии и проверяет владельца.
`byte[]` передаются в JSON как Base64. `UploadKeysRequest`: `identityKey`, `signedPreKey`, `signedPreKeySignature`, `oneTimePreKeys`. За upload или rotate допускается до 100 новых prekeys. Rotate получает `newOneTimePreKeys`.
RotateOneTimePreKeysRequest содержит newOneTimePreKeys. В реализации ротация удаляет использованные записи и добавляет новые, не ограничивая общий размер набора.
## Неработающие и небезопасные части
_oneTimePreKeysRotator не передан в конструктор SessionKeysController: rotate и used падают при обращении к null.
remaining считает все записи, включая IsUsed. Reader выдаёт все OneTimePreKeys и возвращает EF-сущности UserCryptoSession вместо PublicSessionKeysDto. Include(UserSession) может включить внутренние поля, а двусторонние навигации могут привести к циклу сериализации. SignedPreKey не включён явным Include.
Доступ к чужим ключам ограничен дружбой, но Forbid("текст") ошибочно используется как имя authentication scheme. Атомарной выдачи одного неиспользованного prekey потребителю нет: endpoint used относится к текущей сессии владельца.
## Статус E2EE
Это заготовка хранения ключей, не законченный криптографический протокол. Нет доказанной реализации обмена/проверки подписей, одноразового потребления, ratchet и поддержки шифрования на клиенте. Не используйте этот раздел как обещание сквозного шифрования.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Источник: [Govor.API/Controllers/Authentication/SessionKeysController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/Authentication/SessionKeysController.cs).
Сервис проверяет владельца сессии; повторная привязка запрещена. Reader возвращает публичные DTO со `signedPreKey` и неиспользованными `oneTimePreKeys`, без внутренних данных UserSession. Конструктор rotator исправлен; прежняя ошибка null больше не описывает текущий сервер.
`used` относится к сессии владельца, а не к атомарной выдаче ключа произвольному собеседнику. Не стройте новый E2EE-клиент на предположении, что это законченный протокол одноразового обмена. За reverse proxy учитывайте [RequireHttps и forwarded headers](../configuration.md).
+6 -6
View File
@@ -19,17 +19,17 @@
}]
```
Список фильтруется по UserId и !IsRevoked, но не по ExpiresAt; истекшие сессии могут присутствовать. CreatedAt меняется при refresh.
Список фильтруется по UserId и !IsRevoked, но не по ExpiresAt; истекшие сессии могут присутствовать. CreatedAt сохраняет дату первоначального открытия сессии.
Закрытие чужой, неизвестной или уже отозванной сессии возвращает 404 с errorCode UserSession.NotFoundOrUnauthorized. Guid.Empty возвращает 400. CloseAll без активных сессий тоже успешен.
Отзыв деактивирует связанные push-токены. Успех Unit преобразуется в 204, а не в 200.
## Ограничение logout
## Действие отзыва
IsRevoked проверяется при refresh; bearer middleware не сверяет текущий sid с БД. Access token может работать до окончания срока, а существующее соединение SignalR не закрывается этим контроллером.
Bearer middleware проверяет sid, владельца, срок и отзыв по БД. SignalR-фильтр повторяет проверку перед каждой командой и прерывает соединение при отказе. ChatsHub исключает отозванные сессии из маршрутизации. Контроллер не гарантирует мгновенное физическое закрытие всех соединений других хабов; клиент останавливает reconnect и закрывает соединения при logout.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
Отзыв исключает устройство из новых E2EE-получателей, но не удаляет уже имеющиеся на нём ключи, кэш и прочитанную историю.
Источник: [Govor.API/Controllers/SessionController.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Controllers/SessionController.cs).
Источник: [Govor.API/Controllers/SessionController.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Controllers/SessionController.cs).
+109
View File
@@ -0,0 +1,109 @@
# Частые вопросы
## Запуск и сервер
### Нужны ли Firebase и production-БД для разработки?
Нет. Для запуска API нужна отдельная PostgreSQL, а Firebase можно выключить `Firebase__Enabled=false`. Серверные тесты по умолчанию используют SQLite in-memory и подменённые зависимости. [Быстрый старт](getting-started.md), [тесты](testing.md).
### Почему сборка проходит, а сервер не запускается?
Сборка не проверяет runtime-секреты, доступ к БД и Firebase credentials. Проверьте обязательные переменные, файл модерации, порт и журналы. [Диагностика](diagnostics.md).
### Почему /server/ping отвечает 200, а /server/ready — 503?
Процесс доступен, но БД недоступна либо есть неприменённые миграции. Примените миграции отдельным `--migrate-only` на нужной БД. Не запускайте его вслепую на неизвестной базе.
### Создаётся ли первый администратор автоматически?
Сам аккаунт автоматически не создаётся. Оператор задаёт `InvitationAdmin__Key` и создаёт административное приглашение через `/api/admin/InviteUser/InvitationWithKey`, передавая секрет в теле. JWT для этого метода не нужен; без настроенного ключа — 503. Затем выполняется обычная регистрация по коду. После настройки отключите этот способ, убрав ключ. [Администрирование](endpoints/admin-and-groups.md).
### Можно ли запускать несколько серверов?
Не без дополнительной работы: presence, подключения, SRP challenge и rate limit локальны процессу; файлы тоже локальные. Нужны общая инфраструктура событий/файлов и согласованная обработка challenge. [Эксплуатация](operations.md).
## Вход и история
### Чем access отличается от refresh?
Access авторизует HTTP/SignalR; refresh меняет пару токенов на `/api/auth/token/refresh`. Refresh не работает как bearer access. По умолчанию access действует 10 минут, refresh-сессия — 30 дней с продлением. [Аутентификация](endpoints/authentication/README.md).
### Почему старый парольный login перестал работать?
SRP-аккаунт получает `Auth.PasswordProofRequired`: используйте обновлённый клиент. Старый bcrypt-вход остался только для миграции. Не делайте автоматический fallback с передачей открытого пароля. [Переход](password-recovery.md).
### Почему после обновления токена второй запрос получил InvalidToken?
Refresh одноразово заменяет хеш. Параллельные обновления конкурируют; используйте один общий refresh и сохраните новую пару. Потеря ответа после сохранения также может потребовать нового входа.
### Вошёл на новом устройстве, но старые сообщения не читаются. Почему?
Авторизация и ключи истории — разные данные. Если парольная копия настроена, архив восстанавливается по паролю; иначе нужен резервный код или доверенное устройство с ключами. Сервер не может создать отсутствующий приватный ключ. [Восстановление](password-recovery.md).
### Что делать, если забыт пароль?
Администратор может сбросить доступ, но не расшифровать историю. После входа задайте новый пароль и восстановите архив кодом/с устройства. Без старого пароля, кода и устройства можно лишь явно начать с новыми ключами. Полученные собеседниками копии этим не удаляются.
### Нужно ли удалять ключи при выходе или сетевой ошибке?
Не удаляйте единственную копию истории автоматически. Завершение сессии и стирание архива — разные операции. Перед отказом от старого устройства проверьте восстановление на новом.
### Может ли сервер читать зашифрованные сообщения?
Он хранит ciphertext и зашифрованные архивы, но не пользовательские секреты. Метаданные, участники, время и размеры видны; профиль, аватары и реакции не входят в ciphertext сообщения. Первая встреча и состав группы доверяют серверу. FS/PCS и прозрачности ключей нет. [Подробные границы E2EE](e2ee.md).
## Чаты, файлы и события
### Что передавать в recipientId личного сообщения?
ID PrivateChat, полученный через `/api/user/{friendId}/private-chat`. Это не friendId. Для группы передаётся groupId и `recipientType=1`.
### Почему «публичная» группа не отдаёт историю всем?
Публичность разрешает поиск и вступление. История и команды требуют активного незаблокированного членства. Администратор сервера и администратор группы — разные роли. [Группы](groups.md).
### Почему отправка сообщает E2EE_DEVICES_CHANGED?
Каталог устройств изменился между загрузкой ключей и отправкой. Перечитайте его и заново подготовьте согласованный конверт. Не переходите на открытый текст.
### Можно ли повторить Send после сетевого сбоя?
Тот же E2EE-конверт с тем же messageId и контекстом распознаётся как сохранённая отправка. Новый messageId создаёт другую операцию. События могут повториться, поэтому объединяйте по ID. Это не общая идемпотентность всех методов.
### Почему HTTP возвращает id, а хаб — messageId?
Это разные DTO. Явно преобразуйте их в общую клиентскую модель. Также различаются структуры HTTP/SignalR вложений. [Сериализация](code-docs/hubresult-less-than-t-greater-than.md).
### Почему загрузка обычной картинки как вложения даёт 400?
Вложение сообщения сначала шифруется клиентом. MIME upload — `application/vnd.govor.encrypted`, ключ не передаётся открытым полем. Лимит 20 000 000 байт относится ко всему запросу, а не только исходному файлу. [Медиа](endpoints/mediacontroller.md).
### Почему отправленное сообщение не равно прочитанному?
Сохранение, доставка SignalR, принятие FCM и просмотр пользователем — разные этапы. Прочтение фиксируется отдельной командой. [Прочтение](endpoints/message-read.md).
### Почему online не означает доступность для push?
Online отражает соединения PresenceHub в памяти процесса. Push зависит от FCM-токена сессии, разрешений ОС и провайдера. HTTP ping отдельно обновляет lastSeen.
### Как восстановить пропущенные события?
После reconnect загрузите HTTP-снимки истории, счётчиков, реакций, групп/прав, заявок и открытых профилей. SignalR не предоставляет долговременный журнал. Порядок параллельных событий не определяет актуальные права.
### Почему при выключенном Firebase нет отложенных push после включения?
NullPushProvider считает задачи обработанными. Он предназначен для работы без доставки, а не для накопления. [Push](endpoints/push.md).
## Обновления и поддержка
### Сохранятся ли вложения после нового Docker-образа?
Только при постоянном uploads и правильном mount. Сама БД хранит ссылки, но не заменяет файлы. [VPS](vps-deployment.md), [резервные копии](operations.md).
### Можно ли откатить только образ после миграций?
Только если старый код совместим с новой схемой. Скрипт не откатывает БД автоматически. Нужны проверенная копия и план восстановления.
### Какие данные приложить к сообщению об ошибке?
Версию сервера/клиента, UTC-время, метод/маршрут или команду хаба, HTTP/HubResult status, errorCode и обезличенный фрагмент лога. Не прикладывайте пароли, токены, runtime.env, service account или приватные ключи.
+39 -7
View File
@@ -1,9 +1,41 @@
---
description: >-
Description: SignalR hub for managing real-time friend request operations,
including sending, accepting, and rejecting friend requests.
icon: wifi
---
# FriendsHub — заявки
Подключение: /hubs/friends, access token, активная сессия и роль User/Admin. Authorize задан на классе; HubExceptionFilter повторно проверяет сессию перед каждой командой.
## Команды
| Команда | Аргумент | Успех |
| ------------- | ----------------- | ----------------------- |
| SendRequest | Guid targetUserId | status 201, result null |
| AcceptRequest | Guid friendshipId | status 200, result null |
| RejectRequest | Guid friendshipId | status 200, result null |
SendRequest запрещает заявку себе и повтор при Pending/Accepted/Blocked. После Rejected запись переиспользуется. Accept разрешён только адресату и только Pending; после сохранения дружбы создаётся личный чат. Reject разрешён адресату для Pending/Rejected.
## Все события
| Событие | Кому |
| ------------------------- | --------------------------- |
| FriendRequestReceived | Адресату новой заявки |
| YourFriendRequestReceived | Отправителю |
| FriendRequestAccepted | Принимающему адресату |
| YourFriendRequestAccepted | Отправителю исходной заявки |
| FriendRequestRejected | Отклоняющему адресату |
| YourFriendRequestRejected | Отправителю исходной заявки |
Каждое событие передаёт **FriendshipDto**, не строку Guid:
```json
{"id":"11111111-1111-1111-1111-111111111111","requesterId":"22222222-2222-2222-2222-222222222222","addresseeId":"33333333-3333-3333-3333-333333333333","status":0}
```
Status: Pending=0, Accepted=1, Rejected=2, Blocked=3.
## Ошибки и восстановление
Сервисные Failure в SendRequest преобразуются в status 500; Accept/Reject — в 400. Поэтому не обещайте 409/403/404 для всех соответствующих бизнес-ошибок.
Дружба сохраняется до создания чата/рассылки; сбой может оставить частично завершённый сценарий. На reconnect перечитывайте /api/friends, /requests, /responses и /api/user/private-chats. Клиенту нужны дедупликация и обновление cache по id.
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Hubs/FriendsHub.cs).
+40 -33
View File
@@ -1,55 +1,62 @@
# Запуск и конфигурация
# Быстрый старт
## Требования
.NET SDK 10 с корректной feature band, PostgreSQL, доступ к NuGet, файл `libs/SmartRes.dll`, каталог `Govor.API/configs` и Firebase service account в `Govor.API/secrets/firebase-adminsdk.json`.
Нужны .NET SDK 10, доступ к NuGet и отдельная PostgreSQL с созданной БД для разработки. `global.json` задаёт SDK `10.0.100` с `rollForward: latestFeature`; подходит установленный SDK `10.0.400`. В репозитории уже есть `libs/SmartRes.dll` и `Govor.API/configs/ban_usernames.json`.
В `global.json` записана некорректная версия SDK `10.0.0`; замените её в отдельном исправлении на установленную версию, например `10.0.400`. Во время диагностики SDK 10.0.400 всё же собрал отдельный проект API.
Firebase для локального запуска не требуется: в `appsettings.json` он выключен. Секреты БД и приложения задаются отдельно.
## Команды из корня репозитория
## 1. Настроить окружение
PowerShell, из корня серверного репозитория. Подставьте реквизиты своей **локальной** БД. Переменные действуют в текущем терминале.
```powershell
dotnet restore Govor.API/Govor.API.csproj
dotnet build Govor.API/Govor.API.csproj --no-restore
dotnet ef database update --project Govor.Domain --startup-project Govor.API
dotnet run --project Govor.API/Govor.API.csproj
$env:ASPNETCORE_ENVIRONMENT = 'Development'
$env:ConnectionStrings__GovorDbContext = 'Host=127.0.0.1;Port=5432;Database=govor_dev;Username=postgres;Password=YOUR_LOCAL_PASSWORD'
$env:JwtAccessOption__SecretKey = 'local-development-signing-key-change-before-deployment'
$env:EncryptionOption__Secret = 'local-development-refresh-secret-change-before-deployment'
$env:Firebase__Enabled = 'false'
```
Команда миграции требует установленного инструмента dotnet-ef; она приведена как инструкция и не выполнялась на пользовательской БД. Перед обновлением существующей БД проверьте миграции и резервную копию.
Эти строки предназначены для разработки. Для внешнего сервера используйте собственные случайные секреты и HTTPS. [Полный список параметров](configuration.md).
## Конфигурация
## 2. Собрать сервер
| Ключ / ресурс | Назначение |
| --- | --- |
| ConnectionStrings:GovorDbContext | PostgreSQL connection string |
| JwtAccessOption:SecretKey | Ключ подписи JWT |
| JwtAccessOption:Minutes | Срок access token в минутах |
| JwtRefreshOption:RefreshTokenLifetimeDays | Срок refresh-сессии |
| MessageEditingOptions:Enabled | Применять ли срок редактирования |
| MessageEditingOptions:MaxEditTimeMinutes | Срок редактирования; значение класса по умолчанию 15 |
| configs/ban_usernames.json | UsernameModeration: BlockedExact, BlockedContains, Reserved |
| secrets/firebase-adminsdk.json | Обязательные учётные данные Firebase при старте |
| uploads/ | Файлы относительно ContentRootPath |
```powershell
dotnet --version
dotnet restore Govor.Server.slnx
dotnet build Govor.Server.slnx -c Release --no-restore
```
Не переносите реальные ключи, пароли и service account в документацию или Git. Не рассчитывайте только на переменные окружения: Program.cs повторно добавляет appsettings.json после стандартных провайдеров, поэтому JSON может перекрыть их значения. Это нужно исправить.
Решение включает API, прикладной и доменный слои, контракты и четыре действующих тестовых проекта. Старый консольный клиент в серверное решение не входит.
Firebase создаётся безусловно. Наличие NullPushProvider не даёт выключить Firebase конфигурацией в текущем DI.
## 3. Применить миграции
## Развёртывание и проверка
```powershell
dotnet run --project Govor.API/Govor.API.csproj --no-launch-profile -- --migrate-only
```
Dockerfile устарел: использует .NET 8 и ссылается на удалённые Govor.Core/Govor.Data. Solution также ссылается на внешний проект SmartRes. До исправления используйте сборку конкретного API-проекта.
Команда применяет ожидающие EF Core миграции и завершается без HTTP API и Firebase. Обычный запуск **не применяет** миграции автоматически. Отдельный `dotnet-ef` для этого способа не нужен. Для существующей БД сначала сделайте резервную копию и изучите [обновление сервера](operations.md).
HTTPS redirection отключён; TLS и forwarded headers требуют отдельной настройки. SessionKeysController содержит RequireHttps, поэтому HTTP для его методов не подходит.
## 4. Запустить и проверить
`GET /server/ping` — маршрут проверки доступности, но возвращает MVC OkResult из minimal API (предупреждение ASP0004); не считайте его полноценным health check БД и Firebase.
```powershell
dotnet run --project Govor.API/Govor.API.csproj --launch-profile http
```
Swagger включён во всех окружениях. UseSwagger обслуживает документ через middleware; поздний MapSwagger.RequireAuthorization не является надёжным подтверждением защиты всех Swagger-маршрутов.
API: `http://localhost:7155`, Swagger UI: `/swagger`. Для локального HTTPS используйте профиль `https` (`https://localhost:7156`) и доверенный сертификат разработки.
## Что проверено
```powershell
Invoke-WebRequest http://localhost:7155/server/ping
Invoke-WebRequest http://localhost:7155/server/ready
```
Обновление 24.10.2026: серверные тесты обновлены до .NET 10 и находятся в `tests`. `dotnet test Govor.Server.slnx -c Release` запускает все четыре проекта. Release-сборка и 710 тестов проходят на SQLite и отдельной PostgreSQL с применением миграций. Инструкции и ограничения — в [tests/README.md](../tests/README.md). Production, реальная доставка Firebase и контейнер в рамках этой проверки не запускались.
`ping` проверяет процесс. `ready` возвращает `200`, если БД доступна и нет ожидающих миграций, иначе `503`. Они не проверяют Firebase, свободное место и доставку сообщений.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; успешная сборка не означает проверку работающего сервера.
## 5. Первый аккаунт
Источник: [Govor.API/Program.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Program.cs).
Регистрация требует кода приглашения. Для первого администратора оператор задаёт секрет `InvitationAdmin__Key` и использует `POST /api/admin/InviteUser/InvitationWithKey`: этот метод не требует JWT, но проверяет секрет из тела. Создайте ограниченное по сроку/числу регистраций приглашение с `isAdmin=true`, затем зарегистрируйтесь по полученному коду. [Точные поля и пример](endpoints/admin-and-groups.md).
Ключ задаётся до запуска API; без него метод возвращает 503. После первоначальной настройки уберите ключ из runtime и перезапустите API, если этот способ больше не нужен. Для обычных приглашений действующий администратор использует защищённый `/Invitation`. Для проверки кода без настройки настоящего аккаунта подходят [изолированные тесты](testing.md).
Далее: [интеграция клиента](client-integration.md), [вход](endpoints/authentication/README.md), [диагностика](diagnostics.md).
+3 -3
View File
@@ -1,6 +1,6 @@
# Группы и каналы
Рабочий серверный API от 04.10.2026. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль.
Текущий контракт серверной ревизии из обзора. Все маршруты требуют access token и активную сессию. Группа — чат с публикацией для всех активных участников; канал — группа с IsChannel=true, где публиковать и редактировать свои публикации могут только владелец и админы. Тип сообщества задаётся при создании и не меняется через профиль.
Публичные сообщества доступны поиску Govor и вступлению по ID. Приватные сообщества не появляются в поиске: вступление выполняется по действующей ссылке. История, участники, закрытые аватары и команды сообщений доступны только незаблокированным участникам, даже если само сообщество публично.
@@ -145,7 +145,7 @@ GET `/api/admin/required-channel` возвращает channelId и allowLeave.
## Миграция и проверка
```powershell
dotnet ef database update --project Govor.Domain --startup-project Govor.API
dotnet run --project Govor.API/Govor.API.csproj --no-launch-profile -- --migrate-only
dotnet test tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
```
@@ -153,4 +153,4 @@ dotnet test tests/Govor.Server.Tests/Govor.Server.Tests.csproj -c Release
Для существующей группы владельцем выбирается самый ранний активный админ, а при его отсутствии — самый ранний активный участник. Пустые сообщества без активных участников остаются без владельца; для них миграция не назначает владельца произвольно. Новые сообщества всегда создаются с владельцем. Исправляется лишняя связь членства с теневым ChatGroupId; основной GroupId сохраняется.
Удаление сообщества, заявки на вступление, тонкие разрешения админов и UI MAUI в этот примитивный серверный сценарий не входят. Миграция подготовлена, но к рабочей пользовательской БД автоматически не применялась. Локально проверяются SQLite, реальные HTTP/JWT запросы и обработка файлов; PostgreSQL тестируется в существующем CI при его запуске.
Удаление сообщества, заявки на вступление и тонкие разрешения админов в этот серверный API не входят. Наличие миграции в репозитории не подтверждает её применение к установленной БД: проверьте /server/ready и журнал миграций. [Результаты и ограничения текущей проверки](testing.md).
+54 -8
View File
@@ -1,10 +1,56 @@
---
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
Эта страница заменяет устаревший Java-пример: он принимал FriendshipDto как String и не соответствовал серверу. Ниже минимальный пример подключения C#; это пример интеграции, а не проверенный end-to-end тест.
Используйте Microsoft.AspNetCore.SignalR.Client и Govor.Contracts либо эквивалентные DTO с теми же полями.
```csharp
using Govor.Contracts.DTOs;
using Govor.Contracts.Responses.SignalR;
using Microsoft.AspNetCore.SignalR.Client;
var connection = new HubConnectionBuilder()
.WithUrl($"{baseUrl.TrimEnd('/')}/hubs/friends", options =>
{
options.AccessTokenProvider = async () =>
await jwtProvider.GetAccessTokenAsync();
})
.WithAutomaticReconnect()
.Build();
using var received = connection.On<FriendshipDto>(
"FriendRequestReceived", dto =>
{
MainThread.BeginInvokeOnMainThread(() => ApplyFriendship(dto));
});
using var accepted = connection.On<FriendshipDto>(
"YourFriendRequestAccepted", dto =>
{
MainThread.BeginInvokeOnMainThread(() => ApplyFriendship(dto));
});
await connection.StartAsync();
var response = await connection.InvokeAsync<HubResult<object>>(
"SendRequest", targetUserId);
if (response.Status != HubResultStatus.Created)
ShowError(response.ErrorMessage);
```
baseUrl, jwtProvider, ApplyFriendship, ShowError и targetUserId предоставляет приложение. Зарегистрируйте остальные четыре события аналогично с FriendshipDto. AcceptRequest/RejectRequest получают friendshipId.
## Жизненный цикл MAUI
1. Подпишитесь на события до подключения.
2. Первоначальный StartAsync требует собственной обработки повторов; automatic reconnect относится к потерянному соединению.
3. После Reconnected перечитайте HTTP-списки, чтобы восстановить пропущенные события.
4. Изменяйте ObservableCollection на MainThread.
5. Отменяйте повторные попытки при logout и DisposeAsync; не запускайте бесконечный StartAsync из Closed после намеренного StopAsync.
6. AccessTokenProvider должен получать актуальный access token; refresh должен быть сериализован.
Для ChatsHub даже сообщение только с вложением содержит E2EE-конверт. Объединяйте события и HTTP по messageId/id. В собственном клиенте отдельно обработайте временные ошибки refresh, остановку reconnect при logout и восстановление состояния после reconnect. [Полная последовательность интеграции](client-integration.md).
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Hubs/FriendsHub.cs).
+256
View File
@@ -0,0 +1,256 @@
# Ответы, пересылки, блокировки и Govor+
Все запросы требуют действующего access JWT. Для HTTP передавайте
`Authorization: Bearer <token>`, для SignalR используйте существующую авторизацию
хабов. Новые поля совместимы с прежними клиентами: идентификаторы связей nullable,
у пользователей без назначенных прав `privileges = 0`.
## Ответ на сообщение
Вызовите `Send` в `/hubs/chats`, указав `replyToMessageId`:
```json
{
"recipientId": "<chat-id>",
"recipientType": 0,
"encryptedContent": "<fresh E2EE envelope>",
"replyToMessageId": "<original-message-id>",
"mediaAttachments": []
}
```
`recipientType`: `0` — личный чат, `1` — группа/канал. Ответ должен ссылаться
на существующее сообщение того же чата и типа. Сервер проверяет право отправки,
включая блокировку в личном чате, бан в группе и роль администратора канала.
Для E2EE `replyToMessageId` должен совпадать с `replyTo` подписанного конверта.
В публичных группах допускается обычное содержимое согласно существующей политике.
Связь возвращается в результате `Send`, событиях сообщений и истории. Для превью
ответа за пределами загруженной страницы используйте `GET /api/messages/{messageId}`.
Ответ — `MessageResponse` с вложениями, реакциями и прочтениями. Отсутствующее
сообщение и отсутствие доступа дают одинаковый `404`, без раскрытия чужого чата.
После удаления оригинала ссылка остаётся; клиент показывает «Сообщение удалено».
Содержимое удалённого сообщения сервер не архивирует в ответе.
## Пересылка
Используется тот же `Send`; добавьте `forwardedFromMessageId`, передайте новое
содержимое и принадлежащие отправителю вложения для чата назначения:
```json
{
"recipientId": "<destination-chat-id>",
"recipientType": 0,
"encryptedContent": "<new envelope encrypted for destination devices>",
"forwardedFromMessageId": "<source-message-id>",
"mediaAttachments": []
}
```
Сервер проверяет доступ отправителя к исходному сообщению и право отправки в чат
назначения. Несуществующий или недоступный источник отклоняется без записи сообщения
и push. Автор и дата источника берутся из БД, клиент не может передать их сам:
| Поле ответа/истории | Значение |
| --- | --- |
| `senderId` | Пользователь, выполнивший пересылку |
| `forwardedFromMessageId` | ID непосредственно пересланного сообщения |
| `forwardedFromUserId` | Автор непосредственно пересланного сообщения |
| `forwardedFromSentAt` | Дата отправки источника, UTC |
Это снимок происхождения без внешнего ключа: удаление источника не удаляет пересылку.
При повторной пересылке указывается непосредственный источник, цепочка автоматически
не разворачивается. Получатель не получает доступ к исходному чату.
Для зашифрованных сообщений клиент расшифровывает оригинал локально, затем шифрует
новое сообщение для актуального набора устройств назначения с новым `messageId`.
Вложения нужно заново загрузить от текущего пользователя; для E2EE зашифровать их
новыми ключами, а ключи поместить внутрь конверта. Прямая подстановка чужих media ID
не даёт прав на файлы. Сервер не расшифровывает содержимое и не может проверить, что
текст пересылки идентичен оригиналу; метаданные происхождения не являются подписью
исходного автора под новым содержимым.
Повтор одного E2EE-запроса с тем же ID идемпотентен; изменение источника, адресата,
содержимого, ответа или вложений с прежним ID отклоняется. В публичных чатах без E2EE
каждый `Send` создаёт новое сообщение. Для массовой пересылки выполняйте отдельный
вызов для каждого сообщения и адресата.
## Удаление из друзей и блокировка
| HTTP | Действие |
| --- | --- |
| `DELETE /api/friends/{userId}` | Удалить принятую дружбу |
| `PUT /api/friends/{userId}/block` | Заблокировать пользователя |
| `DELETE /api/friends/{userId}/block` | Снять собственную блокировку |
Успех — `204`. Идентификатор текущего пользователя всегда берётся из JWT.
Пустой ID и действие на себя дают `400`; блокировка несуществующего пользователя —
`404`; изменение чужой блокировки — `403`.
Удаление идемпотентно, переводит принятую дружбу в `Rejected`, сохраняет историю
чата и не снимает блокировку. Само удаление дружбы не запрещает отправку в ранее
созданный чат: для этого нужна блокировка. Блокировка может создаваться без дружбы,
исключает пользователя из друзей и запрещает новые сообщения в личном чате в обе
стороны, а также новые заявки. Чтение истории и общие группы сохраняются.
Используется существующая модель `FriendshipStatus.Blocked`: у пары одна блокировка,
её владелец записан как `RequesterId`. Только владелец может снять её; вторая сторона
не может заменить владельца. Повтор собственной блокировки безопасен. Снятие
блокировки не восстанавливает дружбу: требуется новая заявка и согласие получателя.
## Привилегии и Govor+
Платёжная подписка не требуется: статус назначает администратор во время работы
сервера. Права читаются из БД при каждой операции и не кешируются в JWT.
| Бит `privileges` | Право |
| --- | --- |
| `0` | Без специальных прав |
| `1` | Govor+: официальный статус и настройка тега |
| `2` | Настройка тега без статуса Govor+ |
| `3` | Оба явно назначенных бита |
`PUT /api/admin/users/{userId}/privileges` принимает `{"privileges": 1}`.
Требуется роль `Admin`; endpoint заменяет весь набор прав. Для отзыва всех прав
передайте `0`. Неизвестные биты дают `400`, неизвестный пользователь — `404`,
конкурентное создание записи прав — `409` (перечитайте состояние и повторите запрос).
Govor+ не выдаёт административных ролей. Новые возможности добавляются отдельными
битами с явной проверкой в соответствующем серверном сервисе.
`GET /api/profile/{userId}/benefits` возвращает:
```json
{
"privileges": 1,
"isGovorPlus": true,
"canCustomizeProfileTag": true,
"tag": {
"text": "Govor+",
"textColor": "#FFFFFF",
"textGradientEndColor": null,
"backgroundColor": "#2455DD",
"gradientEndColor": null,
"gradientAngle": 90,
"borderColor": "#6688FF",
"borderGradientEndColor": null,
"borderWidth": 1,
"shadowColor": "#00000080",
"shadowBlur": 4,
"shadowOffsetX": 0,
"shadowOffsetY": 1,
"fontFamily": "Inter",
"fontWeight": 600,
"fontSize": 12
},
"revision": 1
}
```
Тот же объект `benefits` входит в `GET /api/profile/download/me` и
`GET /api/profile/download/{id}`. Обычный пользователь получает `tag: null`.
У Govor+ без своего оформления отображается стандартный тег. Официальный статус
нужно определять по `isGovorPlus`, а не по произвольному тексту тега.
## Настройка тега
У каждого пользователя один настраиваемый профильный тег.
`PUT /api/profile/tag` заменяет оформление текущего пользователя объектом `tag`
из примера выше; пропущенные поля получают стандартные значения.
`DELETE /api/profile/tag` сбрасывает оформление к стандартному. Оба endpoint
возвращают актуальный `UserBenefitsView` и требуют права настройки; иначе `403`.
| Параметр | Допустимое значение |
| --- | --- |
| `text` | 1–32 UTF-16 символа, не пробельная строка, без управляющих символов |
| Цвета | `#RRGGBB` или `#RRGGBBAA` |
| `gradientEndColor` | Конечный цвет градиента фона; `null` — сплошной фон |
| `textGradientEndColor`, `borderGradientEndColor` | Конечные цвета градиентов текста и обводки; `null` — сплошной цвет |
| `gradientAngle` | 0–360°, общий угол линейных градиентов |
| `borderWidth` | 0–4 |
| `shadowBlur` | 0–20 |
| `shadowOffsetX`, `shadowOffsetY` | −10–10 |
| `fontFamily` | `Inter`, `Roboto`, `Arial`, `Noto Sans`, `serif`, `sans-serif`, `monospace` |
| `fontWeight` | 100–900 с шагом 100 |
| `fontSize` | 10–24 |
Размеры заданы в логических пикселях. Угол соответствует CSS linear-gradient:
0° вверх, 90° вправо. Клиент обеспечивает наличие выбранного шрифта или безопасный
fallback. Тег — структурированные данные: текст рендерится как plain text, а не HTML;
URL шрифтов, произвольный CSS и внешние ресурсы не принимаются. Некорректное
оформление даёт `400` и не изменяет сохранённый тег.
При отзыве прав сохранённое оформление остаётся в БД, но скрывается в API и не может
редактироваться. При повторной выдаче права оформление восстанавливается.
## Обновления в реальном времени
Подключите каждый клиент к `/hubs/profiles` и слушайте `UserBenefitsUpdated`:
```javascript
connection.on("UserBenefitsUpdated", ({ userId, benefits }) => {
const old = profileBenefits.get(userId);
if (!old || benefits.revision > old.revision) {
profileBenefits.set(userId, benefits);
refreshVisibleUserTags(userId);
}
});
```
Событие содержит полный объект, включая `revision`, и отправляется **всем**
подключённым авторизованным клиентам этого хаба, включая владельца, после фиксации
выдачи/отзыва прав, изменения или сброса тега. Дружба или подписка на конкретный
профиль не требуется. Статус и тег — публичные данные для авторизованных пользователей.
Обновляйте общий кеш профилей и все места отображения пользователя: чат, список
участников, друзей и открытый профиль. HTTP-ответ содержит тот же формат.
Ревизия монотонно увеличивается на пользователя; игнорируйте события и HTTP-снимки
с меньшей или равной ревизией. Это защищает от изменения порядка доставки при
конкурентных запросах. Сначала зарегистрируйте обработчик, подключитесь, затем
загрузите HTTP-снимки, также сравнивая ревизии.
SignalR не хранит историю событий: после восстановления соединения перечитайте
видимые профили/benefits через HTTP. При сбое доставки сохранённый HTTP-запрос остаётся
успешным, ошибка пишется в серверный лог; снимок в БД является источником истины.
Перезапуск API для выдачи статуса или изменения оформления не нужен. При запуске
нескольких экземпляров API необходим общий SignalR backplane/service для доставки
между экземплярами; текущая конфигурация использует стандартный in-process SignalR.
## Миграции и проверка
Перед запуском новой версии примените миграции обычным способом проекта
(`dotnet run --project Govor.API -- --migrate-only`). Добавлены nullable-поля
пересылки в `Messages`, таблица `UserBenefits` и её ревизия. Старые сообщения и
пользователи сохраняются; существующим пользователям права автоматически не выдаются.
Проверки находятся в `ReplyAndForwardTests`, `UserBenefitsTests`, `E2eeTests` и
`ReadApiTests` (`UserBenefitsHttpTests.cs`). Они проверяют SQL-хранение, отсутствие
доступа к чужим сообщениям, шифрование пересылки для нового адресата, идемпотентность,
права админа, валидацию оформления и доставку выдачи/изменения/сброса/отзыва статуса
через реальные WebSocket-подключения трёх пользователей.
```powershell
dotnet test Govor.Server.slnx --no-restore
```
### Результат проверки 31.10.2026
На итоговом исходном коде `dotnet test Govor.Server.slnx --no-restore -c Release`
с Coverlet завершился успешно: **771 тест**, из них **36 новых**. Использовались
SQLite in-memory, HTTP TestServer и реальные SignalR WebSocket-соединения.
Миграции проверены через `has-pending-model-changes` и генерацию PostgreSQL SQL-скрипта;
применение к живой PostgreSQL в этом прогоне не выполнялось.
Для сравнения исходный коммит `a3401ce` проверен отдельной временной рабочей копией
с теми же Release-настройками и штатным скриптом измерения покрытия:
| Сборка | Исходные строки / ветви | Итоговые строки / ветви |
| --- | --- | --- |
| Govor.Application | 98,06% / 88,18% | 98,10% / 88,80% |
| Govor.API, без generated sources | 97,03% / 90,91% | 97,05% / 91,06% |
Пороги CI 98% строк и 92% ветвей **не достигнуты в обеих версиях**; они не снижались.
Это остаётся ограничением общего покрытия репозитория. Новый `UserBenefitsService`,
`FriendManagementController`, `MessageLookupController`, а также изменённые
`MessageSendingService` и `FriendshipService` покрыты по строкам на 100%.
`UserBenefitsController` — 20 из 21 исполняемой строки; непокрытым остаётся HTTP-ответ
409 на конкурентное создание прав (сам конфликт проверен интеграционным тестом сервиса).
+44
View File
@@ -0,0 +1,44 @@
# Обновления, резервные копии и восстановление
## Перед обновлением
Зафиксируйте текущий commit/digest образа, список миграций, адрес БД, путь uploads и предыдущий успешный релиз. Сделайте согласованную резервную копию БД и файлов вне сервера. Секреты храните отдельно с ограниченным доступом. Проверьте восстановление копии на отдельной среде.
Миграции E2EE/парольного восстановления меняют протоколы клиента и сервера. Порядок перехода старых устройств описан в [E2EE](e2ee.md) и [восстановлении](password-recovery.md). Старые ключи, которых нет ни на устройстве, ни в архиве, сервер восстановить не может.
## Порядок релиза
1. Собрать и проверить конкретную ревизию, сохранить digest образа.
2. Проверить совместимость миграций с работающим кодом; при необходимости остановить запись.
3. Применить миграции тем же артефактом через `--migrate-only`. Не запускать конкурирующие миграции.
4. Запустить API с постоянными каталогами и нужным runtime.
5. Проверить внешний `/server/ready`, вход и refresh, историю, старое вложение, новый файл и WSS.
6. Проверить восстановление на новом устройстве и реальный push, если они входят в релиз.
VPS-скрипт сериализует деплои, но автоматического отката БД нет. Если миграция завершилась ошибкой, схема уже могла измениться; сначала выясните состояние. [Команды VPS и возврат образа](vps-deployment.md).
## Что сохранять
| Ресурс | Для чего нужен |
| --- | --- |
| PostgreSQL | Пользователи, сообщения, права, сессии, архивы ключей и ссылки на файлы |
| `uploads` | Сами бинарные вложения, аватары, медиа реакций |
| Runtime-секреты и конфигурация | Подключение, подпись JWT, хеширование refresh, Firebase, домен |
| Образ и конфигурация релиза | Повторяемый запуск совместимой версии |
| Пользовательский код/пароль и доверенное устройство | Расшифровка архива E2EE; операторская копия БД их не заменяет |
Логи полезны для расследования, но не заменяют БД. Ограничьте их срок хранения и следите за размером: журналы могут содержать идентификаторы и внутренние ошибки. Не публикуйте runtime.env, токены и зашифрованные архивы в открытых обращениях поддержки.
## Восстановление после потери сервера
1. Поднимите изолированную среду и совместимый образ.
2. Восстановите согласованные копии БД и uploads; проверьте пути и права записи.
3. Восстановите runtime-конфигурацию. Смена JWT-секрета инвалидирует подпись старых токенов; смена `EncryptionOption:Secret` нарушает поиск старых refresh-хешей и требует нового входа.
4. Убедитесь, что миграции соответствуют коду, проверьте ready и пользовательские сценарии.
5. Переключите трафик после проверки. Не подключайте тестовое восстановление к production Firebase без намерения отправлять уведомления.
Отключённый Firebase использует NullPushProvider и считает задачи обработанными; это не буфер для отложенной доставки. После восстановления старой БД push-задачи могут повториться: клиент дедуплицирует по messageId.
## Несколько экземпляров
OnlineUserStore, ConnectionStore, SRP challenge и rate limiter локальны процессу. Несколько реплик требуют согласования SignalR/presence, маршрутизации/общего одноразового хранилища challenge и общих файлов. Одна только общая PostgreSQL не обеспечивает такую согласованность.
+2
View File
@@ -117,6 +117,8 @@ epoch. Журнал доступен самому аккаунту и собес
$env:ASPNETCORE_ENVIRONMENT = 'Development'
$env:ConnectionStrings__GovorDbContext = 'Host=127.0.0.1;Port=5432;Database=govor_dev;Username=postgres;Password=YOUR_LOCAL_PASSWORD'
$env:Firebase__Enabled = 'false'
$env:JwtAccessOption__SecretKey = 'local-development-signing-key-change-before-deployment'
$env:EncryptionOption__Secret = 'local-development-refresh-secret-change-before-deployment'
dotnet restore Govor.API/Govor.API.csproj
dotnet run --project Govor.API/Govor.API.csproj --no-launch-profile -- --migrate-only
dotnet run --project Govor.API/Govor.API.csproj --launch-profile http
+20 -41
View File
@@ -1,54 +1,33 @@
# Исправления серверной части — 03.10.2026
# Актуальность документации и история
Этот документ описывает изменения рабочей копии относительно диагностики commit `4603be9`. Криптографический протокол E2EE не добавлялся. Страницы, снабжённые ссылками на этот commit, сохраняют описание исходной версии; нижеприведённые изменения и новый контракт прочтения уточняют её поведение.
## Базовая версия
## Доступ и сессии
Текущая документация сверена с `master`, коммит `a3401ce`, 30.10.2026. Ссылки на исходники закреплены за этой ревизией. Тестовый результат: 735 тестов SQLite Release без ошибок/пропусков; [подробности](testing.md).
Чтение, история, отправка, редактирование, удаление и скачивание вложений проверяют участие в конкретном PrivateChat/ChatGroup. Забаненный участник группы доступа не получает. В канале отправлять могут только его администраторы. Связь replyTo ограничена тем же чатом; вложения отправителя должны принадлежать ему и иметь тип Message. Аватар нельзя назначить из чужого файла или приватного вложения.
## Что изменилось относительно старой документации
Глобальное удаление разрешено автору либо администратору группы с действующим участием. HideForMe возвращает 400: отдельного механизма скрытия ещё нет, и запрос больше не удаляет сообщение для всех.
- Запуск использует .NET 10, рабочие серверное решение и Dockerfile, runtime-секреты, отключаемый Firebase, migrate-only и readiness.
- Регистрация транзакционно расходует приглашение и добавляет обязательный канал.
- HTTP проверяет активную сессию; refresh имеет случайный jti и условную ротацию; хабы проверяют сессию перед командой.
- История проверяет доступ и сортируется по (SentAt, Id); вложения проверяют владельца.
- Реализованы E2EE, сертификаты/ротация устройств, зашифрованный архив, SRP-вход, парольная копия кода и явный сброс ключей.
- Исправлены зависимости HTTP presence, старого API ключей, обработка ошибок профиля и HTTP ServerError.
- Справочники групп, реакций, прочтения и push включены в общую навигацию.
Административные пользователи и приглашения требуют Admin. Хеши паролей исключены из ответа. Изменение пароля: `POST /api/admin/Users/user/{id}/password`, JSON `{"password":"<new-password>"}`; прежний GET с паролем в URL удалён. Успех 204, неизвестный пользователь 404. Смена пароля отзывает сессии и отключает push-токены.
Ранняя диагностика `4603be9` и список исправлений 03.10.2026 были историческими снимками. Они заменены актуальной [диагностикой](diagnostics.md), а не оставлены как параллельный контракт API. Историю реализации смотрите в Git.
JWT access проверяется по userId/sid: сессия должна принадлежать пользователю, быть неотозванной и неистёкшей. Refresh JWT не принимается как access. Каждый вход создаёт отдельную сессию; DeviceInfo служит подписью устройства. Refresh получает уникальный jti, а ротация хеша условно-атомарна. Повторно использованный refresh не перезаписывает результат другого запроса. Hub-фильтр перепроверяет сессию перед каждой командой и возвращает объект HubResult. Соединения закрываются при истечении access token. Чат-события адресуются группам активных сессий.
## Как поддерживать документацию
Исправлены отсутствующие зависимости OnlinePingingController и SessionKeysController. Последний возвращает DTO публичных ключей вместо EF-графа с UserSession. Это исправление существующего экспериментального API, а не реализация E2EE.
При изменении маршрута, DTO, прав, событий или конфигурации обновляйте соответствующую страницу, [карту API](api-reference.md), [путь интеграции](client-integration.md) и FAQ, если меняется пользовательский сценарий. Отделяйте проверенные результаты от планов. Не обновляйте дату проверки без чтения кода и выполнения относящихся к изменению проверок.
## Уведомления и прочтение
`docs/SUMMARY.md` задаёт навигацию. Сохраняйте прежние страницы как короткие ссылки на канонический раздел, если их URL уже использовались; не храните две независимые копии контракта. Локальные ссылки должны вести на страницы внутри docs либо на исходники по полному GitHub URL.
ReceiveMessage, изменения и квитанции приходят обоим участникам личного чата либо действующим участникам группы. MessageSent синхронизирует исходящее сообщение на устройствах отправителя. Сбой SignalR не превращает сохранённое сообщение в неудачный Send. При восстановлении соединения клиент загружает историю; SignalR не является журналом событий.
## GitBook и репозитории
Сохранение сообщения и ChatPushNotification выполняется одним SaveChanges. ChatPushWorker опрашивает очередь каждые 2 секунды; ChatPushDispatcher получает условную двухминутную аренду, отправляет push, удаляет успешные задачи и повторяет ошибки с задержкой 2–300 секунд. После перезапуска задачи остаются в БД. Удаление сообщения каскадно удаляет задачу. При отправке заново проверяются получатели и прочтение; прочитавшим push не отправляется.
На момент проверки GitBook Govor-API имеет активный Git Sync с `Govor-team/Govor`, веткой `master`, каталогом `docs`. Проверенный здесь код находится в `stalcker2288969/Govor`. Это разные репозитории; push в текущий origin сам по себе не обновляет подключённое пространство.
Это доставка как минимум один раз до принятия push провайдером: после прерывания между ответом Firebase и удалением задачи push может повториться. Используйте messageId для дедупликации и tag чата. Принятие Firebase не подтверждает показ уведомления устройством. У сообщения пока нет клиентского ключа идемпотентности: повторять Send после потери ответа следует осторожно.
Настройка Git Sync меняется в интерфейсе GitBook. Владельцу нужно выбрать единый канонический репозиторий и синхронизировать с ним документацию, иначе последующий импорт старой ветки может вернуть устаревший текст. Эта переработка не переключает Git Sync и не меняет права интеграции.
FCM разбивается на пачки до 500. Временный отказ провайдера не удаляет все регистрации. Автоматически удаляются только токены Unregistered. Выборка учитывает активность и принадлежность сессии; обновление реактивирует токен, смена аккаунта переносит уникальную регистрацию устройства.
## Изменение публичных адресов
[Контракт HTTP/SignalR и интеграция со скроллом](endpoints/message-read.md). История включает messageViews и reactions; порядок по времени и ID предотвращает пропуск сообщений с одинаковым временем.
## Сборка и обновление
Используйте .NET SDK 10 и `Govor.Server.slnx`: она включает актуальный сервер и Govor.Server.Tests, без удалённых проектов и внешнего исходного проекта SmartRes. Бинарный `libs/SmartRes.dll` используется по существующему правилу репозитория. Обновление 24.10.2026: серверные тесты перенесены в tests, обновлены до .NET 10 и подключены к обоим solution. Инструкции и результаты — в [tests/README.md](../tests/README.md).
```powershell
dotnet restore Govor.Server.slnx
dotnet build Govor.Server.slnx --no-restore -c Release
dotnet test Govor.Server.slnx --no-build -c Release
dotnet ef database update --project Govor.Domain --startup-project Govor.API
```
Перед запуском новой версии примените миграцию `20261003070406_ReliableChatPush` к серверной PostgreSQL. Она добавляет очередь с FK и индексом; существующие сообщения/прочтения не изменяет. Пользовательская БД в ходе работы не обновлялась. SQL для миграции можно сформировать `dotnet ef migrations script --project Govor.Domain --startup-project Govor.API`.
Dockerfile обновлён до .NET 10 и текущих проектов; секреты, uploads, bin/obj исключены из build context. Учётные данные Firebase передавайте в контейнер при запуске, например volume `/app/secrets/firebase-adminsdk.json`. Контейнер в данной среде не запускался: Docker daemon недоступен.
`Firebase:Enabled=false` выключает Firebase и использует NullPushProvider для разработки; при этом реальная push-доставка отключена. Production требует Firebase service account. Переменные окружения имеют стандартный приоритет над appsettings.json. Для веб-клиента задайте `Cors:AllowedOrigins`; нативному MAUI CORS не требуется. Подробные ошибки БД включаются явно через Database:EnableDetailedErrors; значения SQL-параметров не логируются. Swagger UI доступен в Development; production-документ требует авторизации.
## Проверка и ограничения
Исходный набор этих исправлений был проверен 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 не запускались.
Примитивное управление группами и каналами, приглашениями, ролями и обязательным каналом добавлено отдельным этапом: [контракт групп](groups.md). PresenceStore остаётся локальным процессу; для нескольких экземпляров понадобится общая инфраструктура SignalR/presence. Старые журналы с чувствительными SQL-параметрами и уже выданные права нужно оценивать отдельно от этих изменений.
Страницы сгруппированы под началом работы, аутентификацией, E2EE, HTTP API, SignalR и развёртыванием. ID существующих страниц сохранены, внутренние ссылки GitBook используют стабильные ID. Публичные пути перемещённых страниц изменились. Автоматические site redirects недоступны на текущем тарифе; внешние закладки/ссылки на старые пути нужно обновить либо настроить redirects после подключения подходящего тарифа.
+22
View File
@@ -0,0 +1,22 @@
# SignalR — команды и события
SignalR дополняет HTTP: команды меняют состояние, события уведомляют подключённые клиенты, HTTP восстанавливает снимок. Для подключения используйте официальный SignalR-клиент с Bearer access token, а не произвольный WebSocket JSON.
| Хаб | Контракт |
| --- | --- |
| `/hubs/chats` | [Сообщения, прочтение, реакции и сообщества](chathub.md) |
| `/hubs/friends` | [Заявки и их результаты](../friendshub-zayavki.md) |
| `/hubs/presence` | [Online/offline](presencehub.md) |
| `/hubs/profiles` | [Описание и аватар](profilehub.md) |
Все подключения требуют действующей access-сессии. Общий фильтр повторяет проверку перед командой. ChatsHub/ProfileHub используют Authorize, FriendsHub/PresenceHub дополнительно задают User/Admin. Не передавайте refresh как access.
## Общие правила клиента
1. Зарегистрировать обработчики до StartAsync; access token возвращать через AccessTokenProvider.
2. Проверить HubResult.status после InvokeAsync, отдельно от состояния соединения.
3. Объединять повторные события и HTTP по ID, учитывать версии реакций.
4. После reconnect перечитать доступное HTTP-состояние и права.
5. При logout отменить повторные попытки, остановить и освободить соединения.
Automatic reconnect не заменяет собственную обработку первоначального StartAsync. События не имеют долговременной очереди и могут прийти в другом порядке при параллельных изменениях. Успех команды не гарантирует, что каждый клиент получил событие. [Путь интеграции](../client-integration.md) · [Пример C#](../klient-signalr-na-c-dlya-maui.md) · [Формат HubResult](../code-docs/hubresult-less-than-t-greater-than.md).
+4 -4
View File
@@ -1,6 +1,6 @@
# ChatsHub — сообщения
Подключение: `/hubs/chats`, Bearer access token и активная сессия. Команды возвращают `HubResult<T>` (status, result, errorMessage); события приходят независимо от ответа команды. Этот раздел описывает рабочую копию с исправлениями от 04.10.2026.
Подключение: `/hubs/chats`, Bearer access token и активная сессия. Команды возвращают `HubResult<T>` (status, result, errorMessage); события приходят независимо от ответа команды. Контракт сверяется с серверной ревизией, указанной в обзоре.
## Команды
@@ -24,7 +24,7 @@
}
```
RecipientType.User=0 означает личный чат: recipientId — PrivateChat.Id. Group=1 означает ChatGroup.Id. Вложение: `{ mediaId, encryptedKey }`. Содержимое или вложение обязательно; Send ограничивает текст 50 000 символами. SignalR не выполняет MVC DataAnnotations автоматически. DTO проверки дополняются сервисами доступа.
RecipientType.User=0 означает личный чат: recipientId — PrivateChat.Id. Group=1 означает ChatGroup.Id. Вложение: `{ mediaId, encryptedKey }`; для E2EE encryptedKey пустой, секрет находится внутри ciphertext. encryptedContent — подписанный конверт с префиксом govor.e2ee.v1:, максимум 1 000 000 символов; до 100 уникальных вложений. Даже сообщение только с файлом содержит E2EE-конверт. Транспортный лимит входящего SignalR-сообщения — 1 100 000 байт, поэтому учитывайте JSON-overhead. SignalR не выполняет MVC DataAnnotations автоматически. DTO проверки дополняются сервисами доступа.
Send/Read/React и чтение истории проверяют участие в конкретном чате. В группах заблокированный участник не имеет доступа. Reply и вложения не позволяют ссылаться на чужие закрытые чаты. Edit проверяет автора, доступ и временной лимит редактирования. Remove проверяет автора/права администратора группы; HideForMe пока не реализован и возвращает ошибку, ForceRemove удаляет сообщение.
@@ -45,7 +45,7 @@ Send/Read/React и чтение истории проверяют участие
| GroupProfileChanged | GroupProfileChangedResponse: `{ groupId }` |
| GroupMemberChanged | GroupMemberChangedResponse: `{ groupId, userId, status, role }` |
Опечатка MessageReaded сохранена для совместимости. При подключении сервер автоматически добавляет соединение в группу его сессии. События чата направляются активным сессиям участников; заблокированные участники групп исключаются. Не требуется вручную подписываться на SignalR-группу чата. Отзыв сессии прекращает её участие в маршрутизации и проверяется для команд; истечение токена закрывает соединение.
Опечатка MessageReaded сохранена для совместимости. При подключении сервер автоматически добавляет соединение в группу его сессии. События чата направляются активным сессиям участников; заблокированные участники групп исключаются. Не требуется вручную подписываться на SignalR-группу чата. Отзыв сессии прекращает её участие в маршрутизации и проверяется для команд; срок сессии повторно проверяется перед командой. Мгновенное закрытие соединения только по истечению access JWT не гарантируется конфигурацией; не полагайтесь на него как на механизм logout.
UserMessageResponse: messageId, senderId, recipientId, recipientType, encryptedContent, replyToMessageId, sentAt, isEdited, mediaAttachments. История через HTTP также содержит реакции и reactionsVersion. После получения сообщения загрузите снимок реакций при необходимости.
@@ -59,4 +59,4 @@ GroupProfileChanged сообщает об изменении имени, опи
Сохранение в БД и доставка события — разные этапы. После reconnect загрузите историю через HTTP; объединяйте ответ Send и ReceiveMessage по messageId. Для реакций принимайте более новую version и заменяйте counts целиком, затем восстанавливайте состояние видимых сообщений через GET.
SignalR-события не имеют долговременной очереди. Push сообщений использует серверную очередь и повторные попытки; для реакций, политик каналов и изменений сообществ push не отправляется. Реальный push требует корректной конфигурации Firebase и зарегистрированного FCM-токена активной сессии. Повтор Send после неоднозначного сетевого сбоя всё ещё может создать дубликат: clientMessageId/idempotency-key для сообщений не реализован.
SignalR-события не имеют долговременной очереди. Push сообщений использует серверную очередь и повторные попытки; для реакций, политик каналов и изменений сообществ push не отправляется. Реальный push требует корректной конфигурации Firebase и зарегистрированного FCM-токена активной сессии. Для E2EE messageId берётся из подписанного конверта. Повтор того же конверта с тем же автором, чатом, reply и набором вложений возвращает сохранённое сообщение; конфликт содержимого с тем же ID отклоняется. Повтор может повторить уведомления. Создание нового конверта/ID при каждой сетевой попытке всё ещё может породить дубликаты.
+2 -50
View File
@@ -1,51 +1,3 @@
---
description: >-
Description: SignalR hub for managing real-time friend request operations,
including sending, accepting, and rejecting friend requests.
icon: wifi
---
# FriendsHub
# FriendsHub — заявки
Подключение: /hubs/friends с access token, содержащим userId. Атрибут Authorize у класса отсутствует; HubUserAccessor читает claim и бросает исключение при его отсутствии. Это не следует считать полноценной endpoint-политикой авторизации: её нужно добавить явно.
## Команды
| Команда | Аргумент | Успех |
| ------------- | ----------------- | ----------------------- |
| SendRequest | Guid targetUserId | status 201, result null |
| AcceptRequest | Guid friendshipId | status 200, result null |
| RejectRequest | Guid friendshipId | status 200, result null |
SendRequest запрещает заявку себе и повтор при Pending/Accepted/Blocked. После Rejected запись переиспользуется. Accept разрешён только адресату и только Pending; после сохранения дружбы создаётся личный чат. Reject разрешён адресату для Pending/Rejected.
## Все события
| Событие | Кому |
| ------------------------- | --------------------------- |
| FriendRequestReceived | Адресату новой заявки |
| YourFriendRequestReceived | Отправителю |
| FriendRequestAccepted | Принимающему адресату |
| YourFriendRequestAccepted | Отправителю исходной заявки |
| FriendRequestRejected | Отклоняющему адресату |
| YourFriendRequestRejected | Отправителю исходной заявки |
Каждое событие передаёт **FriendshipDto**, не строку Guid:
```json
{"id":"11111111-1111-1111-1111-111111111111","requesterId":"22222222-2222-2222-2222-222222222222","addresseeId":"33333333-3333-3333-3333-333333333333","status":0}
```
Status: Pending=0, Accepted=1, Rejected=2, Blocked=3.
## Ошибки и восстановление
Сервисные Failure в SendRequest преобразуются в status 500; Accept/Reject — в 400. Поэтому не обещайте 409/403/404 для всех соответствующих бизнес-ошибок.
Дружба сохраняется до создания чата/рассылки; сбой может оставить частично завершённый сценарий. На reconnect перечитывайте /api/friends, /requests, /responses и /api/user/private-chats. Клиенту нужны дедупликация и обновление cache по id.
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/FriendsHub.cs).
Актуальный контракт: [FriendsHub — заявки](../../friendshub-zayavki.md).
@@ -1,67 +1,3 @@
---
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
# Клиент SignalR на C# для MAUI
Эта страница заменяет устаревший Java-пример: он принимал FriendshipDto как String и не соответствовал серверу. Ниже минимальный пример подключения C#; это пример интеграции, а не проверенный end-to-end тест.
Используйте Microsoft.AspNetCore.SignalR.Client и Govor.Contracts либо эквивалентные DTO с теми же полями.
```csharp
using Govor.Contracts.DTOs;
using Govor.Contracts.Responses.SignalR;
using Microsoft.AspNetCore.SignalR.Client;
var connection = new HubConnectionBuilder()
.WithUrl($"{baseUrl.TrimEnd('/')}/hubs/friends", options =>
{
options.AccessTokenProvider = async () =>
await jwtProvider.GetAccessTokenAsync();
})
.WithAutomaticReconnect()
.Build();
using var received = connection.On<FriendshipDto>(
"FriendRequestReceived", dto =>
{
MainThread.BeginInvokeOnMainThread(() => ApplyFriendship(dto));
});
using var accepted = connection.On<FriendshipDto>(
"YourFriendRequestAccepted", dto =>
{
MainThread.BeginInvokeOnMainThread(() => ApplyFriendship(dto));
});
await connection.StartAsync();
var response = await connection.InvokeAsync<HubResult<object>>(
"SendRequest", targetUserId);
if (response.Status != HubResultStatus.Created)
ShowError(response.ErrorMessage);
```
baseUrl, jwtProvider, ApplyFriendship, ShowError и targetUserId предоставляет приложение. Зарегистрируйте остальные четыре события аналогично с FriendshipDto. AcceptRequest/RejectRequest получают friendshipId.
## Жизненный цикл MAUI
1. Подпишитесь на события до подключения.
2. Первоначальный StartAsync требует собственной обработки повторов; automatic reconnect относится к потерянному соединению.
3. После Reconnected перечитайте HTTP-списки, чтобы восстановить пропущенные события.
4. Изменяйте ObservableCollection на MainThread.
5. Отменяйте повторные попытки при logout и DisposeAsync; не запускайте бесконечный StartAsync из Closed после намеренного StopAsync.
6. AccessTokenProvider должен получать актуальный access token; refresh должен быть сериализован.
В текущем Govor.Mobile ChatHub фильтрует ReceiveMessage по непустому encryptedContent, поэтому сообщение только с вложением может игнорироваться. Closed пытается перезапуститься даже после намеренного DisconnectAsync. JwtProviderService очищает токены при любом неуспешном HTTP-refresh, включая временную ошибку сервера: это следует исправить отдельно.
***
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/FriendsHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/FriendsHub.cs).
Актуальный пример: [C# для MAUI](../../klient-signalr-na-c-dlya-maui.md).
+2 -4
View File
@@ -17,11 +17,9 @@ OnlineUserStore хранится в памяти одного процесса.
PresenceHub не сохраняет lastSeen в БД при отключении. Для него есть отдельный HTTP ping; нужна единая политика обновления lastSeen.
Для первоначального экрана получайте доступные данные профиля/друзей; события только изменяют локальный cache. После reconnect перечитайте состояние. HTTP /api/online/status сейчас сломан из-за отсутствующих зависимостей.
Для первоначального экрана получайте доступные данные профиля/друзей; события только изменяют локальный cache. После reconnect перечитайте состояние. Для снимка используйте GET /api/online/status/{userId}: зависимости контроллера исправлены.
Обработчики должны быть зарегистрированы до StartAsync. Не используйте события присутствия как гарантированный журнал активности.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/PresenceHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/PresenceHub.cs).
Источник: [Govor.API/Hubs/PresenceHub.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Hubs/PresenceHub.cs).
+3 -5
View File
@@ -18,12 +18,10 @@
## Ограничения
Result от записи профиля не проверяется хабом, поэтому true не всегда подтверждает запись. Ошибка рассылки логируется, но не меняет успешный ответ.
Result от записи проверяется хабом; сервисная ошибка возвращается в HubResult без успешного события. Ошибка последующей рассылки логируется и не отменяет сохранение.
SetAvatar не проверяет владельца файла. REST UploadAvatar не отправляет AvatarUpdated. Политика приватности не применяется к этой рассылке. После reconnect перечитайте профиль; события не гарантированно сохраняются.
SetAvatar проверяет существование, а сервис — загрузчика и OwnerType.Avatar. Чужой файл отклоняется. REST UploadAvatar не отправляет AvatarUpdated. Политика приватности не применяется к этой рассылке. После reconnect перечитайте профиль; события не гарантированно сохраняются.
---
Проверено по исходникам на 03.10.2026, commit `4603be9`. Описано текущее поведение; сервер с БД и Firebase в рамках диагностики не запускался.
Источник: [Govor.API/Hubs/ProfileHub.cs](https://github.com/Govor-team/Govor/blob/4603be9f714135e0af72d505d17f3d1709834bea/Govor.API/Hubs/ProfileHub.cs).
Источник: [Govor.API/Hubs/ProfileHub.cs](https://github.com/stalcker2288969/Govor/blob/a3401ceedf30c2eb6167f7ef6e4ae820883d2de2/Govor.API/Hubs/ProfileHub.cs).
+52
View File
@@ -0,0 +1,52 @@
# Тестирование
## Серверный набор
Из корня репозитория:
```powershell
dotnet restore Govor.Server.slnx
dotnet build Govor.Server.slnx --no-restore -c Release
dotnet test Govor.Server.slnx --no-build --no-restore -c Release --logger trx --results-directory artifacts/test-results
```
По умолчанию каждый тест создаёт изолированную SQLite in-memory БД. HTTP/SignalR тесты поднимают приложение внутри тестового хоста; Firebase и хранилище подменяются. Production-БД, реальные push credentials и пользовательские файлы не нужны.
| Проект | Область |
| --- | --- |
| `tests/Govor.Domain.Tests` | Ограничения БД и миграции |
| `tests/Govor.Application.Tests` | Прикладные сервисы, права, токены, хранение, валидация |
| `tests/Govor.API.Tests` | Контроллеры, хабы, фильтры и транспортные границы |
| `tests/Govor.Server.Tests` | HTTP/JWT, SignalR, E2EE, восстановление, push и группы |
На Windows криптографические тесты требуют обычного профиля Windows CNG. Ограниченная sandbox-учётная запись может дать ошибку импорта PKCS#8; это не следует устранять изменением криптографического протокола.
## PostgreSQL
Используйте отдельную БД с именем, заканчивающимся `_tests`, и пользователя с правом создания/удаления схем. **Не указывайте рабочую БД.**
```powershell
$env:TEST_POSTGRES_CONNECTION = 'Host=localhost;Port=5432;Database=govor_tests;Username=govor;Password=YOUR_TEST_PASSWORD'
dotnet test Govor.Server.slnx -c Release
Remove-Item Env:TEST_POSTGRES_CONNECTION
```
Каждый тест использует отдельную схему и применяет миграции; соединения без пула защищают лимит PostgreSQL. CI запускает SQLite и PostgreSQL; состав job задан в `.github/workflows/dotnet.yml`.
## Проверенная ревизия
30.10.2026 на `a3401ce` прошли **735 тестов** Release на SQLite: Domain — 8, Application — 296, API — 271, Server — 160; ошибок и пропусков нет. Запуск выполнялся до fast-forward слияния, которое сохранило тот же коммит. В этой проверке PostgreSQL, настоящий Firebase, контейнер и UI устройств не запускались.
Сборка выдала предупреждения компилятора и NuGet, включая известные уязвимости `SixLabors.ImageSharp 3.1.12`. Успешные тесты не означают отсутствие этих проблем.
## Покрытие
```powershell
dotnet test Govor.Server.slnx --no-build --no-restore -c Release --collect 'XPlat Code Coverage;Format=json,cobertura' --results-directory artifacts/coverage
./tests/Measure-ApplicationCoverage.ps1 -ResultsDirectory artifacts/coverage
./tests/Measure-ApplicationCoverage.ps1 -ResultsDirectory artifacts/coverage -AssemblyName Govor.API -ExcludeGeneratedSources -MinimumLineCoverage 98 -MinimumBranchCoverage 92
```
CI проверяет пороги 98% строк и 92% ветвей для Application и исходников API. Проценты из разных проектов нельзя складывать: они покрывают пересекающиеся сборки. Отчёты от 24.10.2026 в `tests/APPLICATION-COVERAGE.md` и `tests/API-COVERAGE.md` — исторические измерения; после добавления тестов восстановления они не пересчитывались в текущем запуске.
Перед релизом дополнительно проверьте HTTPS/WSS, доставку на физические устройства, восстановление архива на чистом устройстве, старые вложения после деплоя и восстановление резервной копии. [Порядок обновления](operations.md).
+4 -4
View File
@@ -166,7 +166,7 @@ SignalR. Чтобы проверить сохранность, запишите
восстановления БД. Старые образы и каталоги релизов автоматически не очищаются.
Официальные инструкции:
- https://docs.docker.com/engine/install/ubuntu/
- https://docs.docker.com/engine/storage/bind-mounts/
- https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images
- https://caddyserver.com/docs/quick-starts/reverse-proxy
- [Установка Docker Engine](https://docs.docker.com/engine/install/ubuntu/)
- [Постоянные bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)
- [Публикация образов GitHub Actions](https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images)
- [Reverse proxy Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy)