SHiNE-server/docs/API/01_User_Registration_API.md

API для разработчиков: Регистрация пользователя

Этот файл описывает раздел API, связанный с проверкой наличия пользователя на сервере и dev/test операциями.

Сейчас здесь два метода:

• GetUser — временная серверная проверка существования пользователя и чтение его базовых данных;
• SearchUsers — dev/test поиск логинов по префиксу, при необходимости с фильтром только по server PDA.

Регистрация выполняется только через Solana.

Статус документа

Это временная глава API.

Текущая регистрация пользователя и текущая проверка, существует пользователь или нет, пока реализованы как серверные dev/test операции. В будущем и регистрация, и проверка identity должны идти напрямую через Solana.

1. Операция GetUser

Назначение

Временная серверная проверка, существует пользователь или нет.

Важно:

• это server-side existence-check;
• если пользователя нет в локальной БД, сервер сразу пытается lazy-import из Solana PDA;
• поэтому GetUser можно использовать как актуальный способ получить clientKey и базовые поля пользователя перед E2EE DM.

Запрос

{
  "op": "GetUser",
  "requestId": "user-001",
  "payload": {
    "login": "anya"
  }
}

Успешный ответ: пользователь существует

{
  "op": "GetUser",
  "requestId": "user-001",
  "status": 200,
  "ok": true,
  "payload": {
    "exists": true,
    "login": "Anya",
    "blockchainName": "anya-001",
    "solanaKey": "BASE64_32_PUBLIC_KEY",
    "blockchainKey": "BASE64_32_PUBLIC_KEY",
    "clientKey": "BASE64_32_PUBLIC_KEY",
    "serverLastGlobalNumber": 128,
    "serverLastGlobalHash": "4f...ab",
    "serverBlockchainSizeBytes": 45212,
    "serverBlockchainSizeLimitBytes": 100000
  }
}

Дополнительные серверные поля в GetUser:

• serverLastGlobalNumber — номер последнего блока в пользовательском блокчейне на сервере;
• serverLastGlobalHash — hash последнего блока (hex-строка 64 символа);
• serverBlockchainSizeBytes — текущий размер пользовательского блокчейна на сервере в байтах;
• serverBlockchainSizeLimitBytes — текущий лимит размера блокчейна на сервере в байтах;

Успешный ответ: пользователя нет

{
  "op": "GetUser",
  "requestId": "user-001",
  "status": 200,
  "ok": true,
  "payload": {
    "exists": false
  }
}

Пример ошибки

{
  "op": "GetUser",
  "requestId": "user-001",
  "status": 400,
  "ok": false,
  "error": "BAD_FIELDS",
  "message": "Некорректные поля: login",
  "payload": {
  }
}

Специфические коды ошибок GetUser

• 400 / BAD_FIELDS — не передан или пуст login.
• 501 / DB_ERROR — ошибка БД при поиске пользователя.
• 500 / INTERNAL_ERROR — непредвиденная внутренняя ошибка сервера.

---

2. Операция SearchUsers

Назначение

Поиск пользователей по префиксу логина. Операция зарегистрирована в серверном API и используется как вспомогательная dev/test операция. При необходимости можно включить фильтр только по server PDA.

Запрос

{
  "op": "SearchUsers",
  "requestId": "search-001",
  "payload": {
    "prefix": "an",
    "isServer": true
  }
}

• prefix — обязательный префикс логина.
• isServer — необязательный boolean-флаг; если true, сервер вернёт только логины, у которых в solana_user_pda_current стоит is_server = true.

Успешный ответ

{
  "op": "SearchUsers",
  "requestId": "search-001",
  "status": 200,
  "ok": true,
  "payload": {
    "logins": ["anya", "andrey"]
  }
}

Специфические коды ошибок SearchUsers

• 400 / BAD_FIELDS — некорректный или пустой prefix.
• 501 / DB_ERROR — ошибка БД при поиске.
• 500 / INTERNAL_ERROR — непредвиденная внутренняя ошибка сервера.

---

4. Короткое резюме

• GetUser — проверка существования пользователя на сервере.
• SearchUsers — временный поиск пользователей по префиксу.
• Регистрация выполняется только через Solana.