docs: describe concentration tab and stored instrument classification (WealthLedger/main#48)

2026-11-01 19:13:12 +03:00
parent abe5b16241
commit b95fc69493
13 changed files with 242 additions and 10 deletions
@@ -0,0 +1,81 @@
+# Концентрация портфеля
+
+Вкладка «Концентрация» на странице счёта `/accounts/:accountId` показывает,
+какие акции, облигации, секторы и эмитенты занимают наибольшую часть текущей
+оценки Portfolio. Она отвечает на вопрос «где сконцентрированы деньги»,
+который не решают карточки позиций и [структура
+активов](overview.md#как-читать-экран). Точный смысл полей и долей — в
+[справочнике данных](data-reference.md).
+
+## Вкладка и разрезы
+
+Вкладка есть только у отдельного счёта: в режиме [«Все счета»](all-accounts.md)
+её нет. Появление вкладки не меняет вкладку, открытую по умолчанию («Позиции»),
+и содержание остальных вкладок. Пока Portfolio загружается, при его ошибке или
+штатном пустом составе вкладки нет; при Portfolio хотя бы с одной позицией или
+денежным остатком вкладка показывается.
+
+Вкладка содержит четыре разреза и показывает один из них одновременно:
+
+| Разрез | Что ранжирует | Типы позиций |
+| --- | --- | --- |
+| «Акции» | Пять крупнейших позиций акций | `STOCK` |
+| «Облигации» | Пять крупнейших позиций облигаций | `BOND` |
+| «Секторы» | Пять крупнейших секторов по данным T-Bank | `STOCK`, `BOND`, `FUND` |
+| «Эмитенты» | Пять крупнейших эмитентов (брендов актива) | `STOCK`, `BOND` |
+
+Фонды участвуют только в разрезе «Секторы»: их эмитент — управляющая компания,
+а не компания внутри фонда. Позиции типов `CURRENCY`, `FUTURE`, `OPTION`,
+`STRUCTURED_NOTE`, `DIGITAL_FINANCIAL_ASSET` и `OTHER` во вкладку не входят.
+
+Позиции без сектора образуют явную группу «Сектор не указан», без бренда —
+«Эмитент не указан»; обе группы показываются с видимой долей. Государственные
+облигации определяются значением сектора T-Bank `government` с подписью
+«Государственный сектор»; других собственных классификаций WealthLedger
+не вводит. Название элемента в разрезе эмитентов — название бренда; если у
+одного бренда разные названия, показывается название позиции с наибольшей
+стоимостью.
+
+## Топ-5 и «Прочее»
+
+В каждом разрезе показаны пять крупнейших элементов по текущей денежной оценке,
+каждый с суммой и долей. Рядом показан суммарный показатель «Топ-5 · N %».
+Если в разрезе семь и более элементов, все остальные объединены в одну строку
+«Прочее» с числом элементов, суммой и долей. При шести и меньшем числе
+элементов каждый показан своей строкой. По нажатию на «Прочее» раскрывается
+полный перечень остальных элементов, каждый со своей суммой и долей; топ-5
+и диаграмма при этом не меняются.
+
+Доли считаются от суммы стоимостей позиций разреза в выбранной валюте и
+в сумме дают ровно 100 %; округление — до десятой доли процента, очень малые
+доли показываются как «< 0,1 %». Отрицательные и нулевые стоимости, а также
+позиции без оценки в разрез не входят. Конвертации валют нет: каждая позиция
+входит только в валюту своей оценки.
+
+## Валюта
+
+У вкладки свой список валют — валюты оценок позиций акций, облигаций и фондов,
+отсортированные по ISO-коду, — и свой выбор, независимый от «Структуры
+портфеля». По умолчанию выбрана первая валюта списка. При одной валюте
+переключатель не показывается. Общего итога по нескольким валютам нет.
+Выбранные разрез и валюта сохраняются, пока пользователь остаётся на странице
+счёта, включая переключение её вкладок, и сбрасываются при новом заходе и при
+смене счёта.
+
+## Диаграмма и неполные данные
+
+Рядом с перечнем показана кольцевая диаграмма, согласованная с перечнем;
+информация передаётся не только цветом, есть текстовый эквивалент. Если ответ
+отмечен как неполный (`completeness: "incomplete"` — часть позиций не имеет
+оценки), над разрезом появляется предупреждение «Данные неполные», а под
+списком — сноска «Не учтено позиций: N» с числом позиций, не вошедших в разрез.
+Пустой разрез (нет позиций с положительной оценкой в выбранной валюте)
+показывает текстовое состояние вместо диаграммы.
+
+## Откуда берутся сектор и эмитент
+
+Сектор и эмитент — часть данных Portfolio: их получает backend в часовом
+обходе и сохраняет в снимке вместе с остальными полями позиций
+([поток загрузки](flows/portfolio-loading.md#обновление-сектора-и-эмитента),
+[интеграция T-Bank](../../integrations/tbank.md)). Вкладка считается по уже
+загруженному снимку и не обращается к T-Bank.
@@ -33,6 +33,8 @@
 | `totalsByCurrency` | Стоимости позиций + доступные деньги той же валюты | Не включает невычислимую стоимость; не обещает полную оценку портфеля |
 | `lastSuccessfulAt` | Время формирования успешного снимка, UTC | Не является временем каждой котировки; запасной снимок сохраняет исходное время |
 | `isStale` | Истёк часовой срок свежести сохранённого portfolio source | Не описывает состояние клиентского кэша или ошибку фонового запроса |
+| `sector` | Сектор инструмента в том виде, как его определяет T-Bank, с обрезанными пробелами | Только для позиций `STOCK`, `BOND` и `FUND`; значение из одних пробел считается отсутствующим. Во всех остальных случаях — `null` |
+| `issuer` | Бренд актива инструмента по данным T-Bank: `{ id, name }` | Только для позиций `STOCK`, `BOND` и `FUND`, когда у актива известны uid и название бренда. Во всех остальных случаях — `null`. Не влияет на количество, стоимость и свежесть снимка; используется вкладкой [«Концентрация»](concentration.md) |

 Ненулевые денежные остатки одной валюты суммируются. Позиции одинаковых
 инструментов в ответе отдельного счёта не объединяются; визуальная группировка
@@ -58,6 +60,8 @@ ISIN, тикер и `logoName` могут быть `null`. `logoName` — имя
 или метаданных не меняет количество, суммы и свежесть снимка и не скрывает
 финансовые данные. Metadata обновляется независимо; отсутствие имени не задерживает выдачу
 финансового снимка и оставляет доступный идентификатор.
+`logoName` не равен эмитенту из вкладки «Концентрация»: он берётся из metadata
+инструмента, а эмитент — из [классификации инструмента](flows/portfolio-loading.md#обновление-сектора-и-эмитента).

 ## Структура и доли

@@ -11,9 +11,28 @@
 они не ждут и не вызывают T-Bank и не предлагают ручную синхронизацию. Часовой
 обход текущего подключения обновляет Portfolio независимо от экрана. Для нового
 полного snapshot ему нужны оба финансовых ответа `GetPortfolio` и
-`GetPositions`; суммы и позиции публикуются вместе. Metadata инструмента
-дополняет представление независимо, с доступным UID/FIGI вместо имени до её
-онлайн-загрузки.
+`GetPositions`; суммы и позиции публикуются вместе. Metadata инструмента и
+классификация (сектор и эмитент) дополняют представление независимо,
+с доступным UID/FIGI вместо имени до их загрузки.
+
+## Обновление сектора и эмитента
+
+Часовой обход также обновляет сектор и эмитента позиций типов `share`, `bond`
+и `etf`. Значения хранятся как последнее известное ([ADR
+022](../../../adr/022-stored-instrument-classification.md)): сектор — как его
+определяет T-Bank, эмитент — бренд актива (`uid` и `name`). Каждое поле
+обновляется при первом обходе, начавшемся не ранее чем через 24 часа после его
+последнего успешного получения; пока значение не получено, попытка повторяется
+в каждом обходе. Сектор и эмитент обновляются независимо.
+
+Неуспешное получение не мешает публикации snapshot и не меняет
+`lastSuccessfulAt` и `isStale`; сохранённое значение остаётся доступным.
+Исключение — отказ token: он обрабатывается так же, как отказ token при
+обходе Portfolio. Инструмент ищется по UID, затем по FIGI; ответ «не найдено»
+сохраняет прежнее значение и отсчёт 24 часов начинается заново. Позиции без
+полученных значений участвуют в разрезах вкладки
+[«Концентрация»](../concentration.md) как «Сектор не указан» и
+«Эмитент не указан».

 Открытый экран выполняет локальное перечитывание не чаще одного раза в
 30 минут; retry также повторяет только HTTP GET. `data: null` означает, что
@@ -64,6 +64,10 @@ Backend получает данные через серверную
 без логотипа и с подписью результата. Отсутствующие показатели скрываются,
 а не подменяются нулём или заглушкой.

+Рядом с вкладкой «Позиции» на странице отдельного счёта есть вкладка
+[«Концентрация»](concentration.md): она показывает, где сконцентрированы
+деньги — крупнейшие бумаги, секторы и эмитенты. В режиме «Все счета» её нет.
+
 Существует расхождение: [согласованная спецификация представления позиций](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/portfolio-view/spec.md#requirement-представление-карточек-позиций-на-клиенте)
 требует доступности всех иных типов в отдельной секции, а текущие frontend
 и его проверка исключают `CURRENCY` только из списка карточек. Такие позиции