specs/openspec/specs/brokerage-account-upcoming-events/spec.md

Brokerage Account Upcoming Events Specification

Purpose

Позволяет пользователю просматривать известные будущие денежные и связанные корпоративные события одного брокерского счёта на ближайший месяц.

Requirements

Requirement: User can retrieve upcoming events for an account

Система MUST предоставлять аутентифицированному User read-only список известных будущих событий открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection User, от момента запроса до 30 календарных дней после него включительно. Ответ MUST содержать только события coupon, dividend, maturity и offer, отсортированные по дате по возрастанию, и момент расчёта прогноза.

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

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

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

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

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

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

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

Requirement: Forecasts preserve event meaning and uncertainty

Система MUST передавать для каждого события его календарную дату, тип, доступные идентификаторы и название Instrument, а также прогнозную сумму до налогов как Money, если она известна. Прогнозная сумма MUST рассчитываться по текущему количеству бумаг на момент запроса. Если денежные условия события неизвестны или неприменимы, прогнозная сумма 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 завершать запрос ошибкой, если необходимые для прогноза данные брокера или MOEX недоступны, и MUST NOT возвращать частичный список как полный результат. Система MUST пропускать инструменты, для которых источник не предоставляет поддерживаемые события, не создавая строки «нет данных».

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

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

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

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

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

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

Requirement: Account page presents an upcoming events list

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

При временном сбое обновления страница MUST сохранять ранее доступный результат той же выборки без технических сообщений, времени получения и ручного повтора. При отсутствии результата SHALL показываться первичное ожидание либо нейтральная недоступность с автоматическим восстановлением по frontend-data-resilience. Подтверждённая потеря доступа MUST скрывать личные данные независимо от наличия сохранённого результата.

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

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

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

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

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

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

Requirement: Account overview includes upcoming events

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

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

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

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

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