SHiNE-server/Черновик_TEXT_CHANNEL_META_для_каналов.md

Черновик TEXT_CHANNEL_META для каналов SHiNE

Статус документа

Этот файл является рабочим черновиком и не считается финальной спецификацией.

Важно:

• это не окончательный формат;
• точная версия должна быть зафиксирована отдельно при начале реализации;
• до реализации допустимы изменения синтаксиса, ограничений и полей БД;
• документ временно лежит в корне проекта как согласованный draft.

Назначение

Нужен специальный скрытый тип текстового сообщения канала, который:

• технически хранится в блокчейне как TEXT-блок;
• не показывается пользователям как обычное сообщение ленты;
• может писать только владелец канала;
• не редактируется;
• задаёт полное текущее состояние метаданных канала.

Через этот блок должны обновляться:

• человекочитаемое заглавие канала;
• аватар канала;
• описание канала.

Место в формате блокчейна

• msg_type = 1
• subType = 70
• имя подтипа: TEXT_CHANNEL_META

Этот подтип относится к текстовым блокам, но трактуется как скрытое техническое сообщение канала.

Общая модель применения

TEXT_CHANNEL_META:

• пишется в линию конкретного канала;
• задаёт полный снимок метаданных;
• при чтении канала сервер берёт последний валидный TEXT_CHANNEL_META в линии;
• более старые TEXT_CHANNEL_META остаются в истории блокчейна, но не участвуют в вычислении текущего состояния;
• если meta-блок не найден, используются базовые данные канала без override-полей.

Общий формат текста

Внутри TEXT_CHANNEL_META текст строится так:

1. в начале идут технические теги <SHiNE:...>;
2. после тегов идёт обычный UTF-8 текст;
3. этот хвостовой текст считается описанием канала.

Пример:

<SHiNE:title;v=1;Моё имя канала>
<SHiNE:avatar;v=1;size=248193;sha256=3f2c8a...;ar=AbCdEf...>
Тут описание канала.

Поддерживаемые теги

1. Тег заглавия

Формат:

<SHiNE:title;v=1;Моё имя канала>

Смысл:

• задаёт красивое отображаемое имя канала;
• хранится как обычный UTF-8 текст;
• это не технический slug и не системное имя.

2. Тег аватара

Формат:

<SHiNE:avatar;v=1;size=248193;sha256=3f2c8a...;ar=AbCdEf...>

Смысл:

• задаёт аватар канала;
• ar хранит только txId, без полного URL;
• конкретный gateway/URL уже выбирает клиент или сервер.

Правила порядка

• теги должны идти только в начале текста;
• после начала обычного описания новые теги больше не допускаются;
• рекомендуемый порядок:
  1. title
  2. avatar
  3. текст описания
• каждый тег допустим не более одного раза.

Правила отсутствующих полей

• если title отсутствует, используется обычное техническое имя канала;
• если avatar отсутствует, аватар у канала отсутствует;
• если текста после тегов нет, описание считается пустым;
• если тегов нет вообще, но текст есть, это означает пустые title и avatar, а текст используется как описание.

Полный снимок состояния

Каждый новый TEXT_CHANNEL_META задаёт полное состояние канала целиком.

Это значит:

• новый блок не дозаполняет старые поля;
• новый блок не наследует значения из прошлого meta-блока;
• если в новом блоке нет title, то красивое имя сбрасывается к обычному имени канала;
• если в новом блоке нет avatar, аватар сбрасывается;
• если в новом блоке нет текста описания, описание становится пустым.

Ограничения для тега title

title хранится как UTF-8 строка, но для упрощения формата запрещаются следующие символы:

• <
• >
• ;
• табуляция
• перевод строки
• \0

Дополнительно:

• максимальная длина title — 50 символов;
• допускаются обычные Unicode-символы, включая кириллицу, латиницу, эмодзи и декоративные символы, если они не нарушают запреты выше.

Ограничения для описания

• описание хранится как обычный UTF-8 текст;
• максимальная длина — 250 символов.

Если описание длиннее лимита, meta-блок должен считаться невалидным.

Ограничения для тега avatar

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

• v
• size
• sha256
• ar

Правила:

• size — размер файла в байтах;
• sha256 — SHA-256 файла в hex;
• sha256 должен иметь длину ровно 64 hex-символа;
• ar — только txId Arweave;
• длина ar должна соответствовать длине идентификатора Arweave-транзакции;
• имя файла в meta-теге аватара не хранится.

Валидация блока

Блок TEXT_CHANNEL_META считается валидным только если одновременно соблюдены все условия:

• теги находятся строго в начале текста;
• каждый тип тега встречается не более одного раза;
• title удовлетворяет ограничениям;
• avatar-тег имеет все обязательные поля и корректные значения;
• длина описания не превышает лимит.

Если блок невалиден:

• весь meta-блок не применяется целиком;
• сервер не должен частично брать из него только отдельные поля.

Что именно хранится в текущем состоянии канала

Текущее вычисленное состояние канала должно включать:

• техническое имя канала;
• красивое отображаемое имя;
• описание;
• ava_ar;
• ava_sha256;
• ava_size;
• время последнего meta-обновления.

База данных

Базовую таблицу каналов предлагается не менять концептуально, а расширить существующую модель хранения каналов.

Текущая основа уже есть в таблице:

• channel_names_state

В неё предлагается добавить поля:

• ava_ar
• ava_sha256
• ava_size
• meta_updated_at_ms

При этом:

• техническое имя канала продолжает храниться отдельно;
• красивое имя хранится в display_name;
• описание хранится в channel_description.

Поведение API и чтения каналов

Обычным пользователям TEXT_CHANNEL_META не должен приходить как обычное сообщение ленты.

Это означает:

• в GetChannelMessages такие блоки не показываются как сообщения;
• в обычных списках каналов клиент получает уже вычисленное текущее состояние канала;
• в debug/raw-чтении сам блок может оставаться доступным как часть блокчейна.

UI-заметки

1. В обычной ленте

TEXT_CHANNEL_META не показывается как обычное текстовое сообщение.

2. Системная карточка

UI может показывать специальную системную карточку:

• для текущего состояния канала;
• для стартового состояния при создании канала.

3. Что показывать по нажатию

По нажатию на системную карточку нужно показывать полную информацию:

• дата и время;
• заглавие;
• аватар;
• описание.

4. История UI

На первом этапе UI показывает только текущую системную карточку состояния.

Полная история всех прошлых meta-обновлений в UI на этом этапе не требуется.

Поведение при создании канала

Для UI полезно также иметь отдельный визуальный системный блок в начале канала:

• «канал создан»;
• по нажатию можно показать стартовые данные канала;
• если на момент создания уже есть заглавие/ава/описание, UI показывает именно их.

Это UI-заметка и не требует отдельного нового блокчейн-формата поверх TEXT_CHANNEL_META.

Краткое резюме согласованной схемы

• msg_type=1
• subType=70
• имя: TEXT_CHANNEL_META
• это скрытый технический текстовый блок канала
• порядок: теги в начале, потом описание
• теги:
  • <SHiNE:title;v=1;...>
  • <SHiNE:avatar;v=1;size=...;sha256=...;ar=...>
• title:
  • UTF-8
  • максимум 50 символов
  • нельзя <, >, ;, таб, перевод строки, \0
• описание:
  • UTF-8
  • максимум 250 символов
• avatar:
  • ar только txId
  • хранится без имени файла
• новый meta-блок задаёт полный снимок состояния
• сервер применяет только последний валидный meta-блок
• невалидный meta-блок не применяется целиком
• БД расширяется в той же модели каналов
• в UI обычным сообщением блок не показывается

Что ещё потребуется зафиксировать позже

При переводе черновика в официальную спецификацию нужно будет дополнительно утвердить:

• точный номер версии формата;
• точный способ подсчёта длины title и описания:
  • по Unicode code points;
  • по Java String.length();
  • или по UTF-8 байтам;
• точную проверку длины ar;
• список API-ответов, куда должны быть добавлены новые поля;
• правила миграции старых каналов без meta-блоков.