docs: describe bond pages and rating sources

features/bond-detail.md

@@ -0,0 +1,127 @@
+# Страница облигации
+
+Раздел «Облигации» открывает `/bonds`: поиск по названию, тикеру или ISIN
+с двух символов. `/bonds/:identifier` принимает UID или точный тикер.
+Название и логотип облигации в портфеле счёта и «Всех счетах» ведут на её
+страницу по точному UID без предварительной загрузки карточек всех позиций.
+При открытии выпуска проверенный однозначный тикер заменяет UID в адресе,
+сохраняя период графика и фильтр событий.
+
+Поиск выбирает один режим на нормализованный ISIN, сохраняя разные выпуски
+и записи без ISIN отдельно. Приоритет: доступность API, точный тикер, TQOB,
+затем UID. Ограничение — 30 результатов после выбора режима. Цена и ссылка
+принадлежат выбранному UID. Прямая ссылка из портфеля сохраняет исходный UID,
+если поиск предпочитает другой режим. Неоднозначный точный тикер возвращает
+`409 BOND_TICKER_AMBIGUOUS`; интерфейс предлагает выбрать выпуск через поиск.
+Поиск загружает параметры выпусков и котировки, но оставляет ссылки по UID:
+отдельная проверка тикера для каждого результата не выполняется.
+
+## Содержание
+
+Карточка показывает цену в процентах от номинала, время котировки и статус
+торгов. Изменение выражено в процентных пунктах относительно последней
+завершённой дневной свечи до московской даты котировки; база ищется за 20 дней.
+Денежная оценка без НКД равна цене в процентах, умноженной на текущий номинал
+и делённой на 100. Она округляется до девяти десятичных знаков. Оценка с НКД
+добавляет текущий накопленный купонный доход только при совпадении валют.
+Это ориентир без комиссии: котировка может быть старше текущего номинала и НКД.
+FX-конвертация не выполняется, первоначальный номинал не заменяет текущий.
+
+Условия выпуска: текущий и первоначальный номинал, погашение, оферта,
+количество купонов в год, лот. Отдельно отмечены плавающий купон,
+амортизация, бессрочность и субординация. Неизвестные даты и суммы показываются
+как недоступные.
+
+Сводка «Купон, рейтинг и доходность» показывает ближайший купон на одну
+облигацию, дату выплаты и тип из календаря Т-Банка. Неизвестная сумма ближайшей
+выплаты не заменяется суммой более позднего купона. Флаг плавающего купона
+используется только как fallback типа; отсутствие флага не означает
+фиксированный купон.
+
+Текущая купонная доходность — ближайший купон × 365 / длительность его периода
+в днях / денежная цена без НКД × 100 %. Decimal-расчёт округляется до четырёх
+знаков. Требуются известная неотрицательная выплата, положительные цена и
+период и одинаковая валюта выплаты и цены. Это годовая оценка при сохранении
+размера купона и номинала, без налогов, комиссий и реинвестирования; она не
+является доходностью к погашению. Время котировки показывается отдельно.
+
+Эффективная доходность берётся из `marketdata_yields.EFFECTIVEYIELD` MOEX ISS,
+с проверкой точных SECID, ISIN и BOARDID. Показываются собственная цена
+расчёта, дата торгов и целевая дата (погашение, оферта или другая дата источника).
+Котировка MOEX может отличаться от котировки Т-Банка и поступать с задержкой.
+Доходность не рассчитывается из неполного календаря будущих выплат.
+
+Кредитный рейтинг выпуска читается по точному ISIN из публичного
+[реестра НКР](https://ratings.ru/ratings/issues/). Отображаются агентство,
+дата рейтингового действия, время получения реестра и ссылка на выпуск.
+Отзыв показывается явно; уровень риска Т-Банка и рейтинг эмитента не
+подставляются вместо рейтинга выпуска. Отсутствие записи в НКР не означает
+отсутствия рейтингов других агентств. Покрытие и альтернативы исследованы
+в [обзоре источников](../research/bond-credit-ratings.md).
+
+`NcrRatingsClient` разбирает HTML через Cheerio: штатного открытого API для
+этой таблицы не подтверждено. Общий публичный реестр кэшируется на шесть часов,
+незавершённые загрузки объединяются; повторные запросы после ошибки ограничены
+одной минутой. Изменение структуры таблицы, неоднозначные данные и ошибки
+загрузки означают недоступность источника, а не отсутствие рейтинга.
+
+График и таблица дневных цен сохраняют проценты от номинала и признак
+завершённости свечи. Исторические котировки не пересчитываются в деньги
+по сегодняшнему номиналу. Денежная средняя покупки не наносится на процентную
+шкалу. Периоды: месяц, полгода, год и вся известная история. Окна upstream
+не превышают 365 дней, одинаковые границы дедуплицируются. Если начало истории
+неизвестно, запрос «вся история» возвращает `BOND_HISTORY_START_UNAVAILABLE`.
+
+Позиция агрегирует только `BOND` с точным UID по доступным счетам, используя
+существующий Portfolio Snapshot и decimal-арифметику. Средняя покупка взвешена
+по количеству. Неполные или разновалютные суммы недоступны; для сочетания
+длинных и коротких позиций общая средняя и процент не синтезируются.
+Результат открытой позиции не включает выплаченные купоны и продажи и не
+называется доходностью к погашению. При отсутствии позиции блок скрыт.
+
+## Купоны и личные события
+
+Календарь охватывает пять прошлых лет и следующий год. Будущие купоны
+сортируются по дате выплаты, прошедшие и недатированные доступны отдельно.
+Показаны сумма на облигацию, номер, тип, длительность периода и дата реестра,
+если они известны. Неопределённый будущий купон не заменяется нулём.
+
+Личная оценка доступна только при положительных позициях, известной сумме,
+будущей выплате и известном ещё не прошедшем реестре. Она не подтверждает право
+на выплату и не учитывает налоги и будущие сделки. Время позиции и устаревание
+снимка показываются отдельно от календаря выпуска.
+
+История использует существующий запрос операций всех счетов с точным
+`instrumentUid`, включая прошлые годы. Фильтры: все, сделки, купоны, прочее.
+Смена фильтра сбрасывает пагинацию; истёкший курсор восстанавливается запросом
+первой страницы. Выплаты выпуска не подменяют личные зачисления.
+
+## Владельцы и восстановление
+
+`BondController` и `BondService` принадлежат существующему
+`TbankConnectionModule`. Все `/api/v1/bonds` endpoints требуют Bearer session
+и актуального подключения Т-Банка: поиск, разрешение тикера, карточка по UID,
+`quote`, `candles`, `position`, `coupons`, `metrics`. Wire contract принадлежит runtime
+OpenAPI, frontend snapshot и types генерируются из него.
+
+`BondBy`, `FindInstrument` и `GetBondCoupons` используют существующий sparse
+Instruments client, сохраняющий отсутствие полей. Рыночные RPC проходят
+общие TLS, очередь, rate limit, deadline и retry. Кэш успешных и совместных
+незавершённых запросов ограничен LRU и 30 секундами по пользователю,
+поколению подключения и параметрам. Ошибки не кэшируются; ошибки авторизации
+не подавляются при дополнительной загрузке данных поиска.
+Исходный ответ `BondBy` совместно используется поиском, карточкой, котировкой,
+графиком, купонами и сводкой показателей в пределах того же пользователя, поколения и TTL.
+Одновременная загрузка секций вызывает один `BondBy` на UID. Календарь
+и сводка совместно используют один запрос купонов; котировка переиспользуется
+при расчёте купонной доходности. MOEX и НКР загружаются только для открытого
+выпуска, независимо от поиска. Для 30 новых
+результатов поиск выполняет 32 RPC до повторных попыток: один `FindInstrument`,
+30 `BondBy` и один пакетный запрос цен. Общий ограничитель backend не заменяет
+квоты Т-Банка; при их исчерпании сохраняется `TBANK_UNAVAILABLE`.
+
+Разделы загружаются независимо, показывают skeleton и локальный retry.
+Ошибка фонового обновления сохраняет последние данные. Смена подключения
+сбрасывает subtree `/bonds` вместе с остальными финансовыми запросами;
+logout использует общий session reset. Общие график, позиция и личные события
+переиспользуются страницами акций и облигаций через `instrument-details`.