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

2026-09-09 — Thumbs (уменьшенные превью) вложений в чатах

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

Актуальная карта: chats.md (§ «Вложения и превью»), user-guide: notifications-and-chats.md. База вложений: chat-attachments.md (ITR-2993).

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

Эпик: ITR-2999

База: файлы и изображения в чатах (ITR-2993, chat-attachments) — вложения, хранение в S3. Этот эпик — вариант 3: настоящие thumbs для ленты (вместо превью полным оригиналом).

Цель​

Ускорить и облегчить ленту чата: для изображений в ленте показывать лёгкую уменьшенную копию (thumb), а полный оригинал открывать по клику (крупный просмотр) или при скачивании. Документы по-прежнему без thumb — имя, размер, скачивание.

Контекст​

Как было (после ITR-2993, до thumbs)​

  • К сообщению можно прикрепить изображения и рабочие документы; хранение в S3; скачивание только участникам чата.
  • В ленте картинка сразу видна, но грузился полный оригинал (браузер только уменьшал отображение).
  • В схеме вложения уже были nullable-поля под thumb (ThumbStorageKey, ThumbContentType, ThumbSizeBytes) — в ITR-2993 не заполнялись.
  • Бэкфилл уже отправленных картинок не планировался и не делался.

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

  • При отправке новых картинок (jpeg/png/webp/gif) клиент готовит JPEG-thumb (длинная сторона ≤ 800, quality 0.8) и шлёт вместе с оригиналом; без thumb отправка отклоняется.
  • В ленте — thumb при наличии; по клику — оригинал. Старые вложения без thumb — оригинал в ленте.
  • GIF: в ленте статичный thumb (первый кадр); по клику — исходный GIF.
  • Документы без thumb; список чатов / push без изменений.

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

  • При отправке нового сообщения с картинкой клиент готовит JPEG-thumb и передаёт его вместе с оригиналом.
  • В ленте для картинки с thumb показывается thumb; по клику — оригинал в модалке.
  • Для старых вложений без thumb (после ITR-2993) в ленте по-прежнему оригинал — без миграции данных.
  • Список чатов и push-уведомления не меняются (текстовые формулировки «Фото» / имя файла и т.п. из ITR-2993).

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

  1. Отправка фото. Сотрудник прикрепляет jpeg/png/webp/gif (в т.ч. несколько). Система готовит превью; после отправки в ленте видны лёгкие превью, по клику — полные файлы.
  2. GIF. В ленте — статичное превью (первый кадр); по клику открывается исходный GIF (с анимацией, если она есть).
  3. Сбой подготовки превью. Превью для выбранного файла не удалось создать — отправка заблокирована; у файла можно повторить подготовку превью или убрать файл из набора. Не нужно заново выбирать файл с диска, если достаточно повтора.
  4. Документ без картинок. PDF/Office/DXF/txt — как в ITR-2993, без thumb.
  5. Старое сообщение. Сообщение с картинкой, отправленное до этого эпика (thumb нет) — в ленте показывается оригинал, поведение не ломается.
  6. Удаление. Автор удаляет сообщение — недоступны и оригинал, и thumb; система пытается удалить оба объекта из хранилища.

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

Продукт и UX​

ТемаРешение
Генерация thumbНа фронте при подготовке отправки (не на беке, не фоновой очередью)
РазмерДлинная сторона ≤ 800 px, пропорции сохранить (contain), без кропа
Формат и качествоJPEG, quality 0.8 (одна константа; при необходимости подкрутить позже)
Для каких файловВсе изображения из whitelist ITR-2993: jpeg, png, webp, gif
GIFБез отдельной ветки «анимация / статика»: thumb = первый кадр → JPEG; в ленте превью, по клику — исходный файл
Обязательность (новые)Thumb обязателен для каждой новой картинки: без успешного thumb отправка невозможна; бек отклоняет картинку без thumb
Сбой генерацииПонятная ошибка у файла; действие «Повторить» подготовку превью для уже выбранного файла; можно удалить файл из набора
ДокументыThumb не создаём и не требуем
Лента (чтение)Есть thumb → показывать thumb; нет thumb (legacy) → оригинал, как в ITR-2993
Клик по картинкеКрупный просмотр / модалка — оригинал
Список чатов / pushБез изменений относительно ITR-2993
БэкфиллНе делаем — только новые сообщения
Несколько размеров thumbНет — один thumb на вложение

Передача и хранение​

ТемаРешение
Контракт отправкиMultipart: к каждому image-файлу в том же порядке передаётся part с thumb; у документов part thumb нет
Поля в БДЗаполняются уже заложенные ThumbStorageKey / ThumbContentType / ThumbSizeBytes
ДоступОтдача thumb только участникам чата (те же правила, что у оригинала)
Удаление из S3При удалении сообщения удалять пару: оригинал и thumb (если ключ был); метаданные вложений как в ITR-2993
Флаги вроде skipThumb / isAnimatedНе вводим

Границы эпика​

ТемаВ этом эпикеВне эпика
Превью картинокВариант 3: настоящий thumb в ленте—
ГенерацияНа клиенте при отправкеГенерация на беке / очередь
Старые сообщенияПоказ оригинала без thumbБэкфилл / пересчёт thumbs
Signed URL, двухшаговая загрузка—Как в ITR-2993 «позже»

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

  • Нет блокирующих продуктовых вопросов после обсуждения.
  • На реализации (не блокирует ТЗ): точные имена multipart-полей согласовать с контрактом ITR-2993; при частичном сбое удаления thumb/оригинала из S3 — достаточно лога (как для оригинала в ITR-2993).

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

  1. При отправке сообщения с изображениями (jpeg/png/webp/gif) для каждой картинки создаётся и сохраняется JPEG-thumb (длинная сторона ≤ 800, без кропа); без thumb отправка на клиенте недоступна, бек такую картинку не принимает.
  2. В ленте у новых картинок отображается thumb; по клику открывается оригинал.
  3. Для GIF в ленте — статичное JPEG-превью; анимация (если есть) видна при открытии оригинала.
  4. Документы отправляются без thumb; поведение как в ITR-2993.
  5. Если подготовка превью упала — отправка блокируется; можно повторить подготовку для выбранного файла или убрать файл.
  6. Сообщения с картинками без thumb (до этого эпика) по-прежнему открываются в ленте по оригиналу; массового бэкфилла нет.
  7. После удаления сообщения недоступны оригинал и thumb; система пытается удалить оба объекта из хранилища.
  8. Скачать / открыть thumb и оригинал может только участник чата.
  9. Список чатов и текст уведомлений о новом сообщении не требуют доработки под этот эпик.

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

#ЗадачаСодержание
1Задача 1. Бек. Приём и хранение thumbПри multipart-отправке принимать thumb в том же порядке, что image-файлы; для каждой новой картинки thumb обязателен; заполнять Thumb*; отдавать thumb участникам чата
2Задача 2. Бек. Удаление пары оригинал + thumbПри удалении сообщения удалять из S3 и оригинал, и thumb (если был); метаданные и закрытие доступа — в логике ITR-2993
3Задача 3. Фронт. Генерация thumb и отправкаРесайз (≤ 800, contain) → JPEG 0.8; для всех картинок включая GIF (первый кадр); повтор при ошибке; multipart thumbs в том же порядке; блок отправки без успешного thumb
4Задача 4. Фронт. Лента и просмотрВ ленте — thumb при наличии, иначе оригинал (legacy); по клику — оригинал в модалке
5Задача 5. Документация. Пользовательские материалыПри необходимости кратко: в ленте превью, полный файл по клику; без отдельной пользовательской настройки thumbs

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