docs/features/brokerage-account-upcoming-events.md

Будущие события брокерского счёта

Авторизованный пользователь видит до пяти ближайших событий на обзоре /accounts/:accountId и открывает полный список известных событий Brokerage Account, доступного через текущее T-Bank connection, на /accounts/:accountId/events. Ошибка или пустой результат блока на обзоре не заменяет Portfolio.

sequenceDiagram
  participant U as User
  participant F as Frontend
  participant B as Backend
  participant T as T-Bank gRPC
  participant M as MOEX ISS
  U->>F: Открывает будущие события
  F->>B: GET /api/v1/brokerage-accounts/:accountId/events
  B->>T: GetAccounts и GetPortfolio
  B->>T: GetDividends (дивиденты по акциям)
  B->>M: Получает события облигаций
  B-->>F: Прогноз за выбранный период (по умолчанию 30 дней)
  F-->>U: Компактный список событий

API

GET /api/v1/brokerage-accounts/:accountId/events требует Bearer access token. Необязательные query-параметры from и to принимают календарные даты YYYY-MM-DD, обе границы включены. Без from начало — сегодня в UTC; без to конец — через 30 дней после начала. Неверный формат или несуществующая дата возвращают 400; обратный диапазон — 400 / INVALID_EVENTS_PERIOD. Эти же параметры поддерживает /api/v1/brokerage-accounts/all/events.

Ответ содержит accountId, calculatedAt и отсортированный по календарной дате список events.

Событие содержит type (coupon, dividend, maturity, offer), date, dateKind, идентификаторы и название Instrument, а также nullable projectedAmount как Money { currency, value }. Для offer и неизвестных денежных условий сумма не создаётся искусственно и передаётся null. Дивиденд передаёт dateKind: registry: это дата закрытия реестра, а не гарантированная дата зачисления.

Поведение и ограничения

При первом открытии полного списка frontend показывает structural skeleton заголовка и event rows вместо отдельного spinner. Placeholder не представляет данные и не является интерактивным; при пустом результате фильтр остаётся доступным для изменения периода.

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

• По умолчанию период включает текущую календарную дату и следующие 30 дней. Полный список позволяет выбрать другой период полями «С» и «По», как в операциях: «Применить» сохраняет даты в URL и запрашивает события, «Сбросить» возвращает период по умолчанию. Обзор счёта сохраняет прогноз на 30 дней.
• Суммы до налогов рассчитываются по текущему количеству бумаг на calculatedAt; они не учитывают будущие сделки или владение на дату реестра.
• Фильтр дат применяется на сервере до сортировки и подсчёта incomeTotalsByCurrency (купоны и дивиденды). Запрос дивидендов и ключ его кэша учитывают выбранный период. Список не имеет пагинации и конвертации валют.
• Поддерживаются только известные события по доступным позициям: дивиденды по акциям из T-Bank GetDividends (дата фиксации реестра record_date, сумма dividend_net на бумагу; отменённые выплаты Cancelled не попадают в прогноз), а также купоны, полное погашение и оферты облигаций из MOEX bondization. Будущее частичное погашение и амортизация не синтезируются без надёжного расписания.
• Ошибка T-Bank или MOEX возвращает 503 без частичного списка. Инструмент без поддерживаемых данных не создаёт строку «нет данных».