Перенести документацию в docs и добавить социальный граф

2026-07-13 12:58:41 +04:00
parent c9cfb394d7
commit af12d7b954
91 changed files with 653 additions and 2 deletions
@@ -0,0 +1,201 @@
+# 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;
+- если пользователя нет в локальной БД, сервер сразу пытается 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
+  }
+}
+```
+
+Дополнительные серверные поля в `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.