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).