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

2026-08-19 19:45:09 +04:00
parent fac166f186
commit 6a5c20a165
37 changed files with 2079 additions and 3 deletions
@@ -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 в списке каналов и в канале.