Обновить каналы и перенести черновики

2026-09-09 15:17:31 +03:00
parent f827c3e493
commit 9f77c54955
8 changed files with 168 additions and 85 deletions
@@ -0,0 +1,173 @@
+# Черновик формата вложений в сообщениях блокчейна SHiNE
+
+## Статус документа
+
+Этот файл пока является черновиком и рабочим описанием идеи.
+
+Важно:
+
+- это не финальная спецификация;
+- точная версия формата будет зафиксирована после начала реальной реализации;
+- до момента реализации допустимы изменения полей, синтаксиса и правил отображения;
+- документ специально лежит в корне проекта как временная рабочая заметка.
+
+## Цель
+
+Нужен минимальный формат, позволяющий прикладывать файлы к текстовым сообщениям в каналах и тредах, не превращая само сообщение в отдельный файловый контейнер.
+
+Основная идея:
+
+- само сообщение остаётся обычным текстом;
+- вложения описываются специальными техническими вставками в начале текста;
+- сами файлы хранятся отдельно в архиве/Arweave;
+- в сообщении хранятся только метаданные, достаточные для отображения и скачивания.
+
+## Общий принцип
+
+Если в начале текста сообщения стоит один или несколько блоков:
+
+```text
+<SHiNE:attach;...>
+```
+
+клиент трактует их как описания вложений.
+
+После этих блоков идёт обычный пользовательский текст сообщения.
+
+Если технических блоков нет, сообщение считается обычным текстовым сообщением без вложений.
+
+## Формат одного блока вложения
+
+Общий вид:
+
+```text
+<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=abcdef...;ar=tx_or_url>
+```
+
+Где:
+
+- `attach` — тип технической вставки;
+- `v=1` — текущая рабочая версия чернового формата;
+- `name` — имя файла;
+- `size` — размер файла в байтах;
+- `sha256` — SHA-256 файла в hex;
+- `ar` — идентификатор файла в архиве или адрес файла в Arweave.
+
+## Несколько вложений
+
+Если к одному сообщению приложено несколько файлов, блоки просто идут подряд в начале текста:
+
+```text
+<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=aaa...;ar=...>
+<SHiNE:attach;v=1;name=video.mp4;size=5820193;sha256=bbb...;ar=...>
+Текст сообщения
+```
+
+## Обязательные поля
+
+Для чернового варианта обязательными считаются:
+
+- `v`
+- `name`
+- `size`
+- `sha256`
+- `ar`
+
+Если какого-то из этих полей нет, клиент может:
+
+- игнорировать конкретный битый блок;
+- не считать его валидным вложением;
+- при этом продолжать обрабатывать остальные корректные блоки.
+
+## Почему без `mime` и без `kind`
+
+В минимальном варианте тип файла отдельно не хранится.
+
+Причины:
+
+- это экономит место;
+- тип всё равно обычно определяется клиентом;
+- для первого варианта достаточно имени файла, адреса, хэша и размера;
+- превью и способ отображения клиент может решать сам по расширению имени файла или по попытке открыть файл.
+
+То есть в сообщении не хранится:
+
+- `mime`;
+- `kind`;
+- `width`;
+- `height`;
+- `duration`;
+- `thumbnail`.
+
+Все эти поля можно добавить позже отдельной версией, если они реально понадобятся.
+
+## Логика клиента
+
+Клиент получает:
+
+- имя файла;
+- размер;
+- хэш;
+- адрес файла.
+
+После этого клиент сам решает, как рендерить вложение:
+
+- если расширение похоже на изображение, можно пробовать показать preview;
+- если расширение похоже на видео, можно пробовать встроенный видеоплеер;
+- если расширение похоже на аудио, можно пробовать аудиоплеер;
+- иначе показывать обычную кнопку скачивания.
+
+Если браузер или клиент не смог показать preview, должен быть fallback на скачивание файла.
+
+## Правила совместимости
+
+- Сообщение без `<SHiNE:attach;...>` остаётся обычным текстом.
+- Старые клиенты, которые не умеют распознавать этот формат, могут показывать сообщение как обычный текст целиком.
+- Новые клиенты могут скрывать технические блоки и показывать вместо них UI вложений.
+
+## Ограничения чернового варианта
+
+В текущем виде значения полей не предполагают сложного экранирования.
+
+Значит нужно отдельно договориться, как безопасно хранить `name`, если там встретятся символы:
+
+- `;`
+- `=`
+- `>`
+
+На этапе реальной реализации нужно выбрать один из вариантов:
+
+- жёстко ограничить допустимые символы в `name`;
+- хранить имя файла в безопасно закодированном виде;
+- добавить отдельное правило escape/encoding.
+
+Пока этот вопрос считается открытым.
+
+## Примеры
+
+### Одно вложение
+
+```text
+<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
+Привет, вот фото
+```
+
+### Два вложения
+
+```text
+<SHiNE:attach;v=1;name=photo.jpg;size=248193;sha256=3f2c8a...;ar=6sYk...>
+<SHiNE:attach;v=1;name=report.pdf;size=845221;sha256=9ab01e...;ar=K9Lp...>
+Смотри, прикрепил фото и документ
+```
+
+## Что надо зафиксировать позже
+
+Перед переводом этого черновика в официальную спецификацию нужно отдельно утвердить:
+
+- точное место этого формата в общей документации блокчейна;
+- где именно используются такие вложения: каналы, треды, комментарии или иные текстовые блоки;
+- финальные правила кодирования `name`;
+- допустим ли полный URL в `ar` или только короткий `txId`;
+- нужно ли ограничение на количество вложений в одном сообщении;
+- нужна ли отдельная серверная или клиентская проверка расширения файла;
+- как именно это будет отображаться в web UI и других клиентах.