specs/openspec/specs/brokerage/brokerage-account-income-analytics/spec.md

brokerage-account-income-analytics Specification

Purpose

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

Requirements

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

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

Чтение MUST использовать сохранённые операции текущего подключения и локальное подтверждение доступа без синхронного запроса T-Bank. Ответ MUST иметь envelope { data, meta } по tbank-data-sync. Полнота MUST определяться для выбранного периода и каждого необходимого периода сравнения отдельно. Запрос MUST приоритетно загружать их пропуски до фоновой догрузки остальной истории; известные правила календарных дат MUST сохраняться.

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

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

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

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

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

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

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

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

Scenario: Общий доход требует полноты всех счетов

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

Scenario: Открыт ещё не загруженный период

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

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: 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 исполненных операций этого периода. Каждое comparison MUST дополнительно требовать полного результата соответствующего периода сравнения. Ошибка любой необходимой страницы MUST NOT возвращать частичные totals, comparisons, buckets или breakdown как полный результат. При временной недоступности клиент MUST сохранять предыдущий полный результат той же выборки либо показывать нейтральную недоступность соответствующего расчёта без технических сообщений и ручного повтора. Восстановление SHALL выполняться автоматически по frontend-data-resilience.

Доступные независимые части MUST оставаться видимыми; неполное сравнение MUST обозначаться как недоступное без нулевой базы и окончательной разницы. Успешный полный период без подходящих выплат MUST возвращать нулевой результат и отображаться с объяснением пустого состояния. Неизвестный результат MUST NOT подменяться таким нулевым результатом.

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

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

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

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

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

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

Scenario: Основной период готов, сравнение пока нет

• WHEN выбранный период полностью рассчитан, а необходимый период сравнения ещё не получен
• 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 наследовать последний пользовательский период страницы аналитики. Пустой или неуспешный расчёт MUST оставаться локальным состоянием блока и MUST NOT заменять успешно отображённый Portfolio или другие блоки обзора. Временная ошибка обновления MUST сохранять доступную сводку той же выборки без предупреждения и ручного повтора. При отсутствии результата SHALL показываться нейтральная недоступность после первичного ожидания с автоматическим восстановлением.

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: Income payments remain traceable to exact Ledger Entries

В разделе «Выплаты» страница MUST показывать единый список карточек точных исполненных Ledger Entries применённого периода в исходном серверном порядке entries. Каждая выплата MUST иметь собственную сразу видимую карточку с описанием, датой исполнения, доступной identity Instrument и signed Money в исходной валюте. Купоны и дивиденды MUST использовать то же представление выплаты, что и на экранах журнала, прогноза и графиков инструментов, при этом карточка MUST обозначать эту сумму именно как фактически исполненную, а не прогнозную. В режиме одного Brokerage Account страница MUST NOT добавлять внешние группировочные карточки или заголовки по Instrument либо валюте, subtotals инструмента или количество выплат инструмента. В режиме «Все счета» записи раздела «Выплаты» MUST группироваться по тем же правилам ключа, состава, порядка и итога, что и записи журнала по Requirements «All-accounts ledger groups same-day entries of one instrument», «All-accounts ledger group shows each entry and an exact total» и «All-accounts ledger grouping preserves order and limits» capability brokerage-account-ledger. Каждая запись при этом MUST оставаться отдельной сразу видимой карточкой внутри группы, а итог группы MUST NOT показываться, пока полнота периода не подтверждена; заголовки валютных групп и receipt count MUST NOT добавляться. Список MUST сохранять отрицательные корректировки и повторяющиеся operation IDs как отдельные записи и MUST NOT включать записи вне аналитического итога. Backend MUST обеспечивать согласованность entries, instrumentKey, валюты и receipt count при формировании ответа из одного набора записей. Frontend SHALL доверять типизированному contract без второго runtime consistency validator и MUST NOT пересчитывать аналитические денежные итоги. Единственное исключение — итог визуальной группы режима «Все счета»: это точная сумма показанных записей группы по каждой валюте, и он MUST NOT подменять аналитические итоги.

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

• WHEN в режиме одного Brokerage Account выбранный период содержит несколько включённых 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 подходящие в режиме одного Brokerage Account выплаты одного Instrument представлены в нескольких исходных валютах
• THEN каждая карточка показывает свою Money с исходной валютой, без отдельного заголовка валютной группы или объединённого мультивалютного итога

Scenario: Выплаты одной бумаги на двух счетах в режиме «Все счета»

• WHEN в режиме «Все счета» за один день получены купон по облигации на брокерском счёте +200 RUB и купон по той же облигации на ИИС +100 RUB
• THEN раздел «Выплаты» показывает их одной группой с итогом +300 RUB, внутри которой видны отдельные карточки каждого счёта, а аналитические итоги страницы не меняются

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 эта страница остаётся доступной с прежним поведением независимо от отсутствия прогноза на странице дохода

Requirement: Доход обновляется без технических сообщений

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

Scenario: Доход обновляется при редактировании периода

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

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

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