moex-vibe/apps/docs/docs/adr/ADR-012-frontend-broker-account-aggregation.md

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 запросов;
  • нескольким клиентам нужна одинаковая серверная сводка;
  • появляется требование к согласованному серверному снимку или серверной валютной конвертации;
  • правила агрегации становятся самостоятельной бизнес-логикой, а не логикой представления.