SHiNE-server/Черновик_дополнений_каналов_и_типов_сообщений_SHiNE.md

# Черновик дополнений каналов и типов сообщений SHiNE

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

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

Важно:

- это не финальная спецификация;
- формат блокчейна этим документом пока не меняется автоматически;
- документ фиксирует согласованную на текущий момент концепцию;
- в первую итерацию входят только `TEXT` и `STATUS_ACTION`;
- всё, что касается `CHANNEL_MEMBERSHIP`, вынесено в отдельный отложенный черновик:
  - `Черновик_CHANNEL_MEMBERSHIP_для_каналов.md`

## Цель

Нужно расширить текущую модель каналов SHiNE так, чтобы канал был не только лентой обычных постов, но и пространством:

- материалов;
- упражнений;
- услуг / процедур;
- курсов;
- входных страниц каналов;
- истории действий пользователей по этим материалам.

При этом важно:

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

## Базовая идея первой итерации

На текущий момент согласована следующая модель:

- старый `type=1`, который раньше назывался `TEXT`, по коду можно не менять;
- в документации и логике его можно трактовать шире как основной контентный тип сообщений;
- все новые смысловые материалы каналов добавляются как новые `subType` внутри `type=1`;
- отдельным верхнеуровневым `type` в первой итерации становится только:
  - `type=5` — действия пользователя по материалам.

Иначе говоря:

- `type=1` = сообщения и материалы;
- `type=5` = статусные действия пользователя;
- `type=6` = тема вынесена в отдельный отложенный черновик и в первую итерацию не входит.

## Текущие старые верхнеуровневые типы

Они сохраняются:

- `type=0` — `TECH`
- `type=1` — `TEXT`
- `type=2` — `REACTION`
- `type=3` — `CONNECTION`
- `type=4` — `USER_PARAM`

## Верхнеуровневые типы первой итерации

Используются:

- `0` — `TECH`
- `1` — `TEXT`
- `2` — `REACTION`
- `3` — `CONNECTION`
- `4` — `USER_PARAM`
- `5` — `STATUS_ACTION`

Отдельно:

- `6` — `CHANNEL_MEMBERSHIP`
  - зарезервирован как следующая тема;
  - вынесен в отдельный черновик;
  - в текущую реализацию не входит.

## Подтипы внутри `type=1`

Согласованная таблица первой итерации:

- `subType=10` — `TEXT_POST`
- `subType=11` — `TEXT_EDIT_POST`
- `subType=20` — `TEXT_REPLY`
- `subType=21` — `TEXT_EDIT_REPLY`
- `subType=30` — `TEXT_RATING`
- `subType=50` — `TEXT_REPOST`
- `subType=90` — `TEXT_CHANNEL_META`
- `subType=100` — `TEXT_ENTRYPOINT`
- `subType=110` — `TEXT_EXERCISE`
- `subType=120` — `TEXT_SERVICE`
- `subType=130` — `TEXT_COURSE`

## Принцип форматов внутри `type=1`

### Line-based сообщения

Следующие подтипы считаются line-based и используют тот же body, что и обычный `TEXT_POST`:

- `TEXT_POST`
- `TEXT_REPOST`
- `TEXT_CHANNEL_META`
- `TEXT_ENTRYPOINT`
- `TEXT_EXERCISE`
- `TEXT_SERVICE`
- `TEXT_COURSE`

### Target-based сообщения

Следующие подтипы считаются target-based:

- `TEXT_REPLY`
- `TEXT_EDIT_REPLY`
- `TEXT_RATING`

### Edit для `TEXT`

В первой итерации согласовано оставить в коде два технических edit-подтипа:

- `TEXT_EDIT_POST`
  - edit для сообщений линии канала;
- `TEXT_EDIT_REPLY`
  - edit для reply-сообщений.

То есть в документации больше не используется старое упрощённое описание “один общий `TEXT_EDIT`”.

## Смысл подтипов `type=1`

### `TEXT_POST`

Обычный текстовый пост в канале.

### `TEXT_EDIT_POST`

Редактирование line-based текстового сообщения канала.

Принцип:

- edit всегда ссылается на оригинальный блок;
- edit не должен ссылаться на предыдущий edit;
- фактический тип и правила берутся из оригинального сообщения.

### `TEXT_REPLY`

Обычный ответ / комментарий на сообщение.

Важно:

- reply остаётся единым;
- отвечать можно на `post`, `rating`, `exercise`, `service`, `course`, `entrypoint`, `status_action`;
- reply сам является target-based сообщением.

### `TEXT_EDIT_REPLY`

Редактирование reply-сообщения.

### `TEXT_RATING`

Текстовый отзыв / мнение / оценка на конкретный блок.

Смысл:

- это не line-based пост;
- это target-based сообщение-отзыв;
- оно всегда ссылается на конкретный блок, который оценивает;
- оценку пользователя как отдельную сущность в эту итерацию не включаем.

### `TEXT_REPOST`

Отложенная будущая заготовка.

На текущем этапе:

- код зарезервирован;
- бизнес-логика не входит в первую итерацию;
- детальная реализация может быть возвращена позже.

### `TEXT_CHANNEL_META`

Специальное скрытое сообщение метаданных канала.

Через него задаются:

- красивое имя канала;
- аватар;
- описание;
- и другие общие channel meta.

Оно:

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

### `TEXT_ENTRYPOINT`

Входная / главная страница канала.

Смысл:

- это не отдельный верхнеуровневый тип;
- это специальный line-based текстовый материал;
- он служит входной страницей канала;
- он может объяснять структуру канала, давать ссылки, вводить человека в тему.

Принцип:

- `TEXT_ENTRYPOINT` не редактируется через `TEXT_EDIT_POST`;
- новая версия создаётся новым сообщением `TEXT_ENTRYPOINT`;
- если в канале несколько `entrypoint`, актуальным считается последний.

### `TEXT_EXERCISE`

Упражнение или комплекс упражнений.

Смысл:

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

### `TEXT_SERVICE`

Услуга / процедура.

Смысл:

- материал, который пользователь проходит;
- обычно не “учится выполнять”, а именно получает / проходит;
- прохождение фиксируется отдельным `STATUS_ACTION`.

### `TEXT_COURSE`

Курс.

Смысл:

- материал, по которому есть путь обучения;
- пользователь может заинтересоваться, начать, учиться, завершить, бросить.

## Канал `0`

Согласована новая трактовка канала `0`.

Канал `0` становится:

- обычным каналом публикаций пользователя по умолчанию;
- местом его основной ленты;
- местом его главной страницы, если там есть `entrypoint`.

### Что это значит

Если у пользователя в канале `0` существует `TEXT_ENTRYPOINT`, тогда:

- ссылка `SHiNE/<login>` открывает именно этот последний `entrypoint`.

Если `entrypoint` в канале `0` нет, тогда:

- `SHiNE/<login>` открывает обычную ленту публикаций канала `0`.

## Правила открытия каналов и ссылок

Согласована следующая логика:

- `SHiNE/<login>`
  - главная страница пользователя, то есть канал `0`;
- `SHiNE/<login>/<channel>`
  - основная ссылка канала.

### Как открывается `SHiNE/<login>/<channel>`

Если у канала есть хотя бы один `TEXT_ENTRYPOINT`, тогда:

- по умолчанию открывается последний актуальный `entrypoint`;
- UI показывает, сколько после него было новых сообщений;
- UI показывает кнопку перехода в конец канала.

Если `entrypoint` нет:

- открывается обычная лента канала.

Для подписанного пользователя:

- логичнее вести его в место новых непрочитанных сообщений;
- а не всегда принудительно открывать entrypoint;
- при этом сверху можно показывать кнопку `Открыть entrypoint`.

### Ссылки на конкретные сообщения

Остаются обычные формы:

- `SHiNE/<login>/<channel>/<messageNumber>`
- `SHiNE/<login>/<channel>/<messageNumber>/<hash>`

Если нужно показать старую конкретную версию `entrypoint`, даётся ссылка именно на номер нужного сообщения.

## Новый тип `STATUS_ACTION`

`type=5` вводится для действий пользователя по контенту.

## Принцип `STATUS_ACTION`

Согласовано:

- `STATUS_ACTION` всегда является target-based сообщением;
- статусное действие всегда ссылается на конкретный блок-материал;
- это не обычный пост в канале;
- из таких сообщений можно собирать виртуальную ленту пользователя.

### Как трактуется текст в `STATUS_ACTION`

Основной смысл блока задаётся самим статусным событием.

Текст внутри такого блока:

- это комментарий пользователя к действию, если он есть;
- не является главным смыслом записи;
- служит пояснением.

Примеры:

- “Начал сегодня”
- “Решил пройти серьёзно”
- “Сделал это после практики”
- “Выучил базовый комплекс”

## Подтипы `STATUS_ACTION`

Предлагаемая таблица:

- `subType=10` — `STATUS_DONE_ONCE`
- `subType=20` — `STATUS_INTERESTED`
- `subType=30` — `STATUS_STARTED`
- `subType=40` — `STATUS_IN_STUDY`
- `subType=50` — `STATUS_COMPLETED`
- `subType=60` — `STATUS_ABANDONED`
- `subType=70` — `STATUS_LEARNED`
- `subType=80` — `STATUS_CONFIRMED`

## Смысл подтипов `STATUS_ACTION`

### `STATUS_DONE_ONCE`

Факт одного выполнения / прохождения.

Это накопительное событие.

### `STATUS_INTERESTED`

Пользователя заинтересовал материал.

### `STATUS_STARTED`

Пользователь начал.

Это начальный статус процесса, но ещё не “устойчивое обучение”.

### `STATUS_IN_STUDY`

Пользователь уже полноценно находится в обучении.

Смысл:

- не просто попробовал;
- а реально учится;
- это отдельный статус, более сильный, чем `started`.

### `STATUS_COMPLETED`

Пользователь завершил курс / прохождение.

### `STATUS_ABANDONED`

Пользователь бросил.

### `STATUS_LEARNED`

Пользователь выучил упражнение или комплекс и знает, как его делать.

Это не то же самое, что “сделал один раз”.

### `STATUS_CONFIRMED`

Подтверждение чужого status-события.

Важно:

- подтверждается не курс вообще;
- не упражнение вообще;
- а конкретный `STATUS_ACTION` конкретного пользователя.

## Кто ставит статусы

Согласовано правило:

- любой базовый статус ставит сам пользователь от своего имени;
- другие люди не ставят статус за него;
- другие люди могут только подтверждать его status-событие через `STATUS_CONFIRMED`.

То есть:

- `INTERESTED`, `STARTED`, `IN_STUDY`, `COMPLETED`, `ABANDONED`, `LEARNED`, `DONE_ONCE`
  - ставит сам пользователь;
- `CONFIRMED`
  - ставят другие люди на конкретный статусный блок.

### Вес подтверждений

В базовой версии веса подтверждений не вводятся.

Но в будущем можно добавить:

- более значимое подтверждение от создателя курса;
- более значимое подтверждение от создателя упражнения;
- весовые коэффициенты от близких / доверенных людей;
- слабые подтверждения от обычных пользователей.

## Матрица допустимости статусов по типам контента

### Для `TEXT_SERVICE`

Разрешены:

- `STATUS_DONE_ONCE`
- `STATUS_CONFIRMED`

Не разрешены:

- `INTERESTED`
- `STARTED`
- `IN_STUDY`
- `COMPLETED`
- `ABANDONED`
- `LEARNED`

### Для `TEXT_EXERCISE`

Разрешены:

- `STATUS_DONE_ONCE`
- `STATUS_LEARNED`
- `STATUS_CONFIRMED`

Логика:

- упражнение можно выполнять много раз;
- упражнение можно выучить;
- `LEARNED` и `DONE_ONCE` не конфликтуют и живут параллельно.

### Для `TEXT_COURSE`

Разрешены:

- `STATUS_INTERESTED`
- `STATUS_STARTED`
- `STATUS_IN_STUDY`
- `STATUS_COMPLETED`
- `STATUS_ABANDONED`
- `STATUS_CONFIRMED`

### Для `TEXT_ENTRYPOINT`

Статусные действия не ставятся.

### Для `TEXT_POST`, `TEXT_REPLY`, `TEXT_RATING`, `TEXT_CHANNEL_META`

Статусные действия не ставятся.

## Накопительные и текущие состояния

Нужно различать:

- накопительные события;
- текущий статус.

### Накопительные события

К ним относится:

- `STATUS_DONE_ONCE`

Они могут встречаться сколько угодно раз.

### Текущий статус

Для некоторых статусов есть “актуальное состояние”.

Например:

- `INTERESTED`
- `STARTED`
- `IN_STUDY`
- `COMPLETED`
- `ABANDONED`
- `LEARNED`

Текущий статус определяется как последнее событие соответствующей оси.

### Для упражнения

У упражнения есть две независимые оси:

- количественная: сколько раз выполнено;
- качественная: выучено или нет.

Это значит:

- `STATUS_DONE_ONCE` накапливается;
- `STATUS_LEARNED` живёт как отдельный качественный статус.

### Для курса

У курса текущий статус вычисляется по последнему из:

- `INTERESTED`
- `STARTED`
- `IN_STUDY`
- `COMPLETED`
- `ABANDONED`

## Виртуальная лента достижений пользователя

Согласована важная идея:

- не нужно создавать отдельный физический канал для истории выполнений пользователя;
- вместо этого строится виртуальная лента из его `STATUS_ACTION`.

### Что это даёт

Можно одновременно получить:

- историю человека;
- статистику по самому материалу.

Например, по упражнению можно увидеть:

- сколько разных людей его выполняли;
- сколько всего выполнений было;
- сколько раз конкретный человек его выполнял;
- кто его выучил.

### Что попадает в виртуальную ленту

Попадают status-события пользователя:

- выполненные упражнения;
- выученные упражнения;
- интерес к курсам;
- начатые курсы;
- обучение в процессе;
- завершённые курсы;
- брошенные курсы;
- прохождения услуг;
- подтверждения к этим событиям.

### Можно ли это обсуждать

Да.

Такие статусные сообщения остаются обычными объектами обсуждения:

- на них можно отвечать;
- их можно комментировать;
- на них можно писать отзывы;
- их можно подтверждать.

То есть:

- лента виртуальная;
- но сами записи реальные и обсуждаемые.

## Как это должно выглядеть в интерфейсе

### В каналах

Для разных типов сообщений UI должен понимать роль сообщения.

Например:

- у `TEXT_EXERCISE` можно показать кнопки:
  - `Выполнил`
  - `Выучил`
- у `TEXT_SERVICE`:
  - `Прошёл`
- у `TEXT_COURSE`:
  - `Интересно`
  - `Начал`
  - `Учусь`
  - `Завершил`
  - `Бросил`

### Для `entrypoint`

Если канал открывается по основной ссылке и у него есть `entrypoint`, UI:

- показывает сам последний `entrypoint`;
- показывает число новых сообщений после него;
- показывает кнопку перехода в конец канала.

Если пользователь уже подписан на канал:

- открывать лучше место новых непрочитанных сообщений;
- но с кнопкой открытия последнего `entrypoint`.

### Для виртуальной ленты достижений

В профиле пользователя UI может показывать:

- отдельную вкладку / раздел;
- где лента строится из его `STATUS_ACTION`.

## Что именно не нужно делать в первой итерации

### Не нужен отдельный физический канал достижений

Технически не нужен.

### Не нужны отдельные edit-подтипы для каждого вида контента

Не нужны:

- `TEXT_EDIT_EXERCISE`
- `TEXT_EDIT_SERVICE`
- `TEXT_EDIT_COURSE`

Достаточно текущего разделения:

- `TEXT_EDIT_POST`
- `TEXT_EDIT_REPLY`

### Не нужен отдельный верхнеуровневый тип для `entrypoint`

Он остаётся подтипом `type=1`.

### Не нужен `EDIT` для status-событий

`STATUS_ACTION` не редактируются.

Если нужно изменить смысл, пишется новое событие.

### Не нужен `CHANNEL_MEMBERSHIP` в первой итерации

Эта тема отложена в отдельный черновик.

## Сводная таблица

### Верхнеуровневые `type`

| Код | Имя | Статус |
|---|---|---|
| 0 | TECH | старый |
| 1 | TEXT | старый код, новое расширенное смысловое описание |
| 2 | REACTION | старый |
| 3 | CONNECTION | старый |
| 4 | USER_PARAM | старый |
| 5 | STATUS_ACTION | первая итерация |
| 6 | CHANNEL_MEMBERSHIP | вынесено в отдельный отложенный черновик |

### Подтипы `type=1`

| subType | Имя | Смысл |
|---|---|---|
| 10 | TEXT_POST | обычный post в линии канала |
| 11 | TEXT_EDIT_POST | edit line-based сообщения |
| 20 | TEXT_REPLY | target-based reply |
| 21 | TEXT_EDIT_REPLY | edit reply |
| 30 | TEXT_RATING | target-based отзыв на конкретный блок |
| 50 | TEXT_REPOST | отложенная будущая заготовка |
| 90 | TEXT_CHANNEL_META | скрытые метаданные канала |
| 100 | TEXT_ENTRYPOINT | входная страница канала |
| 110 | TEXT_EXERCISE | упражнение |
| 120 | TEXT_SERVICE | услуга / процедура |
| 130 | TEXT_COURSE | курс |

### Подтипы `type=5`

| subType | Имя | Смысл |
|---|---|---|
| 10 | STATUS_DONE_ONCE | выполнил / прошёл один раз |
| 20 | STATUS_INTERESTED | заинтересовался |
| 30 | STATUS_STARTED | начал |
| 40 | STATUS_IN_STUDY | учится полноценно |
| 50 | STATUS_COMPLETED | завершил |
| 60 | STATUS_ABANDONED | бросил |
| 70 | STATUS_LEARNED | выучил |
| 80 | STATUS_CONFIRMED | подтверждение status-события |

## Что ещё нужно отдельно утвердить перед реализацией

Перед началом реальной реализации желательно отдельно утвердить:

- точный байтовый формат новых line-based `subType` внутри `type=1`;
- точный байтовый формат `TEXT_RATING` как target-based отзыва;
- точный байтовый формат `STATUS_ACTION`;
- правила target-ссылок для status-событий;
- правила target-ссылок для отзывов на status-события;
- поведение удаления:
  - можно ли логически удалять `TEXT_EXERCISE` / `TEXT_SERVICE` / `TEXT_COURSE`;
  - можно ли удалять старые `entrypoint` или только оставлять их в истории;
- серверные read-model таблицы и индексы.

## Предварительная оценка готовности к реализации

На текущий момент концепция уже достаточно зрелая, чтобы начинать проектирование реализации первой итерации.

Реализовывать это уже можно, если дополнительно утвердить:

- байтовые форматы;
- правила валидации;
- API чтения новых сущностей;
- UI-матрицу действий по каждому типу контента.

## Краткий итог

Согласованная модель первой итерации сейчас такая:

- почти всё новое содержимое каналов живёт внутри `type=1`;
- `entrypoint` — это специальное текстовое сообщение, а не отдельный верхнеуровневый тип;
- `entrypoint` не редактируется, а версионируется новыми сообщениями;
- канал `0` становится каналом публикаций пользователя и его главной страницей;
- действия пользователя по материалам выносятся в `STATUS_ACTION`;
- `TEXT_RATING` трактуется как target-based отзыв на конкретный блок;
- `CHANNEL_MEMBERSHIP` отложен в отдельный черновик и в первую итерацию не входит.