docs/features/broker-account-analytics/spec.md

@@ -0,0 +1,112 @@
+# Аналитика прибыльности брокерского счёта
+
+Дата: 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 минут.
+- Пустое состояние отображается при отсутствии данных.
+- Ошибка загрузки не ломает навигацию.
+
+## Вне области фичи
+
+- учёт налогов и комиссий;
+- нереализованная прибыль/убыток по текущим позициям;
+- ручные портфели;
+- мультивалютность;
+- графики и визуализация динамики;
+- экспорт данных.