specs/openspec/specs/frontend-platform/frontend-data-resilience/spec.md

# frontend-data-resilience Specification

## Purpose

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

## Requirements

### Requirement: Client Cached Snapshot остаётся доступным при обновлении Accounts и Portfolio

Frontend MUST сохранять последний успешный результат списка Brokerage Accounts,
Portfolio и других экранов чтения при фоновом обновлении и временной ошибке
для того же пользователя, подключения и набора данных. Подтверждённый пустой
результат MUST также считаться успешным. Смена счёта, инструмента, поискового
запроса, страницы или применённого периода MUST NOT представлять данные прежней
выборки как результат новой.

Доступный результат MUST оставаться видимым без индикаторов фонового чтения
клиента, технических предупреждений об этом чтении и действий ручного повтора,
пока автоматические повторы не исчерпаны; после их исчерпания применяется
требование «Временные сбои чтения восстанавливаются автоматически».
Frontend MUST NOT подменять внутренние признаки свежести и полноты, успешное
время источника или ошибку обновления только ради отсутствия их отображения.
Client Cached Snapshot MUST оставаться отличным от server-side fallback;
ошибка чтения MUST NOT изменять `Portfolio.isStale`.

Состояние источника из `meta` — время последнего успешного результата, признак
устаревания, исход последней часовой попытки и неполнота — MUST представляться
текстом либо доступно именованным элементом, а не только цветом, и MUST
различать отсутствие попытки, выполнение, полный успех, частичный успех и
неуспех. Это состояние принадлежит источнику данных, а не собственному чтению
клиента, и MUST NOT требовать от пользователя действия.

Обновление MUST сохранять выбранные фильтры, период, открытые разделы, ввод,
фокус и положение просмотра, пока соответствующее содержимое существует.
При logout, смене подключения или подтверждённом отказе доступа личные данные
прежней границы MUST перестать отображаться; поздний результат прежней загрузки
MUST NOT возвращать их на экран.

#### Scenario: Список Brokerage Accounts обновляется в фоне
- **WHEN** экран Accounts уже показывает Client Cached Snapshot и начинается фоновое обновление того же списка
- **THEN** frontend оставляет список видимым без индикации собственного чтения и технических действий

#### Scenario: Resource сохраняется после неуспешной часовой попытки
- **WHEN** response содержит полный `data` и `meta`, обозначающий неуспех последней часовой попытки
- **THEN** frontend сохраняет `data` и его исходное время видимыми и отдельно обозначает неуспех попытки, не предлагая запуск повторного получения данных из источника

#### Scenario: Обновление Portfolio завершается ошибкой после успешного ответа
- **WHEN** экран Brokerage Account уже показывает Client Cached Snapshot Portfolio, а последующее обновление этого же Portfolio завершается временной ошибкой
- **THEN** frontend сохраняет Portfolio видимым без предупреждения и ручного повтора, а восстановление выполняется автоматически, пока автоматические повторы не исчерпаны

#### Scenario: Server-side fallback и client cached snapshot различаются
- **WHEN** backend возвращает Portfolio с `isStale` либо фоновое обновление Client Cached Snapshot завершается временной ошибкой, а автоматические повторы ещё не исчерпаны
- **THEN** frontend сохраняет доступные данные без технических сообщений и не подменяет один внутренний вид состояния другим

#### Scenario: Подтверждённая пустота переживает фоновую ошибку
- **WHEN** текущая выборка ранее успешно вернула полный пустой результат, а её обновление временно не удалось
- **THEN** подтверждённое пустое состояние сохраняется без предупреждения и не заменяется первичной загрузкой

#### Scenario: Изменились параметры выборки
- **WHEN** пользователь применил другой период или открыл другой счёт, а данных новой выборки ещё нет
- **THEN** экран показывает ожидание или недоступность новой выборки и не подписывает прежние суммы новым периодом или счётом

#### Scenario: Обновление не сбрасывает работу пользователя
- **WHEN** пользователь раскрыл раздел, выбрал фильтры или вводит данные, а фоновое чтение завершилось
- **THEN** обновление не сбрасывает эти действия, не переносит фокус и не возвращает пользователя в начало сохранившегося содержимого

#### Scenario: Изменился доступ к личным данным
- **WHEN** пользователь вышел, успешно сменил подключение либо получил подтверждённый отказ доступа к текущим данным
- **THEN** прежние личные данные скрываются, а позднее завершение старой загрузки не восстанавливает их

### Requirement: Временные сбои чтения восстанавливаются автоматически

Frontend SHALL автоматически повторять временно неуспешное чтение и восстанавливать
получение необходимых текущему экрану данных без ручного обновления. Повторы
одной попытки MUST иметь конечный предел и паузы, исключающие непрерывную
череду запросов. При исчерпании предела доступные данные SHALL сохраняться,
а при их отсутствии SHALL показываться локальная недоступность. На экранах
Account, Accounts, Income, Operations, Events и секций деталей инструмента при исчерпании предела
frontend SHALL дополнительно показывать неблокирующее локализованное предупреждение
о неудачном обновлении и действие «Повторить» рядом с затронутым результатом либо
локальной недоступностью. Действие MUST повторять только чтение (GET) затронутого
запроса, не запускать получение данных из источника и не менять выбранные
фильтры, период, открытые разделы и ввод; успешное чтение MUST снимать
предупреждение и MUST NOT сообщать об успехе. Предупреждение MUST NOT дублировать
состояние источника из `meta` и MUST NOT изменять `Portfolio.isStale`. На остальных
экранах чтения, включая поиск, диапазон графика, карты и настройки подключения,
предупреждение и действие повтора MUST NOT показываться. Возвращение сети,
возвращение пользователя к открытому экрану и повторное открытие экрана MUST
возобновлять получение отсутствующих или требующих обновления данных без
перезагрузки страницы. Свежий полный результат MUST NOT требовать обращения
к источнику только из-за такого события.

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

#### Scenario: Кратковременный сбой чтения
- **WHEN** чтение текущей выборки временно не удалось, а следующая разрешённая автоматическая попытка успешна
- **THEN** экран самостоятельно показывает результат без ручного действия и без сообщения о сбое или восстановлении

#### Scenario: Источник завершил работу ошибкой
- **WHEN** чтение сохранённых данных успешно, но получение необходимых новых данных из источника временно не удалось
- **THEN** приложение применяет ограниченное автоматическое восстановление к неуспешной работе, а не считает успешное чтение доказательством её успеха

#### Scenario: Повторы исчерпаны
- **WHEN** временная недоступность сохраняется после конечного предела автоматических попыток
- **THEN** приложение прекращает серию повторов, сохраняет доступный результат либо локальную недоступность без бесконечной загрузки и ожидает следующего события восстановления

#### Scenario: Повторы исчерпаны при сохранённом результате
- **WHEN** на экране Account, Accounts, Income, Operations, Events либо в секции деталей инструмента автоматические повторы исчерпаны, а ранее полученный результат остаётся доступным
- **THEN** результат и его исходное состояние источника остаются видимыми, рядом показываются неблокирующее предупреждение о неудачном обновлении и действие «Повторить», а активация действия повторяет только чтение затронутого запроса и после успеха снимает предупреждение

#### Scenario: Повторы исчерпаны без результата
- **WHEN** на тех же экранах автоматические повторы исчерпаны, а результата выборки нет
- **THEN** локальная недоступность содержит действие «Повторить», повторяющее только чтение затронутого запроса, и результат одной секции деталей не блокирует восстановление остальных

#### Scenario: Поиск, график и карты остаются тихими
- **WHEN** автоматические повторы исчерпаны при чтении результата поиска, диапазона графика, карт либо настроек подключения
- **THEN** приложение не показывает предупреждение и действие повтора и сохраняет прежнее локальное поведение

#### Scenario: Сеть или пользователь вернулись
- **WHEN** после временного сбоя восстановилась сеть либо пользователь вернулся к экрану с отсутствующим или требующим обновления результатом
- **THEN** получение данных возобновляется автоматически для текущей выборки и при успехе заменяет состояние недоступности содержимым

#### Scenario: Несколько событий восстановления совпали
- **WHEN** сеть восстановилась одновременно с возвращением пользователя на экран
- **THEN** приложение не запускает дублирующую работу получения одного набора данных

#### Scenario: Работа источника ещё выполняется
- **WHEN** приложение восстанавливает чтение состояния уже выполняющейся работы
- **THEN** оно продолжает получение её результата без повторного запуска той же работы

#### Scenario: Пользователь покинул экран
- **WHEN** пользователь ушёл со страницы с ожидающим восстановлением
- **THEN** новые попытки для покинутого экрана прекращаются, а уже начатая работа не изменяет содержимое другой выборки

#### Scenario: Ошибка требует действия пользователя
- **WHEN** подтверждены недействительное подключение, отсутствие доступа или некорректный ввод
- **THEN** автоматическая серия повторов прекращается и появляется соответствующее действие или локальная ошибка без технической кнопки повторной загрузки

### Requirement: Неполный результат не выдаётся за окончательный

Frontend MUST различать неизвестный результат, доступную часть данных и
подтверждённую пустоту. Неполные суммы и сравнения MUST NOT показываться как
окончательные или заменяться нулями. Доступные записи MAY оставаться видимыми,
но их список MUST NOT представляться полным при неподтверждённой полноте.
Состояние SHALL относиться к содержимому конкретной области, например
недоступному итогу, без отчёта о прогрессе синхронизации. Готовая область MUST
NOT ждать догрузки истории, которая не влияет на её результат.

#### Scenario: Итог ещё не определён
- **WHEN** часть данных, необходимых для суммы или сравнения, отсутствует
- **THEN** соответствующее значение обозначается как недоступное без вымышленного нуля или окончательного частичного итога

#### Scenario: Пустота ещё не подтверждена
- **WHEN** записи не получены и полнота выбранного периода неизвестна
- **THEN** экран не сообщает об отсутствии операций или выплат за этот период

#### Scenario: Период готов раньше остальной истории
- **WHEN** данные показанного периода полны, а не влияющая на него история ещё загружается
- **THEN** пользователь видит готовый результат без сообщения о догрузке остальной истории