docs: reorganize system knowledge by domain

2026-09-12 14:45:42 +03:00
parent 3a99af1a6e
commit f20c3f47bc
83 changed files with 2229 additions and 7335 deletions
@@ -0,0 +1,72 @@
+# Свежесть данных и повторное использование
+
+WealthLedger показывает финансовое наблюдение на момент получения данных.
+Временный кэш уменьшает повторные обращения к брокеру, но не превращает
+снимки в историю портфеля и не обещает рыночные данные в реальном времени.
+
+## Клиентский и серверный снимки
+
+[Client Cached Snapshot](../../glossary.md#client-cached-snapshot) — последний
+успешный ответ, сохранённый TanStack Query в SPA. При обычном фоновом обновлении
+того же набора данных уже показанный результат остаётся на экране; ошибка
+обновления сообщает о проблеме, не заменяя известные значения пустотой.
+Клиентский кэш не является внешней системой или отдельным runtime-приложением.
+
+[Portfolio Snapshot](../../glossary.md#portfolio-snapshot) — полный результат
+загрузки портфеля на backend. В пределах разрешённого сценарием срока он может
+служить серверным fallback при временной ошибке upstream. Backend отмечает
+такой ответ `isStale`; frontend не выводит это поле из состояния собственного
+query-кэша. Серверное предупреждение и ошибка клиентского refetch могут
+возникать независимо.
+
+Свежесть и допустимость fallback определяются сценарием. Портфельный fallback
+не распространяется автоматически на журнал, прогноз событий или страницу
+инструмента. Точные правила находятся в
+[справочнике портфеля](../../domains/portfolio/data-reference.md),
+[журнале операций](../../domains/operations/overview.md) и
+[будущих событиях](../../domains/income/upcoming-events.md).
+
+По [ADR 007](../../adr/007-react-query-fetch-policy.md) запрос связан с открытием
+экрана, а возврат фокуса окна не запускает refetch. Повторное открытие после
+`staleTime` может обновить ответ в фоне. Эта политика не является таймером
+периодического обновления. Перезапуск backend уничтожает его in-memory
+снимки и continuations журнала; SQLite не восстанавливает их.
+
+## Смена подключения
+
+Кэш финансовых данных относится к пользователю, счёту и текущему
+подключению T-Bank. Backend сначала читает подключение и его generation, затем
+проверяет возможность повторного использования ответа. Свежий портфель
+одного счёта не требует нового запроса списка счетов у брокера; при обновлении
+портфеля доступ проверяется заново. Журнал операций проверяет доступ до чтения
+кэшированной страницы. Идентификатор счёта и совпадение параметров запроса
+сами по себе недостаточны для выдачи кэша.
+
+При каждом успешном сохранении подключения token шифруется с новым
+AES-GCM nonce. Из сохранённого шифротекста backend вычисляет непрозрачную
+внутреннюю generation. Она не хранится отдельным полем базы и не входит
+в API, журналы или ошибки. Portfolio Snapshot и Ledger Page Cache допускают
+повторное использование только в пределах соответствующей generation.
+Старый кэш или поздно завершившийся запрос прежней generation не обслуживает
+новый запрос после замены подключения, включая сохранение того же plaintext
+token. Удаление подключения не оставляет доступного контекста для чтения кэша.
+
+После успешного изменения подключения frontend сначала записывает
+подтверждённый status, затем сбрасывает generated GET queries в поддеревьях
+`/api/v1/brokerage-accounts`, `/api/v1/stocks` и `/api/v1/bonds`. Активные
+выборки запрашиваются заново, неактивные — при следующем использовании.
+Client Cached Snapshot прежнего подключения больше не служит результатом
+новой границы.
+
+Неуспешная операция подключения не меняет статус, generation и доступные
+финансовые данные. Обычная ошибка refetch также сохраняет клиентский снимок
+текущей границы. Logout — отдельное событие: оно очищает состояние
+пользовательской сессии, status подключения и query cache.
+
+Пользовательский сценарий описан в [интеграции T-Bank](../../integrations/tbank.md).
+Согласованные правила frontend находятся в workspace-спецификациях
+[query coherence](../../../specs/openspec/specs/frontend-query-coherence/spec.md)
+и [data resilience](../../../specs/openspec/specs/frontend-data-resilience/spec.md);
+серверные правила — в
+[portfolio](../../../specs/openspec/specs/portfolio-view/spec.md) и
+[ledger](../../../specs/openspec/specs/brokerage-account-ledger/spec.md).
@@ -0,0 +1,49 @@
+# Ожидание, ошибки и восстановление интерфейса
+
+Интерфейс различает ожидание данных, известную ошибку запроса и непойманную
+ошибку отображения маршрута. Эти состояния требуют разных действий и
+не подменяют друг друга.
+
+## Ожидание и доступные данные
+
+При первой загрузке без результата structural skeleton показывает
+расположение ожидаемых блоков. При частичной загрузке он занимает только
+незагруженную область. Placeholders не содержат правдоподобных финансовых
+данных, не становятся действиями и не получают клавиатурный фокус; область
+ожидания обозначается как занятая.
+
+При восстановлении сессии SPA показывает нейтральный skeleton каркаса,
+пока неизвестно, доступен public или protected маршрут. При загрузке
+отложенного маршрута уже доступный каркас остаётся видимым.
+
+Фоновое обновление и действие пользователя сохраняют видимые данные или
+элемент управления с компактной индикацией процесса. В частности,
+[клиентский снимок](data-freshness.md#клиентский-и-серверный-снимки) счетов или
+портфеля остаётся доступным после ошибки refetch; сообщение и повтор
+относятся к обновлению, а не к отсутствию инвестиций.
+
+## Известная ошибка сценария
+
+Ошибки счетов, портфеля и подключения T-Bank остаются локальными: рядом
+с затронутыми данными доступны предусмотренные сценарием retry и navigation
+actions. Устаревший серверный Portfolio Snapshot показывает сохранённый
+портфель с предупреждением. Он не превращается в глобальный fallback.
+Ошибка источника не означает нулевой баланс или отсутствие операций.
+
+## Непойманная ошибка маршрута
+
+Непойманная runtime-ошибка при отображении public или protected route
+заменяет его содержимое нейтральным fallback без технических деталей.
+Пользователь может перейти к `/accounts` при активной сессии или к `/login`
+без неё. Переход на другой маршрут сбрасывает это состояние; если новый
+маршрут отображается успешно, пользователь продолжает работу.
+
+Общий fallback восстанавливает навигацию, но не обещает устранить причину
+ошибки. HTTP-коды и безопасная форма серверной ошибки находятся в
+[HTTP API](../http-api.md), восстановление сессии — в
+[аутентификации](../../domains/authentication/overview.md).
+
+Согласованное поведение раскрыто в workspace-спецификациях
+[UI resilience](../../../specs/openspec/specs/frontend-ui-resilience/spec.md),
+[loading presentation](../../../specs/openspec/specs/frontend-loading-presentation/spec.md)
+и [data resilience](../../../specs/openspec/specs/frontend-data-resilience/spec.md).