From dcb528fa9f76f0d7aa98bd827cc7ee39024dbb13 Mon Sep 17 00:00:00 2001 From: codex-bot Date: Fri, 30 Oct 2026 07:28:25 +0300 Subject: [PATCH] docs: describe all-account row grouping (WealthLedger/main#47) (#59) --- domains/income/overview.md | 4 ++-- domains/income/upcoming-events.md | 11 ++++++++++- domains/operations/overview.md | 24 +++++++++++++++++++++--- domains/portfolio/all-accounts.md | 6 ++++++ 4 files changed, 39 insertions(+), 6 deletions(-) diff --git a/domains/income/overview.md b/domains/income/overview.md index 9ec0d21..97c7bae 100644 --- a/domains/income/overview.md +++ b/domains/income/overview.md @@ -54,7 +54,7 @@ - Только точные типы купона и дивиденда источника формируют результат. Суммы остаются точными десятичными строками в исходной валюте; отрицательные корректировки сохраняют знак. Налоги, комиссии, сделки, переводы, погашения и переводы дивидендов не входят в доход. - Итоги, временные интервалы и разбиение по инструментам не смешивают валюты и не создают общий конвертированный итог. Система не загружает другие периоды ради сравнения полученного дохода с выбранным. - Временные интервалы по-прежнему приходят с backend: дни для 1–45 дней, недели для 46–180 и месяцы для более длинного периода, включая пустые интервалы. Страница дохода не строит из них график или текстовую динамику; ответ API не меняется. -- Раздел «Выплаты» показывает единый список карточек выплат в исходном порядке `entries`: одна карточка на каждую выплату. Внешних групп по инструментам или валютам, итогов и количества выплат инструмента нет. Описание, дата, доступные идентификаторы инструмента и сумма со знаком видны в каждой карточке; валюты разделены в итогах. Дополнительный запрос за составом не нужен. +- Раздел «Выплаты» показывает карточки выплат в исходном порядке `entries`. В отдельном счёте каждая выплата — отдельная карточка. В режиме «Все счета» выплаты одного инструмента, дня и точного типа образуют группу, если их две и более ([правила группировки](../operations/overview.md#группировка-в-режиме-все-счета)). Группа стоит на месте первой выплаты; каждая строка счёта показывает название счёта и свою сумму со знаком. Визуальный итог группы — точная сумма по валютам по показанным выплатам; он скрыт, если полнота периода не `complete`, или у выплаты нет суммы, или сумма равна нулю. Это клиентский расчёт и не заменяет серверные итоги аналитики дохода, которые по-прежнему приходят из ответа API и не пересчитываются. Описание, дата, доступные идентификаторы инструмента и сумма со знаком видны в каждой выплате. Дополнительный запрос за составом не нужен. ## Полнота и принадлежность выплат @@ -80,7 +80,7 @@ Backend обеспечивает принадлежность выплат, ва доверяет типизированному contract, не восстанавливает формулу идентификации и не выполняет второй consistency validator. Полностью пустой ответ допустим. Состав и исходный серверный порядок записей и знак сумм -сохраняются, frontend не пересчитывает денежные итоги. Стабильный ID в пределах подключения и счёта определяет одну операцию: +сохраняются; серверные денежные итоги frontend не пересчитывает (визуальный итог группы в режиме «Все счета» отдельный, см. выше). Стабильный ID в пределах подключения и счёта определяет одну операцию: повторная сверка обновляет её без двойного учёта. Одинаковые ID разных счетов остаются разными выплатами. Изменение источника логотипа позволяет заново показать изображение после буквенной заглушки. diff --git a/domains/income/upcoming-events.md b/domains/income/upcoming-events.md index be397aa..76ae07b 100644 --- a/domains/income/upcoming-events.md +++ b/domains/income/upcoming-events.md @@ -71,7 +71,16 @@ без замены периода и без запуска личной работы. Фильтрация на сервере предшествует сортировке и вычислению `incomeTotalsByCurrency`, включающего только купоны и дивиденды. -Итоги остаются в ответе API; полный экран показывает список без общего итога. +Итоги остаются в ответе API; полный экран показывает список без общего итога списка. + +В режиме «Все счета» события одного инструмента, даты, точного типа и `dateKind` образуют +группу, если их две и более, в том числе одного счёта. Ключ дополнительно включает `dateKind`, +поэтому дата реестра дивиденда и иная дата того же инструмента не объединяются. Группа стоит на месте первого +события. Полный список группирует все полученные события; превью обзора сначала берёт пять +событий и группирует только их. Каждая строка счёта остаётся отдельной и показывает название +счёта и свою прогнозную сумму. Визуальный итог группы — точная сумма по валютам; он показывается +только если полнота прогноза `complete` и у каждого события группы известна прогнозная сумма. +Иначе итог скрыт, а строки остаются. Этот итог не равен итогам ответа API и не относится к полученному доходу. ## Получение и отказы diff --git a/domains/operations/overview.md b/domains/operations/overview.md index b786c21..88dd087 100644 --- a/domains/operations/overview.md +++ b/domains/operations/overview.md @@ -13,9 +13,27 @@ Исполненная операция содержит тип события, его категорию, описание, момент совершения, доступные сведения об инструменте и денежное движение. Запросы отменённых или ожидающих исполнения поручений не образуют этот журнал. -Суммы остаются точными десятичными строками в исходной валюте; frontend -только форматирует их. Положительное и отрицательное движение сохраняют -знак. Отсутствие `payment` означает «Без движения денег», а не нулевую сумму. +Суммы остаются точными десятичными строками в исходной валюте. Frontend +форматирует их и считает визуальный итог группы по показанным записям +(см. [группировку](#группировка-в-режиме-все-счета)). Положительное и отрицательное +движение сохраняют знак. Отсутствие `payment` означает «Без движения денег», а не нулевую сумму. + +## Группировка в режиме «Все счета» + +Только в режиме `all` записи журнала и превью обзора, которые относятся к одному +дню экрана, одному инструменту и точному типу операции, объединяются в группу. +Ключом служат день, `instrumentUid` (иначе `figi`) и тип; группа образуется при +двух и более записях, в том числе одного счёта. Группа стоит на месте первой записи. +Каждая запись остаётся отдельной строкой с названием счёта простым текстом и своей суммой. +Одиночный счёт не группируется. + +Группировка выполняется после лимита: превью обзора сначала берёт пять записей, +затем группирует только их. Полный журнал группирует страницу, уже загруженную +курсором; группы не переносятся между страницами. Курсор и порядок записей не меняются. + +Итог группы — точная сумма по каждой валюте, без конвертации. Он показывается только +если полнота журнала `complete`, у каждой записи группы есть `payment`, и ни одна сумма +не равна нулю. Иначе итог скрыт, а строки счетов остаются. Категории объединяют разные события для фильтрации: сделка (`trade`), доход (`income`), налог (`tax`), комиссия (`fee`), перевод (`transfer`) diff --git a/domains/portfolio/all-accounts.md b/domains/portfolio/all-accounts.md index d028588..2a54a46 100644 --- a/domains/portfolio/all-accounts.md +++ b/domains/portfolio/all-accounts.md @@ -81,6 +81,12 @@ Backend публикует статические маршруты под `/api/ применённые фильтры. Coverage/status без изменения строк не ломают cursor. Продолжение не зависит от RAM-кэша или перезапуска. +Визуальная группировка строк одного инструмента в общих списках выполняется только +в пределах уже полученного списка: в журнале — на загруженной странице, без переноса группы +на следующую; в полном списке будущих событий и выплатах дохода — по всем полученным строкам +периода. Группировка не меняет порядок, cursor или ответ API. Протокол курсора прежний. +Правила группировки — в [журнале](../operations/overview.md#группировка-в-режиме-все-счета). + Повторная сверка полного показанного периода публикует все счета и интервалы одной транзакцией; успешное первое окно не смешивается с прежними остальными. Подробнее — [журнал](../operations/overview.md#получение-и-полнота).