SHiNE-server/docs/Blockchain/15_TEXT_Attachments.md

Вложения в TEXT-сообщениях (SHiNE:attach v=1/v=2)

Документ фиксирует текущий формат вложений в текстовых блоках SHiNE.

Область применения

Формат применяется к UTF-8 полю text в TEXT-блоках:

• TEXT_POST
• TEXT_REPLY
• TEXT_EDIT_POST
• TEXT_EDIT_REPLY

Бинарный формат TextBody не меняется. Вложения являются техническим префиксом внутри обычного текста.

Общий вид

Один attach-блок:

<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>

Блок с превью:

<SHiNE:attach;v=2;name=video.mp4;size=5820193;sha256=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;previewAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;previewSha256=eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee>

Несколько вложений идут подряд в самом начале текста:

<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa;ar=BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB>
<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc;ar=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD>
Текст сообщения

После последнего attach-блока идёт обычный пользовательский текст. Пользовательский текст может быть пустым, если есть хотя бы одно валидное вложение.

Клиент SHiNE ограничивает одно сообщение максимум 10 вложениями и сохраняет порядок attach-блоков в том порядке, в котором пользователь прикрепил файлы.

Поля

Обязательные поля:

• v=1 - версия формата attach-блока;
• name - имя файла, закодированное через encodeURIComponent;
• size - размер файла в байтах;
• sha256 - SHA-256 исходного файла в hex, 64 символа;
• ar - короткий Arweave Transaction ID, 43 символа, без gateway URL.

Дополнительные поля для v=2:

• previewAr - короткий Arweave Transaction ID файла-превью;
• previewSha256 - SHA-256 файла-превью в hex.

Хранение файла

Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки:

• имя файла;
• размер;
• SHA-256;
• Arweave txId.

Опционально для видео или больших изображений может храниться отдельный второй файл-превью. В таком случае основной attach-блок остаётся одним, но дополнительно указывает previewAr/previewSha256.

Создание вложения в UI

UI поддерживает три сценария:

• загрузить новый файл в Arweave выбранным Arweave-кошельком;
• ввести существующий txId, скачать файл через Arweave gateway и локально посчитать size/sha256;
• выбрать файл из журнала файлов, загруженных в текущей браузерной сессии.

Для видеофайлов UI может по желанию пользователя автоматически создать превью из первого кадра. Технически клиент загружает два файла:

• основной видеофайл;
• отдельное изображение-превью.

После успешной загрузки в журнале хранится один элемент основного файла, но с полями previewAr/previewSha256. В UI такой элемент помечается как файл С превью.

При ручном добавлении существующего txId для видео UI также позволяет вручную указать txId файла-превью.

Журнал хранится только в sessionStorage текущего браузера и не является частью блокчейна. В настройках клиента есть отдельный экран Загрузка файлов: пользователь может заранее загрузить файл в Arweave без создания сообщения, увидеть компактную плитку с именем, размером, временем загрузки, txId и статусом доступности через gateway, а затем выбрать этот файл из истории при создании сообщения. Если файл загружен заранее, но ещё не был отправлен ни в одном сообщении SHiNE, клиент показывает локальный флаг Не добавлен в SHiNE. Флаг снимается после успешной отправки сообщения с этим вложением. Если история очищена, уже созданные сообщения не меняются: в блокчейне остаются attach-блоки с txId.

Отображение

Новый клиент при чтении сообщения:

1. читает валидные attach-блоки только из начала текста;
2. скрывает технические attach-строки;
3. отображает вложения над пользовательским текстом;
4. показывает вложения горизонтальной каруселью: одно вложение на экране, переключение свайпом или стрелками, счётчик вида 1 из 3;
5. определяет тип вложения по расширению имени файла:
   • изображение показывает как ограниченное по размеру превью;
   • видео показывает как превью с кнопкой воспроизведения и открывает большой HTML5-плеер по нажатию;
   • обычный файл показывает как карточку с именем, расширением, размером и скачиванием;
6. если у видео есть previewAr/previewSha256, использует отдельный preview-файл как poster и как большую превью-плитку в журнале загрузок;
7. при перелистывании останавливает воспроизводящееся видео;
8. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.

Если файл по ссылке Arweave gateway недоступен, клиент показывает диагностический блок:

• если сообщение создано менее 20 минут назад: файл, скорее всего, ещё не распространился в Arweave, нужно повторить через несколько минут;
• если сообщение старше 20 минут: файл считается недоступным.

Старые клиенты без поддержки формата могут показывать attach-блоки как обычный текст.

Редактирование

При редактировании сообщения UI сохраняет существующие attach-блоки и меняет только пользовательский текст. Удаление сообщения по-прежнему выполняется через edit-блок с пустым текстом, как описано в 11_TEXT_Blocks.md.

Совместимость и ограничения

• ar допускает только короткий Arweave txId, полный URL не используется;
• MIME type не записывается, поэтому UI определяет image/video/file по расширению имени файла;
• старые блоки v=1 без превью остаются валидными и читаются без изменений;
• previewAr/previewSha256 используются только если присутствуют оба поля и оба валидны;
• MIME type, width, height, duration и thumbnail не записываются в блокчейн отдельными полями;
• проверка существующего txId скачивает файл локально через gateway, поэтому UI ограничивает максимальный размер такой проверки.