# ADR-012: Сводка брокерских счетов агрегируется на frontend

**Статус:** Accepted

**Дата:** 2026-06-19

## Контекст

Страница списка брокерских счетов должна показывать общую стоимость, дневной результат, свободные
деньги и распределение активов, а также подробные показатели каждого счёта. Endpoint
`GET /api/v1/broker/accounts` возвращает только метаданные счетов. Все необходимые финансовые данные
уже доступны через `GET /api/v1/broker/accounts/:accountId/portfolio`.

Текущий продуктовый сценарий предполагает один–три открытых счёта. Backend кеширует ответы портфеля
и ограничивает запросы к T-Bank через общую очередь.

## Рассмотренные варианты

### 1. Агрегация существующих ответов на frontend

Frontend получает список счетов, параллельно запрашивает портфель каждого счёта и строит общую
сводку из успешно загруженных ответов.

Преимущества:

- не появляется новый API-контракт с данными, уже доступными в portfolio endpoint;
- каждый счёт может загружаться и восстанавливаться после ошибки независимо;
- при одном–трёх счетах число запросов остаётся ограниченным;
- используются существующие backend cache и rate limiting.

Недостатки:

- страница выполняет `1 + N` HTTP-запросов;
- ответы могут иметь разные значения `asOf` и не образуют атомарный снимок;
- правила презентационной агрегации находятся на frontend.

### 2. Новый aggregate endpoint

Добавить endpoint, который возвращает список счетов, их портфели и общую сводку одним ответом.

Преимущества:

- один HTTP-запрос с frontend;
- единый серверный контракт агрегации;
- проще переиспользовать сводку другими клиентами.

Недостатки:

- новый контракт дублирует существующие portfolio-данные;
- нужно определить семантику частичных ошибок и кеширования составного ответа;
- endpoint всё равно получает портфели нескольких счетов и не гарантирует атомарность данных T-Bank.

### 3. Расширение endpoint списка счетов

Добавить финансовую сводку каждого счёта в `GET /api/v1/broker/accounts`.

Преимущества:

- frontend получает всё одним запросом;
- карточки становятся простыми потребителями ответа.

Недостатки:

- лёгкий endpoint метаданных превращается в дорогой составной запрос;
- меняются его кеширование, время ответа и семантика ошибок;
- потребители списка счетов вынужденно получают финансовые данные.

## Решение

Использовать вариант 1: агрегировать существующие portfolio-ответы на frontend.

Frontend параллельно запрашивает портфели после получения списка счетов. Общая сводка строится только
из успешно загруженных ответов и явно помечается как частичная, если часть счетов недоступна. Ошибка
одного портфеля не блокирует остальные карточки.

Денежные значения группируются по валюте. Frontend не выполняет неявную валютную конвертацию и не
складывает несопоставимые суммы. Значения `asOf` отдельных ответов сохраняют свой смысл; сводка не
считается транзакционно согласованным снимком.

## Последствия

- Страница выполняет один запрос списка и до трёх параллельных запросов портфелей.
- Backend остаётся источником финансовых данных отдельного счёта, а frontend владеет только их
  представлением и агрегацией для этой страницы.
- Частичные ошибки становятся штатным состоянием интерфейса и должны быть покрыты тестами.
- API, OpenAPI и frontend codegen для этой фичи не меняются.
- Решение следует пересмотреть, если выполняется хотя бы одно условие:
  - продукт поддерживает более трёх одновременно отображаемых счетов;
  - измерения показывают неприемлемую задержку или нагрузку от `1 + N` запросов;
  - нескольким клиентам нужна одинаковая серверная сводка;
  - появляется требование к согласованному серверному снимку или серверной валютной конвертации;
  - правила агрегации становятся самостоятельной бизнес-логикой, а не логикой представления.