docs/glossary.md

# Глоссарий 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,
включающее позиции, доступный денежный остаток и итоговую сумму в RUB.

_Не использовать_: общий портфель, баланс счёта.

## 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.

## Концентрация

Вкладка страницы одного Brokerage Account, показывающая, какие акции,
облигации, секторы и эмитенты занимают наибольшую часть текущей оценки
Portfolio в RUB. Отличается от [структуры
портфеля](domains/portfolio/data-reference.md#структура-и-доли): в её разрезах
деньги не входят в знаменатель долей.

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

## Разрез

Одна из четырёх группировок вкладки «Концентрация»: «Акции», «Облигации»,
«Секторы», «Эмитенты». Элемент разреза — единица ранжирования; сектор
агрегирует позиции `STOCK`, `BOND` и `FUND`, эмитенты — `STOCK` и `BOND`.

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

## Сектор

Значение сектора инструмента в том виде, как его определяет T-Bank, без
перекодирования и собственной классификации WealthLedger. Заполняется для
позиций `STOCK`, `BOND` и `FUND`; государственные облигации определяются
значением `government` с подписью «Государственный сектор». Позиция без
сектора попадает в явную группу «Сектор не указан».

_Не использовать_: отрасль, собственная классификация приложения.

## Эмитент

В разрезе «Эмитенты» вкладки «Концентрация» — бренд актива по данным T-Bank,
объединяющий акции и облигации одной компании; фонды в разрез не входят.
Название эмитента — название бренда. **Оговорка:** в этом разрезе слово
означает бренд актива T-Bank, а не юридического эмитента ценной бумаги;
[рейтинг выпуска](integrations/nkr.md) не подставляется вместо рейтинга
эмитента и наоборот. Позиция без бренда попадает в явную группу
«Эмитент не указан».

_Не использовать_: юридический эмитент, эмитент рейтинга.

## 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 в RUB; не является
Portfolio Position и передаётся отдельно от `positions`.

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

## Portfolio Snapshot

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

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

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

Полная оценка одного Brokerage Account в RUB на момент успешного
обновления 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](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 в RUB, 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. Сохраняет знаки денежных выплат,
переданных брокером, в RUB. Это не налоговый расчёт,
прогноз или [Результат инвестирования](#результат-инвестирования); правила
расчёта объясняет [область дохода](domains/income/overview.md).

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

## Результат инвестирования

Прибыль, доходность и сравнение с индексом Мосбиржи для счёта или «Все
счета» за всё время в рублях. Правила описаны в
[результате инвестирования](domains/portfolio/investment-performance.md),
решение — в [ADR 023](adr/023-investment-performance-vs-index.md).

_Не использовать_: нереализованный результат, доход.

## Внешний денежный поток

Пополнение (положительный поток) или вывод (отрицательный поток) рублей со
счёта. Сделки, выплаты, налоги и комиссии внешними потоками не являются.

_Не использовать_: операция, выплата.

## Доходность (XIRR)

Годовая ставка, при которой дисконтированные по фактическим дням внешние
потоки и текущая стоимость в сумме дают ноль. При истории короче года
показывается доходность за период. Единственное значение термина
«доходность» для личного результата.

_Не использовать_: доходность к погашению, рост цены позиции.

## Те же деньги в индексе Мосбиржи

Стоимость и доходность тех же внешних потоков, вложенных в индекс полной
доходности MCFTRR по закрытию дня потока. Ценовой IMOEX — только справка.

_Не использовать_: бенчмарк IMOEX, теневой портфель (в интерфейсе).

## Опережение рынка

Разница доходности пользователя и тех же денег в индексе в процентных пунктах
и разница стоимостей в рублях; отрицательное значение называется отставанием.

_Не использовать_: альфа.