Добавить Turbo-загрузку и превью для вложений

2026-08-04 19:09:54 +04:00
parent 391b18a5ac
commit 75b75fd223
13 changed files with 1445 additions and 690 deletions
@@ -141,7 +141,7 @@

 ### Вложения в сообщениях

-Для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` вложения записываются в начало текста сообщения одним или несколькими тегами `SHiNE:attach v=1`.
+Для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` вложения записываются в начало текста сообщения одним или несколькими тегами `SHiNE:attach v=1` или `v=2`.

 Пример текстового содержимого body:

@@ -151,6 +151,12 @@
 Текст сообщения
 ```

+Пример вложения с отдельным preview-файлом:
+
+```text
+<SHiNE:attach;v=2;name=video.mp4;size=5820193;sha256=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;previewAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;previewSha256=eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee>
+```
+
 Сервер хранит это как обычный `TEXT`-блок. Отображение карусели, картинок, видео и карточек файлов делает клиент. Полная спецификация тега находится в `docs/Blockchain/15_TEXT_Attachments.md`.

 ### Создание публичного канала с профилем
@@ -45,7 +45,7 @@ TEXT-тип хранит сообщения и редактирования.
 - Такой edit трактуется как логическое удаление содержимого сообщения.
 - Для удаления используется именно edit-блок; отдельного `DELETE`-подтипа нет.

-## Вложения в текстовых сообщениях (`SHiNE:attach v=1`)
+## Вложения в текстовых сообщениях (`SHiNE:attach v=1/v=2`)

 Для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` клиент может хранить вложения как технические строки в начале обычного `text`.

@@ -59,15 +59,22 @@ TEXT-тип хранит сообщения и редактирования.
 <SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=0123...;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
 ```

+Для файлов с отдельным превью клиент может использовать расширенный вариант:
+
+```text
+<SHiNE:attach;v=2;name=video.mp4;size=5820193;sha256=bbbb...;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;previewAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;previewSha256=eeee...>
+```
+
 Несколько вложений идут подряд в самом начале текста, по одному блоку на строку. После последнего блока идёт обычный пользовательский текст.

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

- `v=1`
+- `v=1` или `v=2`
 - `name` - имя файла, закодированное через `encodeURIComponent`
 - `size` - размер файла в байтах
 - `sha256` - SHA-256 исходного файла в hex
 - `ar` - короткий Arweave Transaction ID, без полного URL
+- для `v=2` дополнительно могут присутствовать `previewAr` и `previewSha256`

 Правила клиента:

@@ -76,4 +83,4 @@ TEXT-тип хранит сообщения и редактирования.
 - старые клиенты без поддержки вложений могут показывать технические строки как обычный текст;
 - пустой пользовательский текст допустим, если перед ним есть хотя бы один валидный attach-блок.

-Файлы хранятся вне блокчейна, в Arweave. В блокчейне остаются только `txId`, имя, размер и SHA-256.
+Файлы хранятся вне блокчейна, в Arweave. В блокчейне остаются только `txId`, имя, размер, SHA-256 и, при наличии отдельного preview-файла, `previewAr/previewSha256`.
@@ -1,4 +1,4 @@
-# Вложения в TEXT-сообщениях (`SHiNE:attach v=1`)
+# Вложения в TEXT-сообщениях (`SHiNE:attach v=1/v=2`)

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

@@ -21,6 +21,12 @@
 <SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
 ```

+Блок с превью:
+
+```text
+<SHiNE:attach;v=2;name=video.mp4;size=5820193;sha256=bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;ar=CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC;previewAr=DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD;previewSha256=eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee>
+```
+
 Несколько вложений идут подряд в самом начале текста:

 ```text
@@ -43,6 +49,11 @@
 - `sha256` - SHA-256 исходного файла в hex, 64 символа;
 - `ar` - короткий Arweave Transaction ID, 43 символа, без gateway URL.

+Дополнительные поля для `v=2`:
+
+- `previewAr` - короткий Arweave Transaction ID файла-превью;
+- `previewSha256` - SHA-256 файла-превью в hex.
+
 ## Хранение файла

 Файл хранится вне блокчейна в Arweave. В блокчейне хранится только метаинформация, достаточная для отображения и проверки:
@@ -52,6 +63,8 @@
 - SHA-256;
 - Arweave `txId`.

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

 UI поддерживает три сценария:
@@ -60,6 +73,15 @@ UI поддерживает три сценария:
 - ввести существующий `txId`, скачать файл через Arweave gateway и локально посчитать `size/sha256`;
 - выбрать файл из журнала файлов, загруженных в текущей браузерной сессии.

+Для видеофайлов UI может по желанию пользователя автоматически создать превью из первого кадра. Технически клиент загружает два файла:
+
+- основной видеофайл;
+- отдельное изображение-превью.
+
+После успешной загрузки в журнале хранится один элемент основного файла, но с полями `previewAr/previewSha256`. В UI такой элемент помечается как файл `С превью`.
+
+При ручном добавлении существующего `txId` для видео UI также позволяет вручную указать `txId` файла-превью.
+
 Журнал хранится только в `sessionStorage` текущего браузера и не является частью блокчейна.
 В настройках клиента есть отдельный экран `Загрузка файлов`: пользователь может заранее загрузить файл в Arweave без создания сообщения, увидеть компактную плитку с именем, размером, временем загрузки, `txId` и статусом доступности через gateway, а затем выбрать этот файл из истории при создании сообщения.
 Если файл загружен заранее, но ещё не был отправлен ни в одном сообщении SHiNE, клиент показывает локальный флаг `Не добавлен в SHiNE`. Флаг снимается после успешной отправки сообщения с этим вложением.
@@ -77,8 +99,9 @@ UI поддерживает три сценария:
   - изображение показывает как ограниченное по размеру превью;
   - видео показывает как превью с кнопкой воспроизведения и открывает большой HTML5-плеер по нажатию;
   - обычный файл показывает как карточку с именем, расширением, размером и скачиванием;
-6. при перелистывании останавливает воспроизводящееся видео;
-7. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.
+6. если у видео есть `previewAr/previewSha256`, использует отдельный preview-файл как `poster` и как большую превью-плитку в журнале загрузок;
+7. при перелистывании останавливает воспроизводящееся видео;
+8. если attach-блок битый, игнорирует только этот блок и продолжает отображать сообщение.

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

@@ -91,9 +114,11 @@ UI поддерживает три сценария:

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

-## Ограничения v1
+## Совместимость и ограничения

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

+## 2026-08-04 12:00:00 +0400
+- Базовый коммит-ориентир: `391b18a`.
+- Формат вложений расширен до `SHiNE:attach v=2` для опционального второго preview-файла: добавлены поля `previewAr` и `previewSha256` при сохранении совместимости со старыми `v=1`.
+- В UI загрузки для видео добавлен сценарий `Добавить превью`: клиент может извлечь первый кадр, загрузить его отдельным файлом в Arweave или через Turbo и сохранить связь preview с основным вложением.
+- В журнале загрузок файлы с preview помечаются явно и показываются расширенной плиткой с картинкой превью.
+
 ## 2026-07-31 17:22:07 +0400
 - Базовый коммит-ориентир: `05bd9f5`.
 - Уточнён UI вложений: превью последнего сообщения в списке каналов скрывает технические attach-блоки, карусель не показывает неактивные стрелки на краях, обычный файл отображается компактной кликабельной полоской без `txId`; формат attach-блока не изменён.
@@ -18,7 +18,7 @@
 7. [14_USER_PARAM_Blocks.md](./14_USER_PARAM_Blocks.md)
   Параметры пользователя (`msg_type=4`).
 8. [15_TEXT_Attachments.md](./15_TEXT_Attachments.md)
-   Вложения в TEXT-сообщениях через `SHiNE:attach v=1`.
+   Вложения в TEXT-сообщениях через `SHiNE:attach v=1/v=2`, включая опциональные `previewAr/previewSha256` для видео и крупных изображений.
 9. [16_TEXT_Channel_Meta.md](./16_TEXT_Channel_Meta.md)
   Скрытый `TEXT_CHANNEL_META` для профиля канала.
 10. [01_Channel_Types_and_CreateChannel.md](./01_Channel_Types_and_CreateChannel.md)