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