docs/adr/022-stored-instrument-classification.md

022. Хранимая классификация инструментов T-Bank

Status: Accepted. Дополняет ADR 019 исключением из правила «справочные сведения запрашиваются онлайн». Решение утверждено владельцем в Issue WealthLedger/main#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 часов; это приемлемо для группировки позиций, но классификация не является источником актуальных данных брокера.
• Второй потребитель хранимой классификации — условие пересмотра решения (выделение независимого процесса обновления, отдельные сроки).