docs/features/brokerage-account-income-analytics.md

# Пассивный доход брокерского счёта

Авторизованный User открывает `/accounts/:accountId/income` из обзора выбранного Brokerage Account. Экран показывает исполненные купоны и дивиденды за применённый календарный период: текстовые итоги по валютам, сравнения и раздел «Выплаты» с отдельной карточкой каждой включённой выплаты.

## API

`GET /api/v1/brokerage-accounts/:accountId/income-summary` возвращает текущий месяц по сегодняшнюю дату для компактного блока обзора. Он не зависит от периода, который User ранее выбрал на странице аналитики.

`GET /api/v1/brokerage-accounts/:accountId/income-analytics?from=YYYY-MM-DD&to=YYYY-MM-DD` возвращает полный результат. Даты задают включительный период в `Europe/Moscow`; без них применяется текущий месяц. Период не может быть будущим или обратным. Максимальная длительность периода не ограничена.

Оба endpoint требуют Bearer token и используют обычные ответы о неподключённом T-Bank, неверном token, недоступном счёте и временной недоступности upstream.

## Выбор периода и состояния страницы

В блоке «Период» два календарных поля Mantine DateInput показывают даты в формате
`ДД.ММ.ГГГГ`. Календарный выбор и ручной ввод изменяют только черновик. Кнопка
«Применить» или submit с клавиатуры проверяют видимый текст и передают допустимые
даты в URL как `from=YYYY-MM-DD&to=YYYY-MM-DD`. До применения результат сохраняется; отдельной
подписи периода под фильтрами нет. Открытие URL и навигация назад восстанавливают
применённый период.

Пустая, несуществующая или будущая дата получает ошибку у своего поля;
обратный диапазон — у поля «По». Некорректный текст не заменяется последней
допустимой датой при потере фокуса, не меняет URL и не отправляет запрос.
Календарь учитывает допустимую соседнюю дату и сегодняшний день в Europe/Moscow.
«Сбросить» сразу применяет текущий московский месяц по сегодняшний день,
восстанавливает оба поля и очищает ошибки, даже если изменён только черновик.

При первой загрузке или новом периоде без cached data показан structural
skeleton. Пустой результат объясняет отсутствие исполненных купонов и
дивидендов, сохраняя фильтры, налоговое пояснение и сравнения. Ошибка запроса
или повреждённый membership даёт локальное состояние с действием «Повторить».
При фоновом обновлении того же периода Client Cached Snapshot и черновик
остаются видимыми: загрузку обозначает progress, неуспешное обновление —
предупреждение с retry.

На узком экране поля и действия идут вертикально; все карточки выплат
остаются в общем потоке страницы без раскрытия или внутренних scroll-панелей.

## Реализованный поток

- Backend проверяет доступ к счёту, проходит все cursor pages исполненных операций и не возвращает частичный результат при ошибке страницы или повреждённой cursor chain.
- Только точные upstream types coupon и dividend формируют результат. Суммы остаются exact decimal strings в исходной валюте; отрицательные корректировки сохраняют знак. Налоги, комиссии, сделки, переводы, погашения и dividend transfer не входят в доход.
- Итоги, сравнения, buckets и Instrument breakdown не смешивают валюты и не создают общий FX total. Сравнения показывают предыдущий период и, когда календарная дата и история счёта позволяют, период годом ранее.
- Buckets по-прежнему приходят с backend: дни для 1–45 дней, недели для 46–180 и месяцы для более длинного периода, включая пустые buckets. Страница дохода не строит из них график или текстовую динамику; API response не меняется.
- Раздел «Выплаты» показывает единый список LedgerEntryRow-карточек в исходном порядке `entries`: одна карточка на каждую выплату. Внешних групп по инструментам или валютам, итогов и количества выплат инструмента нет. Описание, дата, доступная identity и signed Money видны в каждой карточке; валюты по-прежнему разделены в summary/comparisons. Дополнительный запрос за составом не нужен.

## Связь breakdown с выплатами

Каждая запись `income-analytics.entries` содержит обязательный `instrumentKey`,
равный `key` соответствующей строки `instruments`. Backend вычисляет этот ключ
один раз при подготовке income entries и использует его же для группировки.
Приоритет UID, FIGI, ticker/type и operation ID с разделением по валюте остаётся
серверным правилом; клиент воспринимает ключ как непрозрачную строку.
Общий Ledger endpoint не приобретает income-specific поле.

Income VM проверяет принадлежность entries по полученному ключу до подготовки
плоского списка выплат. Отсутствующий, пустой или
нестроковый ключ, неоднозначные instrument keys, неизвестная группа, другая
валюта или несовпадение receipt count приводят к существующему локальному
error/retry состоянию аналитики. Частичный список выплат не показывается как
полный; формула идентификации в клиенте не восстанавливается. Полностью пустой
ответ допустим. Состав и исходный серверный порядок entries и signed Money
сохраняются, frontend не пересчитывает денежные итоги. Повторяющиеся operation
IDs остаются отдельными строками; ключи учитывают instrumentKey, occurrence внутри группы и
logo source для корректного обновления image fallback.

## Совместимость membership и локальное обновление

Сначала обновляется backend: дополнительное поле совместимо с прежним
frontend. Затем синхронизируются OpenAPI snapshot/generated types и обновляется
frontend consumer. При переключении клиент перезагружается, чтобы не переносить
старые in-memory results и незавершённые запросы. Новый frontend требует новый
backend; отсутствие membership не скрывается fallback на прежнюю формулу.

При регрессии сначала возвращается прежний frontend вместе с соответствующим
snapshot/types и перезагружается клиент; затем при необходимости возвращается
backend. Старый frontend может временно работать с новым additive response.
Календарные фильтры и отдельные карточки выплат используют тот же контракт и не требуют
дополнительного обновления backend. SQLite schema, credentials и broker-reported
операции не меняются: rollback
не удаляет данные, производные результаты запрашиваются заново.

## Будущие события и ограничения

На странице дохода нет блоков «Динамика» и «Ближайший прогноз». Она не запрашивает
`/events` и не зависит от его доступности. Самостоятельная страница
[«Будущие события»](brokerage-account-upcoming-events.md) по-прежнему доступна из обзора
выбранного Brokerage Account и сохраняет прежнее поведение. Будущие выплаты
не включаются в realized totals или сравнения.

Аналитика read-only, не хранит историю операций и не рассчитывает налоги, инвестиционную эффективность, доходность, валютную конвертацию или общий мультивалютный итог.