ds-galo/openspec/changes/safe-album-offload/design.md

Design

Context

См. proposal.md — Why. Ниже — что в коде определяет подход.

• SyncCoordinator.reconcile получает serverChecksums(link.serverAlbumId) и вычисляет livePhotoIds = serverChecksums.values.toSet(), но SyncPlanner.plan и offloadUploaded этот набор не используют: первый смотрит только на indexed.serverPhotoId != null, второй — на entity.serverPhotoId != null. reflectLostCopies умеет лишь перекрасить PREVIEW ↔ ORPHANED и тоже по livePhotoIds.
• Разгрузка вызывается из трёх мест: SyncCoordinator.offloadUploaded (режим C), UploadWorker.recordProvenance (сразу после успешной загрузки) и DeviceAlbumViewModel.freeSpace (ручное освобождение по согласию системы).
• AssetOffloader.offload(asset) не требует доказательств, что копия жива.
• SyncRepository.link перезаписывает serverAlbumId; смену цели обслуживают DeviceAlbumViewModel.setTarget и createAlbum — оба просто линкуют и запускают reconcile.
• Серверный перенос фото есть: SyncRemote.movePhotos → POST /api/photo-batch/move, который пропускает удалённые фото и возвращает число перенесённых, не сообщая об ошибке за пропуск.
• LocalAssetState.ORPHANED уже вычисляется и показывается перечёркнутым облаком на элементе; счётчика и заметного предупреждения нет.

Goals / Non-Goals

Goals:

• Сделать невозможной разгрузку без подтверждённой копии в текущем целевом альбоме.
• Не терять связь с уже загруженными фото при смене целевого альбома.
• Сделать потерю серверной копии видимой и оставить её устранение явным действием.

Non-Goals:

• Восстановление уже потерянных копий из корзины сервера.
• Предупреждение об удалении серверного альбома из веб-клиента: сервер и веб не знают о зависимости альбома устройства.
• Ручные загрузки в серверный альбом и их режимы.

Decisions

Единственный источник доверия — живой список фото целевого альбома. И plan, и разгрузка опираются на livePhotoIds, уже полученный в reconcile. Альтернатива — отдельный запрос «фото существует» — отклонена: лишние round-trip и рассинхрон.

Планировщик лечит устаревшую запись, а не игнорирует её. Ветка «записанный photoId» срабатывает только если photoId ∈ livePhotoIds; иначе ассет проходит обычный путь: дедуп по контрольной сумме, а при отсутствии — загрузка. Удаление серверных фото в конце плана тоже ограничено livePhotoIds, чтобы не тронуть чужую копию.

Разгрузка требует доказательства в подписи. AssetOffloader.offload(asset, liveServerPhotoIds) и новый исход OffloadResult.NotOnServer, если копии нет. Так инвариант живёт в одном месте, а вызывающий обязан доказать, что копия жива:

• offloadUploaded передаёт livePhotoIds из reconcile;
• recordProvenance передаёт setOf(photo.id) — только что созданное фото;
• freeSpace сначала читает serverChecksums текущего линка и передаёт его значения; при ошибке не разгружает ничего.

Смена цели — транзакция «перенести, проверить, переключить». SyncCoordinator.retarget переносит фото провенанса этого альбома в новый альбом, затем перечитывает новый альбом и убеждается, что все переносимые копии на месте; только тогда переключает связь. Если прежний альбом недоступен или копии не доехали — связь остаётся прежней, результат возвращается как отказ. Альтернатива «переключить и попробовать потом» отклонена: именно она дала инцидент.

Уже потерянные копии не блокируют смену цели, но сообщаются. Фото, которых нет ни в прежнем альбоме, ни в новом (например, давно осиротевшие), перенести нельзя; они считаются и возвращаются в результате, чтобы пользователь знал, но не мешают переключить альбом.

Потеря копии показывается из ORPHANED, а не из проверки существования альбома. Существование целевого альбома при офлайне недоказуемо, а ORPHANED выставляется только после успешного чтения альбома. Один новый запрос GROUP BY deviceAlbumId по state = 'ORPHANED' даёт счётчик для карточки и баннера; на карточке потеря копии перекрывает прогресс операции.

Risks / Trade-offs

• [Перенос пропускает удалённые фото без ошибки] → проверяем результат чтением нового альбома, а не ответом move; ненулевое расхождение — отказ.
• [Лишние serverChecksums в freeSpace и retarget] → это редкие явные действия, не цикл; при ошибке сети ничего не разгружаем и не переключаем.
• [Планировщик начинает перезаливать содержимое, если сервер не отдал контрольную сумму] → serverChecksums падает вместе с reconcile (исключение до применения плана), поэтому «пустой живой список из-за ошибки» не доходит до загрузок.
• [Счётчик ORPHANED в карточке устаревает между проходами] → приемлемо: он обновляется тем же потоком Room, что и всё представление, и означает «на последнем успешном проходе».

Migration Plan

Схема Room не меняется; миграций нет. Откат — обычная сборка без изменения.

Open Questions

• Нужен ли отдельный сценарий «перенести потерянные копии из прежнего альбома» как ручное действие, когда включённый режим уже сменился — отдельным изменением.