Перенести документацию в 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,129 @@
+# API для разработчиков: параметры пользователя
+
+Документ описывает операции для записи и чтения пользовательских параметров.
+
+Текущие операции:
+
+- `UpsertUserParam`
+- `GetUserParam`
+- `ListUserParams`
+
+## 1. `UpsertUserParam`
+
+### Запрос
+
+```json
+{
+  "op": "UpsertUserParam",
+  "requestId": "param-upsert-001",
+  "payload": {
+    "login": "alice",
+    "param": "display_name",
+    "time_ms": 1774700000123,
+    "value": "Alice",
+    "client_key": "BASE64_DEVICE_PUBLIC_KEY",
+    "signature": "BASE64_SIGNATURE"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "UpsertUserParam",
+  "requestId": "param-upsert-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+  }
+}
+```
+
+### Типовые ошибки
+
+- `400 / BAD_FIELDS` — некорректные обязательные поля.
+- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
+- `501 / DB_ERROR` — ошибка БД.
+
+---
+
+## 2. `GetUserParam`
+
+### Запрос
+
+```json
+{
+  "op": "GetUserParam",
+  "requestId": "param-get-001",
+  "payload": {
+    "login": "alice",
+    "param": "display_name"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "GetUserParam",
+  "requestId": "param-get-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "login": "alice",
+    "param": "display_name",
+    "time_ms": 1774700000123,
+    "value": "Alice",
+    "client_key": "BASE64_DEVICE_PUBLIC_KEY",
+    "signature": "BASE64_SIGNATURE"
+  }
+}
+```
+
+Если параметр не найден, сервер возвращает `404` с пустым `payload`; отдельный прикладной код ошибки текущий handler не задаёт.
+
+---
+
+## 3. `ListUserParams`
+
+### Запрос
+
+```json
+{
+  "op": "ListUserParams",
+  "requestId": "param-list-001",
+  "payload": {
+    "login": "alice"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "ListUserParams",
+  "requestId": "param-list-001",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "login": "alice",
+    "params": [
+      {
+        "login": "alice",
+        "param": "display_name",
+        "time_ms": 1774700000123,
+        "value": "Alice",
+        "client_key": "BASE64_DEVICE_PUBLIC_KEY",
+        "signature": "BASE64_SIGNATURE"
+      }
+    ]
+  }
+}
+```
+
+## Примечание
+
+Имена JSON-полей `time_ms` и `client_key` сейчас соответствуют Java-модели ответа/запроса и должны передаваться именно в таком виде.