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

182 lines
7.6 KiB
Markdown
Raw 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.
# 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.
### Запрос
```json
{
"op": "GetUser",
"requestId": "user-001",
"payload": {
"login": "anya"
}
}
```
### Успешный ответ: пользователь существует
```json
{
"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,
"ownedPublicChannelsCount": 3,
"followingUsersCount": 18,
"followingChannelsCount": 27,
"closeFriendsCount": 4
}
}
```
Дополнительные серверные поля в `GetUser`:
- `serverLastGlobalNumber` — номер последнего блока в пользовательском блокчейне на сервере;
- `serverLastGlobalHash` — hash последнего блока (hex-строка 64 символа);
- `serverBlockchainSizeBytes` — текущий размер пользовательского блокчейна на сервере в байтах;
- `serverBlockchainSizeLimitBytes` — текущий лимит размера блокчейна на сервере в байтах;
- `ownedPublicChannelsCount` — количество публичных каналов, владельцем которых является пользователь;
- `followingUsersCount` — количество пользователей, на которых подписан пользователь;
- `followingChannelsCount` — количество публичных каналов, на которые подписан пользователь;
- `closeFriendsCount` — количество близких друзей пользователя.
### Успешный ответ: пользователя нет
```json
{
"op": "GetUser",
"requestId": "user-001",
"status": 200,
"ok": true,
"payload": {
"exists": false
}
}
```
### Пример ошибки
```json
{
"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`
### Назначение
Поиск пользователей по префиксу логина и фрагменту публичного имени (`first_name`, `last_name`) без учёта регистра и с нормализацией `ё/е`. Совместимый ответ — массив строк `logins`.
При необходимости можно включить фильтр только по server PDA.
### Запрос
```json
{
"op": "SearchUsers",
"requestId": "search-001",
"payload": {
"prefix": "an",
"isServer": true,
"limit": 10
}
}
```
- `prefix` — обязательный поисковый фрагмент (до 120 символов); логины ищутся по началу, публичные имена — по подстроке.
- `limit` — необязательное число результатов 1–50, по умолчанию **5** (совместимость с клиентами).
- `isServer` — необязательный boolean-флаг; если `true`, сервер вернёт только логины,
у которых в `solana_user_pda_current` стоит `is_server = true`.
### Успешный ответ
```json
{
"op": "SearchUsers",
"requestId": "search-001",
"status": 200,
"ok": true,
"payload": {
"logins": ["anya", "andrey"],
"users": [
{ "login": "anya", "displayName": "Анна", "avatarAr": "" },
{ "login": "andrey", "displayName": "Андрей", "avatarAr": "" }
]
}
}
```
### Специфические коды ошибок `SearchUsers`
- `400 / BAD_FIELDS` — некорректный или пустой `prefix`.
- `501 / DB_ERROR` — ошибка БД при поиске.
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
---
## 4. Короткое резюме
- `GetUser` — проверка существования пользователя на сервере.
- `SearchUsers` — временный поиск пользователей по префиксу.
- Регистрация выполняется только через Solana.
## Регистрация V2: полные логины и независимые проверки
Публичные WS-операции нового протокола перечислены в `docs/registration-v2/WS_REGISTRATION_V2_PROPOSED_NOT_ENABLED.md`.
Сначала `GetNamespaces` → `CheckRegistrationLogin` с полным `login@namespace`; затем **только для бесплатной регистрации** отдельное `CheckRegistrationEmail`. После проверки запускается `StartFreeRegistration`, затем `ConfirmFreeRegistration` с тестовым кодом `1111`. Состояние читается через `GetRegistrationStatus`.
Все бесплатные сертификаты подписаны ANS-104 и внутренней подписью Ed25519; успешный Turbo ACK не означает подтверждённую высоту Arweave. Клиент никогда не отправляет пароль или приватные ключи на сервер.