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

2026-11-01 19:29:01 +03:00
parent abe5b16241
commit 37430da4c9
13 changed files with 242 additions and 10 deletions
@@ -0,0 +1,56 @@
+# 022. Хранимая классификация инструментов T-Bank
+
+**Status:** Accepted. Дополняет [ADR
+019](019-hourly-reads-and-online-instrument-reference.md) исключением из
+правила «справочные сведения запрашиваются онлайн». Решение утверждено
+владельцем в [Issue
+WealthLedger/main#48](https://git.personal.ksv741.ru/WealthLedger/main/issues/48).
+
+## Context
+
+ADR 019 установил, что справочные сведения инструментов (detail, lookup,
+каталоги) запрашиваются онлайн и не сохраняются как долговременный справочник:
+«старые справочные строки не являются источником актуальности». Вкладка
+«Концентрация» требует для каждой позиции её сектора и эмитента — бренда
+актива по данным T-Bank. Сектор есть только в описаниях отдельных типов
+инструментов (`share`, `bond`, `etf`), а эмитент — в описании актива по
+`asset_uid` инструмента; из названия, тикера, ISIN или `logoName` его вывести
+нельзя. Запрашивать эти поля онлайн при каждом открытии экрана нельзя:
+ответ Portfolio не ждёт T-Bank, а разрезы должны считаться по уже сохранённому
+снимку.
+
+Существующий metadata-кэш (`TbankInstrument`) не подходит: общий ответ
+`GetInstrumentBy` не содержит `sector`, а его `brand` — данные логотипа,
+а не `{uid, name}` бренда актива.
+
+## Decision
+
+- Сектор и бренд актива позиции хранятся как последнее известное значение в
+  глобальной таблице `TbankInstrumentClassification` (провайдер, ключ
+  инструмента, сектор и время его получения, uid актива и uid/название бренда
+  с временем получения). Данные публичные, без привязки к пользователю или
+  подключению; ограждение по connection revision к ним не применяется, публикация
+  Snapshot ограждается как прежде.
+- Каждое поле обновляется в часовом обходе при его первой попытке, начавшейся
+  не ранее чем через 24 часа после последнего успешного получения этого поля;
+  пока значение не получено, попытка повторяется в каждом обходе. Сектор и
+  бренд обновляются независимо.
+- Неуспешное получение не мешает публикации Portfolio Snapshot и не влияет на
+  его свежесть; сохранённое значение остаётся доступным. Отказ token
+  обрабатывается как отказ token при обходе Portfolio. Ответ «инструмент не
+  найден» сохраняет прежнее значение и перезапускает отсчёт 24 часов.
+- Классификация не входит в `meta.dependencies` Portfolio и не меняет
+  `isStale` и `lastSuccessfulAt`.
+
+## Consequences
+
+- Это первый долговременный справочник T-Bank в системе: ADR 019 теряет
+  характер «только онлайн» для этой области и дополняется, а не заменяется.
+- Разрезы концентрации считаются по снимку без обращений к T-Bank; число
+  вызовов растёт ограниченно — не более одной попытки на поле в сутки на
+  позицию, при первом обходе после выката возможен разовый всплеск, сглаженный
+  общим лимитером и очередью.
+- Значение может быть устаревшим до 24 часов; это приемлемо для группировки
+  позиций, но классификация не является источником актуальных данных брокера.
+- Второй потребитель хранимой классификации — условие пересмотра решения
+  (выделение независимого процесса обновления, отдельные сроки).