From ffe29c58f9699d2a7b20af9c79907e918bdb7599 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Wed, 14 Oct 2026 13:18:18 +0300 Subject: [PATCH] docs: align current pages with hourly freshness model (WealthLedger/docs#34) --- architecture/containers.md | 13 ++++++++----- domains/accounts/overview.md | 7 ++++--- domains/instruments/bonds.md | 10 +++++----- domains/instruments/stocks.md | 14 +++++++------- domains/portfolio/data-reference.md | 2 +- domains/portfolio/overview.md | 16 ++++++++++------ 6 files changed, 35 insertions(+), 27 deletions(-) diff --git a/architecture/containers.md b/architecture/containers.md index d471fc9..f5b0da6 100644 --- a/architecture/containers.md +++ b/architecture/containers.md @@ -140,12 +140,15 @@ membership текущей revision перед каждым финансовым личные данные. Ротация refresh token остаётся атомарной. SQLite хранит полный последний portfolio, операции и их подтверждённые -диапазоны, private прогнозы, общие instrument/market sources и intent/staging. +диапазоны, private прогнозы, сохранённые точки истории оценки, общие +instrument/market sources и intent/staging. Нормализованные финансовые значения сохраняются decimal-строками. Полнота -отделена от свежести и пагинации. Ответ не ждёт внешних RPC; запрос при -необходимости запускает работу в том же backend process через существующий -лимитер. На startup импорт не запускается; восстановление требует следующего -запроса. Подробности — [модель свежести](cross-cutting/data-freshness.md). +отделена от свежести и пагинации. Ответ не ждёт внешних RPC; обновлением +личных данных владеет часовой обход в том же backend process через +существующий лимитер, недостающие общие источники он же ставит в фоновую +очередь. На startup обход начинает следующую попытку по обычному часовому +сроку; после нового подключения первая попытка начинается сразу. +Подробности — [модель свежести](cross-cutting/data-freshness.md). PUT подключения сначала проверяет token у T-Bank, затем одной транзакцией сохраняет encrypted token, новую revision и проверенный membership. diff --git a/domains/accounts/overview.md b/domains/accounts/overview.md index dc185c0..8a52b2e 100644 --- a/domains/accounts/overview.md +++ b/domains/accounts/overview.md @@ -71,9 +71,10 @@ ## Свежесть и границы Обычное открытие использует query owner и локальный server snapshot. -«Обновить» запрашивает membership и сводки доступных счетов; активная работа -наблюдается без нового импорта. Истечение TTL само не запускает запрос. -Membership имеет пятиминутную свежесть, portfolio — минутную. Время списка +«Обновить» перечитывает сохранённые membership и сводки доступных счетов; +активная работа наблюдается без нового импорта. Истечение TTL само не +запускает запрос: обновлением личных данных владеет часовой обход. +Membership и portfolio source имеют часовую свежесть. Время списка не подменяет время каждой сводки. Список не заменяет полный [портфель](../portfolio/overview.md), [журнал](../operations/overview.md) или историю закрытых счетов. Для общего результата доступен diff --git a/domains/instruments/bonds.md b/domains/instruments/bonds.md index 96f0a9a..a5f2595 100644 --- a/domains/instruments/bonds.md +++ b/domains/instruments/bonds.md @@ -121,8 +121,8 @@ HTML-источник, общий кэш и поведение при измен portfolio; они не попадают в общие источники. BondBy переиспользуется зависимостями выпуска. Discovery принадлежит query, -свежесть — конкретному source/range. Missing/stale зависимости запрашиваются -в фоне через прежний limiter; обычный HTTP-ответ не ждёт брокера. +свежесть — конкретному source/range. Missing/stale зависимости ставятся +в фоновую очередь через прежний limiter; обычный HTTP-ответ не ждёт брокера. Покрытые завершённые свечи не перечитываются после restart. Открытый хвост остаётся изменяемым; ручной refresh охватывает показанный период. @@ -150,6 +150,6 @@ BondBy переиспользуется зависимостями выпуск ## Online reference -Bond detail, search, and ticker lookup are read from the upstream integration -on each request. Saved quotes, candles, events, ratings, and portfolio labels -retain their own freshness and failure boundaries. +Страница облигации, поиск и переход по тикеру обращаются к онлайн-справочнику +брокера; сохранённые quotes, свечи, события, ratings и метки портфеля +сохраняют собственные границы свежести и ошибок. diff --git a/domains/instruments/stocks.md b/domains/instruments/stocks.md index f3f5c6b..4f35923 100644 --- a/domains/instruments/stocks.md +++ b/domains/instruments/stocks.md @@ -159,9 +159,10 @@ TTM означает последние 12 месяцев, MRQ — послед источники переиспользуются между пользователями, но личные позиции и выплаты всегда проверяют доступ. -Обычное чтение не ждёт RPC; missing/stale зависимости запрашиваются в фоне -через существующий T-Bank limiter. Минутная свежесть применяется к quotes -и открытому хвосту свечей, суточная — к metadata/company/календарям. +Обычное чтение не ждёт RPC; missing/stale зависимости ставятся в фоновую +очередь через существующий T-Bank limiter. Часовая свежесть применяется +к quotes и открытому хвосту свечей; metadata/company/календари, будучи +сохранёнными, не перечитываются обычным чтением. Закрытые полные свечные интервалы, включая пустые, сохраняются после restart. Новый день не делает прежнюю незавершённую свечу полной. @@ -197,7 +198,6 @@ scope. Частичные строки видны с предупреждени ## Online reference -Stock detail, company data, search, and ticker lookup are read from the -upstream integration on each request. Saved positions, quotes, candles, and -events remain independent local resources and are not replaced by a reference -read failure. +Страница акции, поиск и переход по тикеру обращаются к онлайн-справочнику +брокера; сохранённые позиции, quotes, свечи и события остаются независимыми +локальными ресурсами и не подменяются ошибкой справочника. diff --git a/domains/portfolio/data-reference.md b/domains/portfolio/data-reference.md index 4912199..69dd72e 100644 --- a/domains/portfolio/data-reference.md +++ b/domains/portfolio/data-reference.md @@ -32,7 +32,7 @@ | Cash Balance | Суммы из `GetPositions.money`, объединённые по валюте | Заблокированные деньги не прибавляются; торгуемый инструмент `CURRENCY` остаётся позицией | | `totalsByCurrency` | Стоимости позиций + доступные деньги той же валюты | Не включает невычислимую стоимость; не обещает полную оценку портфеля | | `lastSuccessfulAt` | Время формирования успешного снимка, UTC | Не является временем каждой котировки; запасной снимок сохраняет исходное время | -| `isStale` | Истёк минутный срок свежести сохранённого portfolio source | Не описывает состояние клиентского кэша или ошибку фонового запроса | +| `isStale` | Истёк часовой срок свежести сохранённого portfolio source | Не описывает состояние клиентского кэша или ошибку фонового запроса | Ненулевые денежные остатки одной валюты суммируются. Позиции одинаковых инструментов в ответе отдельного счёта не объединяются; визуальная группировка diff --git a/domains/portfolio/overview.md b/domains/portfolio/overview.md index 9f0f791..c6d5314 100644 --- a/domains/portfolio/overview.md +++ b/domains/portfolio/overview.md @@ -79,18 +79,22 @@ Backend получает данные через серверную не содержат данных и не получают фокус. При обычном фоновом обновлении сохраняются предыдущие суммы и время успешного получения в UTC. -Серверный `isStale` обозначает истечение минутной свежести снимка. +Серверный `isStale` обозначает возраст снимка старше часа: обновлением +владеет часовой обход, а не запрос экрана. Клиентское предупреждение означает неудачную попытку обновить уже показанный ответ. Эти состояния независимы и могут появиться одновременно. Успешный повторный запрос обновляет суммы и время, снимает клиентскую ошибку; серверное предупреждение определяется новым `isStale`. Правила времени и ошибок приведены в [потоке загрузки](flows/portfolio-loading.md). -В текущем решении нет долговременной истории снимков, графиков стоимости -портфеля, валютной конвертации, учёта виртуальных позиций или заблокированных -средств. Последний полный снимок сохраняется после перезапуска; выполнение -синхронизации рассчитано на один экземпляр backend. Действие «Обновить» -перечитывает зависимости открытого экрана независимо от их свежести. +Отдельного чтения истории стоимости нет, но каждый полный снимок +сохраняет точку оценки по счёту и валюте для будущих поддерживаемых +представлений; публичного графика в текущем решении нет. Нет также +валютной конвертации, учёта виртуальных позиций или заблокированных +средств. Последний полный снимок сохраняется после перезапуска; +обновлением личных данных владеет часовой обход, рассчитанный на один +экземпляр backend. Действие «Обновить» выполняет только локальное +перечитывание открытого экрана и не запускает работу с T-Bank. Для проверки конкретной суммы используйте [руководство по расхождениям](how-to/investigate-discrepancy.md).