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).
Пользовательские сценарии
- Отправка фото. Сотрудник прикрепляет jpeg/png/webp/gif (в т.ч. несколько). Система готовит превью; после отправки в ленте видны лёгкие превью, по клику — полные файлы.
- GIF. В ленте — статичное превью (первый кадр); по клику открывается исходный GIF (с анимацией, если она есть).
- Сбой подготовки превью. Превью для выбранного файла не удалось создать — отправка заблокирована; у файла можно повторить подготовку превью или убрать файл из набора. Не нужно заново выбирать файл с диска, если достаточно повтора.
- Документ без картинок. PDF/Office/DXF/txt — как в ITR-2993, без thumb.
- Старое сообщение. Сообщение с картинкой, отправленное до этого эпика (thumb нет) — в ленте показывается оригинал, поведение не ломается.
- Удаление. Автор удаляет сообщение — недоступны и оригинал, и 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).
Критерии приёмки
- При отправке сообщения с изображениями (jpeg/png/webp/gif) для каждой картинки создаётся и сохраняется JPEG-thumb (длинная сторона ≤ 800, без кропа); без thumb отправка на клиенте недоступна, бек такую картинку не принимает.
- В ленте у новых картинок отображается thumb; по клику открывается оригинал.
- Для GIF в ленте — статичное JPEG-превью; анимация (если есть) видна при открытии оригинала.
- Документы отправляются без thumb; поведение как в ITR-2993.
- Если подготовка превью упала — отправка блокируется; можно повторить подготовку для выбранного файла или убрать файл.
- Сообщения с картинками без thumb (до этого эпика) по-прежнему открываются в ленте по оригиналу; массового бэкфилла нет.
- После удаления сообщения недоступны оригинал и thumb; система пытается удалить оба объекта из хранилища.
- Скачать / открыть thumb и оригинал может только участник чата.
- Список чатов и текст уведомлений о новом сообщении не требуют доработки под этот эпик.
Задачи эпика
| # | Задача | Содержание |
|---|---|---|
| 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 — к приёмке / после реализации.