specs/openspec/changes/persist-tbank-data/specs/brokerage-account-upcoming-events/spec.md

MODIFIED Requirements

Requirement: User can retrieve upcoming events for an account

Система MUST предоставлять аутентифицированному User read-only список известных будущих событий выбранного открытого поддерживаемого Brokerage Account либо существующего режима «Все счета» (all) в границах текущего T-Bank connection User. Параметры from и to MUST сохранять существующий контракт: необязательные строгие календарные даты YYYY-MM-DD с включительными границами в UTC. Без from начало MUST соответствовать текущей календарной дате UTC; без to конец MUST соответствовать дате from плюс 30 календарных дней. При from позже to система MUST сохранять существующий отказ INVALID_EVENTS_PERIOD, не подменяя период. В режиме all доступ и полнота обязательных источников MUST проверяться для каждого входящего счёта, события MUST сохранять принадлежность счёту. Ответ MUST иметь envelope { data, meta } по tbank-data-sync; доступный прогноз в data MUST содержать только события coupon, dividend, maturity и offer, отсортированные по дате по возрастанию, и момент расчёта прогноза.

Список будущих событий является прогнозом по последнему успешно сохранённому наблюдаемому состоянию счёта и MUST NOT означать, что WealthLedger хранит долговременное право владения Brokerage Account независимо от T-Bank connection.

Система MUST формировать прогноз из сохранённых позиций и календарей, не ожидая T-Bank при локальном чтении и подтверждении доступа. Свежесть и загрузка зависимостей MUST быть видимы. Отсутствующий подтверждённый результат MUST возвращаться как data: null с состоянием загрузки, а не пустой список. Полнота локальной загрузки поддерживаемых данных MUST NOT означать полноту информации внешнего источника обо всех возможных событиях.

Scenario: Получение событий доступного счёта

• WHEN аутентифицированный User запрашивает будущие события открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection, без явного периода
• THEN система возвращает известные события от сегодняшней даты UTC до даты через 30 календарных дней включительно и момент, на который был выполнен расчёт

Scenario: Отсутствие событий в периоде

• WHEN все необходимые данные применённого периода успешно сохранены и для счёта в нём нет известных событий
• THEN система возвращает успешный пустой список и момент расчёта

Scenario: Отклонение недоступного счёта

• WHEN аутентифицированный User запрашивает события счёта, который не является открытым поддерживаемым счётом, доступным через его T-Bank connection
• THEN система возвращает существующий ответ о недоступности счёта и не раскрывает события

Scenario: Недопустимый период сохраняет ошибку

• WHEN User передаёт from позже to для выбранного счёта либо режима all
• THEN система возвращает существующую ошибку INVALID_EVENTS_PERIOD, не запускает загрузку другого периода и не возвращает его прогноз

Scenario: Прогноз ещё не может быть рассчитан

• WHEN позиции либо необходимый поддерживаемый календарь ещё не сохранены полностью
• THEN система возвращает 200 с data: null и состоянием запрошенной загрузки или её ошибки вместо утверждения об отсутствии событий

Requirement: Forecasts preserve event meaning and uncertainty

Система MUST передавать для каждого события его календарную дату, тип, доступные идентификаторы и название Instrument, а также прогнозную сумму до налогов как Money, если она известна. Прогнозная сумма MUST рассчитываться по количеству бумаг полного успешно сохранённого Portfolio Snapshot, использованного при последнем успешном расчёте показываемого прогноза, с указанием времени этого наблюдения. При неудачном обновлении сохранённый прогноз MUST сохранять эту исходную зависимость и MUST NOT приписываться более новому Portfolio Snapshot. Если денежные условия события неизвестны или неприменимы, прогнозная сумма MUST быть null, а не нулём и не парой разрозненных полей. Дивиденд MUST обозначать переданную дату как дату реестра, а offer MUST передаваться без вымышленной суммы.

Instrument в Future Cash Event MUST иметь тот же доменный смысл, что и в Portfolio: это финансовый инструмент, к которому относится событие, даже если событие не является Portfolio Position.

Scenario: Прогноз купона по текущей позиции

• WHEN поддерживаемая облигация в текущей Portfolio Position имеет известный купон в пределах периода
• THEN система возвращает событие coupon с прогнозной суммой до налогов как Money в исходной валюте, рассчитанной по текущему количеству облигаций

Scenario: Прогноз дивиденда

• WHEN поддерживаемая акция в текущей Portfolio Position имеет объявленный дивиденд с датой фиксации реестра в пределах периода
• THEN система возвращает событие dividend с датой, обозначенной как дата реестра (record_date), и прогнозной суммой до налогов как Money, равной dividend_net на одну бумагу, умноженной на текущее количество акций

Scenario: Отменённый дивиденд не попадает в прогноз

• WHEN запись дивиденда T-Bank имеет тип выплаты Cancelled
• THEN система не добавляет такое событие в результат

Scenario: Отображение оферты без суммы

• WHEN для поддерживаемой облигации известна оферта в пределах периода, но её денежные условия недоступны
• THEN система возвращает событие offer с прогнозной суммой null

Scenario: Неподдерживаемое частичное погашение

• WHEN источник не предоставляет расписание будущих частичных погашений или амортизации облигации
• THEN система НЕ создаёт синтетическое событие частичного погашения

Requirement: Upcoming events use complete source results

Система MUST использовать последний прогноз по полным успешно полученным необходимым источникам и MUST NOT возвращать частичный список как полный результат. Если обновление необходимых данных брокера или MOEX неуспешно, система MUST сохранять прежний подтверждённый прогноз и время его расчёта, возвращая 200 с ошибкой синхронизации в meta. Если полного прогноза ещё нет, ответ MUST содержать data: null и отсутствующее либо частичное покрытие с ошибкой или состоянием загрузки. Подтверждённые ошибки сессии, текущего подключения и доступа MUST сохранять существующие Problem Details и MUST NOT маскироваться прогнозом. Система MUST пропускать инструменты, для которых источник не предоставляет поддерживаемые события, не создавая строки «нет данных».

Scenario: Недоступность источника

• WHEN необходимый источник данных брокера или MOEX временно недоступен
• THEN система сообщает ошибку обновления, сохраняя ранее полный прогноз и время его расчёта либо data: null, без выдачи частичного списка за полный

Scenario: Инструмент без поддерживаемых данных

• WHEN Portfolio содержит инструмент, для которого источник не предоставляет поддерживаемые будущие события
• THEN система не добавляет для него синтетическую строку в результат

Scenario: MOEX отвечает без запрошенного блока

• WHEN MOEX отвечает успешно, но не содержит запрошенного блока данных (например, дивидендов)
• THEN система трактует ответ как отсутствие данных по инструменту и не завершает запрос ошибкой

Requirement: Account page presents an upcoming events list

Страница Brokerage Account MUST предоставлять действие перехода на отдельную страницу «Будущие события». Эта страница MUST сохранять существующий выбор и явное применение периода через from/to и показывать все полученные события применённого периода компактным списком без пагинации и суммарного итога, с датой, типом, инструментом и прогнозной суммой в исходной валюте, если она известна. Страница MUST объяснять, что прогноз основан на текущей позиции, указан до налогов и может быть неполным из-за доступности данных источника.

Страница MUST показывать время сохранённого прогноза, состояние свежести и загрузки, а также действие «Обновить» для текущего применённого периода и его зависимостей. Неполученный результат MUST отличаться от подтверждённого пустого списка. Временная ошибка обновления MUST NOT скрывать сохранённый полный прогноз.

Scenario: Просмотр ближайших событий

• WHEN User открывает «Будущие события» из обзора Brokerage Account без явного периода
• THEN он видит отсортированный список событий периода по умолчанию от сегодняшней даты UTC до даты через 30 календарных дней включительно, где offer обозначен без суммы

Scenario: Пустое состояние страницы

• WHEN запрос будущих событий возвращает подтверждённый полный пустой список в data
• THEN страница сообщает, что за применённый период событий не найдено, и объясняет ограничения покрытия источника

Scenario: Обновление применённого периода

• WHEN User применил допустимый период будущих событий и нажал «Обновить»
• THEN обновляются необходимые позиции и календари для применённого периода, его фильтры сохраняются и обновление не подменяется периодом по умолчанию

Scenario: Ошибка страницы

• WHEN фоновое обновление будущих событий завершается временной ошибкой
• THEN страница сохраняет прежний полный прогноз с его временем и предупреждением либо показывает ошибку первичной загрузки при его отсутствии, не выдаёт частичный список за полный и предоставляет действие повторить обновление

Requirement: Account overview includes upcoming events

Обзор Brokerage Account MUST показывать не более пяти ближайших Future Cash Event и действие перехода на полную страницу «Будущие события». Неуспешный или пустой запрос этого блока MUST оставаться локальным состоянием блока и не заменять успешно отображённый Portfolio.

Scenario: Отображение ближайших событий

• WHEN обзор счёта успешно загружен и календарь содержит будущие события
• THEN обзор показывает первые пять событий в порядке даты и действие перехода к полной странице

Scenario: Ближайшие события недоступны

• WHEN обзор счёта успешно загружен, но запрос будущих событий завершается ошибкой
• THEN Portfolio остаётся доступным, а блок будущих событий отображает собственную ошибку

Scenario: Ошибка обновления сохранённого прогноза обзора

• WHEN блок обзора уже показывает полный прогноз, а его обновление временно неуспешно
• THEN блок сохраняет показанные события и время расчёта с локальным предупреждением, не скрывая Portfolio