docs(portfolio): document investment performance vs index (WealthLedger/main#54)

2026-11-08 14:21:08 +03:00
parent e1981a24bf
commit 3c9efcba03
11 changed files with 187 additions and 16 deletions
@@ -1,6 +1,7 @@
 # Интеграция с MOEX ISS

-MOEX ISS дополняет данные T-Bank публичной информацией об облигациях.
+MOEX ISS дополняет данные T-Bank публичной информацией об облигациях и
+дневными закрытиями индексов Мосбиржи.
 Backend получает её по HTTPS в JSON с `iss.moex.com`; запросы содержат
 идентификаторы выпуска, без token T-Bank и идентификатора брокерского счёта.
 MOEX не определяет доступ пользователя к инвестициям и не подтверждает
@@ -47,6 +48,32 @@ HTTP-запрос ограничен таймаутом. Сеть, неуспе
 [странице облигации](../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).
 Точный механизм транспорта, разбора и сопоставления реализован в