Перенести документацию в 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,176 @@
+# Временное Test API для бесплатной загрузки аватаров в Arweave
+
+> Статус: **временное тестовое решение**.
+> Все операции из этого файла начинаются с `Test...`, чтобы это было видно сразу и в коде, и в UI.
+
+## Назначение
+
+Этот временный API даёт пользователю ограниченную бесплатную загрузку маленьких аватаров в Arweave:
+
+- загрузка идёт через **серверный Arweave-кошелёк**;
+- лимит на пользователя: по умолчанию `3` загрузки за всё время;
+- лимит хранится в SQLite-таблице `test_free_avatar_uploads`;
+- если лимит исчерпан, сервер возвращает понятную ошибку;
+- загружать можно только маленький итоговый файл аватара, по умолчанию до `128 KB`.
+
+## Настройки сервера
+
+В `application.properties`:
+
+```properties
+test.freeAvatar.enabled=true
+test.freeAvatar.gateway=https://arweave.net
+test.freeAvatar.limitPerUser=3
+test.freeAvatar.maxBytes=131072
+test.freeAvatar.walletAddress=
+test.freeAvatar.walletJwkPath=
+```
+
+Пояснения:
+
+- `test.freeAvatar.enabled` - включить или выключить временный API;
+- `test.freeAvatar.gateway` - Arweave gateway для `price/tx/wallet`;
+- `test.freeAvatar.limitPerUser` - пожизненный бесплатный лимит на пользователя;
+- `test.freeAvatar.maxBytes` - максимальный размер итогового файла;
+- `test.freeAvatar.walletAddress` - публичный адрес серверного Arweave-кошелька;
+- `test.freeAvatar.walletJwkPath` - путь к приватному JWK-файлу серверного кошелька.
+
+Важно:
+
+- приватный JWK хранится вне кода;
+- если `walletAddress` указан и не совпадает с адресом, вычисленным из JWK, сервер вернёт ошибку настройки.
+
+## `TestGetFreeAvatarQuota`
+
+Возвращает остаток бесплатных загрузок для текущего авторизованного пользователя.
+
+### Запрос
+
+```json
+{
+  "op": "TestGetFreeAvatarQuota",
+  "requestId": "req-test-avatar-quota-1",
+  "payload": {}
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "TestGetFreeAvatarQuota",
+  "requestId": "req-test-avatar-quota-1",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "enabled": true,
+    "limit": 3,
+    "usedCount": 1,
+    "remainingCount": 2,
+    "maxBytes": 131072
+  }
+}
+```
+
+### Поля ответа
+
+- `enabled` - временный API сейчас включён на сервере или нет;
+- `limit` - полный лимит бесплатных загрузок;
+- `usedCount` - сколько уже израсходовано;
+- `remainingCount` - сколько ещё осталось;
+- `maxBytes` - максимальный размер итогового файла.
+
+### Ошибки
+
+- `422 NOT_AUTHENTICATED` - требуется авторизация.
+
+## `TestUploadFreeAvatar`
+
+Временная бесплатная загрузка маленькой аватарки в Arweave через серверный кошелёк.
+
+### Правила
+
+- операция требует авторизованную сессию;
+- сервер использует текущий login из сессии;
+- сервер принимает только:
+  - `image/jpeg`
+  - `image/png`
+  - `image/webp`
+- размер итогового файла должен быть не больше `maxBytes` из квоты;
+- если пользователь уже сделал `limit` бесплатных загрузок, операция запрещена.
+
+### Запрос
+
+`fileBytesBase64` - это обычный Base64 байт итогового подготовленного файла.
+
+```json
+{
+  "op": "TestUploadFreeAvatar",
+  "requestId": "req-test-avatar-upload-1",
+  "payload": {
+    "contentType": "image/webp",
+    "fileBytesBase64": "UklGRiQAAABXRUJQVlA4WAoAAAAQAAAA...",
+    "sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+```
+
+### Успешный ответ
+
+```json
+{
+  "op": "TestUploadFreeAvatar",
+  "requestId": "req-test-avatar-upload-1",
+  "status": 200,
+  "ok": true,
+  "payload": {
+    "txId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+    "sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "usedCount": 2,
+    "remainingCount": 1,
+    "limit": 3,
+    "gateway": "https://arweave.net"
+  }
+}
+```
+
+### Поля ответа
+
+- `txId` - Arweave Transaction ID загруженного файла;
+- `sha256Hex` - SHA-256 загруженного файла;
+- `usedCount` - сколько бесплатных загрузок уже израсходовано после этой операции;
+- `remainingCount` - сколько бесплатных загрузок осталось;
+- `limit` - общий лимит;
+- `gateway` - gateway, через который сервер отправлял транзакцию.
+
+### Ошибки
+
+- `422 NOT_AUTHENTICATED` - требуется авторизация;
+- `400 BAD_FIELDS` - не переданы `contentType` или `fileBytesBase64`;
+- `400 BAD_BASE64` - `fileBytesBase64` не декодируется;
+- `400 BAD_AVATAR_FILE` - файл не проходит ограничения сервера;
+- `400 FREE_AVATAR_LIMIT_EXHAUSTED` - бесплатный лимит аватарок исчерпан;
+- `501 FREE_AVATAR_TEMP_DISABLED` - временная функция выключена или сервер не настроен;
+- `500 INTERNAL_ERROR` - внутренняя ошибка сервера.
+
+## Как это используется в UI
+
+На экране редактирования профиля в мастере смены аватара есть временный сценарий:
+
+- `Залить аватар бесплатно`
+
+UI:
+
+1. вызывает `TestGetFreeAvatarQuota`;
+2. показывает остаток лимита;
+3. локально подготавливает уменьшенный файл аватара;
+4. проверяет, что итоговый файл не превышает `maxBytes`;
+5. вызывает `TestUploadFreeAvatar`;
+6. после получения `txId` обычным путём записывает `avatar.ar` в профиль через `AddBlock`.
+
+## Почему решение временное
+
+- используется общий серверный Arweave-кошелёк;
+- лимит хранится отдельной технической таблицей;
+- операции имеют префикс `Test...`;
+- сценарий нужен как переходный бесплатный путь для маленьких аватаров.