diff --git a/docs/features/broker-account-sections/spec.md b/docs/features/broker-account-sections/spec.md new file mode 100644 index 0000000..fb80211 --- /dev/null +++ b/docs/features/broker-account-sections/spec.md @@ -0,0 +1,165 @@ +# Разделы брокерского счёта + +Дата: 2026-06-18 +Статус: ожидает проверки + +## Цель + +Сделать страницу конкретного брокерского счёта кратким и понятным обзором, а подробные позиции и +операции разнести по самостоятельным разделам, не теряя контекст выбранного счёта. + +## Пользовательский результат + +Пользователь может: + +- быстро увидеть полную стоимость счёта, денежный остаток и текущую структуру активов; +- понять, сколько разных акций и выпусков облигаций находится на счёте; +- перейти к отдельной таблице акций или облигаций; +- увидеть последние операции на overview и открыть всю доступную историю; +- отфильтровать историю по одному точному типу операции, например только по выплатам купонов или + только по обычному налогу. + +## Область изменений + +Фича изменяет опыт работы с конкретным брокерским счётом и включает: + +- обзор счёта; +- общую навигацию разделов счёта; +- отдельный раздел акций; +- отдельный раздел облигаций; +- отдельный раздел операций; +- данные сводки, необходимые для точных счётчиков позиций. + +## Требования + +### 1. Общая навигация + +- Разделы `Обзор`, `Акции`, `Облигации` и `Операции` принадлежат одному выбранному брокерскому счёту. +- На широком экране разделы доступны через постоянное боковое меню. +- На узком экране боковое меню заменяется горизонтальными прокручиваемыми вкладками. +- Активный раздел визуально и семантически обозначен. +- Переход между разделами не меняет выбранный брокерский счёт. + +### 2. Обзор счёта + +Overview показывает: + +- название счёта; +- полную стоимость портфеля; +- денежный остаток; +- существующие показатели дневной и ожидаемой доходности; +- круговую диаграмму структуры портфеля; +- карточку акций с количеством разных позиций, стоимостью и долей; +- карточку облигаций с количеством разных выпусков, стоимостью и долей; +- пять последних доступных операций; +- переход ко всей доступной истории операций. + +Карточки акций и облигаций ведут в соответствующие разделы счёта. + +### 3. Распределение портфеля + +- Проценты рассчитываются от полной стоимости счёта, включая денежный остаток. +- Диаграмма поддерживает срезы `Акции`, `Облигации`, `ETF/фонды`, `Деньги` и `Прочие`. +- `Прочие` объединяет остальные и неизвестные классы инструментов. +- Срез с нулевым значением не отображается. +- Отрицательное значение не отображается как сектор диаграммы и показывается текстом рядом со + сводкой. +- Легенда показывает название среза, денежную стоимость и процент. +- Информация остаётся понятной без различения цветов. + +### 4. Счётчики позиций + +- Количество акций означает число разных позиций акций, а не сумму штук всех акций. +- Количество облигаций означает число разных выпусков облигаций, а не сумму штук всех облигаций. +- Счётчики отражают полный состав счёта и не зависят от текущей страницы таблицы. + +### 5. Раздел акций + +- Раздел показывает только позиции типа `share`. +- Первая версия содержит таблицу с существующими колонками: тикер, название, количество, текущая + цена и текущая стоимость. +- Тикер ведёт на страницу акции, когда маршрут инструмента может быть определён. +- Таблица сохраняет cursor-пагинацию по 10 позиций. +- При отсутствии акций показывается отдельное пустое состояние. + +### 6. Раздел облигаций + +- Раздел показывает только позиции типа `bond`. +- Первая версия содержит таблицу с существующими колонками: тикер, название, количество, текущая + цена и текущая стоимость. +- Тикер ведёт на страницу облигации, когда маршрут инструмента может быть определён. +- Таблица сохраняет cursor-пагинацию по 10 позиций. +- При отсутствии облигаций показывается отдельное пустое состояние. + +### 7. Последние операции на overview + +- Overview показывает не более пяти последних операций доступного по умолчанию периода. +- Отображение операции сохраняет дату, русское название типа, инструмент и сумму. +- Блок содержит переход к полному разделу операций. +- Если операций нет, блок показывает спокойное пустое состояние и сохраняет переход к полной + истории. + +### 8. Раздел операций + +- Раздел показывает cursor-пагинированную историю по 10 операций. +- Без отдельного фильтра дат раздел использует существующий период по умолчанию: с начала текущего + календарного года до текущего момента. +- Под всей доступной историей в рамках первой версии понимаются все cursor-страницы этого периода, + а не операции за всё время существования счёта. +- Пользователь может выбрать ровно один точный тип операции либо значение `Все операции`. +- Типы с разным финансовым смыслом не объединяются. В частности, `Налог`, `Налог по облигациям` и + `Налог на дивиденды` являются отдельными значениями. +- В интерфейсе показываются русские названия известных типов, а не технические enum-значения. +- Выбор нового типа начинает просмотр результатов с первой cursor-страницы. +- Выбранный фильтр сохраняется в адресе страницы и восстанавливается при открытии ссылки. +- Значение `Все операции` удаляет фильтр типа. +- Фильтр по датам, инструменту и выбор нескольких типов не входят в первую версию. + +### 9. Загрузка, ошибки и пустые состояния + +- Первичная загрузка сводки и таблиц показывает skeleton соответствующей формы. +- При переходе между cursor-страницами текущие строки не исчезают; поверх таблицы показывается + состояние обновления. +- Ошибка одного раздела не скрывает общую навигацию счёта. +- Для пустых акций, пустых облигаций и отсутствия операций выбранного типа используются отдельные + понятные сообщения. +- Недоступные отдельные значения отображаются как `—` и не подменяются нулём. + +## Ограничения + +- Backend остаётся единственным клиентом T-Bank. +- Денежные значения форматируются в валюте, указанной в данных. +- Точная структура портфеля и счётчики не должны требовать загрузки всех cursor-страниц на frontend. +- Существующая cursor-пагинация позиций и операций сохраняется. +- Фича не добавляет отдельные страницы для ETF, фондов и прочих инструментов. +- Фича не добавляет новую аналитику доходности, риска или прогнозов. + +## Acceptance Criteria + +- На широком экране у счёта есть боковая навигация `Обзор`, `Акции`, `Облигации`, `Операции`. +- На узком экране те же разделы доступны через горизонтальные прокручиваемые вкладки. +- Overview не содержит полных таблиц позиций и полной истории операций. +- Overview показывает полную стоимость, деньги, существующую доходность, диаграмму, карточки акций + и облигаций и не более пяти последних операций. +- Диаграмма рассчитывает доли от полной стоимости счёта вместе с деньгами. +- Диаграмма имеет текстовую легенду со стоимостью и процентом каждого ненулевого среза. +- Карточки акций и облигаций показывают количество разных позиций, а не сумму штук. +- Количество позиций корректно для портфеля, содержащего больше одной cursor-страницы. +- Раздел акций содержит только акции и сохраняет пагинацию по 10 строк. +- Раздел облигаций содержит только облигации и сохраняет пагинацию по 10 строк. +- Раздел операций содержит пагинацию по 10 строк и фильтр по одному точному типу. +- Без параметров дат раздел операций показывает доступный период с начала текущего календарного года. +- Фильтры `Выплата купона`, `Налог`, `Налог по облигациям` и `Налог на дивиденды` дают независимые + результаты. +- После смены типа операций открывается первая страница отфильтрованной истории. +- Выбранный тип восстанавливается из URL после перезагрузки. +- Загрузка, обновление, ошибка и пустое состояние каждого раздела отображаются согласно требованиям. + +## Вне области фичи + +- страницы ETF, фондов, валют, деривативов и прочих инструментов; +- multi-select типов операций; +- продуктовые группы операций; +- UI-фильтры операций по датам и инструментам; +- изменение правил расчёта доходности; +- экспорт позиций или операций. diff --git a/docs/research/2026-06-18-broker-account-sections.md b/docs/research/2026-06-18-broker-account-sections.md new file mode 100644 index 0000000..47235fa --- /dev/null +++ b/docs/research/2026-06-18-broker-account-sections.md @@ -0,0 +1,122 @@ +# Исследование структуры страницы брокерского счёта + +Дата: 2026-06-18 + +## Цель исследования + +Определить, как упростить страницу конкретного брокерского счёта, разделить обзор и подробные +данные по классам инструментов, а также добавить понятную фильтрацию истории операций. + +## Текущее состояние + +### Frontend + +- Маршрут `/broker/:accountId` открывает `BrokerAccountDetailPage`. +- На одной странице находятся сводка, отдельные секции позиций и полная таблица операций. +- `BrokerPositionsSection` загружает акции, облигации, ETF и фонды отдельными запросами и показывает + cursor-пагинацию. +- `BrokerOperationsTable` показывает 10 операций, русские названия известных типов и + cursor-пагинацию. +- Для известных типов инструментов уже существуют переходы на `/stocks/:ticker` и + `/bonds/:ticker`. +- В `brokerDisplay.ts` уже есть отображаемые названия известных T-Bank operation types и правила + визуальной классификации операций. + +### Backend и контракты + +- `GET /api/v1/broker/accounts/:accountId/portfolio` возвращает итоговую стоимость, суммы по классам + активов, доходность, деньги и заблокированные деньги. +- Ответ portfolio не содержит точного количества разных позиций по классам. +- `GET /api/v1/broker/accounts/:accountId/positions` поддерживает `type`, `cursor` и `limit`, но не + возвращает общее количество элементов. +- `GET /api/v1/broker/accounts/:accountId/operations` поддерживает `operationTypes`, `cursor`, + `limit`, `from`, `to`, `instrumentId` и `state`. +- `operationTypes` уже преобразуется backend в список точных T-Bank enum-значений. +- Если период операций не указан, backend использует период от начала текущего календарного года + до текущего момента. + +## Выявленное ограничение + +Точный счётчик разных акций и выпусков облигаций нельзя эффективно получить из текущего frontend- +контракта: endpoint позиций пагинирован и не возвращает total. Загрузка всех cursor-страниц ради +двух счётчиков увеличит число запросов и свяжет overview с размером портфеля. + +Рекомендуемое техническое направление для последующего plan.md — дополнить существующий portfolio +summary счётчиками разных позиций по классам. Новый summary endpoint не нужен, потому что он будет +дублировать назначение существующего portfolio endpoint. + +## Рассмотренные продуктовые варианты + +### Размещение операций + +1. Полная история на overview. +2. Только отдельная страница операций. +3. Гибрид: последние операции на overview и вся доступная история отдельно. + +Выбран вариант 3. Он сохраняет полезный контекст на overview и не превращает сводку в длинную +рабочую таблицу. + +### Область круговой диаграммы + +1. Только инструменты. +2. Весь портфель вместе с денежным остатком. + +Выбран вариант 2. Он показывает реальную долю свободных денег и не создаёт впечатление, что весь +счёт инвестирован. + +### Семантика количества + +1. Количество разных позиций. +2. Сумма штук всех бумаг класса. + +Выбран вариант 1. Складывать штуки разных акций или облигаций малоинформативно. Рядом со счётчиком +должны оставаться стоимость класса и его доля в портфеле. + +### Фильтр операций + +1. Один точный тип операции. +2. Несколько точных типов одновременно. +3. Семантические группы, например «Все налоги». + +Выбран вариант 1. Значения «Налог», «Налог по облигациям» и «Налог на дивиденды» остаются разными +фильтрами. Multi-select и группировка категорий не входят в первую версию. + +### Навигация + +Рассматривались верхние вкладки, боковое меню и карточки-переходы на overview. Выбрано постоянное +боковое меню на широком экране. На узком экране оно заменяется горизонтальными прокручиваемыми +вкладками. + +## Согласованная информационная архитектура + +- Overview счёта: баланс, денежный остаток, существующие показатели доходности, распределение всего + портфеля, карточки акций и облигаций, последние пять операций. +- Страница акций: таблица только акций. +- Страница облигаций: таблица только облигаций. +- Страница операций: полная доступная история с cursor-пагинацией и фильтром по одному точному типу. + +## Согласованные правила диаграммы + +- Основа процентов — полная стоимость счёта. +- Срезы: акции, облигации, ETF/фонды, деньги и прочие инструменты. +- В «прочие» входят фьючерсы, опционы, структурные продукты, ЦФА и неизвестные типы. +- Нулевые срезы не отображаются. +- Отрицательные значения не рисуются как сектор, но показываются текстом рядом со сводкой. +- Легенда всегда содержит название, стоимость и процент; цвет не является единственным носителем + информации. + +## Зафиксированные границы первой версии + +Не входят в первую версию: + +- отдельные страницы ETF, фондов и прочих инструментов; +- фильтр операций по датам или инструменту в UI; +- выбор нескольких типов операций; +- группировка точных типов в продуктовые категории; +- новая аналитика доходности или риска; +- изменение интеграции с T-Bank помимо данных, необходимых для согласованной сводки. + +## Результат + +Исследование завершено, продуктовые неоднозначности закрыты. Требования зафиксированы в +`docs/features/broker-account-sections/spec.md`.