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:
- Сохраняется текст как есть.
- Всем активным участникам кроме отправителя создаётся уведомление типа
Chat(Header = "Новое сообщение",Text = текст сообщения,ChatId). - Уведомление уходит через 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:
- Принять
textс токенами. - Распарсить все
@{type:id:display}. - Для
e: проверить, чтоid— активный участник чата (дефолт скоупа; уточнение у заказчика — ниже). - Для неизвестного type / битого guid / битой разметки — ошибка валидации.
- Сохранить
textкак есть. - Уведомления — без спец-логики «вас упомянули»; перед записью/отправкой в
Notification.Textи в push прогнать текст через общую функцию: токены →@Display(чтобы в пуше не утекли guid). То же дляlastMessageTextв списке чатов.
Отдельное поле mentionedEmployeeIds в request не нужно — ids внутри токенов.
Поведение фронта (ориентир)
- Модель ввода хранит raw-строку с токенами (или внутренние segments → перед send сборка в raw).
- В поле пользователь видит
@Display. - Кнопка и ввод
@: один автокомплит по участникам чата → вставка@{e:id:display}. message-item: парсинг → подсветка@Display.- Общая функция «токены → читаемый текст»:
@{e:guid:Вася}…→@Вася…. Использовать для превью списка чатов, колокольчика и обязательно для push (и любого другого места, куда уходит текст уведомления). В ленте сообщений — отдельный парсинг с подсветкой, не путать с этой очисткой.
Желаемое поведение (продукт)
- В строке ввода — кнопка обращения; также можно начать обращение символом
@. Оба пути — один автокомплит по участникам. - После выбора в текст вставляется обращение; пользователь видит
@Имя. - В ленте обращения визуально выделены.
- Редактирование сообщения умеет менять текст и обращения целиком.
- Старые сообщения до фичи остаются plain text без токенов — без подсветки, это нормально.
Вне скоупа (сейчас)
- Отдельная таблица
MessageMention. - Обращения по роли (
r) и@всех— форматrтолько зарезервирован. - Отдельные уведомления / тип для упомянутых.
- Фильтр / список «обращения ко мне».
- Клик по упоминанию → карточка сотрудника (опционально позже).
- Реакции, reply/thread, вложения, deep-link на сообщение, email.
Открытые вопросы (к заказчику / дефолт тимлида)
| Вопрос | Дефолт для старта реализации (если нет ответа) |
|---|---|
| Только участники чата или любой сотрудник? | Только активные участники чата, без автодобавления |
| Можно ли упомянуть себя? | Разрешить |
| Нужен ли фильтр «ко мне»? | Нет в MVP |
Порядок работ
- Спека токена + общий парсер (бек и фронт, одна грамматика).
- Бек: валидация при Add/Update; общая очистка текста для уведомлений, push, last message.
- Фронт: кнопка, триггер
@, общий автокомплит, вставка, подсветка в ленте, edit. - Проверка: несколько 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 |
| Уведомления / push | MessageService.Add → NotificationService / WebPush — тот же читаемый текст |