Files

T

iu 96268ee16c feat(photos): separate object storage from metadata layer

Move physical file facts out of the photos table into an objects ledger:

- objects / photo_objects / variant_jobs tables (migration 000008)
- drop storage_key/thumb_key/preview_key/size/width/height/mime_type from
  photos (migration 000009); they are derived via joins to the original object
- album-free storage keys: objects/{id}/{role}.{ext}
- explicit GC via pending/ready/deleting states; objects deleted only when no
  photo references them
- background worker drives variant generation (durable variant_jobs) and GC
- copy/move are metadata-only; storage objects are shared between photos
- remove unused storage.DeletePrefix

Non-destructive to the external JSON API: size/dimensions/mime and URLs are
still returned, just sourced from the object layer.

OpenSpec change: media-object-layer

2026-10-10 23:31:41 +03:00

3.5 KiB

Raw Blame History

Proposal

Why

Слой хранения S3 сейчас знает о сущности «альбом»: ключи объектов имеют вид albums/{album_id}/original/{photo_id}.{ext} (photos/service.go:72,114,115). Это протекание модели метаданных в физический слой: перенос фото оставляет ключ в старом namespace, копия делит объекты под префиксом исходного альбома, а неиспользуемый DeletePrefix (storage/storage.go:107) создаёт латентный риск удаления живых объектов. Нужно развести слои: S3 хранит непрозрачные объекты, а сущности и их жизненный цикл живут в БД.

What Changes

Ввести таблицу objects — физические блобы (ключ, mime, размер, габариты, checksum, состояние) и photo_objects — связка photo↔object с ролью (original|thumb|preview).
BREAKING: удалить storage_key, thumb_key, preview_key из photos; ключи фото выводятся через джойн к объекту-оригиналу. Миграция разрушительная (в базе только дев-данные).
Сделать ключи S3 album-free: objects/{id}/{role}.{ext}, где id — случайный идентификатор объекта.
Ввести явный GC через ledger-состояния объектов pending | ready | deleting: физический объект удаляется только когда на него не осталось ни одной связки.
Перенести генерацию вариантов в фоновый воркер: таблица variant_jobs (ровно-один-раз, ретраи с backoff), воркер также удаляет осиротевшие объекты и досасывает зависшие pending. SSE photo.created публикует воркер.
Удалить DeletePrefix из клиента хранения — entity-namespace больше нет.

Capabilities

New Capabilities

media-objects: физическое объектное хранилище с непрозрачными ключами, журнал объектов и их жизненный цикл, сборка мусора по отсутствию ссылок, привязка объектов к фото по ролям.

Modified Capabilities

photos: уточняется семантика удаления (корзина не удаляет объекты хранилища) и разделение объектов между фото при переносе и копировании.

Impact

Backend: internal/photos/{service,store}.go, internal/storage/storage.go, internal/albums/* (косвенно, через ключи обложки), wiring фонового воркера, migrations/ (новая схема + удаление колонок).
Данные: разрушительная миграция photos (dev-only), новые таблицы.
Внешний JSON API не меняется: thumb_url/preview_url/original_url и size/width/height/mime_type по-прежнему отдаются, но выводятся из объектов.
Документация: project.md §10 (структура в S3).

3.5 KiB Raw Blame History