ds-galo/openspec/changes/archive/2026-10-16-phone-album-two-way-sync/design.md

# Design

## Context

Мотивацию см. в `proposal.md`, требования — в дельтах `specs/`. Здесь текущее состояние,
задающее подход.

- Движок синхронизации (`android/.../data/sync/*`) построен на локальном индексе Room:
  `SyncedAlbumEntity` (связь «альбом устройства → серверный», режим) и `DeviceAssetEntity`
  (ассет: `assetKey`, `contentHash`, `serverPhotoId`, `state`). Изменения считаются диффом
  «MediaStore сейчас ↔ индекс»; серверные фото читаются как `checksum → photoId`.
- «Своя загрузка» сегодня = наличие `serverPhotoId` в индексе. Иного признака владения нет;
  провенанс-метка (`ProvenanceStamp`) пишет `photo`, `hash`, `mode`, `asset`, но не различает
  «загрузил я» и «скачал я».
- Сервер уже отдаёт всё нужное: `preview_url`/`medium_url`/`original_url`, `?since=` для
  дельты, мягкое удаление (`SetDeleted`) и восстановление (`Restore`) из корзины. Изменений
  API не требуется.
- Файлы, записанные приложением в MediaStore (превью, постеры), ему принадлежат и
  изменяются/удаляются без системного диалога; чужие файлы (снимки пользователя) требуют
  `createWriteRequest`/`createDeleteRequest`.

## Goals / Non-Goals

**Goals:**

- Симметричный состав альбома: набор медиа на устройстве и на сервере совпадает, изменения
  состава ходят в обе стороны, режим задаёт только локальную полноту (B — оригиналы, C —
  превью).
- Явное разграничение происхождения элемента, пригодное для политики удалений, разгрузки и
  восстановления после переустановки.
- Идемпотентность и возобновляемость: надгробия против повторной материализации и эха,
  отсутствие дублей при гонках.
- Безопасность: удаление элемента не приводит к безвозвратной потере единственной копии без
  системного согласия и без возможности отката через корзину сервера.

**Non-Goals:**

- Серверная модель устройств/сессий синхронизации и разрешение конфликтов владения между
  пользователями; изменения схемы БД сервера.
- Транскодирование видео на устройстве; версионирование содержимого.
- Синхронизация вложенных папок/облачных «плейсхолдеров» сверх того, что отдаёт MediaStore.

## Decisions

### 1. Состав зеркалится, режим задаёт локальную полноту

Единица синхронизации — по-прежнему bucket MediaStore; но связанная пара трактуется как один
набор медиа. `mode` перестаёт влиять на состав и влияет только на то, чем представлен элемент
на устройстве: B — оригинал, C — превью (видео — постер).

*Альтернатива:* оставить одностороннее содержимое (устройство — источник) и отражать сервер
только метаданными. Отклонено: не даёт пользовательского ожидания «синхронизированный альбом
— один и тот же набор». *Альтернатива:* отдельный «альбом-зеркало» 1:1 вместо связи с
существующим. Отклонено: ломает уже принятый выбор цели и n:1.

### 2. Признак происхождения вместо «есть serverPhotoId»

`DeviceAssetEntity` получает явный `origin` (`OWN` | `MIRROR`). Политика удалений, разгрузка,
дедуп и восстановление читают его, а не наличие серверной ссылки. Провенанс-метка получает
тот же признак, чтобы `SyncRecovery` после переустановки не назвал скачанное «своим».

*Альтернатива:* выводить владение из `uploadedAt != null` или из `contentHash` — ненадёжно
после переустановки и при дедупликации. Отклонено.

### 3. Журнал удалений (надгробия)

Локальное удаление элемента записывается как надгробие (`photoId`, момент, состояние
«ожидает серверного удаления»). Проход не материализует элемент, пока надгробие не снято
подтверждением сервера или не истекло. Серверное `photo.deleted` идемпотентно: повтор
ничего не меняет.

*Альтернатива:* полагаться на дифф без журнала. Отклонено: между локальным удалением и
серверным DELETE элемент ещё виден на сервере и был бы скачан заново.

### 4. Двустороннее удаление с опорой на права и корзину

Удаление элемента → `DELETE /api/photos/:id` (мягко, в корзину). Серверное удаление → снятие
локального элемента. Для файла, снятого на устройстве и не принадлежащего приложению,
снятие требует системного согласия (`createDeleteRequest`); для файлов, записанных
приложением, — без диалога. Отказ сервера (403/нет прав) не роняет проход: операция
отмечается неуспешной и сообщается пользователю, остальные действия прохода выполняются.

Для **материализованного** (серверного) элемента намерением удалить считается только явное
удаление в приложении: тогда ставится надгробие и фото уходит на сервере. Если локальная
копия просто пропала (очистка галереи, перемещение файла), клиент фото на сервере не
трогает, а материализует заново — иначе потеря собственной копии приводила к удалению
серверных оригиналов (наблюдалось на практике: 101 фото в корзине).

*Альтернатива:* «удалять только своё» (текущее). Отклонено по решению продукта.
*Альтернатива:* удалять серверное фото при любом отсутствии локальной копии. Отклонено:
приводило к потере серверных данных. *Альтернатива:* беззвучно стирать локальный файл при
серверном удалении. Отклонено: для чужих снимков нужно согласие ОС.

### 5. Конвейер материализации

Новый загрузчик тянет объект по подписанному URL (`original_url` в B, `preview_url`/`medium_url`
в C; для видео — постер) и вставляет файл в `RELATIVE_PATH` бакета альбома устройства с
уникальным именем, `DATE_TAKEN` из `taken_at` и меткой провенанса. Запись идёт через
существующий механизм записи превью (аналогично `OffloadManager`). Дедуп: перед вставкой
проверяется, нет ли содержимого на устройстве (`contentHash`/серверный checksum) — тогда
элемент связывается, а файл не создаётся.

*Альтернатива:* хранить зеркала только в приватном кэше. Отклонено продуктом: зеркало
обязано быть видно в системной галерее.

### 6. Обнаружение новых серверных фото и первый проход

Дельта состава берётся из списка фото целевого альбома (`?since=`/курсор) и сопоставляется с
индексом/надгробиями. Первый проход ограничен сохранённым watermark-ом: по умолчанию
материализуется только новое после включения; «скачать всё» — явный выбор, задающий watermark
в начало. Скачивание подчиняется ограничению «только Wi-Fi».

*Альтернатива:* всегда материализовать весь состав. Отклонено: включение синхронизации на
полном серверном альбоме неожиданно заливает гигабайты.

### 7. Несколько источников в одну цель (n:1)

Серверное фото материализуется ровно в один бакет — выбранный при включении синхронизации
(для единственной связи это её бакет). Выбор сохраняется в индексе. Остальные связанные
бакеты не получают дубликат.

*Альтернатива:* материализовать во все связанные бакеты. Отклонено: дубликат в галерее и
кратный трафик.

### 8. Порядок и идемпотентность прохода

Проход сериализован (существующий мьютекс): сначала серверные события/дельты применяются к
индексу (включая надгробия и признак происхождения), затем считаются действия, затем
выполняются. Материализация — операция с устойчивым ключом (photoId + бакет), чтобы повтор
не создавал второй файл.

### 9. Явное выключение синхронизации устойчиво к восстановлению происхождения

Метка происхождения в разгруженных превью нужна для восстановления связи после переустановки,
но она же способна «воскресить» связь после того, как пользователь явно выключил
синхронизацию (или отвязал альбом): фоновый проход вызывает восстановление и создаёт связь
заново. Поэтому выключение записывается явным признаком в app-only метаданные альбома
(`device_album_meta.syncDisabledAt`). Восстановление происхождения пропускает такой альбом;
повторное включение синхронизации очищает признак. После настоящей переустановки данные
приложения пусты, признака нет, и восстановление работает как раньше.

*Альтернатива:* не удалять связь, а держать её в режиме выключено. Отклонено: связанный
серверный альбом остаётся скрытым в списке, хотя синхронизация выключена. *Альтернатива:*
стирать метки из превью при выключении. Отклонено: требует перезаписи всех превью и ломает
восстановление, если пользователь оставил превью вместо возврата оригиналов.

### 10. Дренирующая очередь загрузки и стоимость прохода

Доставка на сервер не создаёт задание на каждый файл: одна WorkManager-задача
(`galo-upload-drain`) берёт из Room все ожидающие загрузки и выполняет их последовательно
(по одному файлу на HTTP-запрос, как требует сервер). Иначе JobScheduler на большом альбоме
перестаёт запускать оставшиеся задания, и заливка не доходит до конца. Foreground-уведомление
выставляется best-effort (ОС может запретить его из фона — загрузка всё равно идёт).

Проход синхронизации не должен перечитывать и перехэшировать всё на каждое событие:
наблюдатель MediaStore дебаунсится, а `sha256` переиспользуется для файлов с неизменными
`(size, dateModified)`. Список серверных фото читается целиком (дельта `?since=` не сообщает
об удалениях, без которых нельзя чистить локальные зеркала), но при **неудачном** чтении
проход пропускается, а не трактует альбом как пустой — иначе удаляются локальные зеркала.

## Risks / Trade-offs

- [В C удаление превью стирает серверный оригинал] → серверное удаление мягкое (корзина);
  кроме того, файлы превью принадлежат приложению, а чужие — требуют согласия; в UI
  предусмотреть откат/уведомление.
- [Сторонняя галерея/чистильщик удаляет превью, и это трактуется как удаление] → надгробие
  не даёт немедленной материализации заново; откат через корзину сервера.
- [Материализация загрязняет бакет «Camera»] → осознанный выбор продукта; уникальные имена,
  метка происхождения, дата съёмки; возможность отвязать и оставить файлы обычными.
- [Трафик и место при включении на полном альбоме] → watermark «только новое» по умолчанию,
  «скачать всё» — явно, Wi-Fi-ограничение.
- [Эхо и гонки удалений/материализации] → надгробия + идемпотентность + сериализация.
- [После переустановки метка может быть утрачена] → элемент считается неопознанным: не
  удаляется и не загружается повторно (существующее безопасное поведение).
- [Отказ сервера при удалении чужого фото] → проход не падает; операция сообщается.
- [Выключение синхронизации отменяется восстановлением происхождения] → явный признак
  `syncDisabledAt` блокирует восстановление до повторного включения; закрыто тестом
  `moveToOffStaysOffAfterRecovery`.

## Migration Plan

1. Room-миграция: добавить `origin` (значение по умолчанию `OWN` для существующих строк),
   таблицу надгробий и watermark первого прохода. Существующие связи не меняют поведение.
2. Загрузчик материализации и расширение провенанс-метки признаком происхождения.
3. Планировщик: состав/удаления в обе стороны, надгробия, права; тесты на идемпотентность.
4. UI: сетка альбома устройства включает скачанные элементы, обновляется по проходу.
5. Откат: перевод связи в режим A останавливает двусторонность; серверные фото и уже
   скачанные файлы сохраняются, ничего не удаляется.