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
@@ -18,4 +18,4 @@ flowchart LR

 ## Consequences

-Контроль секретов, повторов и лимитов централизован на сервере. Boundary реализована и используется поставленными сценариями; текущее API, resilience и ограничения описаны в [Подключении T-Bank](../features/tbank-connection.md).
+Контроль секретов, повторов и лимитов централизован на сервере. Boundary реализована и используется поставленными сценариями; текущее API, resilience и ограничения описаны в [Подключении T-Bank](../integrations/tbank.md).
@@ -12,4 +12,4 @@

 ## Consequences

-Ключ обязателен только в server environment и не логируется. AES-256-GCM storage и per-user connection реализованы; current-state contract и ограничение отсутствующей ротации ключа описаны в [Подключении T-Bank](../features/tbank-connection.md).
+Ключ обязателен только в server environment и не логируется. AES-256-GCM storage и per-user connection реализованы; current-state contract и ограничение отсутствующей ротации ключа описаны в [Подключении T-Bank](../integrations/tbank.md).
@@ -12,4 +12,4 @@ Access token живёт 15 минут только в памяти frontend. Rot

 ## Consequences

-Перезагрузка страницы восстанавливает access token через cookie-сессию. Rotating sessions, logout и bounded revocation model реализованы; access token остаётся действительным не более 15 минут без database lookup на каждый запрос. Текущее поведение описано в [Аутентификации](../features/authentication.md).
+Перезагрузка страницы восстанавливает access token через cookie-сессию. Rotating sessions, logout и bounded revocation model реализованы; access token остаётся действительным не более 15 минут без database lookup на каждый запрос. Текущее поведение описано в [Аутентификации](../domains/authentication/overview.md).
@@ -12,4 +12,4 @@ React Query запрашивает серверные данные при отк

 ## Consequences

-Пользователь может видеть cached snapshot до успешного background response, а ошибка обновления не превращает известные данные в пустой экран. Конкретные freshness intervals и UI-поведение описаны в [Brokerage Accounts](../features/brokerage-accounts.md) и [Portfolio](../features/portfolio-view.md). Live updates и focus-triggered refetch требуют отдельной продуктовой необходимости.
+Пользователь может видеть cached snapshot до успешного background response, а ошибка обновления не превращает известные данные в пустой экран. Конкретные freshness intervals и UI-поведение описаны в [Brokerage Accounts](../domains/accounts/overview.md) и [Portfolio](../domains/portfolio/overview.md). Live updates и focus-triggered refetch требуют отдельной продуктовой необходимости.
@@ -0,0 +1,83 @@
+# 013. НКР как первый источник кредитных рейтингов облигаций
+
+**Статус:** принятое и реализованное решение; ретроспективная запись.
+
+## Контекст
+
+Странице облигации нужен рейтинг агентства для конкретного выпуска по ISIN,
+без требования к пользователю иметь подписку на информационную систему.
+Уровень риска брокера и рейтинг эмитента не заменяют рейтинг выпуска.
+
+Исследование источников от 10 сентября 2026 года выявило практически
+пригодный первый источник — публичный реестр эмиссий НКР. В проверенном HTML
+одна таблица содержала ISIN, рейтинг или отзыв, дату действия и ссылку
+на выпуск. Дополнительный запрос каждой карточки для этих данных не требовался.
+Это давало частичное покрытие одного агентства без покупки доступа,
+но не рейтинг любой российской облигации и не стабильный контракт API.
+
+Основания выбора сохранены из исследования, а применение решения подтверждено
+backend-коммитом `235c179` (`feat: add bond details, yields and credit ratings`).
+Исходное исследование содержало также рекомендации; эта запись фиксирует
+выбранный подход, не объявляя все рекомендации реализованными.
+
+## Решение
+
+Использовать публичный [реестр выпусков НКР](https://ratings.ru/ratings/issues/)
+как первый источник рейтинга облигации. Загружать общий реестр на backend
+и сопоставлять выпуск по точному ISIN, без угадывания по названию или тикеру.
+Объединять одновременные загрузки и повторно использовать публичный справочник
+между запросами разных выпусков.
+
+Сохранять агентство, исходное обозначение рейтинга, дату действия, ссылку
+на выпуск и время получения данных. Различать действующий рейтинг, отзыв,
+отсутствие записи в реестре и недоступность источника. Сбой рейтингового
+источника не должен скрывать доступные цену, купоны и позицию.
+
+Рейтинг эмитента, прогноз из постороннего текста и уровень риска T-Bank
+не подставляются вместо оценки выпуска. Исходные шкалы агентств сохраняют
+своё происхождение: `AAA.ru`, `ruAAA` и `AAA(RU)` не превращаются в безымянное `AAA`.
+Различие оценок эмитента и обязательства объясняет
+[Банк России](https://www.cbr.ru/finm_infrastructure/ra/); опубликованное
+[сопоставление шкал](https://www.cbr.ru/press/pr/?file=638557747357168625INFR.htm)
+не отменяет указания агентства.
+
+## Рассмотренные источники
+
+Таблица сохраняет результаты исследования на указанную дату, а не утверждает
+текущую доступность внешних сайтов или окончательный отказ от других агентств.
+
+| Источник | Что ограничивало первый вариант интеграции |
+| --- | --- |
+| [Эксперт РА](https://raexpert.ru/ratings/debt_inst/) | ISIN находился в отдельных карточках, список использовал серверную пагинацию. Официальная [структурированная выгрузка](https://raexpert.ru/all-services/rating-export/) предоставлялась по подписке; требовались дополнительные запросы или отдельный доступ |
+| [MOEX ISS CCI](https://iss.moex.com/iss/reference/781) и [поиск выпуска](https://iss.moex.com/iss/reference/867) | Интерфейсы документированы, но проверенный анонимный запрос списка вернул пустое тело; пригодный ответ и условия доступа не были подтверждены |
+| [АКРА](https://www.acra-ratings.ru/ratings/) | В проверенной среде возвращался HTTP 403; доступный источник не был подтверждён |
+| [НРА](https://www.ra-national.ru/ratings/) | В публичном списке не был найден точный ISIN; карточки и условия требовали отдельной проверки |
+| [Cbonds API](https://cbonds.ru/api/) | Структурированный продукт с индивидуальным доступом; публичное демо не подтверждало бесплатную полную базу |
+| [Интерфакс / RusBonds](https://www.rusbonds.ru/) | Проверенный запрос возвращал JavaScript challenge; рабочий анонимный источник и условия API не были установлены |
+
+HTTP 403, challenge и пустой ответ характеризуют конкретную проверку,
+а не отсутствие данных у провайдера. Они не являются основаниями обходить
+ограничения или обещать недокументированный доступ.
+
+## Последствия и ограничения
+
+Первый источник даёт рейтинг только для выпусков, представленных в реестре
+НКР. Отсутствие записи не означает отсутствия рейтингов других агентств.
+Дата рейтингового действия не равна времени загрузки; давняя дата сама
+по себе не означает отзыв.
+
+Публичный HTML может измениться. В этом случае интеграция сообщает
+недоступность источника, а не успешное отсутствие рейтинга. Публичная страница
+не даёт гарантии API, SLA или полного покрытия рынка.
+
+Исследование не установило свободную лицензию на массовое переиспользование.
+В условиях НКР и Эксперт РА были указаны ограничения распространения информации
+без предварительного согласия и ссылки на источник. Техническая доступность
+страницы не является разрешением публично перераздавать базу или коммерчески
+предоставлять данные. При таком изменении продукта условия правообладателя
+нужно проверить отдельно.
+
+Текущее получение, кэширование и обработка отказов описаны в
+[интеграции НКР](../integrations/nkr.md), пользовательская интерпретация —
+на [странице облигаций](../domains/instruments/bonds.md). Расширение покрытия
+или переход к другому способу доступа требует отдельного подтверждённого решения.
@@ -1,6 +1,12 @@
 # ADR

-Здесь фиксируются долгоживущие технические решения. Новый ADR описывает контекст, решение и последствия; заменяемое решение получает новый ADR со ссылкой на прежний.
+Единый журнал значимых решений WealthLedger. Записи сохраняют исходный
+контекст, принятое решение и последствия, включая решения, впоследствии
+заменённые. Baseline ADR читается как история выбора, а не как полный
+справочник текущей реализации.
+
+Устройство системы раскрыто в [архитектуре](../architecture/README.md),
+правила изменения журнала — в [CONTRIBUTING](../CONTRIBUTING.md).

 - [001 — Prisma и SQLite для локального MVP](001-prisma-sqlite-local-mvp.md)
 - [002 — Nest-generated OpenAPI contract](002-nest-generated-openapi-contract.md)
@@ -14,3 +20,4 @@
 - [010 — Native OpenSpec SDD и local orchestration](010-native-openspec-sdd-and-local-orchestration.md) — исторический; частично заменён ADR 011, обязательность SDD отменена ADR 012.
 - [011 — Native OpenSpec lifecycle и repository gates](011-native-openspec-lifecycle-with-repository-gates.md) — заменён ADR 012 в части обязательного lifecycle.
 - [012 — Прямая разработка с контекстом по задаче](012-task-driven-development-with-scoped-context.md)
+- [013 — НКР как первый источник кредитных рейтингов облигаций](013-nkr-bond-credit-ratings.md)