docs/domains/income/upcoming-events.md

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

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

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

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

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

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

Суммы рассчитаны по количеству на calculatedAt. Они не учитывают будущие сделки, право владения на дату реестра и персональный налоговый расчёт. Есть неразрешённое ограничение интерпретации: основная спецификация и текущая подсказка экрана называют прогноз суммой «до налогов», но для дивиденда реализация только умножает dividend_net на количество. Налоговый смысл этого поля не подтверждён локальными материалами; на странице акции он также не трактуется как персональная сумма до или после налога. Расчёт подтверждён, налоговую формулировку требуется согласовать отдельно.

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

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

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

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

В режиме «Все счета» события одного инструмента, даты, точного типа и dateKind образуют группу, если их две и более, в том числе одного счёта. Ключ дополнительно включает dateKind, поэтому дата реестра дивиденда и иная дата того же инструмента не объединяются. Группа стоит на месте первого события. Полный список группирует все полученные события; превью обзора сначала берёт пять событий и группирует только их. Каждая строка счёта остаётся отдельной и показывает название счёта и свою прогнозную сумму. Визуальный итог группы — точная сумма по валютам; он показывается только если полнота прогноза complete и у каждого события группы известна прогнозная сумма. Иначе итог скрыт, а строки остаются. Этот итог не равен итогам ответа 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-ответ. Без выбранного счёта запрос не выполняется. Смена сессии и подключения следует общим правилам финансовых данных.

Внешние границы объясняют интеграции T-Bank и MOEX ISS, точные транспортные поля — HTTP API. Календарь конкретного выпуска и личные исполненные операции доступны на страницах акций и облигаций, где их смысл также разделён.