refactor: refactor future event list

2026-08-20 08:23:42 +03:00
parent 6795ee6f96
commit 601a498991
5 changed files with 138 additions and 2 deletions
@@ -0,0 +1,44 @@
+## 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 не требует миграции данных, состояние не сохраняется.