113 lines
7.0 KiB
Markdown
113 lines
7.0 KiB
Markdown
# Аналитика прибыльности брокерского счёта
|
||
|
||
Дата: 2026-06-24
|
||
Статус: спецификация
|
||
Эпик: [Портфель брокера](../../epics/BrokerPortfolio.md)
|
||
|
||
## Цель
|
||
|
||
Дать пользователю брокерского счёта T-Bank отдельный раздел, где можно увидеть агрегированную аналитику прибыльности портфеля: сколько всего было вложено (нетто), сколько получено (дивиденды + купоны) и общую доходность.
|
||
|
||
## Пользовательский результат
|
||
|
||
Пользователь может:
|
||
|
||
- открыть вкладку `Аналитика` внутри брокерского счёта;
|
||
- увидеть, сколько всего денег было внесено на счёт (пополнения);
|
||
- увидеть, сколько всего денег было выведено со счёта;
|
||
- увидеть нетто-вложения (пополнения минус выводы);
|
||
- увидеть сумму полученных дивидендов;
|
||
- увидеть сумму полученных купонов;
|
||
- увидеть общую сумму полученного дохода (дивиденды + купоны);
|
||
- увидеть доходность в процентах от нетто-вложений.
|
||
|
||
## Область изменений
|
||
|
||
Фича относится только к брокерским счетам T-Bank и включает:
|
||
|
||
- новый backend endpoint `GET /api/v1/broker/accounts/:accountId/analytics`;
|
||
- новый сервис `BrokerAnalyticsService` с агрегацией через raw SQL;
|
||
- новую вкладку `Аналитика` в навигации брокерского счёта;
|
||
- страницу аналитики с отображением вложений, полученного дохода и сводки.
|
||
|
||
## Требования
|
||
|
||
### 1. Источники данных
|
||
|
||
- Все данные агрегируются из таблицы `BrokerOperation`.
|
||
- Для расчёта вложений используются операции с типами пополнений (`OPERATION_TYPE_INPUT` и аналоги) и выводов (`OPERATION_TYPE_OUTPUT` и аналоги).
|
||
- Для расчёта полученного дохода используются операции с типами дивидендов (`OPERATION_TYPE_DIVIDEND`, `OPERATION_TYPE_DIV_EXT`) и купонов (`OPERATION_TYPE_COUPON`).
|
||
- Данные считаются «навсегда»: без фильтра по дате, за всё время существования счёта.
|
||
- Аналитика read-only и не изменяет данные.
|
||
|
||
### 2. Endpoint
|
||
|
||
- `GET /api/v1/broker/accounts/:accountId/analytics` — возвращает агрегированные показатели.
|
||
- Кешируется с TTL 5 минут (как существующие broker-эндпоинты).
|
||
- При отсутствии счёта возвращает 404.
|
||
|
||
### 3. Показатели
|
||
|
||
Endpoint возвращает:
|
||
|
||
| Поле | Описание |
|
||
|------|----------|
|
||
| `totalDeposits` | Сумма всех пополнений счёта |
|
||
| `totalWithdrawn` | Сумма всех выводов со счёта |
|
||
| `netInvested` | `totalDeposits − totalWithdrawn` (нетто-вложения) |
|
||
| `totalDividends` | Сумма полученных дивидендов |
|
||
| `totalCoupons` | Сумма полученных купонов |
|
||
| `totalReceived` | `totalDividends + totalCoupons` |
|
||
| `totalReturnPercent` | `(totalReceived / netInvested) × 100`, если `netInvested > 0`, иначе `null` |
|
||
| `currency` | Валюта (RUB) |
|
||
|
||
### 4. Агрегация
|
||
|
||
- Запрос выполняется одним агрегирующим запросом к таблице `BrokerOperation`.
|
||
- Из выборки исключаются операции с `payment IS NULL`.
|
||
- Учитываются только исполненные операции (state = `OPERATION_STATE_EXECUTED` или `null`).
|
||
|
||
### 5. Вкладка
|
||
|
||
- В навигации брокерского счёта появляется вкладка `Аналитика` рядом с `События`.
|
||
- Вкладка использует `useBrokerAccountContext()` для получения `accountId`.
|
||
- Страница показывает три блока:
|
||
1. **Вложено** — пополнения, выводы, нетто-итог
|
||
2. **Получено** — дивиденды, купоны, итог
|
||
3. **Сводка** — нетто-вложения, полученный доход, доходность в процентах
|
||
|
||
### 6. Пустые состояния и ошибки
|
||
|
||
- Если аналитика недоступна (нет операций), показывается пустое состояние.
|
||
- Если нетто-вложения равны нулю, `totalReturnPercent` не показывается.
|
||
- Ошибка загрузки не ломает навигацию счёта.
|
||
|
||
## Ограничения
|
||
|
||
- Фича работает только внутри маршрутов `/broker/:accountId/*`.
|
||
- Ручные портфели `PortfolioModule` не входят в область фичи.
|
||
- Фича не учитывает налоги, комиссии и валютную конвертацию.
|
||
- Фича не учитывает нереализованную прибыль/убыток по текущим позициям.
|
||
- Доходность считается только по полученным выплатам (дивиденды + купоны), без учёта изменения цены бумаг.
|
||
|
||
## Acceptance Criteria
|
||
|
||
- На странице брокерского счёта есть вкладка `Аналитика`.
|
||
- Вкладка показывает нетто-вложения (пополнения минус выводы).
|
||
- Вкладка показывает сумму полученных дивидендов.
|
||
- Вкладка показывает сумму полученных купонов.
|
||
- Вкладка показывает общую сумму полученного дохода.
|
||
- Доходность в процентах отображается, если нетто-вложения > 0.
|
||
- Данные кешируются на 5 минут.
|
||
- Пустое состояние отображается при отсутствии данных.
|
||
- Ошибка загрузки не ломает навигацию.
|
||
|
||
## Вне области фичи
|
||
|
||
- учёт налогов и комиссий;
|
||
- нереализованная прибыль/убыток по текущим позициям;
|
||
- ручные портфели;
|
||
- мультивалютность;
|
||
- графики и визуализация динамики;
|
||
- экспорт данных.
|