docs: reorganize system knowledge by domain

2026-09-12 14:45:42 +03:00
parent 3a99af1a6e
commit f20c3f47bc
83 changed files with 2229 additions and 7335 deletions
@@ -0,0 +1,45 @@
+# Интеграция с реестром НКР
+
+НКР предоставляет кредитный рейтинг конкретного выпуска облигаций.
+Backend загружает общий публичный [реестр выпусков](https://ratings.ru/ratings/issues/)
+по HTTPS и ищет запись локально по точному ISIN. Ни token T-Bank,
+ни сведения о пользователе или его счёте в запрос реестра не передаются.
+
+## Значение и выбор записи
+
+Рейтинг загружается для показателей открытой [страницы облигации](../domains/instruments/bonds.md#содержание),
+а не для каждого результата поиска инструментов. Выбирается последнее
+рейтинговое действие для ISIN. Отозванный рейтинг сохраняется как отдельное
+состояние без действующего значения; противоречивые записи с одной датой
+не разрешаются произвольным выбором.
+
+Результат содержит агентство, значение или отзыв, дату рейтингового действия,
+время получения реестра и ссылку на выпуск. Дата действия и время загрузки
+имеют разный смысл: обращение к кэшу не делает сам рейтинг новее.
+
+Отсутствие записи в успешно прочитанном реестре означает, что этот источник
+не дал рейтинга выпуска. Оно не доказывает отсутствия рейтингов других
+агентств. Рейтинг эмитента и уровень риска T-Bank не подставляются вместо
+рейтинга выпуска. Причины выбора, альтернативы и ограничения распространения
+данных сохранены в [ADR 013](../adr/013-nkr-bond-credit-ratings.md).
+
+## Загрузка, кэш и отказ источника
+
+Интеграция читает публичную HTML-таблицу. Штатный открытый API для этой таблицы
+не подтверждён; текущий механизм зависит от её структуры, формата рейтинга,
+ISIN, даты и ссылки на выпуск. Изменение таблицы, противоречивые записи,
+пустой распознанный реестр или ошибка загрузки означают `NCR_UNAVAILABLE`,
+а не успешный ответ «рейтинга нет».
+
+Общий реестр сохраняется в памяти экземпляра backend на шесть часов.
+Одновременные обращения к разным выпускам используют одну незавершённую загрузку.
+После ошибки новая загрузка ограничена минутным интервалом; внутри одного
+HTTP-запроса повторных попыток нет. Обновление запускается следующим обращением
+после истечения кэша, без фонового задания. Точный механизм и сроки принадлежат
+[клиенту НКР](../../backend/src/tbank/ncr-ratings.client.ts).
+
+При отказе реестра показатели облигации отмечают недоступность рейтинга,
+сохраняя остальные доступные показатели. Готовый ответ метрик имеет
+[собственный кэш](../domains/instruments/bonds.md#получение-данных-и-восстановление),
+отдельный от общего публичного реестра. Такая обработка не обещает непрерывной
+доступности источника или наличия рейтинга у каждого выпуска.