SHiNE-server/docs/Personal_Messages/Технические_вставки_DM_v1.md

Технические вставки внутри plaintext DM v1

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

Этот файл описывает внутренний формат технических вставок, которые находятся внутри уже расшифрованного plaintext DM.

Важно:

• это не отдельный серверный DM-envelope;
• это часть plaintext контентного DM после E2EE-расшифровки;
• сервер не обязан знать этот формат;
• клиент может использовать эти вставки для специального UI-рендера.

1. Общий принцип

Обычное сообщение по-прежнему остаётся обычным текстом.

Если в начале plaintext стоит один или несколько специальных блоков формата:

<SHiNE:...>

то клиент трактует их как технические вставки.

Техническими считаются только блоки, которые:

• стоят строго в начале plaintext;
• начинаются с точного префикса <SHiNE:;
• заканчиваются первым символом >.

Если текст не начинается с <SHiNE:, никакие технические вставки не ищутся.

2. Правило скрытия

Все корректно распознанные блоки <SHiNE:...> в начале plaintext:

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

Если блок битый и не закрыт символом >, он не считается техническим и сообщение показывается как обычный текст целиком.

3. Защита от случайного пользовательского ввода

Перед отправкой обычного текстового сообщения клиент обязан проверить:

• если пользовательский текст начинается с <SHiNE:

то клиент автоматически превращает начало в:

< SHiNE:

Такой текст уже не считается техническим блоком и должен отображаться как обычное сообщение.

4. Формат блока

Общий вид:

<SHiNE:kind;key=value;key=value;...>

Правила:

• kind — ASCII-идентификатор типа вставки;
• параметры отделяются ;;
• ключ и значение отделяются =;
• значения не экранируются в v1;
• формат чувствителен к точному префиксу <SHiNE:.

5. Тип reply

Формат:

<SHiNE:reply;v=1;id=user1|user2|1720612345678|77>Текст ответа

Где поле id — это логический идентификатор сообщения:

fromLogin|toLogin|timeMs|nonce

Правила:

• этот блок должен стоять в начале plaintext;
• после него может идти обычный текст ответа;
• официальный UI формирует такой блок при отправке ответа через пункт Ответить в меню сообщения;
• если клиент не находит сообщение, на которое ссылается reply, он просто не показывает reply-preview;
• в таком случае само сообщение отображается как обычный текст без блока <SHiNE:reply...>.

6. Тип call

Успешный звонок

<SHiNE:call;v=1;status=completed;duration=367>

Где:

• duration — длительность разговора в секундах.

Неуспешный звонок

<SHiNE:call;v=1;status=failed;reason=offline>

Допустимые причины в v1:

• offline
• no_answer
• connect_failed
• busy
• declined

Правила:

• call-блок в v1 должен содержать только техническую запись звонка;
• пользовательский текст после такого блока в штатной логике не предполагается;
• UI может рисовать такие сообщения отдельным специальным стилем.
• официальный UI не отправляет call-summary, если от старта исходящего звонка до его завершения прошло меньше 5 секунд.

7. Поведение официального UI

Официальный UI SHiNE в v1:

• скрывает все корректные <SHiNE:...> блоки в начале plaintext;
• для call строит специальный человекочитаемый текст:
  • Звонок: M:SS
  • Звонок: H:MM:SS
  • Звонил, но недозвонился: ...
• для reply скрывает сам блок и показывает только текст ответа;
• если исходное reply-сообщение не найдено, reply-preview не показывается.

8. Совместимость

Так как это часть plaintext, а не часть серверного envelope:

• сервер не обязан понимать этот формат;
• будущие клиенты могут добавлять новые kind;
• клиенты, которые распознают SHiNE-вставки, должны скрывать неизвестные блоки целиком, если они стоят в начале и корректно закрыты.