Перейти к основному содержимому

2026-08-26 - Обращения (mentions) в чатах

Статус: Реализовано

Актуальная карта: chats.md (§ «Обращения»), user-guide: notifications-and-chats.md.

Источник: Алексей

Эпик: ITR-2912

Цель​

Дать возможность в сообщении чата пометить (упомянуть) сотрудника, чтобы было видно, что обращение адресовано ему — по аналогии с @ в мессенджерах.

Ключевое ограничение от заказчика: основной способ — кнопка в интерфейсе строки ввода (+ автокомплит), потому что русские ФИО неудобно набирать через @ с клавиатуры. Символ @ оставляем вторым способом вставки того же обращения.

Контекст (состояние до эпика)​

Ниже — «как было» на момент согласования ТЗ. После реализации: typed-токены в Message.Text (@{e:…}), отдельной таблицы mentions нет; UI — кнопка и @. См. chats.md.

Модель​

  • Чаты: заказ покупателя / групповой / личный (EnChatType).
  • Участники: ChatParticipant (роль, entry/exit, lastRead).
  • Сообщение: Message — плоский Text: string, отправитель, даты отправки / правки / удаления.
  • Mentions / обращений в модели на момент ТЗ не было (сейчас — токены в тексте).

Код: MessageEntity, MessageRequest / MessageResponse, MessageService, фронт widgets/chat/message-input.tsx, entities/chat/....

Отправка и уведомления​

При MessageService.Add:

  1. Сохраняется текст как есть.
  2. Всем активным участникам кроме отправителя создаётся уведомление типа Chat (Header = "Новое сообщение", Text = текст сообщения, ChatId).
  3. Уведомление уходит через SignalR + (по умолчанию) WebPush.

Уведомления не меняем под mentions: отдельный тип/формулировка «вас упомянули» не требуется.

UI ввода и отображения​

  • Ввод: обычный TextField (multiline), справа только кнопка Send.
  • Отображение: msg.text как plain text, без разметки.

Принятые решения​

Хранение — вариант A (typed-токены в тексте)​

Отдельной таблицы mentions нет. Правда — одна строка Message.Text.

В БД / в API (пример):

@{e:3f2a0000-0000-0000-0000-000000000001:Вася} я сделал счёт @{e:9c1b0000-0000-0000-0000-000000000002:Маша} может отнести документ на подпись

Пользователю в UI (ввод и лента):

@Вася я сделал счёт @Маша может отнести документ на подпись

Формат токена:

@{<type>:<id>:<display>}
typeСмыслMVP
eсотрудник (employeeId)да
rроль (roleId)нет, формат зарезервирован

Запас под роли: парсер и валидатор с первого дня понимают e и r; в MVP клиент вставляет только e. Обращения по роли (@Помощники) — отдельная доработка без смены схемы хранения.

UX​

ТемаРешение
ТриггерОсновной: кнопка в строке ввода. Дополнительный: ввод символа @. Оба открывают один и тот же автокомплит / поиск по ФИО.
ВыборОдно действие: выбрал человека → сразу вставка в позицию курсора (без лишних подтверждений).
Голый @ в текстеЕсли пользователь набрал @ и не выбрал никого из списка (закрыл Escape / ушёл дальше) — оставляем обычный символ @, в mention не превращаем.
Вид в тексте@Имя (display), без chip/плашки. В ленте — выделить имя (цвет/вес).
Несколько в одном сообщенииДа. Контракт — несколько токенов в строке. Техлимит (например 10–20) можно задать на реализации.
РедактированиеПолное: можно изменить и обычный текст, и набор обращений (пересобрать text с токенами).
Упоминаемый вышел / уволенВ истории продолжаем показывать display из токена как было.
УведомленияКак сейчас: всем участникам «Новое сообщение». Везде, где текст показывают человеку не как сырой Message.Text, нужен читаемый вид @Имя (без guid и @{…}): превью в списке чатов, колокольчик, push (WebPush), SignalR-пейлоад уведомления.

Поведение бека (ориентир)​

При Add / Update:

  1. Принять text с токенами.
  2. Распарсить все @{type:id:display}.
  3. Для e: проверить, что id — активный участник чата (дефолт скоупа; уточнение у заказчика — ниже).
  4. Для неизвестного type / битого guid / битой разметки — ошибка валидации.
  5. Сохранить text как есть.
  6. Уведомления — без спец-логики «вас упомянули»; перед записью/отправкой в Notification.Text и в push прогнать текст через общую функцию: токены → @Display (чтобы в пуше не утекли guid). То же для lastMessageText в списке чатов.

Отдельное поле mentionedEmployeeIds в request не нужно — ids внутри токенов.

Поведение фронта (ориентир)​

  • Модель ввода хранит raw-строку с токенами (или внутренние segments → перед send сборка в raw).
  • В поле пользователь видит @Display.
  • Кнопка и ввод @: один автокомплит по участникам чата → вставка @{e:id:display}.
  • message-item: парсинг → подсветка @Display.
  • Общая функция «токены → читаемый текст»: @{e:guid:Вася}… → @Вася…. Использовать для превью списка чатов, колокольчика и обязательно для push (и любого другого места, куда уходит текст уведомления). В ленте сообщений — отдельный парсинг с подсветкой, не путать с этой очисткой.

Желаемое поведение (продукт)​

  1. В строке ввода — кнопка обращения; также можно начать обращение символом @. Оба пути — один автокомплит по участникам.
  2. После выбора в текст вставляется обращение; пользователь видит @Имя.
  3. В ленте обращения визуально выделены.
  4. Редактирование сообщения умеет менять текст и обращения целиком.
  5. Старые сообщения до фичи остаются plain text без токенов — без подсветки, это нормально.

Вне скоупа (сейчас)​

  • Отдельная таблица MessageMention.
  • Обращения по роли (r) и @всех — формат r только зарезервирован.
  • Отдельные уведомления / тип для упомянутых.
  • Фильтр / список «обращения ко мне».
  • Клик по упоминанию → карточка сотрудника (опционально позже).
  • Реакции, reply/thread, вложения, deep-link на сообщение, email.

Открытые вопросы (к заказчику / дефолт тимлида)​

ВопросДефолт для старта реализации (если нет ответа)
Только участники чата или любой сотрудник?Только активные участники чата, без автодобавления
Можно ли упомянуть себя?Разрешить
Нужен ли фильтр «ко мне»?Нет в MVP

Порядок работ​

  1. Спека токена + общий парсер (бек и фронт, одна грамматика).
  2. Бек: валидация при Add/Update; общая очистка текста для уведомлений, push, last message.
  3. Фронт: кнопка, триггер @, общий автокомплит, вставка, подсветка в ленте, edit.
  4. Проверка: несколько mentions, edit, закрытый чат, превью списка чатов, колокольчик и push без сырых @{…} / guid.

Связанные файлы​

СлойГде
Бек сообщенияServices/Notification/Services/MessageService.cs
Бек сущностиModels/Entities/Notification/MessageEntity.cs
Фронт вводwidgets/chat/message-input.tsx
Фронт пузырьentities/chat/ui/components/message-item.tsx
Типыentities/chat/model/chat.type.ts
Список чатов (preview)ChatService / карточка чата — читаемый текст без guid
Уведомления / pushMessageService.Add → NotificationService / WebPush — тот же читаемый текст