Добавить user_settings и синхронизацию настроек

2026-08-19 19:45:09 +04:00
parent fac166f186
commit 6a5c20a165
37 changed files with 2079 additions and 3 deletions
@@ -51,6 +51,9 @@
 | `UpsertUserParam` | `10_User_Params_API.md` | запись параметра пользователя |
 | `GetUserParam` | `10_User_Params_API.md` | чтение одного параметра пользователя |
 | `ListUserParams` | `10_User_Params_API.md` | список параметров пользователя |
+| `UpsertUserSetting` | `13_User_Settings_API.md` | запись пользовательской настройки |
+| `GetUserSetting` | `13_User_Settings_API.md` | чтение одной пользовательской настройки |
+| `ListUserSettings` | `13_User_Settings_API.md` | список пользовательских настроек |
 | `GetFriendsLists` | `11_Connections_API.md` | входящие/исходящие друзья |
 | `ListContacts` | `11_Connections_API.md` | контакты текущего пользователя |
 | `GetUserConnectionsGraph` | `11_Connections_API.md` | граф связей пользователя |
@@ -63,6 +66,8 @@
 | `DeleteMessage` | `12_Direct_Messages_Push_Calls_API.md` | tombstone одного личного сообщения у обеих сторон |
 | `DeleteConversation` | `12_Direct_Messages_Push_Calls_API.md` | tombstone удаления истории переписки |
 | `DmSyncBatch` | `12_Direct_Messages_Push_Calls_API.md` | межсерверная догоняющая синхронизация DM по курсору |
+| `UserSettingsSyncBatch` | `13_User_Settings_API.md` | межсерверная догоняющая синхронизация пользовательских настроек по курсору |
+| `MarkAllUserSettingsUnsynced` | `13_User_Settings_API.md` | служебная пометка всех настроек как несинхронизированных |
 | `GetDirectMessages` | `12_Direct_Messages_Push_Calls_API.md` | постраничная загрузка истории личного диалога |
 | `AckSessionDelivery` | `12_Direct_Messages_Push_Calls_API.md` | подтверждение доставки в сессию |
 | `CallInviteBroadcast` | `12_Direct_Messages_Push_Calls_API.md` | broadcast приглашения к звонку |
@@ -0,0 +1,98 @@
+# API пользовательских настроек
+
+Этот раздел описывает `user_settings` - отдельное хранилище пользовательских настроек, не связанное с `users_params` и не связанное с legacy DM-таблицами.
+
+## 1. Назначение
+
+`user_settings` хранит технические пользовательские настройки, которые должны синхронизироваться между максимум двумя access/sync-серверами пользователя.
+
+Основной текущий кейс:
+
+- `setting_type = 1` - курсор прочитанности канала;
+- `setting_key = ownerBlockchainName/channelName`;
+- `value_num = number of messages already seen in channel`;
+- `value_text = ''`.
+
+Если настройки нет, канал считается просмотренным до конца, то есть unread = `0`.
+
+## 2. Структура записи
+
+- `login` - логин владельца настройки;
+- `setting_type` - числовой код типа настройки;
+- `setting_key` - строковый ключ настройки;
+- `time_ms` - время установки значения в миллисекундах;
+- `value_text` - строковое значение;
+- `value_num` - числовое значение;
+- `client_key` - публичный Ed25519 ключ клиента в Base64;
+- `signature` - Ed25519 подпись preimage в Base64;
+- `synced` - была ли настройка успешно доставлена на второй сервер.
+
+Уникальность: `(login, setting_type, setting_key)`.
+Обновление: только если `time_ms` новее текущего значения.
+
+## 3. Формат подписи
+
+Подписывается строка:
+
+`SHiNe/UserSettings:|login|setting_type|setting_key|time_ms|value_text|value_num`
+
+Где внутри полей используется экранирование `\` и `|`.
+
+Подпись создаётся клиентским `client_key`.
+
+## 4. Операции
+
+### `UpsertUserSetting`
+
+Записывает или обновляет настройку пользователя.
+
+Если запрос пришёл от клиента, сервер:
+
+- сохраняет запись локально;
+- пытается сразу отправить её на доступный sync-сервер;
+- если отправка успешна, помечает запись как `synced=true`;
+- если нет, оставляет `synced=false`.
+
+Если запрос пришёл по синхронизации между серверами, используется `sync_delivery=true`, и повторной пересылки дальше не делается.
+
+### `GetUserSetting`
+
+Чтение одной настройки по `(login, setting_type, setting_key)`.
+
+### `ListUserSettings`
+
+Список всех настроек пользователя.
+
+### `UserSettingsSyncBatch`
+
+Внутренний межсерверный batch-эндпоинт.
+
+- отдаёт настройки, новые относительно курсора;
+- используется для bootstrap и догрузки после восстановления;
+- применяется только для пользователей, чей сервер есть в `access_servers`.
+
+### `MarkAllUserSettingsUnsynced`
+
+Внутренний служебный запрос.
+
+- помечает все настройки пользователя или все настройки сразу как `synced=false`;
+- нужен после добавления нового sync-сервера или при потере локальной БД.
+
+## 5. Синхронизация
+
+Синхронизация настроек работает отдельно от DM.
+
+- локальная запись создаётся с `synced=false`, если её ещё не подтвердил второй сервер;
+- если запись пришла с другого сервера, она сохраняется сразу как `synced=true`;
+- периодический sync раз в 6 часов проверяет несинхронизированные записи и догружает новые записи по курсору;
+- если появляется новый sync-сервер или локальная БД была потеряна, нужно пометить все настройки несинхронизированными и заново догрузить batch с нуля.
+
+## 6. Текущий UI-кейс
+
+UI при открытии канала отправляет `UpsertUserSetting` с:
+
+- `setting_type = 1`;
+- `setting_key = ownerBlockchainName/channelName`;
+- `value_num = количество уже просмотренных сообщений в канале`.
+
+Это значение используется сервером для расчёта unread в списке каналов и в канале.
@@ -19,6 +19,10 @@
 Каждый сервер регистрирует в своей Solana PDA список `sync_servers` —
 логины SHiNE-аккаунтов партнёрских серверов, с которыми он синхронизируется.

+Важно: в текущей архитектуре у пользователя одновременно может быть не более
+двух sync/access-серверов. Это ограничение считается обязательным для runtime-логики
+`synced` и пользовательских курсоров.
+
 - Список хранится в блоке `ServerProfileBlock` внутри `user_pda` сервера.
 - Адрес каждого партнёрского сервера читается из его PDA на Solana.
 - Синхронизация двусторонняя: оба сервера должны иметь друг друга в `sync_servers`.
@@ -39,6 +43,13 @@
 - Порядок блоков сохраняется (по глобальному номеру блока и хэшу).
 - Дедупликация по глобальному номеру блока и хэшу.

+### 3.3 Пользовательские настройки
+
+- Отдельная таблица `user_settings`.
+- Синхронизируются технические настройки пользователя, включая курсор прочитанности каналов.
+- Для текущего UI-кейса хранится `setting_type = 1` и `setting_key = ownerBlockchainName/channelName`.
+- Синхронизация идёт с учётом `time_ms` и флага `synced`.
+
 ## 4. Текущая реализованная схема

 На текущем этапе сервер уже умеет базовую межсерверную синхронизацию пользовательских блокчейнов.