Files
Govor/docs/client-integration.md
Artemy 632ac04b56 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.
2026-10-31 18:29:40 +07:00

52 lines
6.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Путь интеграции клиента
Этот сценарий соединяет отдельные справочные страницы в рабочую последовательность. Используйте базовый 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), очистите её токены по политике приложения. Не удаляйте единственную копию ключей истории без подтверждённого архива/кода. На новом устройстве проверьте восстановление до отказа от старого.