ds-galo/openspec/changes/archive/2026-10-15-album-live-sync/design.md

Design

Context

Мотивация — в proposal.md. Состояние, важное для подхода:

• Хаб internal/sse держит два независимых пространства подписок: albums[albumID] и users[userID]; публикация в личный канал уже реализована (PublishUser) и уже используется — единственным продюсером является notifications.Service.Create.
• Пер-альбомные события публикуются из albums.Service.Update/Delete, members.Service.Accept/ChangeRole/Remove, photos.Service, social.Service.
• Персональный поток GET /api/sse/me доступен клиентам, авторизация принимает токен в query-параметре, поэтому существующий web-обёртка SSEClient подходит без изменений.
• Объект альбома в ответе списка собирается SQL-выборкой с джойном обложки и подзапросами счётчиков (photos_count, members_count); albums.Service.Create и Update возвращают объект без обложки, поэтому его нельзя переиспользовать как payload события «как есть».
• Владелец альбома не входит в album_members: albums.owner_id — отдельный источник (владелец не меняет роль и не удаляется из состава).
• album_members ссылается на albums с ON DELETE CASCADE: после удаления альбома состав участников уже недоступен.
• Web-клиент подписан на SSE только на странице альбома; список альбомов загружается один раз за сессию и не обновляется по событиям. Android-парсер пер-альбомного потока игнорирует неизвестные типы событий.

Goals / Non-Goals

Goals:

• Доставлять события жизненного цикла альбома (создание, метаданные, состав, удаление) тем пользователям, у которых меняется список альбомов, независимо от того, что они смотрят.
• Обновлять список альбомов и счётчик photos_count при изменении состава фото (загрузка, перемещение, копирование, восстановление, корзина, окончательное удаление).
• Отдавать в событии объект альбома той же формы, что REST-список, чтобы клиент применял его без запроса.
• Дать web-клиенту единую подписку на персональный поток и догон состояния при реконнекте.

Non-Goals:

• Персистентные уведомления, их список и UI непрочитанных — не затрагиваются.
• Android-клиент не подключается к личному потоку в этом этапе; пер-альбомный контракт должен остаться прежним.
• Серверный обрыв пер-альбомного SSE при исключении участника не входит в этап.
• Новые HTTP-эндпоинты и изменения схемы БД не требуются.

Decisions

1. Канал доставки — существующий личный поток, веер по владельцу и участникам. Событие публикуется в личный канал каждого затронутого пользователя. Альтернативы: (а) публиковать только в канал альбома — не доходит до тех, кто его не смотрит, то есть не решает задачу; (б) новое пространство подписок «альбомы пользователя» — дублирует уже существующий личный канал без выигрыша; (в) WebSocket — ломает сложившийся механизм SSE и требует второго транспорта. Выбран веер по users[userID]: переиспользует готовую инфраструктуру и не меняет транспорт.

2. Payload — полный объект альбома, а не сигнал-инвалидация. Клиент применяет upsert/remove без запроса; порядок списка не меняется. Альтернатива — тонкий сигнал «список изменился» и рефетч: проще на сервере, но добавляет запрос на каждое изменение и оставляет окно, когда UI показывает старое состояние; при массовых операциях (приглашение нескольких участников) даёт несколько лишних запросов. Отвергнуто в пользу полного payload'а при том же объёме клиентской логики.

3. Источник payload'а — тот же код, что формирует элемент списка. Перед публикацией альбом перечитывается через Store.GetByID и обогащается attachCover, то есть формой он идентичен элементу GET /api/albums. Причина: Create/Update отдают объект без URL обложки, а Create — ещё и без счётчиков; сборка объекта вручную в точке публикации неизбежно разошлась бы с REST-формой.

4. Резолвер аудитории — лёгкий список идентификаторов пользователей. Нужен метод, возвращающий id владельца и id участников без джойна с users. Альтернатива — переиспользовать members.Repository.List, но он тянет PublicUser (join с users) и возвращает данные, которые никуда не идут; для веера это лишняя работа на каждое событие. Метод добавляется в репозиторий и закрывается интерфейсом в сервисах, как уже сделано для OwnerID.

5. Аудиторию удаления вычисляем до удаления альбома. Remove/Delete должны собрать список получателей заранее: album_members удаляется каскадом вместе с альбомом, а GetByID после удаления недоступен. Для album.deleted payload'у достаточно только id, поэтому перечитывать объект не нужно.

6. Для исключённого участника переиспользуем album.deleted. Отдельный тип («доступ отозван») не вводим: клиентская реакция одинакова — убрать альбом из списка и закрыть открытую страницу, а таксономия остаётся минимальной. Альтернатива — album.access.revoked/member.left в личном потоке: семантически точнее, но добавляет второй путь обработки и тип события ради отсутствующего сейчас UI-сообщения. Компромисс: если позже появятся текстовые уведомления («вас исключили»), тип придётся разделить — это зафиксировано в рисках.

7. Точки публикации.

Событие	Триггер	Получатели
album.created	создание альбома	владелец
album.created	принятие приглашения	приглашённый
album.updated	принятие приглашения	владелец и участники (кроме приглашённого)
album.updated	смена названия/описания/обложки	владелец и участники
album.updated	смена роли участника	владелец и участники
album.updated	исключение участника	владелец и оставшиеся участники
album.updated	загрузка/копирование/перемещение/восстановление/корзина/удаление фото	владелец и участники (личный поток)
photo.created	загрузка фото в альбом	подписчики канала альбома
album.deleted	удаление альбома	владелец и участники (аудитория до удаления)
album.deleted	исключение участника	исключённый

11. Изменения состава фото публикуются только в личный поток. album.updated при изменении состава фото уходит получателям в личные каналы, но не в канал альбома: открытая страница узнаёт об изменениях из пер-альбомных photo.created / photo.deleted, а пер-альбомный album.updated заставлял бы её перечитывать альбом через REST на каждое фото (массовая загрузка = поток лишних запросов). Личные каналы для карточек обходятся без REST. Дополнительно Upload публикует photo.created в канал альбома — это реализация уже существующего требования способности realtime («События альбома»), а не новый контракт.

12. photos_count считает только фото вне корзины. Запросы альбома добавляют deleted_at IS NULL к подзапросу счётчика в sqlite- и postgres-сторах. Причина: сейчас счётчик включал фото в корзине и расходился с сеткой, из-за чего «удаление» не меняло бы карточку. Так счётчик совпадает с видимым составом, а перевод в корзину, восстановление и окончательное удаление меняют его предсказуемо. Уже помещённые в корзину фото перестают учитываться без миграции данных.

8. Пер-альбомный album.updated сохраняется. Метаданные продолжают публиковаться и в канал альбома: его ждёт Android-парсер (обрабатывает album.updated/album.deleted как «перечитать альбом»), а открытая страница альбома делает идемпотентную перезагрузку. Снимать пер-альбомную публикацию означало бы ломать совместимость мобильного клиента ради экономии одного запроса.

9. Web: одна подписка на уровне layout'а приложения. Подписка на /api/sse/me живёт вместе с layout'ом (app), а не с отдельными страницами, чтобы соединение не пересоздавалось при навигации; обработчики вызывают методы стора albums (upsert/remove), onReconnect вызывает albums.load(). Альтернатива — подписка на каждой странице: дублирование соединений и логики.

10. Страница альбома при потере доступа. При событии удаления/потери доступа страница перестаёт отображать альбом и уходит на главную; отдельного сообщения пользователю в этом этапе не делаем (это уже область центра уведомлений). Обработка нужна с обоих потоков: страница подписана и на канал альбома, и косвенно на личный.

Risks / Trade-offs

• Дублирование album.updated (пер-альбомный и личный каналы) для открытой страницы → обработчики должны быть идемпотентны: личный делает upsert, страница — перезагрузку; лишний запрос на изменение метаданных принимаем осознанно.
• Веер O(участники) на каждое изменение → при больших альбомах это стоимость пропорциональна числу подписанных пользователей, а не числу участников (публикация уходит в хаб, у которого нет подписчика — no-op). Массовые операции с фото (batch-удаление, перемещение) публикуют album.updated на каждое фото: для получателя это дешёвый upsert в сторе, на сервере — перечитывание альбома и веер по личным каналам. Это принято осознанно; при необходимости батчи можно схлопнуть в одно событие на альбом.
• Backpressure хаба отключает медленного клиента → вместе с личным потоком клиент теряет и обновления списка; это уже существующее поведение SSE, и оно компенсируется догоном через albums.load() после переподключения.
• album.deleted для исключённого семантически перегружен → если появятся текстовые уведомления, потребуется отдельный тип события; изменение аддитивное.
• Исключённый участник продолжает получать пер-альбомный SSE до разрыва соединения (доступ проверяется только при подключении) → в этом этапе не закрывается, остаётся отдельной задачей; событие из личного потока закрывает список и открытую страницу, но не отменяет уже установленное соединение.
• URL обложки в payload'е может истечь (presigned для S3) → URL формируется тем же кодом и с тем же TTL, что в REST-ответе; при переподключении клиент получает свежий список.
• События SSE не имеют идентификаторов → повторная доставка и пропуски обрабатываются только догоном через REST; история событий не хранится.
• photo.created при загрузке приходит без URL вариантов (thumb/preview ещё не готовы) → клиент вставляет фото-заглушку, а пришедший позже photo.updated заполняет URL на месте; порядок сетки не меняется.
• photos_count теперь без корзины → у альбомов с фото в корзине отображаемое число уменьшится сразу после выката; данные не мигрируются.

Migration Plan

Изменение аддитивное: новых эндпоинтов и миграций нет, старые клиенты неизвестные события игнорируют, пер-альбомный контракт событий сохраняется.

1. Задеплоить сервер целиком (статика вшита в бинарник): публикации и веер начинают работать сразу, web-клиент подписку получает в том же артефакте.
2. Порядок отката: вернуть предыдущий бинарник — сервер снова публикует только пер-альбомные события, клиент в том же артефакте просто не получает событий в личном потоке и возвращается к загрузке списка при открытии страницы. Состояние БД не меняется (счётчик снова начнёт включать корзину — это поведение старого бинарника).
3. Проверка после выката: список альбомов на втором устройстве/вкладке обновляется без перезагрузки при переименовании, смене обложки, добавлении и исключении участника, загрузке/перемещении/восстановлении/удалении фото и удалении альбома; исключённый видит исчезновение альбома из списка, а открытая страница добавляет загруженное фото.