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. этот хвостовой текст считается описанием канала.

Пример:

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

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

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

Формат:

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

Смысл:

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

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

Формат:

```text
<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-блоков.