jellybit/openspec/changes/archive/2026-08-10-card-live-refresh/design.md

Context

Живое обновление веб-UI собрано из трёх независимых поллеров, каждый привязан к своей фазе или региону:

• карточка списка опрашивает себя, пока SelfPoll — а это d.State == StateCatched (internal/httpapi/httpapi.go:664, card.html:2);
• вложенный блок прогресса опрашивает себя, пока Active — а это d.State == StateDownloading (internal/httpapi/live.go:88, progress.html:1);
• страница /download/{id} повторяет первое правило (internal/httpapi/download.go:116, download_main.html:2), а внутри неё секция «Раздача» опрашивает себя сама (seeding.html:1).

Ни одно из правил не покрывает выход из downloading, поэтому дальше задача живёт на экране в прошлом. Домен предикат уже даёт: State.IsTerminal() (internal/store/download.go:63) со своим единым перечнем терминальных состояний — заводить второй перечень в транспорте нельзя.

Цена тика у двух поверхностей разная, и это главное ограничение дизайна:

• фрагмент карточки — GetDownload плюс чтение in-memory снимка воркера;
• страница загрузки — Reviewer.ReviewData, а он на каждом вызове строит предпросмотр раскладки через layout.BuildLinks (internal/worker/review.go:1096), то есть ходит в файловую систему.

Ещё одно свойство, из которого растут решения Р2 и Р5: #seeding-{id} лежит внутри #download-main (download_main.html:61, корень закрыт на строке 129), а страница свопает этот корень целиком.

Goals / Non-Goals

Goals:

• смена состояния становится видимой без перезагрузки страницы, кто бы её ни сделал — воркер, веб-UI, Telegram или фоновая сверка;
• обновление само прекращается, когда состояние менять больше некому;
• число фоновых запросов на открытую страницу известно и обосновано.

Non-Goals:

• переход на SSE — отдельная задача sse-live-updates, и этот change её не приближает и не отменяет;
• изменение состава живой телеметрии и /api/**;
• обновление списка целиком (появление новых задач, изменение порядка и групп) — сегодня его нет, и эта задача его не заводит;
• экран /review/{id}: он сохраняет фазовое самообновление, заказанное спекой review («пока загрузка в recognizing»), и приводится к общему правилу отдельной задачей.

Decisions

Р1. Условие обновления — наблюдаемость, предикат общий с доменом

SelfPoll в обоих представлениях перестаёт зависеть от фазы. Наблюдаема задача, состояние которой ещё может измениться без участия этого браузера.

Одного !IsTerminal() для этого мало, и это выяснилось на ревью дизайна. Терминальность в проекте значит «не активна», а не «навсегда»: фоновая сверка двигает часть терминальных сама — ListRecoverable (internal/store/download.go:606) возвращает в поток failed/stuck с кодами magnet_timeout и stalled, а desyncStates (internal/worker/reconcile.go:22) переоценивает done, target_missing и orphaned. Карточка, застывшая по IsTerminal, показывала бы «Ошибка» у задачи, которая уже качается, — ровно тот дефект, ради которого затеян change.

Решено на чекпоинте: наблюдаемы все нетерминальные плюс failed, target_missing, orphaned — те, кого сверка возвращает в поток сама. Замолкают done, cancelled, reverted, deleted.

done в этот перечень не входит, хотя формально его тоже переоценивает сверка: переход done → target_missing/orphaned означает, что файлы удалили руками мимо сервиса, — событие редкое, а карточек done в списке больше всех. Платить за редкий случай постоянным фоновым запросом на каждую разложенную задачу дороже, чем показать её новое состояние при следующем заходе. Это принятое ограничение, а не упущение.

Предикат живёт в домене, рядом с IsTerminal, а не в httpapi: второй перечень состояний в транспорте разъедется на первом же новом состоянии.

Побочно это чинит и то, чего задача не заказывала: stuck и deferred нетерминальны, и их карточки тоже перестают застревать.

Рассмотрено и отвергнуто: «поллить, пока задача в активной группе списка» — группа считается из того же IsTerminal, то есть это то же условие, названное через представление, а не через домен.

Р2. Один источник обновления на поверхность

Правило общее для карточки и для страницы: вложенные живые регионы своего опроса не ведут.

• в карточке блок прогресса (progress.html) остаётся вложенной разметкой без своего hx-get;
• на странице секция «Раздача» (seeding.html) — тоже.

Основание фактическое, а не эстетическое. Своп корня меняет outerHTML целиком и уносит вложенный узел вместе с его таймером: два опроса на одну поверхность опрашивают одно и то же дважды, подменяют разметку друг друга, а тик корня, попавший в незавершённый запрос региона, роняет его ответ в никуда. До этого change конфликта не было только потому, что поверхности поллились в фазах, где вложенных регионов не существует (catched — ни прогресса, ни раздачи).

Цена названа прямо: цифры сидирования обновлялись раз в 3 с, станут обновляться с тиком страницы. Рейтинг и число пиров — не те величины, которым нужна трёхсекундная свежесть; прогресс качания, которому она нужна, едет с быстрым интервалом карточки.

Рассмотрено и отвергнуто: оставить регионам их опрос, а корень свопать частями (hx-select по кускам) — это заводит вторую механику свопа ради сохранения того, что и так не нужно с трёхсекундной частотой.

Р3. Способ доставки — самополлинг фрагмента, а не сигнал из прогресса

Вариант «фрагмент прогресса, заметив уход из downloading, просит браузер обновить карточку» (HX-Trigger или hx-swap-oob) дешевле по запросам, но покрывает ровно один переход — тот, у которого был поллер. Переходы review → linking → done, сделанные из Telegram, остались бы невидимыми, а именно они дают самое долгое расхождение: задача стоит в ревью часами.

Вариант «поллить список одним запросом целиком» дал бы заодно появление новых задач, но перерисовывал бы всю страницу, ломая фильтр, поиск и прокрутку, — спека live-status это прямо запрещает. Это направление принадлежит SSE-задаче.

Следствие принятого варианта, названное сценарием спеки: карточка, дошедшая до конца на глазах у смотрящего, остаётся на своём месте в прежней группе списка — группы и фильтр считаются на рендере страницы и пересчитываются навигацией.

Р4. Две частоты, потому что цена тика разная

Интервал зависит от того, несёт ли поверхность блок живых цифр качания:

• быстрый — карточка задачи в downloading: цифры меняются непрерывно, и это единственное место, где реже значит хуже;
• медленный — все прочие наблюдаемые поверхности, включая страницу /download/{id} в любом состоянии: блока прогресса на ней нет вовсе (grep progress web/templates/partials/download_main.html пуст), а цифры раздачи трёхсекундной свежести не требуют.

Критерий именно «есть блок живых цифр», а не «состояние downloading»: на странице эти два признака расходятся, и по второму она перерисовывалась бы 20 раз в минуту, не показывая ни одной изменившейся величины.

Арифметика, ради которой это и сделано. Открытая страница /download/{id} в review при быстром интервале звала бы BuildLinks 20 раз в минуту всё время, что вкладка открыта; при медленном — 4 раза. Для списка из N наблюдаемых карточек быстрый интервал везде дал бы 20 × N запросов в минуту, разный — 20 за качающиеся и 4 × N за остальные.

Уточнение после ревью кода: один тик карточки — это два обращения к хранилищу (GetDownload и LayoutSizeByDownload, оба по первичному ключу и индексу idx_file_link_download), а не одно. То есть открытый список даёт 8 × N чтений в минуту вместо 4 × N. Полный рендер страницы берёт размеры одним батчем, самообновление — по карточке: это цена того, что список не пересобирается целиком (см. Non-Goals). Замера под нагрузкой нет; порог, при котором это перестанет быть бесплатным, ищет задача scale-100-downloads.

Решено на чекпоинте: быстрый интервал — 5 с, вровень с [worker].poll_interval (docs/database.md:201), медленный — 15 с. Сегодняшние 3 с обгоняют источник: воркер снимает телеметрию раз в 5 с, поэтому примерно два тика из пяти возвращают тот же кадр. Выравнивание убирает холостые запросы, а свежесть цифр не портит — она и так ограничена тиком воркера, что спека live-status прямо и требует («Свежесть не выше тика поллинга»).

Обе константы живут в одном месте кода рядом с представлениями и записываются в docs/database.md в таблицу настроек с числовым значением, там же — связь быстрого интервала с частотой опроса qBittorrent.

Рассмотрено и отвергнуто: единая частота — проще на один параметр, но делает открытую вкладку с ревью источником постоянных обращений к файловой системе; частота из конфига — настройка, которую никто не будет крутить, а config.example.toml и документацию она утяжелит.

Р5. Фрагменты прогресса и раздачи остаются — и гасят разметку прошлой версии

Оба маршрута (/fragments/downloads/{id}/progress, .../seeding) после Р2 остаются без потребителя в новой разметке. Удалить их сразу нельзя: htmx не свопит ответы 4xx/5xx и не снимает с узла hx-trigger, поэтому вкладка, открытая до деплоя, слала бы запросы на удалённый маршрут каждые 3 секунды до самого закрытия — молча для смотрящего и десятками тысяч строк в журнале доступа.

Оставленные маршруты отдают те же партиалы, которые после правки поллинга не несут, — то есть первый же тик старой вкладки гасит её собственный опрос. Уборка этих двух обработчиков — отдельная мелкая задача после деплоя; она уезжает в урожай ревью, а не остаётся обещанием в комментарии.

buildProgress и buildSeeding остаются в любом случае: ими собираются виды, вложенные в карточку и страницу.

Р6. Самообновление не теряет полей полного рендера

handleFragCard сегодня зовёт buildCardView с layoutSize = 0 — упрощение времени, когда фрагмент обслуживал только catched, где раскладки не бывает. После расширения тот же обработчик обслуживает linking, deferred и прочие состояния с уже разложенными файлами, и при отсутствии раздачи в снимке самообновление подменило бы показанный размер прочерком.

Фрагмент читает размер раскладки так же, как это делает своповый путь действия (renderCardFragment → LayoutSizeByDownload).

Р7. Отказ тика самозавершается

Тик, не сумевший прочитать задачу (записи нет — например, её убрала уборка; или отказало хранилище), отвечает 200 и фрагментом без hx-*. Иначе htmx не свопит ответ, поверхность остаётся прежней навсегда, а опрос продолжается: при затяжном отказе хранилища одна открытая вкладка даёт 4 × N записей в журнале в минуту. Форма ответа согласована с уже записанной конвенцией для htmx-пути действий (docs/conventions/web-ui.md).

Risks / Trade-offs

• Своп карточки раз в интервал попадает в момент, когда человек ведёт мышь к кнопке → поведение уже существует у карточек в catched; кнопки — обычные формы, потеря фокуса восстанавливается повторным наведением. Отдельного гашения свопа при наведении не делаем: заметная механика ради редкого случая.
• Сообщение об ошибке действия (ActionError) живёт до следующего тика → сегодня оно живёт до любого следующего свопа, и в catched уже так. Отдельно не удерживаем: место для устойчивого объяснения — страница загрузки.
• Открытая на ночь вкладка держит опрос, пока есть хоть одна наблюдаемая задача → ограничено медленным интервалом и прекращается само. Полный отказ от фонового опроса — предмет SSE-задачи.
• Цифры раздачи стали обновляться реже → принято осознанно в Р2; величины медленные, а альтернатива — вложенный поллер внутри свопаемого корня.

Open Questions

Нет. Обе развилки решены на чекпоинте и записаны в Р1 и Р4: наблюдаемы нетерминальные плюс failed/target_missing/orphaned; интервалы — 5 с и 15 с.