spec: add reduce-screen-sync-polling change

OpenSpec change: screen sync status polling and observe reads run every five seconds during active sync; terminal state observes resources immediately.
2026-10-07 14:12:35 +03:00
parent 33cc4f3e0c
commit 271024b8d8
5 changed files with 271 additions and 0 deletions
@@ -0,0 +1,104 @@
+## 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
+
+1. Изменить policy interval у существующего screen-sync module.
+2. Адаптировать и дополнить его seam tests для пятиисекундного ритма и
+   terminal refresh.
+3. Выполнить локальные 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 |