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