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

6.6 KiB
Raw Permalink Blame History

Путь интеграции клиента

Этот сценарий соединяет отдельные справочные страницы в рабочую последовательность. Используйте базовый HTTPS-адрес сервера без /api на конце.

1. Войти и подготовить устройство

  1. Проверьте /server/ping; при необходимости /server/ready.
  2. Зарегистрируйтесь по приглашению или выполните SRP-вход, проверьте серверное доказательство.
  3. Сохраните токены в защищённом хранилище. Организуйте один общий последовательный refresh.
  4. Загрузите свой профиль /api/profile/download/me. ID пользователя отличается от sid JWT.
  5. Восстановите архив истории по паролю/резервному коду либо создайте первый архив. Зарегистрируйте публичные ключи текущей сессии через E2EE API. Секреты храните раздельно по серверу и аккаунту.

Повторный вход создаёт новую сессию. Один только access token не позволяет расшифровать историю. Не перезаписывайте локальные ключи при временной ошибке сети или конфликте ревизии архива.

2. Загрузить состояние и подключить события

Прочитайте друзей, входящие/исходящие заявки, личные чаты и /api/groups/mine. Подпишитесь на события до запуска нужных хабов:

Хаб Для чего
/hubs/chats Сообщения, прочтение, реакции, изменения групп
/hubs/friends Заявки и их результаты
/hubs/presence Online/offline
/hubs/profiles Изменение описания и аватара

SignalR использует протокол SignalR, а не произвольный JSON WebSocket. Для C# — пример клиента. AccessTokenProvider возвращает действующий access token. Первоначальный StartAsync требует собственной обработки сбоев; automatic reconnect применяется к потере уже установленного соединения.

Между HTTP-снимком и подпиской возможна гонка. Подключите события, загрузите состояние повторно при необходимости и объединяйте по ID, не добавляйте записи вслепую.

3. Открыть чат и отправить сообщение

  1. Для собеседника получите GET /api/user/{friendId}/private-chat. Ответ — GUID чата. Для группы используйте её groupId.
  2. Загрузите историю. Для пагинации используйте ID якоря, удаляя дубли из-за включения самого якоря.
  3. Получите актуальный каталог E2EE участников/устройств. Для файлов сначала зашифруйте содержимое и загрузите медиа.
  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. Прочтение, редактирование и восстановление

Прочтение отправляйте, когда пользователь действительно увидел сообщения. Push/получение по сети не равно прочтению. Для редактирования сформируйте новый подписанный конверт с прежним messageId и признаком edit; соблюдайте окно редактирования.

После reconnect перечитайте историю, счётчики, реакции видимых сообщений, группы/права, заявки и открытые профили. HTTP определяет актуальное состояние. Не считайте порядок событий порядком транзакций. При 403 обновите права; при 409 обновите соответствующую ревизию/каталог; при 401 проверьте refresh/вход.

FCM-токен регистрируется для текущей сессии отдельно. Push может повторяться и не заменяет загрузку истории.

5. Выход

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