From 61f4c1e11506fa67f9f8b715d078b9ce5b6a385211e7ac9617f720ed22082b91 Mon Sep 17 00:00:00 2001
From: ai5590 <aidarkc@yandex.by>
Date: Sun, 5 Apr 2026 12:39:21 +0300
Subject: [PATCH] docs: clarify user params profile keys and sessionId format

---
 Dev_Docs/API/03_Session_Management_API.md     | 20 +++++++++++++++
 .../API/04_Add_Block_to_Blockchain_API.md     | 25 +++++++++++++++++++
 Dev_Docs/API/05_Technical_Requests_API.md     | 20 +++++++++++++++
 3 files changed, 65 insertions(+)

diff --git a/Dev_Docs/API/03_Session_Management_API.md b/Dev_Docs/API/03_Session_Management_API.md
index 2792637..ae98b9d 100644
--- a/Dev_Docs/API/03_Session_Management_API.md
+++ b/Dev_Docs/API/03_Session_Management_API.md
@@ -114,3 +114,23 @@
   }
 }
 ```
+
+
+## 4. Формат `sessionId`
+
+Текущее серверное значение `sessionId` генерируется как:
+
+- случайные **32 байта** (`SecureRandom`),
+- кодирование в **стандартный Base64 RFC 4648** (алфавит `A-Z a-z 0-9 + /`),
+- **без padding** `=`.
+
+Практически это строка длиной около **43 символов** (для 32 байт без `=`).
+
+Пример реального формата:
+
+```
+K9v3nQ4u8jYk0a2p7cD4mLx1zR0sT5wV6bN8eH3fQ1M
+```
+
+Важно: это **не человеко-читаемое имя**, а непрозрачный идентификатор.
+Нужно передавать его как есть, без нормализации регистра и без URL-экранирования внутри JSON.
diff --git a/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md b/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md
index 51d1b8f..3447eeb 100644
--- a/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md
+++ b/Dev_Docs/API/04_Add_Block_to_Blockchain_API.md
@@ -133,3 +133,28 @@
    - пересобрать следующий блок на актуальной вершине.
 3. Для edit-блоков всегда ссылаться на **оригинальный** блок, а не на предыдущий edit.
 4. Для связей/подписок использовать target на **root** (HEADER или CREATE_CHANNEL), а не на произвольный пост.
+
+
+## 8. USER_PARAM для «личных данных»
+
+Да, на текущем API это можно добавить **без изменения серверного кода**:
+
+- в `UserParam` поле `param` сейчас не ограничено фиксированным справочником;
+- сервер хранит пары `param -> value` как строки (при наличии корректной подписи и `time_ms`);
+- чтение уже есть через `GetUserParam` и `ListUserParams`.
+
+Рекомендуемый стартовый набор ключей для профиля (MVP):
+
+- `name`
+- `last_name`
+- `address_physical`
+- `address_web`
+- `phone`
+
+Практическая рекомендация: заранее зафиксировать единый словарь ключей в клиенте/документации, чтобы избежать дублей вида `lastname` vs `last_name`, `site` vs `address_web` и т.д.
+
+Ограничения, которые важно учесть:
+
+- сейчас нет серверной ACL-политики чтения параметров (в MVP их может читать любой клиент, который знает `login`);
+- нет валидации формата значений для конкретных ключей (телефон, URL и т.д. проверяются только на стороне клиента);
+- нет отдельного индекса/поиска по этим полям — только точечное чтение и listing по `login`.
diff --git a/Dev_Docs/API/05_Technical_Requests_API.md b/Dev_Docs/API/05_Technical_Requests_API.md
index b96f972..24d894a 100644
--- a/Dev_Docs/API/05_Technical_Requests_API.md
+++ b/Dev_Docs/API/05_Technical_Requests_API.md
@@ -135,3 +135,23 @@
 - `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
 - `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
 - Оба запроса доступны без авторизации.
+
+
+## 4. Прямое техническое сообщение в конкретную сессию
+
+На текущий момент в публичном JSON API этого документа **нет отдельного RPC** для отправки произвольного технического сообщения в конкретную сессию пользователя (по `sessionId`).
+
+Что уже есть в системе:
+
+- сервер хранит `sessionId` активной сессии;
+- есть `ListSessions`, чтобы клиент получил список sessionId своего пользователя;
+- у сервера есть внутренний реестр активных WS-подключений по `sessionId`.
+
+Чего не хватает для полноценной фичи «direct tech message by sessionId»:
+
+1. отдельная API-операция (например, `SendSessionTechMessage`);
+2. правило авторизации (кто имеет право писать в чужую/свою сессию);
+3. унифицированный формат payload и события доставки;
+4. коды ошибок (`SESSION_OFFLINE`, `SESSION_NOT_FOUND`, `FORBIDDEN` и т.п.).
+
+Итог: как инфраструктурная база это почти готово, но нужен отдельный RPC-слой и политика доступа.