# Исследование структуры страницы брокерского счёта

Дата: 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`.