spec: unify income payment cards and drop period comparisons (WealthLedger/main#33) (#37)

spec: unify income payment cards and drop period comparisons (WealthLedger/main#33)

openspec/changes/unify-income-payment-cards/tasks.md

@@ -0,0 +1,67 @@
+# Tasks
+
+## 1. Удаление сравнений и поставка контракта дохода
+
+- [x] 1.1 [backend] Оставить для дохода только выбранный период в чтении и планировании фоновой загрузки; сохранить точные итоги, signed entries, полноту, текущую месячную сводку и существующие buckets.
+  - **Covers:** `brokerage-account-income-analytics` — `Period comparisons preserve calendar and currency meaning` (удаление); `brokerage-account-income-analytics` — `Realized analytics never presents an incomplete result as complete`; `brokerage-account-income-analytics` — `Realized income analytics is account-scoped and period-bound`; `brokerage-account-income-analytics` — `Account overview has an independent current-month income summary`.
+  - **Source:** `design.md` §§ Decisions/backend, Data / Storage Changes; `system-analysis/analysis.md` §§ Interaction Flows, Data and State Semantics.
+  - **Verification:** адресные backend tests: один выбранный диапазон в аналитике и screen sync, без previous/year; полные, неполные, пустые, многостраничные и signed-мультивалютные результаты; неизменная current-month summary.
+  - **Depends on:** none
+
+- [x] 1.2 [backend] Удалить comparison-only поля и роли из обоих публичных income-analytics ответов и опубликовать обновлённый backend-generated OpenAPI как явный контракт для frontend.
+  - **Covers:** `brokerage-account-income-analytics` — `Period comparisons preserve calendar and currency meaning` (удаление); `brokerage-account-income-analytics` — `Realized analytics never presents an incomplete result as complete`.
+  - **Source:** `system-analysis/analysis.md` §§ Contracts, Compatibility / Migration; `system-analysis/contracts/income-analytics-response.schema.json`; `design.md` § Contract Implementation.
+  - **Verification:** `npm run openapi:generate`, `npm run test:openapi-contract` и сопоставление 200 response schema обоих маршрутов с утверждённым target: отсутствуют `previous`, `yearComparison` и роли `previous`/`year`, остальные данные/ошибки сохранены; релевантные HTTP checks и `npm run verify` в backend.
+  - **Depends on:** 1.1
+
+- [x] 1.3 [frontend] Обновить полученный OpenAPI snapshot и generated types, удалить UI, display-only расчёты и состояния сравнений на странице дохода, сохранив фильтры, итоги, налоговое пояснение, плоские выплаты и состояния выбранного периода.
+  - **Covers:** `brokerage-account-income-analytics` — `Period comparisons preserve calendar and currency meaning` (удаление); `brokerage-account-income-analytics` — `User explicitly applies an analytics period represented in the URL`; `brokerage-account-income-analytics` — `Analytics summary remains readable per currency`; `brokerage-account-income-analytics` — `Income page excludes upcoming forecasts`; `brokerage-account-income-analytics` — `Realized analytics never presents an incomplete result as complete`.
+  - **Source:** `design.md` §§ Decisions/frontend, Contract Implementation, UI/UX Package; `system-analysis/analysis.md` § Contracts.
+  - **Verification:** frontend behavior checks для applied/draft периода, URL/back/reset, неполного/пустого/ошибочного selected и отсутствия comparison headings/notices во всех состояниях; локальные typecheck и `npm run verify` на итоговом frontend diff.
+  - **Depends on:** 1.2
+
+## 2. Одна предметная карточка купона и дивиденда
+
+- [x] 2.1 [frontend] Предоставить единый публичный компонент выплаты с явными режимами исполнения, прогноза и графика, сохранив исходную валюту, знак, отсутствие данных и различимые подписи суммы/дат.
+  - **Covers:** `brokerage-account-income-analytics` — `Income payments remain traceable to exact Ledger Entries`; `brokerage-account-ledger` — `Full ledger presents compact rows`; `brokerage-account-upcoming-events` — `Account page presents an upcoming events list`; `instrument-income-schedules` — `Instrument payout schedules do not imply executed income`.
+  - **Source:** `design.md` §§ Decisions/frontend, UI/UX Package; `system-analysis/analysis.md` § Data and State Semantics.
+  - **Verification:** frontend checks разных source modes с signed Money, нулём против неизвестного, registry date и separate per-security/position amounts; `npm run deps`, `npm run typecheck`.
+  - **Depends on:** none
+
+- [x] 2.2 [frontend] Использовать единый компонент для исполненных купонов/дивидендов в доходе, полном журнале, недавних операциях и личной истории инструментов; сохранить порядок, повторы и представление остальных операций.
+  - **Covers:** `brokerage-account-income-analytics` — `Income payments remain traceable to exact Ledger Entries`; `brokerage-account-ledger` — `Account overview includes recent ledger events`; `brokerage-account-ledger` — `Full ledger presents compact rows`.
+  - **Source:** `design.md` §§ Decisions/frontend, UI/UX Package; `qa-analysis.md` § Coverage Matrix.
+  - **Verification:** frontend checks для одного и того же типа карточки во всех перечисленных местах, повторов IDs, исправлений с минусом, fallback identity, деталей личной истории и неизменённых trade/tax rows.
+  - **Depends on:** 2.1
+
+- [x] 2.3 [frontend] Использовать тот же компонент в полном прогнозе и его превью только для купонов/дивидендов, обозначить прогноз и дату реестра дивиденда, сохранить offer/maturity.
+  - **Covers:** `brokerage-account-upcoming-events` — `Account page presents an upcoming events list`; `brokerage-account-upcoming-events` — `Account overview includes upcoming events`.
+  - **Source:** `design.md` §§ Decisions/frontend, UI/UX Package; `system-analysis/analysis.md` § Data and State Semantics.
+  - **Verification:** frontend checks для известной, нулевой и неизвестной projected amount, registry date, preview/full list, offer/maturity и локальных ошибок источника.
+  - **Depends on:** 2.1
+
+- [x] 2.4 [frontend] Использовать тот же компонент в будущих и прошедших графиках акций/облигаций с отдельными подписями условий на бумагу и оценки без приписывания личного зачисления.
+  - **Covers:** `instrument-income-schedules` — `Instrument payout schedules do not imply executed income`.
+  - **Source:** `design.md` §§ Decisions/frontend, UI/UX Package; `system-analysis/analysis.md` § Data and State Semantics.
+  - **Verification:** frontend checks для будущего купона, прошлого дивиденда, недатированного/неизвестного условия, разных сумм на бумагу и позицию; проверка узкого viewport и клавиатуры, `npm run verify` на итоговом frontend diff.
+  - **Depends on:** 2.1
+
+## 3. Актуальная документация после подтверждения целевого поведения
+
+- [x] 3.1 [docs] Привести страницы дохода одного и всех счетов к состоянию без сравнений и описать прежнюю полноту выбранного периода.
+  - **Covers:** `brokerage-account-income-analytics` — `Period comparisons preserve calendar and currency meaning` (удаление); `brokerage-account-income-analytics` — `Analytics summary remains readable per currency`; `brokerage-account-income-analytics` — `Realized analytics never presents an incomplete result as complete`.
+  - **Source:** `docs-impact.md` § Documentation Changes — `docs/domains/income/overview.md`, `docs/domains/portfolio/all-accounts.md`.
+  - **Verification:** сопоставление двух страниц с согласованными ответами income API, UI и проверка ссылок/Markdown средствами docs repo.
+  - **Depends on:** 1.2, 1.3
+
+- [x] 3.2 [docs] Зафиксировать одинаковую карточку исполненной выплаты, прогнозного события и графика с разными финансовыми смыслами на существующих тематических страницах.
+  - **Covers:** `brokerage-account-income-analytics` — `Income payments remain traceable to exact Ledger Entries`; `brokerage-account-ledger` — `Full ledger presents compact rows`; `brokerage-account-ledger` — `Account overview includes recent ledger events`; `brokerage-account-upcoming-events` — `Account page presents an upcoming events list`; `brokerage-account-upcoming-events` — `Account overview includes upcoming events`; `instrument-income-schedules` — `Instrument payout schedules do not imply executed income`.
+  - **Source:** `docs-impact.md` § Documentation Changes — `docs/domains/operations/overview.md`, `docs/domains/income/upcoming-events.md`, `docs/domains/instruments/stocks.md`, `docs/domains/instruments/bonds.md`.
+  - **Verification:** сверить текст четырёх страниц с экранами и публичными исходными данными, проверить ссылки/Markdown средствами docs repo.
+  - **Depends on:** 2.2, 2.3, 2.4
+
+- [x] 3.3 [docs] Обновить описание HTTP income analytics без дублирования машинной схемы.
+  - **Covers:** `brokerage-account-income-analytics` — `Period comparisons preserve calendar and currency meaning` (удаление).
+  - **Source:** `docs-impact.md` § Documentation Changes — `docs/architecture/http-api.md`; `system-analysis/analysis.md` § Contracts.
+  - **Verification:** сопоставить текст с опубликованным backend OpenAPI обоих маршрутов и target schema, проверить ссылки/Markdown средствами docs repo.
+  - **Depends on:** 1.2