ksv741
c0dfb80617
Document exact balances, corrections, archive behavior and safe migration and rollback. Update product navigation and UI catalog.
239 lines
13 KiB
Markdown
239 lines
13 KiB
Markdown
# Глоссарий WealthLedger
|
||
|
||
Краткие определения предметных понятий и значимых технических терминов.
|
||
Связи между ними объясняет [обзор продукта](overview.md), подробные правила —
|
||
[предметные области](README.md#предметные-области).
|
||
|
||
## User
|
||
|
||
Локальный владелец данных WealthLedger, идентифицируемый `id` и
|
||
нормализованным email. User владеет Session, T-Bank connection и своими
|
||
ручными банковскими картами, категориями и операциями. Он видит только
|
||
Brokerage Accounts, доступные через его текущее T-Bank connection.
|
||
|
||
_Не использовать_: клиент T-Bank, инвестор T-Bank.
|
||
|
||
## Session
|
||
|
||
Локальная authenticated-сессия User: короткоживущий access token в браузере и
|
||
server-side refresh token rotation через cookie. Session не является
|
||
T-Bank connection и не подтверждает доступ к Brokerage Account без текущего
|
||
Bearer token.
|
||
|
||
_Не использовать_: T-Bank сессия, browser session.
|
||
|
||
## Money
|
||
|
||
Денежная сумма в одной ISO-валюте, передаваемая как `{ currency, value }`, где
|
||
`value` — decimal string без экспоненциальной записи. Backend выполняет точные
|
||
операции, frontend форматирует Money для отображения. Неизвестное или
|
||
неприменимое денежное значение передаётся как `null`, а не как ноль и не как
|
||
раздельные `amount`/`currency`.
|
||
|
||
_Не использовать_: сумма без валюты, транспортное представление как доменный термин.
|
||
|
||
## Bank Card
|
||
|
||
Независимая дебетовая карта в RUB для [ручного учёта](domains/cards/overview.md)
|
||
локального пользователя. Хранит начало учёта, начальный остаток и собственную
|
||
историю; не является Brokerage Account или общим счётом нескольких карт.
|
||
|
||
## Bank Card Balance
|
||
|
||
Баланс по внесённым операциям: начальный остаток плюс пополнения, входящие
|
||
переводы и возвраты, минус расходы и исходящие переводы. Может быть отрицательным
|
||
и не подтверждает текущий остаток в банковском приложении.
|
||
|
||
## Expense Category
|
||
|
||
Принадлежащая пользователю категория ручных банковских расходов, общая для
|
||
его карт. Переименование сохраняет идентичность и роль категории по умолчанию.
|
||
Возврат использует текущую категорию своей исходной покупки.
|
||
|
||
## Net Card Expenses
|
||
|
||
Расходы выбранного месяца за вычетом возвратов, полученных в этом месяце.
|
||
Итог может быть отрицательным; начальные остатки, переводы и пополнения
|
||
в него не входят.
|
||
|
||
## T-Bank connection
|
||
|
||
Единственное принадлежащее User подключение к T-Bank Invest, содержащее
|
||
зашифрованный token для server-side запросов.
|
||
|
||
_Не использовать_: аккаунт T-Bank, авторизация T-Bank.
|
||
|
||
## Brokerage Account
|
||
|
||
Открытый поддерживаемый инвестиционный счёт T-Bank, доступный через текущее
|
||
T-Bank connection User: брокерский счёт, ИИС, Инвесткопилка или фонд денежного
|
||
рынка. WealthLedger не хранит Brokerage Account как долговременный объект
|
||
владения независимо от T-Bank connection.
|
||
|
||
_Не использовать_: счёт T-Bank, банковский счёт.
|
||
|
||
## Investment Account Type
|
||
|
||
Нормализованная категория Brokerage Account, независимая от upstream enum
|
||
T-Bank: `BROKERAGE`, `INDIVIDUAL_INVESTMENT`, `INVEST_BOX` или
|
||
`MONEY_MARKET_FUND`.
|
||
|
||
_Не использовать_: тип аккаунта T-Bank, protobuf type.
|
||
|
||
## Portfolio
|
||
|
||
Текущее нормализованное состояние инвестиций одного Brokerage Account,
|
||
включающее позиции, доступные денежные остатки и итоги по каждой валюте.
|
||
|
||
_Не использовать_: общий портфель, баланс счёта.
|
||
|
||
## Portfolio Position
|
||
|
||
Ненулевой обычный инвестиционный актив в составе Portfolio с количеством и
|
||
доступными оценочными показателями. Portfolio Position не является Cash
|
||
Balance, даже когда её type равен `CURRENCY`.
|
||
|
||
_Не использовать_: валютная позиция, виртуальная позиция.
|
||
|
||
## Portfolio Position Type
|
||
|
||
Нормализованный display type Portfolio Position, полученный из upstream
|
||
instrument type: `STOCK`, `BOND`, `FUND`, `CURRENCY`, `FUTURE`, `OPTION`,
|
||
`STRUCTURED_NOTE`, `DIGITAL_FINANCIAL_ASSET` или `OTHER`.
|
||
|
||
_Не использовать_: upstream instrument type как доменный enum.
|
||
|
||
## Currency Instrument Position
|
||
|
||
Portfolio Position с type `CURRENCY`, представляющая торгуемый валютный
|
||
Instrument. Она остаётся в `positions` и не объединяется с Cash Balance той же
|
||
валюты.
|
||
|
||
_Не использовать_: денежный остаток, cash balance.
|
||
|
||
## Instrument
|
||
|
||
Ценная бумага или иной торгуемый актив T-Bank, на который ссылается Portfolio
|
||
Position или Future Cash Event через FIGI или instrument UID. Metadata
|
||
Instrument обогащают отображение Position или Event, но не определяют
|
||
количество, стоимость или факт события.
|
||
|
||
_Не использовать_: бумага, тикер, актив позиции.
|
||
|
||
## Instrument Logo
|
||
|
||
Имя файла бренда T-Bank для отображения Instrument в интерфейсе;
|
||
presentation metadata, которая не влияет на количество или стоимость
|
||
позиции. Изображение загружается frontend из публичного брендового CDN
|
||
без авторизации; при отсутствии имени или ошибке загрузки используется
|
||
фолбэк с первой буквой отображаемого имени.
|
||
|
||
_Не использовать_: аватар актива, иконка бумаги.
|
||
|
||
## Cash Balance
|
||
|
||
Ненулевой доступный денежный остаток Portfolio в одной валюте; не является
|
||
Portfolio Position и передаётся отдельно от `positions` в `cashBalances`.
|
||
|
||
_Не использовать_: валютная позиция, заблокированные средства.
|
||
|
||
## Portfolio Snapshot
|
||
|
||
Полный успешно полученный состав Portfolio на определённый момент времени,
|
||
который может быть свежим или устаревшим fallback-представлением.
|
||
|
||
_Не использовать_: история портфеля, snapshot для графика.
|
||
|
||
## Client Cached Snapshot
|
||
|
||
Технический термин: последний успешно полученный frontend-ответ React Query, который остаётся
|
||
видимым во время фонового обновления или после его ошибки. Не является
|
||
server-side fallback и не использует поле `Portfolio.isStale`.
|
||
|
||
_Не использовать_: устаревший Portfolio Snapshot, fallback портфеля.
|
||
|
||
## Account Ledger
|
||
|
||
Упорядоченная read-only история исполненных операций одного Brokerage Account,
|
||
отражающая фактические денежные и инструментальные движения без рыночной
|
||
переоценки или расчёта остатка после операции.
|
||
|
||
_Не использовать_: история Portfolio, баланс счёта.
|
||
|
||
## Ledger Entry
|
||
|
||
Нормализованное представление одной операции T-Bank в Account Ledger; хранит
|
||
исходные суммы и доступные детали операции, не создавая синтетических записей
|
||
для комиссии сделки. В публичном API история доступна через маршруты
|
||
`/operations`; в доменной документации запись называется Ledger Entry.
|
||
|
||
_Не использовать_: проводка, рассчитанная операция.
|
||
|
||
## Operation Category
|
||
|
||
Нормализованная категория Ledger Entry для фильтрации и отображения:
|
||
`trade`, `income`, `tax`, `fee`, `transfer` или `other`.
|
||
|
||
_Не использовать_: upstream operation type как category.
|
||
|
||
## Ledger Page Cache
|
||
|
||
Технический термин: кэш страницы Account Ledger, отделённый от кэша отдельных операций.
|
||
|
||
_Не использовать_: operations cache, кэш отдельных операций.
|
||
|
||
## Ledger Page Cache Key
|
||
|
||
Ключ, разделяющий страницы журнала по пользователю, текущему подключению,
|
||
счёту и параметрам запроса, включая необязательный UID инструмента.
|
||
Полный состав и правила нормализации описаны в
|
||
[журнале операций](domains/operations/overview.md#получение-и-полнота).
|
||
|
||
_Не использовать_: сырой URL query, ключ отдельной Ledger Entry.
|
||
|
||
## Concurrent Refresh Attempt
|
||
|
||
Два или более перекрывающихся запроса с одним ещё действительным refresh token
|
||
одной Session; один становится Refresh Winner, остальные — Refresh Loser и
|
||
получают `401`, не отзывая Session победителя.
|
||
|
||
_Не использовать_: повторное использование refresh token, последовательный
|
||
refresh.
|
||
|
||
## Superseded Refresh Token
|
||
|
||
Refresh token, который перестал быть действительным после успешной ротации
|
||
Session; его предъявление получает `401`, но само по себе не отзывает Session.
|
||
|
||
_Не использовать_: активный refresh token, признак взлома сессии.
|
||
|
||
## Future Cash Event
|
||
|
||
Прогнозируемое на ближайший период денежное или связанное корпоративное
|
||
событие одного Brokerage Account, рассчитанное по текущей Portfolio Position;
|
||
не является исполненной Ledger Entry. Прогнозная сумма события передаётся как
|
||
nullable Money: известные coupon, dividend и maturity содержат Money в исходной
|
||
валюте, offer или неизвестные денежные условия передаются как `null`.
|
||
В публичном API прогноз доступен через маршруты `/events`; в доменной
|
||
документации событие называется Future Cash Event.
|
||
|
||
_Не использовать_: будущая операция, гарантированная выплата.
|
||
|
||
## Future Cash Event Type
|
||
|
||
Нормализованный тип Future Cash Event: `coupon`, `dividend`, `maturity` или
|
||
`offer`.
|
||
|
||
_Не использовать_: upstream dividend type, MOEX row name.
|
||
|
||
## Realized Income Analytics
|
||
|
||
Результат анализа исполненных купонов и дивидендов по счёту за календарный
|
||
период включительно в часовом поясе Europe/Moscow. Сохраняет исходные валюты
|
||
и знаки денежных выплат, переданных брокером. Это не налоговый расчёт,
|
||
прогноз или инвестиционная доходность; правила расчёта объясняет
|
||
[область дохода](domains/income/overview.md).
|
||
|
||
_Не использовать_: доходность, общий доход в одной валюте, гарантированный
|
||
доход.
|