specs/openspec/changes/archive/2026-08-28-portfolio-income-analytics/specs/brokerage-account-income-analytics/spec.md

Purpose

Позволяет User анализировать фактически полученные купоны и дивиденды одного Brokerage Account по исходным валютам, проверять состав результата и отдельно видеть известный ближайший прогноз.

ADDED Requirements

Requirement: Realized income analytics is account-scoped and period-bound

Система MUST предоставлять аутентифицированному User аналитику фактически полученного дохода только для одного открытого поддерживаемого Brokerage Account, доступного через текущий T-Bank connection User. Применённый период MUST задаваться включительными календарными датами from и to в Europe/Moscow, MUST NOT начинаться после своего окончания, MUST NOT содержать будущую дату и MUST NOT превышать 366 дней. При отсутствии применённого периода система MUST использовать интервал от первого дня текущего месяца до сегодняшнего дня включительно.

Scenario: Аналитика за период по умолчанию

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

Scenario: Аналитика за допустимый пользовательский период

• WHEN User применяет включительный период не более 366 дней без будущих дат
• THEN система рассчитывает аналитику доступного Brokerage Account за все календарные даты этого периода по Europe/Moscow

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

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

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

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

Requirement: Realized income uses exact executed coupon and dividend payments

Система MUST рассчитывать фактически полученный доход только по исполненным Ledger Entries с точным upstream-типом coupon или dividend. Для каждой исходной валюты система MUST отдельно возвращать общий итог, купонный subtotal и дивидендный subtotal как точные суммы исходных broker-reported payments. Знак каждой выплаты MUST сохраняться, поэтому отрицательная корректировка MUST уменьшать соответствующий итог и оставаться доступной в составе результата. Dividend transfer, погашение principal, offer, trade, transfer, fee, tax, overnight income, иной тип операции, нереализованный результат и изменение рыночной цены MUST NOT входить в фактически полученный доход. Система MUST NOT выполнять валютную конвертацию или формировать общий итог по разным валютам.

Scenario: Купоны и дивиденды образуют раздельные subtotals

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

Scenario: Отрицательная корректировка сохраняет знак

• WHEN исполненная coupon или dividend Ledger Entry содержит отрицательную broker-reported payment
• THEN система включает её с исходным знаком, уменьшает соответствующие subtotal и total и сохраняет запись доступной для проверки

Scenario: Налоги и иные операции не входят в доход

• WHEN выбранный период наряду с coupon и dividend содержит tax, fee, trade, transfer, maturity или иной тип Ledger Entry
• THEN система не включает эти записи в coupon subtotal, dividend subtotal или total

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

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

Requirement: Period comparisons preserve calendar and currency meaning

Система MUST сопоставлять выбранный период с непосредственно предшествующим периодом. Для полного календарного месяца предыдущим периодом MUST быть предыдущий полный календарный месяц; для любого другого периода предыдущий период MUST иметь ту же включительную продолжительность и непосредственно предшествовать выбранному. Когда соответствующие календарные даты годом ранее доступны, система MUST также показывать year-over-year comparison; когда они недоступны, система MUST обозначать сравнение как недоступное, а не подменять его нулём. Каждое сравнение MUST показывать абсолютные coupon, dividend и total значения и их денежные разницы отдельно по исходным валютам и MUST NOT характеризовать их как инвестиционную эффективность.

Scenario: Сравнение полного календарного месяца

• WHEN User применяет период от первого до последнего дня календарного месяца
• THEN система сравнивает его с полным непосредственно предшествующим календарным месяцем

Scenario: Сравнение произвольного периода

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

Scenario: Доступно сравнение год к году

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

Scenario: Годовая история недоступна

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

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

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

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

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

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

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

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

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

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

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

Requirement: Analytics summary and trend remain readable per currency

Страница MUST обозначать фактический результат как «Получено купонами и дивидендами» и для каждой исходной валюты показывать total, coupon subtotal и dividend subtotal выбранного периода. Она MUST объяснять, что tax operations не включены, не называя фактический результат gross, net, суммой до налогов, суммой после налогов или налоговым расчётом. Страница MUST показывать stacked column visualization с отдельными coupon и dividend значениями: период до 45 дней включительно группируется по календарным дням, период от 46 до 180 дней включительно — по календарным неделям, более длинный период — по календарным месяцам. Пустые buckets внутри периода MUST оставаться видимыми с нулевыми значениями. При нескольких валютах явный currency control MUST переключать visualization между ними, а эквивалентные значения MUST оставаться доступными как читаемый текст, не только как графика, цвет или положение.

Scenario: Короткий период группируется по дням

• WHEN включительная продолжительность выбранного периода не превышает 45 дней
• THEN visualization показывает отдельные календарные day buckets с coupon и dividend значениями и сохраняет пустые дни как нулевые buckets

Scenario: Средний период группируется по неделям

• WHEN включительная продолжительность выбранного периода составляет от 46 до 180 дней
• THEN visualization показывает calendar week buckets с раздельными coupon и dividend значениями

Scenario: Длинный период группируется по месяцам

• WHEN включительная продолжительность выбранного периода превышает 180 дней
• THEN visualization показывает calendar month buckets с раздельными coupon и dividend значениями

Scenario: User переключает валюту visualization

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

Requirement: Instrument breakdown is traceable to exact Ledger Entries

Для каждой исходной валюты страница MUST показывать instrument breakdown, отсортированный по combined total по убыванию. Каждая строка MUST содержать доступную identity Instrument, coupon subtotal, dividend subtotal, combined total и количество включённых выплат. User MUST иметь возможность перейти от строки к точным исполненным Ledger Entries выбранных Instrument, валюты и периода, которые образовали её значения; drill-down MUST сохранять отрицательные корректировки и MUST NOT включать записи вне аналитического итога.

Scenario: Breakdown показывает состав дохода по инструментам

• WHEN выбранный период содержит подходящие выплаты нескольких Instrument в одной валюте
• THEN страница показывает строки по убыванию combined total с identity, двумя subtotals, combined total и receipt count каждого Instrument

Scenario: Drill-down воспроизводит строку breakdown

• WHEN User открывает drill-down строки Instrument
• THEN он видит точные coupon и dividend Ledger Entries этого Instrument, периода и валюты, сумма и количество которых соответствуют строке

Requirement: Realized analytics never presents an incomplete result as complete

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

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

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

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

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

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

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

Requirement: Account overview has an independent current-month income summary

Обзор выбранного Brokerage Account MUST показывать компактный source-currency summary «Получено купонами и дивидендами» за период от первого дня текущего месяца по Europe/Moscow до сегодняшнего дня включительно и действие перехода на страницу «Пассивный доход». Summary MUST всегда использовать этот current-month период и MUST NOT наследовать последний пользовательский период страницы аналитики. Пустой или неуспешный расчёт summary MUST оставаться локальным состоянием блока и MUST NOT заменять успешно отображённый Portfolio или другие блоки обзора.

Scenario: Обзор показывает доход текущего месяца

• WHEN обзор Brokerage Account загружен и current-month analytics успешно рассчитана
• THEN он показывает отдельные source-currency итоги с начала текущего месяца по сегодняшний день и переход к полной аналитике

Scenario: Пользовательский период не влияет на обзор

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

Scenario: Current-month summary недоступен

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

Requirement: Forecast is separate from realized income

Страница «Пассивный доход» MUST показывать семантически и визуально отдельный forecast block известных coupon и dividend Future Cash Events на следующие 30 дней от сегодняшней даты независимо от выбранного исторического периода. Forecast totals MUST включать только события coupon и dividend с известной projected amount и MUST оставаться разделёнными по исходным валютам; maturity и offer MUST NOT входить в эти totals. Блок MUST показывать три ближайших подходящих события, обозначать результат как не гарантированный прогноз и предоставлять переход к существующей полной странице «Будущие события». Forecast values MUST NOT входить в realized total, comparisons, trend или instrument breakdown. Ошибка forecast MUST оставаться локальной для блока и MUST NOT скрывать успешно загруженную realized analytics.

Scenario: Forecast показывает ближайшие известные выплаты

• WHEN на следующие 30 дней известны coupon или dividend Future Cash Events
• THEN блок показывает не более трёх ближайших подходящих событий, source-currency totals известных projected amounts, предупреждение о неопределённости и переход к полному списку будущих событий

Scenario: События без суммы не искажают forecast total

• WHEN подходящее coupon или dividend Future Cash Event не имеет известной projected amount
• THEN событие не добавляет нулевую или вымышленную сумму в forecast total

Scenario: Maturity и offer не входят в forecast income

• WHEN ближайшие Future Cash Events содержат maturity или offer
• THEN forecast block не включает их в coupon или dividend totals

Scenario: Пользовательский исторический период не влияет на forecast

• WHEN User применяет любой допустимый исторический период
• THEN forecast block по-прежнему охватывает следующие 30 дней от сегодняшней даты

Scenario: Forecast недоступен при успешной realized analytics

• WHEN realized analytics успешно загружена, а запрос forecast завершается ошибкой
• THEN realized totals, comparisons, trend и breakdown остаются доступными, а forecast block показывает собственную ошибку