docs: specify broker account sections
This commit is contained in:
parent
5b9d7f3a27
commit
0c12e6d610
165
docs/features/broker-account-sections/spec.md
Normal file
165
docs/features/broker-account-sections/spec.md
Normal file
@ -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-фильтры операций по датам и инструментам;
|
||||
- изменение правил расчёта доходности;
|
||||
- экспорт позиций или операций.
|
||||
122
docs/research/2026-06-18-broker-account-sections.md
Normal file
122
docs/research/2026-06-18-broker-account-sections.md
Normal file
@ -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`.
|
||||
Loading…
x
Reference in New Issue
Block a user