docs/glossary.md

Глоссарий WealthLedger

Краткие определения предметных понятий и значимых технических терминов. Связи между ними объясняет обзор продукта, подробные правила — предметные области.

Релиз развёртывания WealthLedger

Версия комплекта установки WealthLedger, закрепляющая проверенную совместимую пару релизов frontend и backend. Понятие принято в ADR 016.

Не использовать: релиз 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 для ручного учёта локального пользователя. Хранит начало учёта, начальный остаток и собственную историю; не является 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, но не определяют количество, стоимость или факт события.

Не использовать: бумага, тикер, актив позиции.

Скринер акций

Подбор выпусков акций по заданным условиям из каталога T-Bank с указанием времени получения списка. Скринер отличается от текстового поиска конкретного инструмента, личного портфеля и подтверждения исполнимости сделки.

Не использовать: гарантия покупки, личная проверка доступа к сделке.

Instrument Logo

Имя файла бренда T-Bank для отображения Instrument в интерфейсе; presentation metadata, которая не влияет на количество или стоимость позиции. Изображение загружается frontend из публичного брендового CDN без авторизации; при отсутствии имени или ошибке загрузки используется фолбэк с первой буквой отображаемого имени.

Не использовать: аватар актива, иконка бумаги.

Cash Balance

Ненулевой доступный денежный остаток Portfolio в одной валюте; не является Portfolio Position и передаётся отдельно от positions в cashBalances.

Не использовать: валютная позиция, заблокированные средства.

Portfolio Snapshot

Полный успешно полученный состав Portfolio на определённый момент времени, который может быть свежим или устаревшим fallback-представлением.

Не использовать: история портфеля, snapshot для графика.

Точка истории стоимости портфеля

Полная оценка одного Brokerage Account в одной валюте на момент успешного обновления Portfolio; последовательность таких точек описывает изменение оценки во времени, включая неторговые дни. Не является Portfolio 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. Текущее хранение coverage и независимая свежесть объяснены в модели данных.

Не использовать: свежесть истории, отсутствие операций как признак полноты.

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 инструмента. Полный состав и правила нормализации описаны в журнале операций.

Не использовать: сырой 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. Сохраняет исходные валюты и знаки денежных выплат, переданных брокером. Это не налоговый расчёт, прогноз или инвестиционная доходность; правила расчёта объясняет область дохода.

Не использовать: доходность, общий доход в одной валюте, гарантированный доход.