Files
SHiNE-server/docs/Blockchain/11_TEXT_Blocks.md
T

157 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TEXT блоки (`type=1`, `version=1`)
TEXT-тип хранит сообщения, материалы и редактирования.
## Подтипы
1. `subType=10` — `TEXT_POST`
- пост в линии канала;
- содержит line-поля + текст.
2. `subType=11` — `TEXT_EDIT_POST`
- редактирование поста;
- line-поля + compact target (`toBlockGlobalNumber`, `toBlockHash32`) на оригинальный POST + новый текст.
3. `subType=20` — `TEXT_REPLY`
- ответ на сообщение;
- target (`toLogin`, `toForkNumber`, `toBlockGlobalNumber`, `toBlockHash32`) + текст.
4. `subType=21` — `TEXT_EDIT_REPLY`
- редактирование ответа;
- compact target (`toBlockGlobalNumber`, `toBlockHash32`) на исходный REPLY + новый текст.
- допускается пустой `text` для логического удаления сообщения (без физического удаления блока).
5. `subType=30` — `TEXT_RATING`
- target-based отзыв на конкретный блок;
- содержит target (`toLogin`, `toForkNumber`, `toBlockGlobalNumber`, `toBlockHash32`) + текст отзыва;
- не является сообщением линии канала.
6. `subType=50` — `TEXT_REPOST`
- репост сообщения в линию канала;
- содержит line-поля + target на оригинальное сообщение + текст комментария;
- на текущем этапе продуктовой логики репост не редактируется (версии не накапливаются);
- временно отключён для записи через `AddBlock` до будущей реализации репостов.
7. `subType=90` — `TEXT_CHANNEL_META`
- скрытый технический снимок профиля канала;
- содержит line-поля + текст с тегами `S:title`/`S:ava` и описанием;
- не отображается как обычное сообщение ленты;
- применяется сервером к текущему состоянию канала.
8. `subType=92` — `TEXT_CHANNEL_DELETE`
- скрытый технический soft-delete канала;
- содержит line-поля и обязательный пустой `text`;
- становится хвостом той же линии канала;
- новый самостоятельный channel-пост автоматически делает канал активным снова; `CHANNEL_META` и `EDIT_POST` не оживляют канал.
9. `subType=100` — `TEXT_ENTRYPOINT`
- входная страница канала;
- line-based сообщение с тем же body, что у `TEXT_POST`;
- не редактируется через `TEXT_EDIT_POST`: новая версия создаётся новым `TEXT_ENTRYPOINT`.
10. `subType=110` — `TEXT_EXERCISE`
- line-based материал упражнения;
- использует тот же body, что у `TEXT_POST`.
11. `subType=120` — `TEXT_SERVICE`
- line-based материал услуги / процедуры;
- использует тот же body, что у `TEXT_POST`.
12. `subType=130` — `TEXT_COURSE`
- line-based материал курса;
- использует тот же body, что у `TEXT_POST`.
Подробные спецификации: [16_TEXT_Channel_Meta.md](./16_TEXT_Channel_Meta.md) и [17_TEXT_Channel_Delete.md](./17_TEXT_Channel_Delete.md).
## Канонический target-формат TEXT
Внешние цели (`TEXT_REPLY`, `TEXT_RATING`, `TEXT_REPOST`) используют:
```text
[1] toLoginLen (uint8)
[N] toLogin UTF-8
[2] toForkNumber (uint16, BigEndian)
[4] toBlockGlobalNumber
[32] toBlockHash32
```
`toForkNumber`: строго `1..999` — fork, который видел автор действия. Поле информационное и **не входит в логическую идентичность цели**. Цель определяется только `toLogin + toBlockGlobalNumber + toBlockHash32`; несовпадение текущего fork само по себе не инвалидирует ссылку.
Собственные edit (`TEXT_EDIT_POST`, `TEXT_EDIT_REPLY`) используют компактный target:
```text
[4] toBlockGlobalNumber
[32] toBlockHash32
```
Login/fork для edit не подписываются: edit может ссылаться только на собственный блок текущей цепочки.
## Правило для edit
`EDIT_POST` и `EDIT_REPLY` должны ссылаться на **оригинальный** блок, а не на предыдущий edit.
Важно:
- `TEXT_EDIT_POST` — технический edit для line-based сообщений канала;
- `TEXT_EDIT_REPLY` — технический edit для reply-сообщений;
- `TEXT_ENTRYPOINT` через `TEXT_EDIT_POST` не редактируется.
## Пустой text в edit
- Для `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` допустим `textLen=0`.
- Такой edit трактуется как логическое удаление содержимого сообщения.
- Для удаления отдельного сообщения используется именно edit-блок; отдельного `DELETE`-подтипа сообщения нет. `TEXT_CHANNEL_DELETE=92` относится только к soft-delete всего канала.
## Вложения в текстовых сообщениях (`S:att v=1` и `v=2`)
Для `TEXT_POST`, `TEXT_REPLY`, `TEXT_EDIT_POST` и `TEXT_EDIT_REPLY` клиент может хранить вложения как технические строки в начале обычного `text`.
Подробная спецификация: [15_TEXT_Attachments.md](./15_TEXT_Attachments.md).
Бинарный формат `TextBody` не меняется: вложения являются частью UTF-8 текста.
Arweave-вложение:
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123...;ar=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA>
```
Вложение на сервере доступа автора:
```text
<S:att;v=1;nm=report.pdf;sz=845221;sha256=0123...>
```
Несколько вложений идут подряд в самом начале текста, по одному блоку на строку. После последнего блока идёт обычный пользовательский текст.
Обязательные поля:
- `v=1` для исторических записей, `v=2` для новых
- `nm` - имя файла: для `v=1` старое `encodeURIComponent`, для `v=2` UTF-8 с экранированием только `%`, `<`, `>`, `=`, `;`
- `sz` - размер файла в байтах
- `sha256` - SHA-256 исходного файла в hex
Опциональное поле:
- `ar` - короткий Arweave Transaction ID, без полного URL.
Правило источника файла:
- `ar` присутствует -> файл хранится в Arweave;
- `ar` отсутствует -> файл хранится как public file на текущем сервере доступа автора и читается по `/files/<sha256>`;
- адрес сервера доступа в attach-блок не записывается.
Отдельные preview-файлы сейчас **не поддерживаются и не являются частью текущего протокола**. Поля `preAr`, `preSha256`, `previewAr`, `previewSha256` новые клиенты создавать не должны. Изображения и видео отображаются из исходного файла.
Правила клиента:
- если сообщение начинается с одного или нескольких валидных attach-блоков (`<SHiNE:attach;...>`, `<S:attach;...>` или `<S:att;...>`), новый клиент скрывает эти блоки и показывает карточки вложений;
- если блок битый, клиент может игнорировать только этот блок и продолжить разбор остальных;
- старые клиенты без поддержки вложений могут показывать технические строки как обычный текст;
- пустой пользовательский текст допустим, если перед ним есть хотя бы один валидный attach-блок.
В `v=2` при структурированном чтении проверяется уникальность полей, допустимость кодирования и значений. Безопасное текстовое представление и файловые URL должны дополнительно валидироваться на клиенте и сервере.
Сам файл всегда хранится вне блокчейна. В блокчейне остаются имя, размер, SHA-256 и, только для Arweave-вложения, `ar`.