specs/openspec/changes/archive/2026-10-14-unify-income-payment-cards/specs/brokerage-account-income-analytics/spec.md

REMOVED Requirements

Requirement: Period comparisons preserve calendar and currency meaning

Reason: Сравнения с предыдущим периодом и годом ранее больше не входят в назначение аналитики полученного дохода и требуют избыточной загрузки истории.

Migration: Пользователь видит только итоги и состав выплат применённого периода; потребители ответа аналитики больше не получают данные сравнений и состояния их доступности. Исторический период можно по-прежнему применить самостоятельно, но система не сопоставляет его с другим периодом автоматически.

MODIFIED Requirements

Requirement: User explicitly applies an analytics period represented in the URL

Страница выбранного Brokerage Account «Пассивный доход» MUST позволять User редактировать черновик from и to, не изменяя видимую аналитику до явного применения. Верхний блок фильтров MUST предоставлять два подписанных календарных поля начала и окончания периода с тем же взаимодействием выбора даты, что в истории событий портфеля, и отображением дат в формате ДД.ММ.ГГГГ. Поля и действия применения и сброса MUST быть доступны с клавиатуры. Явное применение MUST заменить применённый период, загрузить соответствующий результат и представить применённые даты в URL страницы. Недопустимый черновик MUST показывать ошибку соответствующего поля и MUST NOT заменять последний применённый период. Сброс MUST немедленно вернуть применённый период к текущему месяцу по сегодняшний день и синхронизировать URL. Перезагрузка или открытие URL с допустимым периодом MUST восстановить тот же применённый период. Страница MUST NOT дублировать период отдельной подписью под блоком фильтров. Действие перехода на страницу MUST быть доступно из выбранного Brokerage Account, а не из глобальной навигации.

Scenario: Черновик периода не применён

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

Scenario: Выбор дат в верхнем блоке

• WHEN User выбирает начало и окончание периода через календарные поля
• THEN выбранные даты отображаются в подписанных полях в формате ДД.ММ.ГГГГ, а изменение остаётся черновиком до явного применения

Scenario: Управление фильтрами с клавиатуры

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

Scenario: Применение периода

• WHEN User явно применяет допустимый черновик периода
• THEN страница загружает аналитику этого периода и отражает применённые from и to в URL

Scenario: Недопустимый черновик периода

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

Scenario: Восстановление применённого периода из URL

• WHEN User открывает URL страницы с допустимыми from и to
• THEN страница показывает аналитику за указанный применённый период

Scenario: Сброс периода

• WHEN User сбрасывает пользовательский период
• THEN страница немедленно применяет период от первого дня текущего месяца по Europe/Moscow до сегодняшнего дня и синхронизирует URL

Requirement: Realized analytics never presents an incomplete result as complete

Система MUST формировать выбранный результат, его trend buckets, instrument breakdown и drill-down только после успешного получения всех необходимых cursor pages исполненных операций выбранного периода. Ошибка любой необходимой страницы MUST завершать расчёт восстанавливаемой ошибкой и MUST NOT возвращать частичные totals, buckets или breakdown как полный результат. Успешный период без подходящих выплат MUST возвращать нулевой результат и отображаться с явным объяснением пустого состояния. Система MUST NOT загружать другие периоды ради сравнения полученного дохода с выбранным периодом.

Scenario: Все страницы операций успешно получены

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

Scenario: Одна из страниц операций недоступна

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

Scenario: В периоде нет купонов и дивидендов

• WHEN все необходимые операции успешно получены, но среди них нет подходящих coupon или dividend Ledger Entries
• THEN страница показывает нулевой результат и объясняет, что за выбранный период купоны и дивиденды не найдены

Requirement: Income payments remain traceable to exact Ledger Entries

В разделе «Выплаты» страница MUST показывать единый список карточек точных исполненных Ledger Entries применённого периода в исходном серверном порядке entries. Каждая выплата MUST иметь собственную сразу видимую карточку с описанием, датой исполнения, доступной identity Instrument и signed Money в исходной валюте. Купоны и дивиденды MUST использовать то же представление выплаты, что и на экранах журнала, прогноза и графиков инструментов, при этом карточка MUST обозначать эту сумму именно как фактически исполненную, а не прогнозную. Страница MUST NOT добавлять внешние группировочные карточки или заголовки по Instrument либо валюте, subtotals инструмента или количество выплат инструмента. Список MUST сохранять отрицательные корректировки и повторяющиеся operation IDs как отдельные записи и MUST NOT включать записи вне аналитического итога. Backend MUST обеспечивать согласованность entries, instrumentKey, валюты и receipt count при формировании ответа из одного набора записей. Frontend SHALL доверять типизированному contract без второго runtime consistency validator и MUST NOT пересчитывать денежные итоги.

Scenario: Каждая выплата показана отдельной карточкой

• WHEN выбранный период содержит несколько включённых Ledger Entries одного или разных Instrument
• THEN раздел «Выплаты» сразу показывает отдельную карточку каждой записи в исходном порядке без внешних группировочных блоков, раскрытия, итогов инструмента и receipt count на UI

Scenario: Список воспроизводит точный состав дохода

• WHEN User просматривает загруженный раздел «Выплаты»
• THEN он видит все и только включённые coupon и dividend Ledger Entries применённого периода с датой, описанием, доступной identity и исходной суммой, обозначенной как исполненная выплата

Scenario: Отрицательная корректировка и повторяющиеся IDs сохраняются

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

Scenario: Валюта видна в сумме каждой выплаты

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

Requirement: Analytics summary remains readable per currency

Страница MUST обозначать фактический результат как «Получено купонами и дивидендами» и для каждой исходной валюты показывать total, coupon subtotal и dividend subtotal выбранного периода. Она MUST объяснять, что tax operations не включены, не называя фактический результат gross, net, суммой до налогов, суммой после налогов или налоговым расчётом. Значения MUST оставаться доступными как читаемый текст, не только как графика, цвет или положение. Страница MUST NOT показывать блок «Динамика», его график, переключатель валюты графика или текстовый список временных buckets независимо от длительности выбранного периода. Страница MUST NOT показывать блоки «Предыдущий период» и «Годом ранее» или сообщения о недоступности сравнений.

Scenario: Итоги дохода доступны как текст

• WHEN выбранный период содержит исполненные купонные или дивидендные выплаты
• THEN страница показывает читаемые total, coupon subtotal и dividend subtotal с обозначением фактически полученного дохода и объяснением исключения tax operations

Scenario: Итоги нескольких валют остаются разделёнными

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

Scenario: Динамика отсутствует для периода любой длительности

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

Requirement: Income page excludes upcoming forecasts

Страница «Пассивный доход» MUST NOT показывать блок «Ближайший прогноз», его суммы, список будущих выплат, состояния загрузки, пустоты или ошибки. Forecast values MUST NOT входить в realized total, trend buckets или instrument breakdown. Доступность данных Future Cash Events MUST NOT влиять на отображение успешно загруженной realized analytics. Существующая самостоятельная страница «Будущие события» и её доступность из выбранного Brokerage Account MUST сохраняться.

Scenario: Известные будущие выплаты не появляются на странице дохода

• WHEN для выбранного Brokerage Account известны будущие coupon или dividend события с суммой или без неё либо maturity или offer события
• THEN страница дохода не показывает блок «Ближайший прогноз» и не включает эти будущие события в фактически полученный доход

Scenario: Изменение исторического периода не возвращает прогноз

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

Scenario: Данные будущих событий недоступны

• WHEN realized analytics успешно загружена, а данные Future Cash Events недоступны
• THEN итоги и карточки выплат остаются доступными, а страница дохода не показывает состояние ошибки или загрузки прогноза

Scenario: Самостоятельная страница будущих событий сохраняется

• WHEN User переходит из выбранного Brokerage Account на существующую страницу «Будущие события»
• THEN эта страница остаётся доступной с прежним поведением независимо от отсутствия прогноза на странице дохода