docs: describe quiet reading and visible source state (#51)

ADR 021 фиксирует решение: автоматическое чтение клиента не сообщает о себе, состояние источника из meta остаётся видимым, ошибки явных действий пользователя сохраняются. Приведены к AS-IS: ui-resilience, accounts, income, bonds, stocks, portfolio overview и how-to. ADR 017 не правился — он помечен историческим и заменён ADR 019/021.
2026-10-17 22:09:38 +03:00
parent 11f819ed31
commit 174fbf01c3
9 changed files with 120 additions and 30 deletions
@@ -62,8 +62,8 @@

 - `409 TBANK_NOT_CONNECTED`: список не запрашивается у T-Bank, экран ведёт в настройки.
 - `400 INVALID_TBANK_TOKEN`: сохранённый токен не удаляется, экран ведёт в настройки для замены или удаления.
- `503 TBANK_UNAVAILABLE`: экран предлагает повторить загрузку или открыть настройки.
- Неизвестная ошибка: экран предлагает только повторить загрузку.
+- `503 TBANK_UNAVAILABLE`: экран показывает спокойное состояние недоступности; чтение возобновляется автоматически.
+- Неизвестная ошибка: то же состояние недоступности без действия повтора.
 - Успешный пустой ответ: штатное состояние отсутствия инвестиционных счетов.

 Карточка ведёт на `/accounts/:accountId` по всей области и доступна с клавиатуры. Карточки расположены в одну колонку при любой ширине. Карточка показывает название, локализованный тип, крупный валютный итог и вторую валюту при наличии, число остальных валют, дату открытия без времени и видимое действие открытия. Отдельные цветные блоки «Акции» и «Облигации» показывают количество наименований бумаг. Недоступная или пустая сводка отображается локально; отсутствие сумм не скрывает известные количества бумаг, а недоступная сводка не подменяет их нулями. Наведение и видимый клавиатурный фокус подчёркивают переход; настройка уменьшения движения отключает анимацию.
@@ -39,10 +39,11 @@
 При первой загрузке или новом периоде без сохранённых данных показан
 каркас страницы. Пустой результат объясняет отсутствие исполненных купонов и
 дивидендов, сохраняя фильтры и налоговое пояснение. Ошибка запроса
-или нарушение принадлежности выплат даёт локальное состояние с действием «Повторить».
+или нарушение принадлежности выплат даёт локальное состояние недоступности
+без действия повтора; чтение восстанавливается автоматически.
 При фоновом обновлении того же периода сохранённый ответ и черновик
-остаются видимыми: загрузку обозначает индикатор, неуспешное обновление —
-предупреждение с повторной попыткой.
+остаются видимыми без индикации обновления и технического предупреждения.
+Неполнота применённого периода обозначается состоянием самого результата.

 На узком экране поля и действия идут вертикально; все карточки выплат
 остаются в общем потоке страницы без раскрытия или внутренних областей прокрутки.
@@ -131,7 +131,8 @@ BondBy переиспользуется зависимостями выпуск
 выплат. Наблюдение статуса не запускает повторный импорт. Политика источников
 и границы — в [модели свежести](../../architecture/cross-cutting/data-freshness.md).

-Разделы загружаются независимо, показывают каркас загрузки и локальную повторную попытку.
+Разделы загружаются независимо, показывают каркас загрузки и локальное
+спокойное состояние недоступности без действия повтора.
 Ошибка фонового обновления сохраняет последние данные. Смена подключения
 сбрасывает поддерево клиентских запросов облигаций вместе с остальными финансовыми запросами;
 выход очищает кэш сессии. Общие график, позиция и личные события
@@ -42,7 +42,8 @@
 время получения списка. Изменение условий не заменяет текущий список до
 следующего нажатия «Найти». Повторный поиск получает новый каталог; страницы
 одного результата не пересчитываются. Подтверждённый пустой результат отличается
-от ошибки источника, для которой интерфейс предлагает повторить поиск.
+от ошибки источника: она сообщается рядом с полем поиска, а повторить запрос
+пользователь может обычным «Найти» — отдельного действия повтора чтения нет.

 Ссылка карточки принадлежит выбранному UID; данные разных режимов не смешиваются.
 Прямые ссылки из портфеля сохраняют
@@ -63,8 +64,9 @@
 рыночные данные и личная история остаются доступны.

 Каждый раздел загружается независимо. Первичная загрузка показывает каркас
-раздела, ошибка — локальную повторную попытку. При ошибке фонового обновления
-сохраняются предыдущие данные и предупреждение. Цена содержит собственное время
+раздела, затянувшаяся недоступность — локальное спокойное состояние без
+повторной попытки. При ошибке фонового обновления сохраняются предыдущие
+данные без технического предупреждения. Цена содержит собственное время
 UTC, которое может быть старше времени получения ответа. Статус торгов не
 выводится из свежести цены. Отсутствующее значение не заменяется нулём.

@@ -166,8 +168,9 @@ TTM означает последние 12 месяцев, MRQ — послед
 Закрытые полные свечные интервалы, включая пустые, сохраняются после restart.
 Новый день не делает прежнюю незавершённую свечу полной.

-«Обновить» передаёт текущий инструмент, выбранный график и personal-history
-scope. Частичные строки видны с предупреждением; неполные личные оценки
+Отдельного действия «Обновить» на странице нет: чтение текущего инструмента,
+выбранного графика и personal-history scope выполняется автоматически.
+Частичные строки видны с обозначением неполноты; неполные личные оценки
 не становятся нулями. Статус и `sync=observe` не создают новый импорт.
 Смена подключения и известный access loss очищают личное представление;
 поздние ответы не возвращают прежние данные. Детали —
@@ -12,11 +12,12 @@
   величины. Убедитесь, что сравниваемые значения относятся к одному составу
   счетов и инструменту. Название или тикер сами по себе не доказывают
   совпадение выпуска; используйте доступные UID, FIGI и ISIN.
-2. **Сопоставьте время.** Проверьте `lastSuccessfulAt`, `isStale` и наличие
-   предупреждения о клиентском обновлении. Серверный снимок не обещает время
+2. **Сопоставьте время.** Проверьте `lastSuccessfulAt`, `isStale` и показанный
+   исход последней часовой попытки. Серверный снимок не обещает время
   каждой котировки, а общий портфель может соединять разные моменты.
-   Если запрос завершился ошибкой, доступное действие «Повторить» должно
-   обновить результат или оставить объяснимую ошибку. Перезагрузка backend
+   Действия «Повторить» на экране нет: временный сбой чтения восстанавливается
+   автоматически, поэтому расхождение проверяйте по показанному состоянию
+   источника, а не по результату ручного обновления. Перезагрузка backend
   сохраняет последний полный снимок в SQLite, но не создаёт историю стоимости.
 3. **Проверьте состав суммы.** Для одной валюты итог складывается из
   вычислимых стоимостей позиций и доступных денег. Не добавляйте деньги
@@ -80,11 +80,12 @@ Backend получает данные через серверную
 сохраняются предыдущие суммы и время успешного получения в UTC.

 Серверный `isStale` обозначает возраст снимка старше часа: обновлением
-владеет часовой обход, а не запрос экрана.
-Клиентское предупреждение означает неудачную попытку обновить уже показанный
-ответ. Эти состояния независимы и могут появиться одновременно.
-Успешный повторный запрос обновляет суммы и время, снимает клиентскую ошибку;
-серверное предупреждение определяется новым `isStale`.
+владеет часовой обход, а не запрос экрана. Он показывается рядом с суммами
+вместе с временем последнего успешного результата и исходом последней часовой
+попытки. Неудачная попытка клиента обновить уже показанный ответ о себе не
+сообщает: эти состояния независимы, но пользователю видимо только состояние
+источника. Успешное автоматическое перечитывание обновляет суммы и время;
+обозначение устаревания определяется новым `isStale`.
 Правила времени и ошибок приведены в [потоке загрузки](flows/portfolio-loading.md).

 Отдельного чтения истории стоимости нет, но каждый полный снимок