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–несколько фото (например, брак на производстве), пишет короткий комментарий, отправляет. Участники видят превью картинок уже в ленте; по клику открывают крупнее; в уведомлении — подпись и указание, что есть фото.
- Только файлы без текста. Сотрудник прикрепляет PDF или Excel и отправляет без текста. Сообщение уходит; в списке чатов / уведомлении — имя файла или «N файлов».
- Чертёж DXF. Конструктор прикрепляет
.dxf(если браузер передаёт допустимый тип файла — см. политику ниже). Участник скачивает файл через систему (не публичная ссылка). - Несколько разных вложений. В одном сообщении — и картинки, и документы, в пределах лимитов (размер и количество).
- Отказ в сомнительном файле. Пользователь выбирает файл с «неизвестным» типом (
octet-stream), exe, SVG, HTML или тип вне списка — система не принимает вложение, отправка с этим файлом не проходит (понятная ошибка). - Редактирование. Автор правит только текст сообщения; состав вложений не меняется.
- Удаление. Автор удаляет сообщение — в ленте «Сообщение удалено», вложения недоступны для просмотра и скачивания; файлы из хранилища система пытается удалить сразу. Сведения о том, что вложения были, для служебных нужд сохраняются.
- Права. Загрузить и скачать вложение могут только те, кто уже может писать / читать этот чат (те же правила доступа, что у сообщений).
Принятые решения
Продукт и 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 | Исходное имя файла |
| ContentType | MIME |
| SizeBytes | Размер оригинала |
| StorageKey | Ключ объекта в S3 (не публичный URL) |
| ThumbStorageKey | Ключ thumb в S3; в ITR-2993 всегда пусто |
| ThumbContentType | MIME 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, ориентир):
| Расширение | Допустимые типы (ориентир) |
|---|---|
.pdf | application/pdf |
.doc | application/msword |
.docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
.xls | application/vnd.ms-excel |
.xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
.dxf | узкий список вроде image/vnd.dxf / application/dxf / application/x-dxf (без octet-stream) |
.txt | text/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–10 вложениями; один файл — не больше 20 МБ.
- Принимаются только файлы из whitelist (картинки jpeg/png/webp/gif и документы pdf/doc/docx/xls/xlsx/dxf/txt) при совпадении расширения и Content-Type; сомнительные типы (в т.ч.
octet-stream, SVG, HTML, exe) — отклоняются с понятной ошибкой. - Сообщение только с вложениями (без текста) отправляется; сообщение без текста и без вложений — нет.
- В ленте вложения под текстом; картинка сразу видна как превью оригинала (без отдельного thumb-файла), по клику — крупный просмотр; документ — имя, размер, скачивание.
- Скачать / открыть вложение может только участник этого чата; прямого публичного доступа к файлу в хранилище нет.
- В списке чатов и в уведомлении о новом сообщении — краткая человекочитаемая формулировка, не URL хранилища.
- Редактирование меняет только текст; состав вложений не меняется.
- После удаления сообщения вложения в UI недоступны; система пытается удалить файлы из хранилища; повторно скачать удалённое вложение нельзя.
- Обращения (mentions) в тексте продолжают работать; вложения на них не завязаны.
- На этапе разработки вложения попадают в объектное хранилище с отдельным префиксом (не смешиваются с логами как с «простым сбросом файлов без правил»); смена корзины на отдельные 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 — к приёмке / после реализации.