ksv741
271024b8d8
Specs security / security (push) Successful in 8s
Specs verify / verify (push) Successful in 10s
Conventional commits / commits (pull_request) Successful in 15s
Specs security / security (pull_request) Successful in 11s
Specs verify / verify (pull_request) Successful in 10s
OpenSpec change: screen sync status polling and observe reads run every five seconds during active sync; terminal state observes resources immediately.
105 lines
6.8 KiB
Markdown
105 lines
6.8 KiB
Markdown
## 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 |
|