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

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

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

- `AddUser` — операция отключена (регистрация только через Solana);
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
- `SearchUsers` — dev/test поиск логинов по префиксу.

Регистрация выполняется через Solana (`shine_users`). Сервер при входе может лениво импортировать пользователя из Solana PDA в локальную БД, если записи ещё нет.

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

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

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

---

## 1. Операция `AddUser`

### Назначение

Операция отключена. Используется только как явный ответ клиентам старых версий.

### Запрос

```json
{
  "op": "AddUser",
  "requestId": "reg-001",
  "payload": {
    "login": "anya",
    "blockchainName": "anya-001",
    "solanaKey": "BASE64_32_PUBLIC_KEY",
    "blockchainKey": "BASE64_32_PUBLIC_KEY",
    "clientKey": "BASE64_32_PUBLIC_KEY",
    "bchLimit": 1000000
  }
}
```

### Пример ответа

```json
{
  "op": "AddUser",
  "requestId": "reg-001",
  "status": 410,
  "ok": false,
  "error": "ADD_USER_DISABLED",
  "message": "Серверная регистрация AddUser отключена. Используйте регистрацию через Solana.",
  "payload": {
  }
}
```

### Специфические коды ошибок `AddUser`

- `410 / ADD_USER_DISABLED` — серверная регистрация отключена, используйте Solana-first flow.

---

## 2. Операция `GetUser`

### Назначение

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

Важно:

- это server-side existence-check;
- если пользователя нет в локальной БД, он может быть импортирован при авторизации из Solana PDA.

### Запрос

```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
  }
}
```

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

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

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

```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` — непредвиденная внутренняя ошибка сервера.

---

## 3. Операция `SearchUsers`

### Назначение

Поиск пользователей по префиксу логина. Операция зарегистрирована в серверном API и используется как вспомогательная dev/test операция.

### Запрос

```json
{
  "op": "SearchUsers",
  "requestId": "search-001",
  "payload": {
    "prefix": "an"
  }
}
```

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

```json
{
  "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. Короткое резюме

- `AddUser` — отключен (`410 / ADD_USER_DISABLED`).
- `GetUser` — проверка существования пользователя на сервере.
- `SearchUsers` — временный поиск пользователей по префиксу.
- Регистрация выполняется только через Solana.