docs/domains/income/upcoming-events.md

# Будущие события

Будущие события помогают увидеть известные выплаты и даты по текущим
позициям счёта. Обзор `/accounts/:accountId` показывает до пяти ближайших
событий, полный список находится на `/accounts/:accountId/events`.
[Общий режим](../portfolio/all-accounts.md) сохраняет отдельные строки
событий каждого доступного счёта. Ошибка или пустой результат превью
не заменяет основной портфель.

Прогноз отличается от [полученного дохода](overview.md): он основан
на текущем количестве бумаг и опубликованных условиях, не подтверждает
будущее зачисление и не входит в итоги исполненных выплат.

## Смысл события

| Событие | Источник и дата | Денежная оценка |
| --- | --- | --- |
| Купон | Календарь облигации из MOEX `bondization` | Известная выплата на бумагу × текущая позиция |
| Дивиденд | T-Bank `GetDividends`, дата реестра `record_date` | `dividend_net` на бумагу × текущая позиция |
| Полное погашение | MOEX `bondization` | Известные условия погашения × текущая позиция |
| Оферта | MOEX `bondization` | Сумма не синтезируется, `projectedAmount: null` |

Для дивиденда `dateKind: registry` явно означает дату закрытия реестра,
а не гарантированную дату поступления денег. Отменённые выплаты `Cancelled`
не включаются. Будущие частичные погашения и амортизация не синтезируются
без надёжного расписания. Неизвестные или неприменимые денежные условия
остаются `null`, а не заменяются нулём.

Суммы рассчитаны по количеству на `calculatedAt`. Они не учитывают будущие
сделки, право владения на дату реестра и персональный налоговый расчёт.
Есть неразрешённое ограничение интерпретации:
[основная спецификация](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-forecasts-preserve-event-meaning-and-uncertainty)
и текущая подсказка экрана называют прогноз суммой «до налогов», но для
дивиденда реализация только умножает `dividend_net` на количество.
Налоговый смысл этого поля не подтверждён локальными материалами; на
[странице акции](../instruments/stocks.md#дивиденды-и-финансовые-показатели)
он также не трактуется как персональная сумма до или после налога.
Расчёт подтверждён, налоговую формулировку требуется согласовать отдельно.

## Период и список

Без фильтра период начинается сегодня в UTC и заканчивается через 30 дней
после начала, обе даты включены. `from` и `to` принимают только строгие даты
`YYYY-MM-DD`; без `from` используется текущая дата UTC, без `to` — `from + 30`
календарных дней. Поля «С» и «По» сохраняют выбранные календарные даты в URL,
а «Сбросить» возвращает период по умолчанию.

События упорядочены по календарной дате. У каждой строки видны тип,
инструмент, дата и доступная сумма в исходной валюте. Список не имеет
пагинации и не конвертирует валюты. Пустой результат означает отсутствие
известных поддерживаемых событий в выбранном окне, а не доказательство
отсутствия всех будущих выплат. Инструмент без поддерживаемых данных
не получает искусственную строку «нет данных».

Сохранённый forecast сохраняет свой `calculatedAt` и исходное включительное
окно. GET для отдельного счёта или `all` возвращает только пересечение этого
окна и запрошенного UTC-периода, не меняя ни `calculatedAt`, ни исходное окно.
Пустое пересечение или отсутствие событий в пересечении — успешный пустой
список с теми же metadata; это не отсутствие forecast. Неверный формат или
несуществующая дата дают `400`; обратный период — `400 INVALID_EVENTS_PERIOD`
без замены периода и без запуска личной работы.
Фильтрация на сервере предшествует сортировке и вычислению
`incomeTotalsByCurrency`, включающего только купоны и дивиденды.
Итоги остаются в ответе API; полный экран показывает список без общего итога.

## Получение и отказы

Запрос требует сессии, подключения и локально подтверждённого membership.
Он читает сохранённый forecast и не запускает личную синхронизацию. Часовой
обход строит forecast из полного личного portfolio и общих календарей: T-Bank
для дивидендов, MOEX для bond events. Личные оценки сохраняются отдельно от
общих календарей.

Последний полный forecast привязан к scope, исходному окну и membership. Если
часовой обход не может получить полный новый forecast, прежний полный прогноз,
его `calculatedAt` и исходное окно остаются читаемыми, в том числе после
рестарта; `meta.lastAttempt` отдельно сообщает об ошибке обновления. Без
полного forecast `data: null` и metadata обозначает initial loading либо
временную недоступность, а не подтверждённое отсутствие выплат. В режиме `all`
результат complete только при полном вкладе каждого включённого счёта. Другой
scope или изменившийся membership не получают старый forecast под новым
названием.
Успешный ответ MOEX без запрошенного блока означает отсутствие поддерживаемых
событий этого источника; это отличается от transport failure и повреждённого
формата ответа.

При первом открытии без complete forecast показан каркас заголовка и строк,
без интерактивных заглушек. Пустой успешный ответ сохраняет возможность
изменить период. При failed HTTP reread уже полученный Client Cached Snapshot
остаётся на экране; это отличается от server-side failed hourly attempt.
Повторная попытка перечитывает только HTTP-ответ. Без выбранного счёта запрос
не выполняется. Смена сессии и подключения следует
[общим правилам финансовых данных](../../architecture/cross-cutting/data-freshness.md).

Внешние границы объясняют интеграции [T-Bank](../../integrations/tbank.md)
и [MOEX ISS](../../integrations/moex.md),
точные транспортные поля — [HTTP API](../../architecture/http-api.md).
Календарь конкретного выпуска и личные исполненные операции доступны
на страницах [акций](../instruments/stocks.md) и
[облигаций](../instruments/bonds.md), где их смысл также разделён.