SHiNE-server/Dev_Docs/API/14_Test_Free_Avatar_Upload_API.md

Временное Test API для бесплатной загрузки аватаров в Arweave

Статус: временное тестовое решение. Все операции из этого файла начинаются с Test..., чтобы это было видно сразу и в коде, и в UI.

Назначение

Этот временный API даёт пользователю ограниченную бесплатную загрузку маленьких аватаров в Arweave:

• загрузка идёт через серверный Arweave-кошелёк;
• лимит на пользователя: по умолчанию 3 загрузки за всё время;
• лимит хранится в SQLite-таблице test_free_avatar_uploads;
• если лимит исчерпан, сервер возвращает понятную ошибку;
• загружать можно только маленький итоговый файл аватара, по умолчанию до 128 KB.

Настройки сервера

В application.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

Возвращает остаток бесплатных загрузок для текущего авторизованного пользователя.

Запрос

{
  "op": "TestGetFreeAvatarQuota",
  "requestId": "req-test-avatar-quota-1",
  "payload": {}
}

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

{
  "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 байт итогового подготовленного файла.

{
  "op": "TestUploadFreeAvatar",
  "requestId": "req-test-avatar-upload-1",
  "payload": {
    "contentType": "image/webp",
    "fileBytesBase64": "UklGRiQAAABXRUJQVlA4WAoAAAAQAAAA...",
    "sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

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

{
  "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...;
• сценарий нужен как переходный бесплатный путь для маленьких аватаров.