45 lines
4.3 KiB
Markdown
45 lines
4.3 KiB
Markdown
## 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 не требует миграции данных, состояние не сохраняется.
|