diff --git a/architecture/domain-glossary.md b/architecture/domain-glossary.md index ff20bd3..d14a94e 100644 --- a/architecture/domain-glossary.md +++ b/architecture/domain-glossary.md @@ -199,3 +199,13 @@ _Не использовать_: будущая операция, гаранти `offer`. _Не использовать_: upstream dividend type, MOEX row name. + +## Realized Income Analytics + +Read-only account-scoped result исполненных coupon и dividend Ledger Entries за +включительный календарный period в Europe/Moscow. Он сохраняет исходные +currencies и signed broker-reported payments; это не налоговый расчёт, не +forecast и не investment performance. + +_Не использовать_: доходность, общий доход в одной валюте, гарантированный +доход. diff --git a/architecture/system-overview.md b/architecture/system-overview.md index f918dcf..37a5373 100644 --- a/architecture/system-overview.md +++ b/architecture/system-overview.md @@ -11,7 +11,8 @@ WealthLedger — локальное приложение для просмотр token на User. - [Брокерские счета](../features/brokerage-accounts.md), [Portfolio](../features/portfolio-view.md), - [Account Ledger](../features/brokerage-account-ledger.md) и + [Account Ledger](../features/brokerage-account-ledger.md), + [Пассивный доход](../features/brokerage-account-income-analytics.md) и [Future Cash Events](../features/brokerage-account-upcoming-events.md). - [Frontend UI resilience](../features/frontend-ui-resilience.md): явные loading, error, empty и cached-snapshot состояния; initial и частичные diff --git a/features/README.md b/features/README.md index 224b168..0ff8c8f 100644 --- a/features/README.md +++ b/features/README.md @@ -10,5 +10,7 @@ - [Account Ledger](brokerage-account-ledger.md) — исполненные операции счёта. - [Future Cash Events](brokerage-account-upcoming-events.md) — прогнозируемые события по текущим позициям. +- [Пассивный доход брокерского счёта](brokerage-account-income-analytics.md) — + исполненные купоны и дивиденды. - [Frontend UI resilience](frontend-ui-resilience.md) — устойчивые состояния интерфейса. diff --git a/features/brokerage-account-income-analytics.md b/features/brokerage-account-income-analytics.md new file mode 100644 index 0000000..b5a4cec --- /dev/null +++ b/features/brokerage-account-income-analytics.md @@ -0,0 +1,25 @@ +# Пассивный доход брокерского счёта + +Авторизованный 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`; без них применяется текущий месяц. Период не может быть будущим, обратным или длиннее 366 дней. + +Оба endpoint требуют Bearer token и используют обычные ответы о неподключённом T-Bank, неверном token, недоступном счёте и временной недоступности upstream. + +## Реализованный поток + +- Backend проверяет доступ к счёту, проходит все cursor pages исполненных операций и не возвращает частичный результат при ошибке страницы или повреждённой cursor chain. +- Только точные upstream types coupon и dividend формируют результат. Суммы остаются exact decimal strings в исходной валюте; отрицательные корректировки сохраняют знак. Налоги, комиссии, сделки, переводы, погашения и dividend transfer не входят в доход. +- Итоги, сравнения, buckets и Instrument breakdown не смешивают валюты и не создают общий FX total. Сравнения показывают предыдущий период и, когда календарная дата и история счёта позволяют, период годом ранее. +- Trend buckets приходят с backend: дни для 1–45 дней, недели для 46–180 и месяцы для более длинного периода. Пустые buckets остаются в response и текстовом представлении. +- Breakdown раскрывает включённые Ledger Entries из того же ответа, поэтому отображённые строки не требуют отдельного запроса и воспроизводят сумму Instrument и валюты. + +## Прогноз и ограничения + +Блок прогноза переиспользует `/events`: его `incomeTotalsByCurrency` содержит только coupon/dividend с известной projected amount, а на UI отображаются не более трёх ближайших таких событий. Maturity, offer и неизвестные суммы не искажают totals. Прогноз не гарантирован, не входит в фактические итоги и не зависит от выбранного исторического периода; его loading/error/empty outcome локален для блока. + +Аналитика read-only, не хранит историю операций и не рассчитывает налоги, инвестиционную эффективность, доходность, валютную конвертацию или общий мультивалютный итог.