docs: align investment domain terminology
This commit is contained in:
@@ -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.
|
||||
|
||||
_Не использовать_: будущая операция, гарантированная выплата.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`: это дата закрытия реестра, а не гарантированная дата зачисления.
|
||||
|
||||
## Поведение и ограничения
|
||||
|
||||
|
||||
@@ -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, экран ведёт в настройки.
|
||||
|
||||
@@ -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 без конвертации.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user