diff --git a/features/brokerage-account-upcoming-events.md b/features/brokerage-account-upcoming-events.md new file mode 100644 index 0000000..b2fc9dd --- /dev/null +++ b/features/brokerage-account-upcoming-events.md @@ -0,0 +1,32 @@ +# Будущие события брокерского счёта + +Авторизованный пользователь видит до пяти ближайших событий на обзоре `/accounts/:accountId` и открывает полный список известный событий этого счёта на `/accounts/:accountId/events`. Ошибка или пустой результат блока на обзоре не заменяет Portfolio. + +```mermaid +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->>M: Получает дивиденды и события облигаций + B-->>F: Прогноз на 30 дней + F-->>U: Компактный список событий +``` + +## API + +`GET /api/v1/brokerage-accounts/:accountId/events` требует Bearer access token. Ответ содержит `accountId`, `calculatedAt` и отсортированный по календарной дате список `events`. + +Событие содержит `type` (`coupon`, `dividend`, `maturity`, `offer`), `date`, `dateKind`, идентификаторы и название инструмента, а также исходную `currency` и nullable `amount`. Для `offer` сумма не создаётся искусственно. Дивиденд передаёт `dateKind: registry`: это дата закрытия реестра, а не гарантированная дата зачисления. + +## Поведение и ограничения + +- Период включает текущую календарную дату и следующие 30 дней. +- Суммы до налогов рассчитываются по текущему количеству бумаг на `calculatedAt`; они не учитывают будущие сделки или владение на дату реестра. +- Список не имеет фильтров, пагинации, конвертации валют и общего итога. +- Поддерживаются только известные MOEX события по доступным позициям: купоны, дивиденды, полное погашение и оферты. Будущее частичное погашение и амортизация не синтезируются без надёжного расписания. +- Ошибка T-Bank или MOEX возвращает `503` без частичного списка. Инструмент без поддерживаемых данных не создаёт строку «нет данных».