docs: document frontend audit remediation delivery

2026-09-06 19:49:38 +03:00
parent 598dfb2bdb
commit 55d35c7f78
10 changed files with 1563 additions and 4 deletions
@@ -18,6 +18,37 @@
 - Trend buckets приходят с backend: дни для 1–45 дней, недели для 46–180 и месяцы для более длинного периода. Пустые buckets остаются в response и текстовом представлении.
 - Breakdown раскрывает включённые Ledger Entries из того же ответа, поэтому отображённые строки не требуют отдельного запроса и воспроизводят сумму Instrument и валюты.

+## Связь 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 состоянию аналитики. Частичный drill-down не показывается как
+полный; формула идентификации в клиенте не восстанавливается. Полностью пустой
+ответ допустим. Состав и порядок выплат, signed Money и сортировка breakdown
+сохраняются, frontend не пересчитывает денежные итоги.
+
+## Совместимость и локальное обновление
+
+Сначала обновляется backend: дополнительное поле совместимо с прежним
+frontend. Затем синхронизируются OpenAPI snapshot/generated types и обновляется
+frontend consumer. При переключении клиент перезагружается, чтобы не переносить
+старые in-memory results и незавершённые запросы. Новый frontend требует новый
+backend; отсутствие membership не скрывается fallback на прежнюю формулу.
+
+При регрессии сначала возвращается прежний frontend вместе с соответствующим
+snapshot/types и перезагружается клиент; затем при необходимости возвращается
+backend. Старый frontend может временно работать с новым additive response.
+SQLite schema, credentials и broker-reported операции не меняются: rollback
+не удаляет данные, производные результаты запрашиваются заново.
+
 ## Прогноз и ограничения

 Блок прогноза переиспользует `/events`: его `incomeTotalsByCurrency` содержит только coupon/dividend с известной projected amount, а на UI отображаются не более трёх ближайших таких событий. Maturity, offer и неизвестные суммы не искажают totals. Прогноз не гарантирован, не входит в фактические итоги и не зависит от выбранного исторического периода; его loading/error/empty outcome локален для блока.