specs/openspec/changes/archive/2026-10-30-group-account-rows-by-instrument/specs/brokerage-account-income-analytics/spec.md

MODIFIED 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: 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, внутри которой видны отдельные карточки каждого счёта, а аналитические итоги страницы не меняются