# Design

## Context

См. `proposal.md` — Why. Текущее состояние, определяющее подход:

- Каждый домен имеет конкретный `Store` с полем `*pgxpool.Pool` и SQL диалекта Postgres.
  Всего ~72 метода: `auth(9)`, `albums(7)`, `members(8)`, `photos(20)`,
  `photos/objects(15)`, `social(6)`, `notifications(3)`, `sharelinks(4)`.
- Postgres-специфика: `FOR UPDATE SKIP LOCKED`, `ANY($1)`, `make_interval`/`power`/`least`,
  `now()`, `timestamptz`, `jsonb`/`::jsonb`, `ON CONFLICT`, `RETURNING`.
- Кросс-доменные зависимости уже выражены интерфейсами (`AlbumAccess`, `PhotoLookup`,
  `Notifier`, `MemberLookup`, `AlbumReader`); свои store сервисы берут конкретными.
- Сборка `CGO_ENABLED=0`; model: один экземпляр приложения на инсталляцию.
- Ограничение: SQLite допускает один писатель, много читателей (WAL); один файл на
  один экземпляр приложения.

## Goals / Non-Goals

**Goals:**
- Ввести интерфейсы репозиториев по доменам и вторую реализацию на SQLite с паритетом.
- Сохранить текущее поведение PostgreSQL по умолчанию и не менять сервисную логику.
- Обеспечить атомарность объектов, GC и очереди вариантов на обоих бэкендах.
- Гарантировать паритет общим контрактным набором тестов.

**Non-Goals:**
- Горизонтальное масштабирование и несколько экземпляров на один файл SQLite.
- Миграция данных между PostgreSQL и SQLite.
- Изменение наблюдаемого поведения API/спек (см. `proposal.md`, изменений требований нет).
- Изменение слоя хранения (см. `local-fs-storage-backend`).

## Decisions

### D1. Параллельные реализации, а не слой диалекта
Выбрано (по решению пользователя): Postgres-store не трогаем, пишем отдельные
SQLite-store. Интерфейс `Repository` становится швом между доменом и хранилищем.
- Альтернатива: единая логика + `Dialect` — отвергнута: правки во всех существующих
  store и риск регрессии Postgres ради экономии дублирования.
- Цена: каждая будущая фича реализуется дважды; снижается контрактными тестами (D9).

### D2. Именование и размещение
Интерфейс домена — `Repository`; существующий pgx-тип остаётся `Store` (`NewStore(pool)`),
SQLite-тип — `SQLiteStore` и живёт в том же пакете (`photos/sqlite_store.go` и т.п.).
- В том же пакете — доступ к `models` и sentinel-ошибкам без циклов импорта и без
  перемещения существующего кода.
- Сервисы типизируются интерфейсом (`albums.Repository` и т.д.); кросс-доменные
  интерфейсы удовлетворяются любой реализацией.

### D3. Драйвер SQLite — `modernc.org/sqlite`
Чистый Go, совместим с `CGO_ENABLED=0`.
- Альтернатива `mattn/go-sqlite3` (CGO) — отвергнута, ломает модель сборки.

### D4. Роль `$1`-плейсхолдеров
Плейсхолдеры остаются `$1`: и pgx, и `modernc` понимают именованные параметры.
Поскольку реализации раздельные, каждая пишет свой SQL; отдельный слой диалекта не нужен.

### D5. Отдельный набор миграций для SQLite
`migrations/sqlite/` рядом с Postgres-набором, драйвер `golang-migrate/database/sqlite`.
Отображение типов: `timestamptz`→TEXT, `jsonb`→TEXT, `bigint`→INTEGER,
`double precision`→REAL, `now()`→`strftime('%Y-%m-%dT%H:%M:%fZ','now')`,
`REFERENCES ... ON DELETE CASCADE` и `CHECK` сохраняются.
- Альтернатива: переносимый единый набор — отвергнута, тянет переписывание обоих.

### D6. Настройка соединения и конкурентность
`journal_mode=WAL`, `busy_timeout=5000`, `foreign_keys=ON` через DSN-параметры
`_pragma`. Писатель один; читатели — параллельно.
- `ANY($1)` переписывается в `IN (?, ...)` с построением списка в Go; батчи малы.
- `FOR UPDATE`/`SKIP LOCKED` заменяются транзакцией с немедленной блокировкой записи
  (`BEGIN IMMEDIATE`); порядок «проверить состояние — вставить/заявку» сохраняется.

### D7. Атомарность жизненного цикла объектов
`BindObject` и claim-методы (`ClaimGarbage`, `ClaimStalePending`, `ClaimVariantJobs`)
выполняются в `BEGIN IMMEDIATE`-транзакции, что сериализует запись и воспроизводит
инварианты Postgres-версии (нельзя привязать объект, уходящий в GC; нельзя удалить
используемый; одинаковая роль без дублей).

### D8. Backoff и `now()`
`FailVariantJob` считает задержку в Go (`min(300, 10*2^attempts)`) вместо
`make_interval/power/least`. Время пишется/читается через хелперы преобразования
`time.Time` <-> RFC3339 TEXT; запросы сравнения используют `datetime('now')`/значения Go,
а не неявное приведение драйвера.

### D9. Контрактные тесты на интерфейс
Один набор тестов на каждый `Repository`, прогоняемый на обоих бэкендах: Postgres под
`TEST_DATABASE_URL` (пропуск без него), SQLite на временном файле (всегда). Это механизм
удержания паритета при параллельных реализациях.

### D10. Фабрика и сборка зависимостей
`store.NewPostgres(pool)` и `store.NewSQLite(db)` возвращают бандл репозиториев;
`app.New` принимает бандл и `storage.Backend`. Выбор бэкенда — на старте по
`DB_BACKEND=postgres|sqlite` (дефолт `postgres`), путь — `SQLITE_PATH`.
- Альтернатива: ветвление внутри `app.New` по типу пула — отвергнута, размазывает выбор.

### D11. Маппинг ошибок и `RETURNING`
`schema`-уровневые sentinel-ошибки домена сохраняются; каждая реализация сама
отображает `pgx.ErrNoRows`/`sql.ErrNoRows` в sentinel. `RETURNING` используется и в
SQLite (>=3.35), поэтому вставки с возвратом `created_at` переносятся один-в-один.

## Risks / Trade-offs

- [Дрейф параллельных реализаций] → общий контрактный набор тестов на интерфейс (D9).
- [Пропускная способность записи SQLite под многими пользователями] → WAL,
  `busy_timeout`, один писатель; документируем как режим малой инсталляции.
- [Потеря валидации `jsonb`] → хранение как TEXT, проверка JSON при необходимости в Go.
- [Ошибки преобразования времени/JSON между бэкендами] → хелперы + контрактные тесты.
- [Расхождение миграций] → симметричные наборы, прогон `up` на обоих в тестах.
- [Лимит параметров SQLite в `IN (...)`] → малые батчи (`WORKER_BATCH`), построение
  списка в Go.

## Migration Plan

1. Ввести интерфейсы, не меняя Postgres-реализации и дефолт `postgres`.
2. Добавить SQLite-реализации, миграции и фабрику; включение — `DB_BACKEND=sqlite`.
3. Существующие развёртывания не меняются; откат — вернуть `DB_BACKEND=postgres`.
4. Перенос данных между бэкендами не автоматизируется и вне рамок изменения.

## Open Questions

- Нужен ли SQLite-специфичный поиск меток (например, FTS) или достаточно текущих
  запросов с точным совпадением/префиксом.