# Интеграция с 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-ответа не гарантирует котировку без задержки.

## Индексы

Для [результата инвестирования](../domains/portfolio/investment-performance.md)
backend читает дневные закрытия MCFTRR (полная доходность после налогов) и
IMOEX (ценовой, справка) из
`/iss/history/engines/stock/markets/index/securities/{SECID}.json` с
`history.columns=TRADEDATE,CLOSE`, постранично по `history.cursor`.
Любая некорректная страница считается сбоем: частичная история не
сохраняется.

Закрытия и подтверждённый диапазон покрытия хранятся локально в SQLite
(исключение из ADR 019, см. [ADR 023](../adr/023-investment-performance-vs-index.md)).
Догрузка выполняется при чтении результата одной одновременной загрузкой на
индекс: расширение диапазона назад — сразу, проверка ещё не опубликованного
закрытия и повтор после сбоя — не чаще раза в час. Недоступность
MOEX не возвращается как HTTP-ошибка: при достаточной сохранённой истории
результат считается по ней, иначе сравнение помечается
`INDEX_HISTORY_UNAVAILABLE`. События лога —
`integration.moex.index_history.succeeded` и `.failed`, без данных
пользователя.

ISS бесплатно отдаёт данные для ознакомления; приложение личное и не
распространяет их, источник указан в пояснении «Как считали».

## Ссылки

Условия обработки источника в прогнозе закреплены в
[спецификации будущих событий](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-upcoming-events-use-complete-source-results).
Точный механизм транспорта, разбора и сопоставления реализован в
[клиенте MOEX](https://git.personal.ksv741.ru/WealthLedger/backend/src/commit/016782657acfd35ff3fd755462007938fac35156/src/integrations/moex/moex.client.ts).