moex-vibe/docs/features/broker-events-and-payouts/spec.md

Календарь событий и прогноз будущих выплат брокерского счёта

Дата: 2026-06-21 Статус: согласовано к планированию Эпик: Портфель брокера

Цель

Дать пользователю брокерского счёта T-Bank отдельный раздел, где можно увидеть будущие события по бумагам счёта и ориентировочный денежный поток по выбранному диапазону дат.

Пользовательский результат

Пользователь может:

• быстро увидеть ближайшие события по текущему счёту прямо на overview;
• открыть отдельную вкладку События внутри счёта;
• выбрать период, например с 2026-06-22 по 2026-07-29;
• получить список дивидендов, купонов, погашений и оферт, попадающих в этот период;
• увидеть ориентировочную сумму будущих выплат по выбранному диапазону;
• понимать, какие значения являются оценкой по текущим позициям, а не подтверждённым правом на выплату.

Область изменений

Фича относится только к брокерским счетам T-Bank и включает:

• новый блок ближайших событий на overview счёта;
• новую вкладку События в навигации брокерского счёта;
• фильтр диапазона дат;
• список событий по текущим позициям счёта;
• агрегированный summary по будущим выплатам за выбранный период.

Требования

1. Область первой версии

• Первая версия работает только внутри маршрутов /broker/:accountId/*.
• Ручные портфели PortfolioModule не входят в область фичи.
• Backend остаётся единственным клиентом T-Bank и MOEX.
• Фича является read-only и не изменяет состав счёта или права пользователя.

2. Навигация и точки входа

• На overview брокерского счёта показывается компактный блок ближайших событий.
• Блок overview содержит переход во вкладку События.
• У счёта появляется отдельный раздел События рядом с существующими разделами Обзор, Акции, Облигации и Операции.
• Переход между разделами не меняет выбранный счёт.

3. Типы событий первой версии

Первая версия поддерживает события:

• dividend — дивиденд по акции;
• coupon — купон по облигации;
• maturity — погашение облигации;
• offer — оферта по облигации.

По смыслу события делятся на:

• cashflow — событие с ожидаемым денежным эффектом;
• corporate — важное событие без обязательной денежной оценки в первой версии.

Правила классификации:

• dividend относится к cashflow;
• coupon относится к cashflow;
• maturity относится к cashflow;
• offer относится к corporate.

4. Диапазон дат

• Пользователь задаёт диапазон from / to.
• Диапазон фильтруется по дате события, а не по дате поступления денег.
• Границы диапазона включительные.
• Если eventDate не попадает в диапазон, событие не показывается.
• В первой версии отдельный режим фильтрации по paymentDate отсутствует.

5. Источники данных

• Для состава счёта используются текущие позиции T-Bank.
• Для акций используются дивидендные данные MOEX.
• Для облигаций используются уже доступные поля MOEX enrichment, включая nextCouponDate, couponValue, matDate, offerDate и faceValue.
• Фича не требует отдельного постоянного хранилища событий в первой версии.

6. Правила прогноза выплат

• Все денежные суммы первой версии являются оценкой по текущим позициям счёта на момент запроса.
• Фича не восстанавливает историческое владение бумагой на дату отсечки.
• Если состав счёта изменится, прогноз по тем же датам может измениться.
• UI обязан явно показывать, что сумма является estimate или прогнозом.

Дивиденды

• Событие строится по registryCloseDate.
• Если размер выплаты доступен, ориентировочная сумма считается как количество бумаг в текущем счёте, умноженное на выплату на единицу.
• Если размер выплаты отсутствует, событие всё равно может быть показано без итоговой суммы.

Купоны

• Событие строится по nextCouponDate.
• Если размер купона доступен, ориентировочная сумма считается как количество облигаций в текущем счёте, умноженное на couponValue.
• Если размер купона отсутствует, событие показывается без итоговой суммы.

Погашение

• Событие строится по matDate.
• Если известен faceValue, ориентировочная сумма считается как количество облигаций в текущем счёте, умноженное на номинал.
• Если номинал отсутствует, событие показывается без итоговой суммы.

Оферта

• Событие строится по offerDate.
• В первой версии оферта считается информационным событием.
• Для оферты не требуется обязательная денежная оценка.

7. Overview счёта

• Overview показывает ближайшие 3-5 событий выбранного счёта.
• Для каждого события overview показывает дату, инструмент, тип события и сумму при наличии.
• Если ближайших событий нет, overview показывает спокойное пустое состояние.
• Ошибка загрузки блока событий не должна ломать остальной overview счёта.

8. Вкладка События

• Вкладка содержит фильтр периода, summary и список событий.
• Список событий показывает:
  • дату события;
  • тип события;
  • инструмент;
  • тип инструмента;
  • количество бумаг, использованное для расчёта;
  • выплату на единицу при наличии;
  • итоговую ориентировочную сумму при наличии;
  • валюту при наличии.
• Для денежных оценок UI показывает признак estimate.

9. Summary по периоду

Summary по выбранному периоду показывает:

• количество событий;
• ближайшую дату события;
• общий ориентировочный денежный поток;
• сумму дивидендов;
• сумму купонов;
• сумму погашений.

Оферты не обязаны входить в денежный итог первой версии.

10. Ошибки, пустые состояния и частичная деградация

• Ошибка по одному инструменту не должна ломать весь календарь счёта.
• Если по событию недоступна сумма, событие может быть показано без суммы.
• Если в выбранном диапазоне нет событий, пользователь видит пустое состояние, а не ошибку.
• Ошибка вкладки События не должна скрывать общую навигацию счёта.

Ограничения

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

Acceptance Criteria

• На overview брокерского счёта отображается блок ближайших событий.
• В навигации брокерского счёта есть вкладка События.
• Пользователь может задать диапазон дат.
• Вкладка показывает только события, дата которых попадает в выбранный диапазон.
• Пользователь видит дивиденды, купоны, погашения и оферты, если они доступны по текущим позициям.
• Summary показывает агрегированный прогноз будущих выплат по диапазону.
• Все денежные суммы явно обозначены как оценочные.
• Пустой диапазон отображается как отдельное пустое состояние.
• Ошибка по одному инструменту не ломает весь ответ.

Вне области фичи

• точный entitlement-расчёт по историческому владению и датам отсечки;
• поддержка ручных портфелей;
• единый календарь по нескольким доменам портфелей;
• налоги, мультивалютный net cashflow и комиссии;
• iCal/export, уведомления и напоминания;
• отдельный аналитический раздел вне брокерского счёта.