ksv741
271024b8d8
OpenSpec change: screen sync status polling and observe reads run every five seconds during active sync; terminal state observes resources immediately.
6.8 KiB
Context
useScreenSync уже является общим module для экранной синхронизации. Его
interface принимает scope и набор resource queries; реализация опрашивает
статусы выполняющейся работы и вызывает observe() для ресурсов того же
экрана. Один интервал в 1 секунду управляет обоими видами запросов, поэтому
страницы с несколькими ресурсами умножают фоновый трафик.
Нужна меньшая частота обновления при сохранении текущей cache identity, автоматического восстановления, защиты доступа и итогового обновления сразу после завершения работы.
Goals / Non-Goals
Goals:
- Сократить периодический HTTP-трафик выполняющейся экранной синхронизации примерно в пять раз.
- Сохранить небольшую и прежнюю interface
useScreenSyncдля всех page VMs. - Сразу обновлять ресурсы после terminal state синхронизации.
- Проверять поведение на HTTP seam, а не детали реализации TanStack Query.
Non-Goals:
- Изменять backend status contract, resource endpoints или модель синхронизации.
- Вводить отдельный polling module, второй cache или push-канал.
- Менять пользовательское представление загрузки и ошибок.
Decisions
Preserve one screen-sync module and lengthen its interval
useScreenSync остаётся единственным module, который владеет связью между
статусом экранной синхронизации и observe reads. Его implementation заменяет
интервал status polling с одной секунды на пять секунд. Поскольку effect уже
наблюдает ресурсы после нового status response, это одним изменением
ограничивает оба потока запросов без расширения interface для callers.
Alternative: добавить второй timer только для observe reads при status polling раз в секунду. Отклонено: status traffic останется частым, а два независимых ритма увеличат implementation и риск дублирующих наблюдений без требуемой пользы.
Alternative: читать ресурсы только после terminal state. Отклонено: это устранит промежуточную публикацию уже готовых данных и изменит существующее поведение сильнее, чем требуется.
Keep completion observation driven by the terminal status response
Текущий effect уже distinguishes running и completed status: для terminal state он observes every resource, включая тот, который был fetching. Этот путь сохраняется. Terminal response не ждёт отдельного timer, поэтому итоговый результат появляется в обработке того же status response; максимальная задержка возникает только до следующей пятиисекундной проверки.
Test the public HTTP outcome at the screen-sync seam
Colocated tests screen-sync будут использовать MSW и fake timers, чтобы
проверить отсутствие повторного status/read traffic до пяти секунд, следующий
цикл после интервала и одно итоговое observe read при terminal status. Existing
tests продолжат доказывать, что уход с экрана останавливает polling и что
observe reads не создают новую импортирующую работу.
UI/UX Applicability and Package
Applicability and scope: N/A. Изменяется только частота невидимых фоновых запросов; экраны, состояния, interactions и responsive behavior не меняются.
Delivery Map
| Area | Status | Architectural outcome or N/A reason |
|---|---|---|
| frontend | affected | useScreenSync реже опрашивает статус и тем самым реже наблюдает ресурсы, сохраняя немедленное обновление после terminal state. |
| backend | N/A | Status и resource contracts не меняются. |
| specs | affected | Delta фиксирует пятиисекундную верхнюю частоту и итоговое наблюдение после terminal state. |
| docs | N/A | Пользовательские и эксплуатационные инструкции не меняются. |
Risks / Trade-offs
- Промежуточно готовые данные могут появиться до четырёх секунд позже, чем раньше; пользователь явно выбрал меньший трафик в обмен на эту задержку.
- Terminal state обнаруживается следующей status-проверкой, поэтому его отображение также может ждать до пяти секунд после фактического завершения backend work. После обнаружения дополнительной задержки нет.
- Смена только общей константы затрагивает все экраны-потребители; тесты module защищают единое ожидаемое поведение.
Migration Plan
- Изменить policy interval у существующего screen-sync module.
- Адаптировать и дополнить его seam tests для пятиисекундного ритма и terminal refresh.
- Выполнить локальные frontend quality gates перед поставкой.
Rollback Contract
| Field | Decision |
|---|---|
| Status | N/A |
| Reason | Изменение локальной frontend polling policy не меняет данные, публичный contract, security или миграции; rollback состоит в возврате прежнего значения интервала. |
| Trigger | N/A |
| Actions | N/A |
| Data safety | N/A |
| Verification | N/A |