specs/openspec/changes/archive/2026-08-19-source-share-dividends-from-tbank/design.md

Context

См. motivation в proposal.md. Прогноз будущих событий (GET /api/v1/brokerage-account-upcoming-events) строится read-through: текущие Portfolio Position из T-Bank обогащаются данными источников. Дивиденды акций брались из MOEX dividends.json, который больше не возвращает блок dividends. T-Bank gRPC уже используется для Portfolio и Instruments, а GetDividends описан в instruments.proto и фильтруется по record_date — это прямой заменяющий источник для текущих позиций, поскольку токен владельца счёта уже есть в системе.

Goals / Non-Goals

Goals:

• Восстановить прогноз дивидендов по акциям через источник, доступный тем же токеном, что и Portfolio.
• Сохранить семантику события (dateKind: registry по дате фиксации реестра) и расчёт суммы до налогов по текущему количеству.
• Убрать ставший мёртвым MOEX-путь дивидендов.

Non-Goals:

• Изменение API-контракта и frontend.
• Замена источника событий облигаций.
• Учёт налогов, удержаний и будущих сделок.

Decisions

Share dividends via T-Bank GetDividends

Ветка акций в UpcomingEventsService вызывает TbankClient.getDividends(token, instrumentId, from, to) с instrumentId = instrumentUid ?? figi позиции и окном 30 календарных дней. Запись превращается в событие dividend: дата = record_date, dateKind: registry, валюта и сумма на бумагу из dividend_net, итоговая сумма = dividend_net × quantity. Выплаты с dividend_type: Cancelled пропускаются.

Это использует уже имеющийся токен и покрывает именно инструменты портфеля, тогда как публичный MOEX-источник дивидендов сейчас недоступен. Альтернатива (новый cci/corp-actions MOEX) требует авторизации и не подходит для анонимного серверного вызова.

Strict source completeness unchanged

Недоступность T-Bank или MOEX по-прежнему завершает запрос ошибкой без частичного списка; инструмент без поддерживаемых событий просто пропускается. Смена источника не меняет семантику ошибок endpoint.

MOEX client keeps bond events only

Из moex.client.ts удаляются dividends() и MoexDividend; остаётся bondEvents() с блоками coupon, offer, description. Отсутствующий блок в успешном ответе MOEX трактуется как «нет данных», а не сбой.

Risks / Trade-offs

• [T-Bank возвращает только известные ему выплаты] → покрытие дивидендов зависит от данных T-Bank, что согласуется с ограничением «прогноз может быть неполным из-за доступности источника».
• [GetDividends лимитируется rate limiter] → запросы уже проходят через общий RateLimiter T-Bank.
• [Отменённые выплаты в истории] → фильтр dividend_type: Cancelled исключает их из прогноза.

Migration Plan

1. Добавить TbankClient.getDividends и тип TbankDividend.
2. Переключить ветку акций в UpcomingEventsService; удалить MOEX-метод дивидендов.
3. Обновить тесты и docs/features/brokerage-account-upcoming-events.md.
4. Откат: вернуть ветку акций на MOEX не требует миграции данных, состояние не сохраняется.