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

2026-09-08 — Файлы и изображения в чатах

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

Актуальная карта: chats.md (§ «Вложения и превью»), user-guide: notifications-and-chats.md. Thumbs (лёгкое превью): ITR-2999, chat-attachment-thumbs.md.

После ITR-3111: ограничения по типу и размеру основного файла сняты (проверки на беке/фронте помечены obsolete, не удалены). Остаётся лимит до 10 файлов на сообщение; для растровых картинок по-прежнему нужен thumb. Ниже — исходное ТЗ MVP (whitelist / 20 МБ) как история согласования.

Источник / заказчики: Максим; Олег

Эпик: ITR-2993

Связанные эпики: обращения в чатах (ITR-2912) — mentions в тексте; вложения — отдельная возможность, отображаются под текстом. Настоящие thumbs (вариант 3 превью) — ITR-2999.

Цель​

Дать участникам чатов возможность прикреплять к сообщению изображения и рабочие документы (офисные файлы, PDF, чертежи DXF, текстовые .txt), чтобы обмениваться материалами прямо в переписке по заказу или в личном/групповом чате — без пересылки только через внешние каналы.

На первом этапе — безопасный и простой MVP: понятные лимиты, строгий список типов файлов, хранение вне Google Drive (лимит объёма), превью картинок в ленте (после ITR-2999 — лёгкий thumb; до него / для legacy без thumb — оригинал), просмотр крупнее по клику и скачивание документов участниками чата.

Контекст​

Как было (до эпика)​

  • В чатах с UI можно было отправлять только текст (в т.ч. обращения); прикрепить файл из интерфейса нельзя.
  • Файлы по системе в целом часто жили в Google Drive; для чатов это не подходит как основное хранилище вложений — у Drive ограниченный объём (~10 Гб).

Как сейчас (после реализации)​

  • Отправка с UI: multipart …/Message/with-attachments (текст + файлы; для картинок — ещё thumbs, см. ITR-2999).
  • Хранение в S3; скачивание через бек только участникам чата.
  • В ленте — вложения под текстом; документы — имя, размер, скачать; картинки — превью (thumb при наличии, иначе оригинал), по клику — крупный просмотр.
  • ITR-3111: тип и размер основного файла не ограничиваются; лимит количества — до 10.

Как должно быть (зафиксировано в ТЗ)​

  • К сообщению можно прикрепить одно или несколько вложений (картинки и/или документы из разрешённого списка).
  • Текст может быть подписью к файлам или отсутствовать, если есть хотя бы одно вложение.
  • В ленте чата вложения видны под текстом сообщения.
  • Картинки в ленте: в ITR-2993 — превью по оригиналу; после ITR-2999 — лёгкий thumb, оригинал по клику (legacy без thumb — оригинал в ленте).
  • Документы — имя, размер, скачивание.
  • В списке чатов и в уведомлениях — краткая подпись («Фото», имя файла, «N файлов»), а не ссылка на хранилище.
  • Хранение вложений — в объектном хранилище (S3), по той же инфраструктурной линии, что логи; на время разработки — общая корзина с логами и отдельным префиксом путей; позже — отдельные корзины для чатов (stage / prod).

Пользовательские сценарии​

  1. Отправка фото с подписью. Сотрудник в чате заказа прикрепляет 1–несколько фото (например, брак на производстве), пишет короткий комментарий, отправляет. Участники видят превью картинок уже в ленте; по клику открывают крупнее; в уведомлении — подпись и указание, что есть фото.
  2. Только файлы без текста. Сотрудник прикрепляет PDF или Excel и отправляет без текста. Сообщение уходит; в списке чатов / уведомлении — имя файла или «N файлов».
  3. Чертёж DXF. Конструктор прикрепляет .dxf (если браузер передаёт допустимый тип файла — см. политику ниже). Участник скачивает файл через систему (не публичная ссылка).
  4. Несколько разных вложений. В одном сообщении — и картинки, и документы, в пределах лимитов (размер и количество).
  5. Отказ в сомнительном файле. Пользователь выбирает файл с «неизвестным» типом (octet-stream), exe, SVG, HTML или тип вне списка — система не принимает вложение, отправка с этим файлом не проходит (понятная ошибка).
  6. Редактирование. Автор правит только текст сообщения; состав вложений не меняется.
  7. Удаление. Автор удаляет сообщение — в ленте «Сообщение удалено», вложения недоступны для просмотра и скачивания; файлы из хранилища система пытается удалить сразу. Сведения о том, что вложения были, для служебных нужд сохраняются.
  8. Права. Загрузить и скачать вложение могут только те, кто уже может писать / читать этот чат (те же правила доступа, что у сообщений).

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

Продукт и UX​

ТемаРешение
Типы на MVPКартинки (без SVG) + .pdf, .doc, .docx, .xls, .xlsx, .dxf, .txt
Число вложенийНесколько, до 10 на сообщение
Размер файлаДо 20 МБ на файл
ТекстПодпись к вложениям; отдельное поле «caption» не вводим. Пустой текст без вложений — запрещён; с вложениями — разрешён
Расположение в UIВложения под текстом; mentions только в тексте
РедактированиеТолько текст; набор файлов после отправки не меняется
Удаление сообщенияUI как у удалённого сообщения; скачивание/просмотр вложений закрыты; объекты в S3 удаляем сразу; метаданные вложений оставляем
Last message / push«Фото» / имя файла / «N файлов» (+ подпись, если есть); без URL и ключей хранилища
Превью картинокВариант 2 (этот эпик): в ленте сразу видно изображение — грузится оригинал, отображение уменьшает браузер (CSS). По клику — модалка / крупный просмотр того же файла. Отдельной уменьшенной копии в хранилище нет. Вариант 3 (ITR-2999): настоящие thumbs — отдельный лёгкий файл для ленты, оригинал по клику
Документы в лентеИмя, размер, скачать

Превью изображений: варианты (чтобы не путать термины)​

ВариантЧто в лентеОтдельный файл-копияГде
1. ЗаглушкаПлейсхолдер; картинка только по кликуНетНе берём в реализацию (отвергли в пользу варианта 2)
2. Превью оригиналаКартинка видна сразу; грузится полный файлНетЭтот эпик (ITR-2993)
3. Настоящий thumbВ ленте лёгкая уменьшенная копия; оригинал по кликуДа (генерация на фронте, хранение пары файлов)ITR-2999

Хранение и доступ​

ТемаРешение
Где хранитьS3-совместимое хранилище, не Google Drive
На время разработкиКорзина логов + отдельный префикс путей для чатов
ПозжеОтдельные корзины чатов для stage и prod; конфиг имени корзины и префикса — с первого дня
ПубличностьКорзина не публичная
Скачивание (MVP)Через приложение (бек отдаёт файл участнику чата)
Signed URLОпционально позже. Signed URL — временная подписанная ссылка на файл в S3: браузер качает напрямую из хранилища, без прокачки байтов через бек; ссылка сама истекает через короткое время
Загрузка (MVP)Один запрос: текст + файлы вместе (multipart)
Двухшаговая загрузка (сначала файл, потом сообщение)Опционально позже

Модель данных​

  • Вложения — отдельная таблица (связь 1:N с сообщением), не колонки «файл» на самом сообщении и не FileLink заказа (Drive).
  • Текст сообщения: при наличии вложений — пустая строка (не null), чтобы не усложнять поиск; отдельного поля caption нет. Валидация: непустой текст или хотя бы одно вложение.
  • Preview для списка чатов / уведомлений в БД не храним — формулировки собираются при отдаче / создании уведомления (как сейчас last message считается на лету).
  • После soft-delete сообщения строки вложений не удаляем (метаданные остаются); скачивание закрывается по факту удаления сообщения; объекты в S3 удаляем сразу.

Таблица вложений (ориентир полей):

ПолеНазначение
IdИдентификатор
MessageIdСообщение
SortOrderПорядок в UI
FileNameИсходное имя файла
ContentTypeMIME
SizeBytesРазмер оригинала
StorageKeyКлюч объекта в S3 (не публичный URL)
ThumbStorageKeyКлюч thumb в S3; в ITR-2993 всегда пусто
ThumbContentTypeMIME thumb; в ITR-2993 пусто
ThumbSizeBytesРазмер thumb; в ITR-2993 пусто

Не добавляем на вложение UploadedById / UploadedAt: при multipart «текст + файлы вместе» это дублирует отправителя и дату сообщения. Имеет смысл только при двухшаговой загрузке (вне MVP).

Thumb в схеме сразу (nullable): в ITR-2993 поля thumb не заполняются (вариант 2 — только оригинал). В ITR-2999 заполняются без второй ломки таблицы. Отдельную таблицу thumbs и несколько размеров (xs/md) не закладываем.

Индекс по сообщению + порядку (например MessageId, SortOrder).

Безопасность и типы файлов (строгая политика)​

Принцип MVP: резать всё сомнительное. Файл принимается только если и расширение, и заявленный тип (Content-Type) входят в согласованный whitelist. Иначе — отказ.

  • application/octet-stream, пустой или неизвестный MIME — отклонять, даже если расширение «правильное» (в т.ч. типичный случай для .dxf в некоторых браузерах).
  • SVG, HTML, исполняемые и скрипты — не принимать.
  • Антивирус на MVP не делаем; опора на whitelist, лимиты и права доступа к чату.
  • Проверка на клиенте и на сервере; при возможности дополнительно сверять «магические» байты для типов, где это надёжно (например jpeg/png/pdf).

Картинки (ориентир MIME): image/jpeg, image/png, image/webp, image/gif — без image/svg+xml.

Документы (расширение → допустимые MIME, ориентир):

РасширениеДопустимые типы (ориентир)
.pdfapplication/pdf
.docapplication/msword
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.xlsapplication/vnd.ms-excel
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.dxfузкий список вроде image/vnd.dxf / application/dxf / application/x-dxf (без octet-stream)
.txttext/plain

Презентации (.ppt / .pptx) и OpenDocument в MVP не входят.

Известный компромисс: часть пользователей может не суметь прикрепить .dxf (или реже старые office), если браузер шлёт octet-stream. Это принятый риск строгой политики; при массовых жалобах политику можно смягчить отдельным решением, не размывая MVP сейчас.

Уведомления и обновление ленты​

  • Уведомление о новом сообщении с вложениями: краткий текст («Фото» / имя / «N файлов» + подпись), без бинарника.
  • Отдельный канал realtime только под сообщения на MVP не делаем — достаточно текущей схемы обновления чата по уведомлениям.
  • Превью для списка чатов и push — текстовая строка при создании сообщения, не второй файл в хранилище.

Этапы (границы эпика)​

ТемаВ этом эпике (MVP)Позже / вне эпика
ТипыКартинки + pdf/doc/docx/xls/xlsx/dxf/txtРасширение списка по запросу
ЗагрузкаТекст + файлы одним запросомДвухшаговая загрузка
СкачиваниеЧерез бекSigned URL (временная прямая ссылка на S3)
Превью картинокВариант 2: оригинал в ленте (без thumb-файла)Вариант 3: настоящие thumbs — ITR-2999
КорзиныОбщая с логами + префиксОтдельные chat-корзины
Удаление из S3Сразу при удалении сообщенияБолее сложный GC при необходимости

Открытые вопросы​

  • Нет блокирующих продуктовых вопросов после первоначального обсуждения.
  • На реализации (не блокирует согласование ТЗ): при сбое удаления файла из S3 после удаления сообщения — достаточно лога или нужен простой повтор; точная таблица MIME для .dxf по фактическому поведению браузеров (в рамках строгой политики, без octet-stream).

Критерии приёмки​

  1. В чате можно отправить сообщение с 1–10 вложениями; один файл — не больше 20 МБ.
  2. Принимаются только файлы из whitelist (картинки jpeg/png/webp/gif и документы pdf/doc/docx/xls/xlsx/dxf/txt) при совпадении расширения и Content-Type; сомнительные типы (в т.ч. octet-stream, SVG, HTML, exe) — отклоняются с понятной ошибкой.
  3. Сообщение только с вложениями (без текста) отправляется; сообщение без текста и без вложений — нет.
  4. В ленте вложения под текстом; картинка сразу видна как превью оригинала (без отдельного thumb-файла), по клику — крупный просмотр; документ — имя, размер, скачивание.
  5. Скачать / открыть вложение может только участник этого чата; прямого публичного доступа к файлу в хранилище нет.
  6. В списке чатов и в уведомлении о новом сообщении — краткая человекочитаемая формулировка, не URL хранилища.
  7. Редактирование меняет только текст; состав вложений не меняется.
  8. После удаления сообщения вложения в UI недоступны; система пытается удалить файлы из хранилища; повторно скачать удалённое вложение нельзя.
  9. Обращения (mentions) в тексте продолжают работать; вложения на них не завязаны.
  10. На этапе разработки вложения попадают в объектное хранилище с отдельным префиксом (не смешиваются с логами как с «простым сбросом файлов без правил»); смена корзины на отдельные chat-корзины возможна через конфигурацию без переделки идеи хранения.

Задачи эпика​

#ЗадачаСодержание
1Задача 1. Бек. Хранение и отправка вложенийПрикладной клиент S3 и конфиг корзины/префикса (сейчас S3 только у логов); сохранение файлов при отправке сообщения (multipart текст + файлы); метаданные вложений; строгий whitelist и лимиты 20 МБ / 10 шт.; текст опционален при наличии вложений
2Задача 2. Бек. Скачивание и удалениеСкачивание через бек только участникам чата; при удалении сообщения — сразу удалять объекты из S3, метаданные оставлять, download закрыть
3Задача 3. Бек. Preview в уведомлениях и списке чатовЧеловекочитаемые формулировки («Фото» / имя файла / «N файлов» + подпись); без URL и ключей хранилища; mentions без сырых токенов
4Задача 4. Фронт. Отправка вложенийВыбор файлов в чате; клиентские лимиты и ошибки; multipart-отправка; согласование с контрактом задачи 1
5Задача 5. Фронт. Лента, просмотр и скачиваниеВложения под текстом; превью картинки в ленте по оригиналу (вариант 2) + крупный просмотр по клику; документ — имя, размер, скачать; редактирование только текста
6Задача 6. Фронт. Список чатов и уведомленияОтображение кратких формулировок last message / уведомлений (согласовано с задачей 3)
7Задача 7. Документация. Пользовательские материалыКак прикреплять файлы; допустимые типы и лимиты; просмотр и скачивание; поведение после удаления сообщения

Порядок: задача 1 → 2 и 3; фронт 4 — после контракта из 1 (или параллельно на согласованном API); 5 опирается на 1–2; 6 — на 3; 7 — к приёмке / после реализации.