ksv741
07de062ebb
Conventional commits / commits (pull_request) Successful in 14s
Docs security / security (pull_request) Successful in 8s
Docs verify / verify (pull_request) Successful in 13s
Docs security / security (push) Successful in 8s
Docs verify / verify (push) Successful in 12s
Document local data ownership, coverage and freshness, refresh behavior, failure recovery and additive migration rollback. Record ADR 017.
262 lines
15 KiB
Markdown
262 lines
15 KiB
Markdown
# Глоссарий WealthLedger
|
||
|
||
Краткие определения предметных понятий и значимых технических терминов.
|
||
Связи между ними объясняет [обзор продукта](overview.md), подробные правила —
|
||
[предметные области](README.md#предметные-области).
|
||
|
||
## Релиз развёртывания WealthLedger
|
||
|
||
Версия комплекта установки WealthLedger, закрепляющая проверенную совместимую
|
||
пару релизов frontend и backend. Понятие принято в
|
||
[ADR 016](adr/016-versioned-deployment-bundle.md).
|
||
|
||
_Не использовать_: релиз frontend или backend как синоним релиза всей установки.
|
||
|
||
## 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.
|
||
|
||
_Не использовать_: проводка, рассчитанная операция.
|
||
|
||
## Полнота истории счёта
|
||
|
||
Подтверждённость того, что за указанный период загружены все доступные
|
||
исполненные операции счёта на момент успешной сверки с брокером. Полный период
|
||
может не содержать операций; полнота не гарантирует отсутствия последующих
|
||
исправлений брокера и отличается от свежести данных.
|
||
|
||
Понятие принято в [ADR 017](adr/017-local-tbank-reads-and-background-sync.md).
|
||
Текущее хранение coverage и независимая свежесть объяснены в
|
||
[модели данных](architecture/cross-cutting/data-freshness.md).
|
||
|
||
_Не использовать_: свежесть истории, отсутствие операций как признак полноты.
|
||
|
||
## Operation Category
|
||
|
||
Нормализованная категория Ledger Entry для фильтрации и отображения:
|
||
`trade`, `income`, `tax`, `fee`, `transfer` или `other`.
|
||
|
||
_Не использовать_: upstream operation type как category.
|
||
|
||
## Ledger Page Cache
|
||
|
||
Исторический технический термин: RAM-кэш страницы Account Ledger.
|
||
Текущее чтение использует сохранённые операции и coverage в SQLite;
|
||
страница не является единицей полноты.
|
||
|
||
_Не использовать_: operations cache, кэш отдельных операций.
|
||
|
||
## Ledger Page Cache Key
|
||
|
||
Исторический ключ RAM-кэша, разделявший страницы по пользователю, подключению,
|
||
счёту и параметрам запроса, включая необязательный 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).
|
||
|
||
_Не использовать_: доходность, общий доход в одной валюте, гарантированный
|
||
доход.
|