docs: refresh project onboarding entrypoints

2026-08-24 10:29:00 +03:00
parent b623805cbe
commit 88c0cd3281
8 changed files with 260 additions and 7 deletions
@@ -0,0 +1,119 @@
+# Глоссарий домена
+
+## T-Bank connection
+
+Единственное принадлежащее User подключение к T-Bank Invest, содержащее
+зашифрованный token для server-side запросов.
+
+_Не использовать_: аккаунт T-Bank, авторизация T-Bank.
+
+## Brokerage Account
+
+Открытый поддерживаемый инвестиционный счёт T-Bank, доступный через T-Bank
+connection: брокерский счёт, ИИС, Инвесткопилка или фонд денежного рынка.
+
+_Не использовать_: счёт T-Bank, банковский счёт.
+
+## Investment Account Type
+
+Нормализованная категория Brokerage Account, независимая от upstream enum
+T-Bank.
+
+_Не использовать_: тип аккаунта T-Bank, protobuf type.
+
+## Portfolio
+
+Текущее нормализованное состояние инвестиций одного Brokerage Account,
+включающее позиции, доступные денежные остатки и итоги по каждой валюте.
+
+_Не использовать_: общий портфель, баланс счёта.
+
+## Portfolio Position
+
+Ненулевой обычный инвестиционный актив в составе Portfolio с количеством и
+доступными оценочными показателями.
+
+_Не использовать_: валютная позиция, виртуальная позиция.
+
+## Instrument
+
+Ценная бумага или иной торгуемый актив T-Bank, на который ссылается Portfolio
+Position через FIGI или instrument UID. Metadata Instrument обогащают
+отображение Position, но не определяют количество или стоимость.
+
+_Не использовать_: бумага, тикер, актив позиции.
+
+## Cash Balance
+
+Ненулевой доступный денежный остаток Portfolio в одной валюте; не является
+Portfolio Position.
+
+_Не использовать_: валютная позиция, заблокированные средства.
+
+## 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; хранит
+исходные суммы и доступные детали операции, не создавая синтетических записей
+для комиссии сделки.
+
+_Не использовать_: проводка, рассчитанная операция.
+
+## Ledger Page Cache
+
+Кэш страницы Account Ledger, отделённый от кэша отдельных операций.
+
+_Не использовать_: operations cache, кэш отдельных операций.
+
+## Ledger Page Cache Key
+
+Каноническая идентичность страницы Ledger Page Cache: User, Brokerage Account,
+нормализованные диапазон и categories, opaque upstream cursor и limit.
+
+_Не использовать_: сырой 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.
+
+_Не использовать_: будущая операция, гарантированная выплата.