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
@@ -2,7 +2,10 @@

 **Status:** Accepted. Заменяет request-driven, manual-refresh и
 no-periodic-walk части [ADR 017](017-local-tbank-reads-and-background-sync.md)
-и дополняет [ADR 018](018-minimal-runtime-coordination.md).
+и дополняет [ADR 018](018-minimal-runtime-coordination.md). Правило «справочные
+сведения запрашиваются онлайн» дополнено исключением для сектора и бренда
+актива позиции — [ADR
+022](022-stored-instrument-classification.md).

 ## Decision

@@ -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 часов; это приемлемо для группировки
+  позиций, но классификация не является источником актуальных данных брокера.
+- Второй потребитель хранимой классификации — условие пересмотра решения
+  (выделение независимого процесса обновления, отдельные сроки).
@@ -26,3 +26,4 @@
 - [019 — Часовой обход и онлайн-справочник инструментов](019-hourly-reads-and-online-instrument-reference.md)
 - [020 — Evidence for hourly sync read boundaries](020-hourly-sync-verification-evidence.md)
 - [021 — Тихое чтение и редкие подтверждения](021-quiet-reading-and-rare-confirmations.md)
+- [022 — Хранимая классификация инструментов T-Bank](022-stored-instrument-classification.md)