jellybit/openspec/changes/archive/2026-07-04-time-storage-rfc3339/design.md

Context

Метки времени хранятся как TEXT в формате datetime('now') — 2006-01-02 15:04:05 (UTC по конвенции, но не по значению). Формат выбирался ради двух свойств: лексикографическая сортировка TEXT = хронология (нужно для ORDER BY COALESCE(source_added_at, created_at) в списке загрузок) и байт-в-байт совпадение меток из Go (store.FormatTime) с метками из DEFAULT (datetime('now')).

Timestamp-колонки (актуальная схема, миграция 0006): download.created_at, download.updated_at, download.source_added_at (nullable), а также created_at в download_infohash, recognition, hint, override, metadata_candidate, file_link — всего 7 таблиц. Все INSERT в store сейчас полагаются на DEFAULT (не перечисляют created_at). Одно инлайн-обновление вне хелпера: updated_at = datetime('now') в download.go:510.

Зона отображения зашита в код: mskLoc (Europe/Moscow) в internal/httpapi/live.go:189-201, используется fmtDate/humanizeAge.

Goals / Non-Goals

Goals:

• Самоописываемое хранилище: зона зафиксирована в значении (RFC 3339, Z).
• Значения — валидный ISO 8601, пригодны напрямую для JSON API / <time> / JS.
• Единая, тестируемая точка генерации времени в Go (как internal/ident для id).
• Конфигурируемая зона отображения (дефолт UTC); хранение всегда UTC.
• Сохранить инвариант сортировки и ULID-корреляцию (хронология по created_at).

Non-Goals:

• Не меняем точность (остаётся секундная).
• Не трогаем формат времени в логах (уже RFC 3339 с долями секунды).
• Не вводим хранение в локальной зоне — БД остаётся строго UTC.
• Не добавляем таблицу/структуру данных (только формат значений и DEFAULT).

Decisions

1. Формат хранения — RFC 3339, всегда UTC (...Z)

Форма 2006-01-02T15:04:05Z = stdlib time.RFC3339 для UTC-времени. Фиксированная ширина (20 символов, константные T и Z) сохраняет лексикографический порядок, поэтому ORDER BY COALESCE(source_added_at, created_at) продолжает давать верную хронологию при смешивании заполненных и фолбек-значений.

internal/store/download.go:

• sqliteTimeLayout удаляется, FormatTime(t) = t.UTC().Format(time.RFC3339), ParseTime(s) = time.Parse(time.RFC3339, s).
• time.Parse(time.RFC3339, "...Z") даёт time.Time в UTC — совместимо с текущим контрактом ParseTime (всегда UTC).

2. Единая точка генерации: убрать DEFAULT, писать из Go

DEFAULT (datetime('now')) снимается со всех колонок. Время всегда пишет приложение — зеркально принципу «ULID генерит только internal/ident». Вводим store.Now() time.Time (тонкая обёртка над time.Now().UTC()) как единственную точку получения «сейчас» в слое store — тестируемую и единообразную.

• Каждый INSERT-сайт (не метод!) явно передаёт created_at в INSERT. Сайтов больше, чем методов: в CreateDownloadIfNoActive — вставка download и вставка хешей download_infohash; плюс dedup top-up хешей и AddInfohashes (INSERT OR IGNORE) — после снятия DEFAULT+NOT NULL время обязательно на новой строке. Полный список — в tasks 3.1.
• Инлайн updated_at = datetime('now') (download.go:510) → параметр FormatTime(store.Now()). Ключевая ловушка: нельзя оставить рядом datetime('now') (пробел, без Z) и RFC 3339 из кода — сортировка сломается.

Почему убираем DEFAULT, а не переписываем его на strftime(...Z): единая точка генерации ценнее «страховочного» дефолта; два источника формата (SQLite-дефолт и Go-хелпер) — именно то, что порождает риск расхождения. Побочная выгода — fail-loud: забытый INSERT падает по NOT NULL, а не пишет тихо старый формат. Выбор пользователя.

3. Миграция: rebuild без DEFAULT + backfill, атомарно

Одна goose-миграция (стиль 0006 — Go или SQL, table-rebuild, т.к. SQLite не умеет ALTER COLUMN ... DROP DEFAULT):

1. Backfill каждой timestamp-колонки в новый формат прямо на месте: UPDATE <t> SET <col> = strftime('%Y-%m-%dT%H:%M:%SZ', <col>) WHERE <col> IS NOT NULL. strftime разбирает старый пробел-формат и переписывает в RFC 3339. Идемпотентно по инстанту (тот же момент времени).
2. Пересоздать таблицы без DEFAULT на timestamp-колонках (в остальном схема без изменений), перенести данные, FK, индексы.

Все три части (backfill + смена схемы + смена Go-кода) — один change: между ними не должно быть окна, где часть строк в старом формате, а новые пишутся в новом (смешанный формат ломает лексикографическое сравнение).

Порядок в миграции: сначала backfill существующих строк, затем rebuild — либо, по образцу 0006, всё внутри одной транзакции с temp-таблицами. Конкретную технику (in-place UPDATE + rebuild vs. rebuild с strftime в INSERT ... SELECT) фиксируем на этапе apply; обе эквивалентны по результату.

Критично при rebuild: новая схема ОБЯЗАНА байт-в-байт повторить из 0006 все REFERENCES ... ON DELETE CASCADE, PK (включая составной download_infohash (infohash, download_id)), UNIQUE (override) и индексы — иначе тихо теряется каскад/индекс. Rebuild нужен только затем, что SQLite не умеет ALTER COLUMN DROP DEFAULT; это самая рискованная часть change (ср. объём 0006).

4. Настройка зоны отображения в конфиге

Новая секция [general] (общие настройки приложения), поле timezone, дефолт UTC:

• Размещение: секция [general] — дом для кросс-каттинг настроек приложения; timezone — её первое поле. В примере конфига [general] идёт первой секцией. Отдельная секция (а не корневой ключ) снимает вопрос TOML-порядка корневых ключей и оставляет место для будущих общих настроек.
• internal/config: секция General struct { Timezone string } + распарсенный DisplayLocation *time.Location, распарсенное на старте через time.LoadLocation. Пустое значение → UTC. Нераспознаваемая зона → ошибка валидации конфига на старте (не тихий фолбэк).
• Встраиваем time/tzdata (import _ "time/tzdata" в точке входа): zoneinfo всегда в статическом бинаре, независимо от окружения контейнера. Тогда time.LoadLocation падает только на реально битом имени → жёсткая валидация на старте корректна и однозначна, а прежний тихий фолбэк на UTC при «нет zoneinfo» (текущее latent-поведение mskLoc — молча показывает UTC на контейнере без tzdata) устраняется. Цена — ~450КБ к размеру бинаря; приемлемо для эта «один статический бинарь». Соответственно сценарий «нет zoneinfo → деградация» из спеки убран — он недостижим при встроенной базе.
• Проброс *time.Location в internal/httpapi; fmtDate/humanizeAge (свободные функции — тянем параметром через toView либо делаем методами server) используют её вместо зашитого mskLoc/Europe/Moscow. Guard: t.In(nil) паникует — при незаданной зоне подставляем time.UTC.

Хранение настройка НЕ затрагивает — только рендеринг. Логи остаются в UTC.

Risks / Trade-offs

• Смешанный формат при частичной выкатке — главный риск; снимается тем, что backfill, схема и код едут одним change/деплоем. Откат — обратной миграцией (strftime('%Y-%m-%d %H:%M:%S', col)), но проще не разрывать выкатку.
• Пропущенное место записи — любой забытый datetime('now') или сырой INSERT без created_at даст рассинхрон. Митигируется аудитом (grep из proposal показывает полный список: 7 Create-методов + 1 инлайн) и тестом сортировки.
• Стороннее чтение старого дампа — значения в старом формате остаются парсибельными strftime, но ParseTime после перехода ждёт RFC 3339; это ок, т.к. в живой БД после миграции все строки уже в новом формате.
• Зашитое 2006-01-02 форматирование даты в UI остаётся (это формат вывода, не хранения) — меняется только зона, в которую переводится time.Time.
• Новая секция [general] — вводится ради одной настройки, но это осознанный дом для будущих общих настроек; в примере идёт первой секцией.