From 68d975befda90c198a0287bb8d43ac5d6e386eb5 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Tue, 25 Aug 2026 22:30:08 +0300 Subject: [PATCH] docs: align investment domain terminology --- architecture/domain-glossary.md | 42 ++++++++++++++----- architecture/system-overview.md | 5 ++- features/brokerage-account-upcoming-events.md | 4 +- features/brokerage-accounts.md | 4 +- features/portfolio-view.md | 8 ++-- 5 files changed, 43 insertions(+), 20 deletions(-) diff --git a/architecture/domain-glossary.md b/architecture/domain-glossary.md index bbf083a..ff20bd3 100644 --- a/architecture/domain-glossary.md +++ b/architecture/domain-glossary.md @@ -3,8 +3,8 @@ ## User Локальный владелец данных WealthLedger, идентифицируемый `id` и -нормализованным email. User владеет Session, T-Bank connection и видит только -свои Brokerage Accounts. +нормализованным email. User владеет Session и T-Bank connection и видит только +Brokerage Accounts, доступные через его текущее T-Bank connection. _Не использовать_: клиент T-Bank, инвестор T-Bank. @@ -21,7 +21,9 @@ _Не использовать_: T-Bank сессия, browser session. Денежная сумма в одной ISO-валюте, передаваемая как `{ currency, value }`, где `value` — decimal string без экспоненциальной записи. Backend выполняет точные -операции, frontend форматирует Money для отображения. +операции, frontend форматирует Money для отображения. Неизвестное или +неприменимое денежное значение передаётся как `null`, а не как ноль и не как +раздельные `amount`/`currency`. _Не использовать_: number amount, MoneyDto как доменный термин. @@ -34,8 +36,10 @@ _Не использовать_: аккаунт T-Bank, авторизация T ## Brokerage Account -Открытый поддерживаемый инвестиционный счёт T-Bank, доступный через T-Bank -connection: брокерский счёт, ИИС, Инвесткопилка или фонд денежного рынка. +Открытый поддерживаемый инвестиционный счёт T-Bank, доступный через текущее +T-Bank connection User: брокерский счёт, ИИС, Инвесткопилка или фонд денежного +рынка. WealthLedger не хранит Brokerage Account как долговременный объект +владения независимо от T-Bank connection. _Не использовать_: счёт T-Bank, банковский счёт. @@ -57,7 +61,8 @@ _Не использовать_: общий портфель, баланс сч ## Portfolio Position Ненулевой обычный инвестиционный актив в составе Portfolio с количеством и -доступными оценочными показателями. +доступными оценочными показателями. Portfolio Position не является Cash +Balance, даже когда её type равен `CURRENCY`. _Не использовать_: валютная позиция, виртуальная позиция. @@ -69,11 +74,20 @@ instrument type: `STOCK`, `BOND`, `FUND`, `CURRENCY`, `FUTURE`, `OPTION`, _Не использовать_: upstream instrument type как доменный enum. +## Currency Instrument Position + +Portfolio Position с type `CURRENCY`, представляющая торгуемый валютный +Instrument. Она остаётся в `positions` и не объединяется с Cash Balance той же +валюты. + +_Не использовать_: денежный остаток, cash balance. + ## Instrument Ценная бумага или иной торгуемый актив T-Bank, на который ссылается Portfolio -Position через FIGI или instrument UID. Metadata Instrument обогащают -отображение Position, но не определяют количество или стоимость. +Position или Future Cash Event через FIGI или instrument UID. Metadata +Instrument обогащают отображение Position или Event, но не определяют +количество, стоимость или факт события. _Не использовать_: бумага, тикер, актив позиции. @@ -101,6 +115,9 @@ _Не использовать_: валютная позиция, заблоки _Не использовать_: история портфеля, snapshot для графика. +Следующие термины описывают runtime/cache-механизмы. Они не являются +самостоятельными бизнес-сущностями. + ## Client Cached Snapshot Последний успешно полученный frontend-ответ React Query, который остаётся @@ -167,9 +184,12 @@ _Не использовать_: активный refresh token, признак Прогнозируемое на ближайший период денежное или связанное корпоративное событие одного Brokerage Account, рассчитанное по текущей Portfolio Position; -не является исполненной Ledger Entry. API/code сохраняют legacy names -`UpcomingEventDto`, `UpcomingEventsDto`, `/events` и frontend `BrokerageEvent`; -в доменной документации primary term — Future Cash Event. +не является исполненной Ledger Entry. Прогнозная сумма события передаётся как +nullable Money: известные coupon, dividend и maturity содержат Money в исходной +валюте, offer или неизвестные денежные условия передаются как `null`. +API/code сохраняют legacy names `UpcomingEventDto`, `UpcomingEventsDto`, +`/events` и frontend `BrokerageEvent`; в доменной документации primary term — +Future Cash Event. _Не использовать_: будущая операция, гарантированная выплата. diff --git a/architecture/system-overview.md b/architecture/system-overview.md index 6a5f2f7..3bd4920 100644 --- a/architecture/system-overview.md +++ b/architecture/system-overview.md @@ -28,8 +28,9 @@ WealthLedger — локальное приложение для просмотр генерируется штатным workflow. - Поставка остаётся локальной: deployment, Docker, CI/CD и облачные сервисы не входят в текущие границы. -- Snapshot Portfolio и кэш Ledger существуют только в runtime-памяти; система - не предоставляет историческое хранилище портфеля. +- Portfolio Snapshot, Future Cash Events и Ledger pages существуют как + read-only наблюдения текущего T-Bank connection; система не хранит историю + портфеля, будущих событий или брокерских счетов как долговременные агрегаты. ## Поток auth/session diff --git a/features/brokerage-account-upcoming-events.md b/features/brokerage-account-upcoming-events.md index ff5d9c3..280cf9a 100644 --- a/features/brokerage-account-upcoming-events.md +++ b/features/brokerage-account-upcoming-events.md @@ -1,6 +1,6 @@ # Будущие события брокерского счёта -Авторизованный пользователь видит до пяти ближайших событий на обзоре `/accounts/:accountId` и открывает полный список известный событий этого счёта на `/accounts/:accountId/events`. Ошибка или пустой результат блока на обзоре не заменяет Portfolio. +Авторизованный пользователь видит до пяти ближайших событий на обзоре `/accounts/:accountId` и открывает полный список известных событий Brokerage Account, доступного через текущее T-Bank connection, на `/accounts/:accountId/events`. Ошибка или пустой результат блока на обзоре не заменяет Portfolio. ```mermaid sequenceDiagram @@ -22,7 +22,7 @@ sequenceDiagram `GET /api/v1/brokerage-accounts/:accountId/events` требует Bearer access token. Ответ содержит `accountId`, `calculatedAt` и отсортированный по календарной дате список `events`. -Событие содержит `type` (`coupon`, `dividend`, `maturity`, `offer`), `date`, `dateKind`, идентификаторы и название инструмента, а также исходную `currency` и nullable `amount`. Для `offer` сумма не создаётся искусственно. Дивиденд передаёт `dateKind: registry`: это дата закрытия реестра, а не гарантированная дата зачисления. +Событие содержит `type` (`coupon`, `dividend`, `maturity`, `offer`), `date`, `dateKind`, идентификаторы и название Instrument, а также nullable `projectedAmount` как Money `{ currency, value }`. Для `offer` и неизвестных денежных условий сумма не создаётся искусственно и передаётся `null`. Дивиденд передаёт `dateKind: registry`: это дата закрытия реестра, а не гарантированная дата зачисления. ## Поведение и ограничения diff --git a/features/brokerage-accounts.md b/features/brokerage-accounts.md index 9ba456d..4ce705f 100644 --- a/features/brokerage-accounts.md +++ b/features/brokerage-accounts.md @@ -1,6 +1,6 @@ # Брокерские счета -Авторизованный пользователь просматривает открытые поддерживаемые инвестиционные счета T-Bank на странице `/accounts`. Для получения списка требуется сохранённое T-Bank connection; frontend никогда не обращается к T-Bank напрямую. +Авторизованный пользователь просматривает открытые поддерживаемые инвестиционные счета T-Bank, доступные через его текущее T-Bank connection, на странице `/accounts`. Для получения списка требуется сохранённое T-Bank connection; frontend никогда не обращается к T-Bank напрямую. WealthLedger не хранит Brokerage Account как долговременное владение отдельно от брокерского подключения. ```mermaid sequenceDiagram @@ -40,6 +40,8 @@ sequenceDiagram Поддерживаемые `type`: `BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX`, `MONEY_MARKET_FUND`. Банковские и неизвестные типы T-Bank не возвращаются. Пустое upstream-название заменяется названием типа, а отсутствующая дата открытия передаётся как `null`. +Список является результатом текущего наблюдения T-Bank connection: если счёт больше не открыт, не поддерживается или недоступен через это подключение, он не считается доступным для WealthLedger. + ## Состояния - `409 TBANK_NOT_CONNECTED`: список не запрашивается у T-Bank, экран ведёт в настройки. diff --git a/features/portfolio-view.md b/features/portfolio-view.md index 67bb6a9..1fcfab4 100644 --- a/features/portfolio-view.md +++ b/features/portfolio-view.md @@ -1,6 +1,6 @@ # Портфель -Авторизованный пользователь просматривает текущий состав одного доступного брокерского счёта на `/accounts/:accountId`. Frontend обращается только к backend API; T-Bank остаётся server-side интеграцией. +Авторизованный пользователь просматривает текущий Portfolio Snapshot одного Brokerage Account, доступного через текущее T-Bank connection, на `/accounts/:accountId`. Frontend обращается только к backend API; T-Bank остаётся server-side интеграцией. ```mermaid sequenceDiagram @@ -31,11 +31,11 @@ sequenceDiagram ## API -`GET /api/v1/brokerage-accounts/:accountId/portfolio` требует Bearer access token. Успешный ответ содержит `lastSuccessfulAt` в RFC 3339 UTC, `isStale`, `totalsByCurrency`, `positions` и `cashBalances`. +`GET /api/v1/brokerage-accounts/:accountId/portfolio` требует Bearer access token. Успешный ответ содержит Portfolio Snapshot: `lastSuccessfulAt` в RFC 3339 UTC, `isStale`, `totalsByCurrency`, `positions` и `cashBalances`. -Все количества и суммы передаются decimal strings без экспоненциальной записи. Деньги содержат ISO-код валюты. Backend выполняет точные операции через `BigInt`; frontend форматирует строки для русской локали и не выполняет финансовую арифметику кроме display-only оценки доли позиции. +Все количества и суммы передаются decimal strings без экспоненциальной записи. Деньги передаются как Money `{ currency, value }` с ISO-кодом валюты. Backend выполняет точные операции через `BigInt`; frontend форматирует строки для русской локали и не выполняет финансовую арифметику кроме display-only оценки доли позиции. -`Portfolio Position` -- ненулевой обычный актив из T-Bank portfolio. `currentValue` равен количеству, умноженному на текущую цену, когда оба значения и валюта доступны. `absoluteReturn` доступен только при одинаковой известной валюте текущей и средней цены. `isin` берётся из metadata Instrument и передаётся nullable-строкой. Невычислимые значения передаются `null`, а не нулём. Позиции остаются в upstream-порядке; виртуальные позиции не входят в ответ. +`Portfolio Position` -- ненулевой обычный актив из T-Bank portfolio. Position с type `CURRENCY` означает торгуемый валютный Instrument и не является Cash Balance. `currentValue` равен количеству, умноженному на текущую цену, когда оба значения и валюта доступны. `absoluteReturn` доступен только при одинаковой известной валюте текущей и средней цены. `isin` берётся из metadata Instrument и передаётся nullable-строкой. Невычислимые значения передаются `null`, а не нулём. Позиции остаются в upstream-порядке; виртуальные позиции не входят в ответ. `Cash Balance` -- доступный ненулевой денежный остаток. Несколько остатков одной валюты суммируются; заблокированные средства не включаются. Итоги группируются по валюте и включают стоимость позиций и Cash Balance без конвертации.