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,53 @@
+# Интеграция с MOEX ISS
+
+MOEX ISS дополняет данные T-Bank публичной информацией об облигациях.
+Backend получает её по HTTPS в JSON с `iss.moex.com`; запросы содержат
+идентификаторы выпуска, без token T-Bank и идентификатора брокерского счёта.
+MOEX не определяет доступ пользователя к инвестициям и не подтверждает
+личное получение выплаты.
+
+## Данные и сопоставление выпуска
+
+| Данные MOEX | Использование в WealthLedger |
+| --- | --- |
+| Эффективная доходность, цена её расчёта, целевая дата и время торгов | Рыночный показатель на [странице облигации](../domains/instruments/bonds.md#содержание) |
+| Купоны и оферты из календаря `bondization` | [Будущие события](../domains/income/upcoming-events.md) по текущим позициям |
+| Дата погашения, номинал и валюта из описания выпуска | Прогноз полного погашения в том же разделе событий |
+
+Для доходности backend сопоставляет SECID, ISIN и BOARDID с идентификаторами
+облигации T-Bank. Совпадения названия недостаточно. Значение сопровождается
+собственной ценой расчёта и временем MOEX; оно может отличаться от котировки
+T-Bank и не является личной доходностью инвестора.
+
+Для календаря используется SECID, разрешённый из тикера позиции или её
+метаданных. Backend читает страницы календаря, затем применяет выбранный
+период и текущее количество бумаг. Смысл прогнозных сумм и ограничения
+оферты определяет [область будущих выплат](../domains/income/upcoming-events.md).
+Купонный календарь непосредственно на странице облигации получает данные
+через T-Bank `GetBondCoupons`; эти два пользовательских представления
+не следует считать одним источником календаря.
+
+## Недоступность и свежесть
+
+HTTP-запрос ограничен таймаутом. Сеть, неуспешный HTTP-ответ, кроме `404`,
+или некорректная структура ответа приводят к `MOEX_UNAVAILABLE`.
+`404` и отсутствие запрошенного блока означают отсутствие доступных данных;
+для доходности неподходящий выпуск или неполные обязательные значения
+также дают отсутствие показателя. Это отличается от отказа источника.
+
+Последствие ошибки зависит от потребителя:
+
+- Метрики облигации отмечают недоступность доходности, сохраняя доступные
+  показатели других источников.
+- Расчёт будущих событий завершается ошибкой `503`, если необходимый календарь
+  недоступен; частичный список не выдаётся за полный.
+
+Клиент MOEX не использует очередь, повторы и лимитер gRPC T-Bank и не хранит
+собственный кэш. Повторное использование собранных метрик принадлежит
+[странице облигации](../domains/instruments/bonds.md#получение-данных-и-восстановление).
+Наличие успешного HTTP-ответа не гарантирует котировку без задержки.
+
+Условия обработки источника в прогнозе закреплены в
+[спецификации будущих событий](../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-upcoming-events-use-complete-source-results).
+Точный механизм транспорта, разбора и сопоставления реализован в
+[клиенте MOEX](../../backend/src/tbank/moex.client.ts).