# Docs Impact

Issue: WealthLedger/main#54

## Summary

Обновление долговременной документации нужно. Появляется новое понятие
«Результат инвестирования» с методикой. Из-за него снимается общий запрет
на термин «доходность», и это архитектурно значимое решение: оно требует
ADR. Ещё добавляются новый источник данных (индексы MOEX), сохраняемая
публичная история и новые маршруты HTTP API. Существующие формулировки
«не доходность» для других понятий сохраняются, но получают ссылку на новое
понятие.

## Documentation Changes

| Action | Path | Content | Source | Reason |
| --- | --- | --- | --- | --- |
| create | `docs/adr/023-investment-performance-vs-index.md` | Решение: XIRR как «доходность»; сравнение с теми же потоками в MCFTRR (PME по Long–Nickels), IMOEX только для справки; только RUB; «за N дн.» при истории меньше года; отклонены простой ROI, TWR без истории стоимости, ценовой IMOEX как ориентир и конвертация валют; сохранение публичных закрытий индексов как исключение из ADR 019; оговорка о налоговых ставках MCFTRR и условиях ISS | proposal, system-analysis «Расчёт», «Индексы MOEX», design Decisions backend 3, 5 | Архитектурно значимое решение о методике и хранимых данных |
| create | `docs/domains/portfolio/investment-performance.md` | Что показывает вкладка «Результат», внешние и внутренние потоки, смысл прибыли, доходности и «тех же денег в индексе», опережение и отставание, правило меньше года, «Все счета» и переводы между своими счетами, причины недоступности и неполноты, отсутствие линии прошлой стоимости, ссылки на спецификацию и HTTP API | specs `investment-performance`, system-analysis «Маппинг операций», «Переводы», «Причины недоступности» | Новая долговременная предметная область |
| update | `docs/glossary.md` | Новые термины: «Результат инвестирования», «Доходность (XIRR)», «Те же деньги в индексе Мосбиржи», «Опережение рынка», «Внешний денежный поток», каждый с _Не использовать_. У «Точки истории стоимости портфеля» и «Realized Income Analytics» вместо запрета «доходность» — уточнение «не является результатом инвестирования» со ссылкой | specs, ADR 023 | Терминология и снятие конфликтующего запрета |
| update | `docs/overview.md` | Вкладка «Результат» в списке возможностей; абзац «что есть сейчас / что исполнено…» дополнить вопросом «как сработали вложенные деньги». Оговорка, что выплаты сами по себе не равны доходности, сохраняется | proposal | Обзор продукта |
| update | `docs/domains/portfolio/overview.md` | Строки 3–6 и 31: снимок по-прежнему не является расчётом полной доходности; полная доходность считается в «Результате инвестирования» (ссылка) | specs | Устранить противоречие |
| update | `docs/domains/portfolio/all-accounts.md` | «Результат» в режиме «Все счета»: исключение счетов с пометкой о неполноте, переводы между включёнными счетами | specs | Поведение режима `all` |
| update | `docs/domains/portfolio/data-reference.md` | Поля результата: доли (`Rate`), `basis`, `UnavailableReason` и их отображение; деньги в RUB | system-analysis «Contracts» | Справочник смысла данных |
| update | `docs/domains/income/overview.md` | Строка 97: вместо «не рассчитывает доходность» — «не рассчитывает доходность; её показывает Результат инвестирования» (ссылка) | specs | Навигация и отсутствие противоречия |
| update | `docs/integrations/moex.md` | Раздел «Индексы»: MCFTRR и IMOEX, маршрут ISS history, пагинация, догрузка при чтении не чаще раза в час, локальное хранение закрытий, поведение при недоступности, события лога, условия использования данных ISS | system-analysis «Индексы MOEX», design 5 | Новый поток интеграции |
| update | `docs/architecture/context.md` | Строка 34: MOEX поставляет также дневные закрытия индексов Мосбиржи | system-analysis | Контекст системы |
| update | `docs/architecture/http-api.md` | Маршруты `GET /brokerage-accounts/{accountId\|all}/performance`: смысл `data: null`, `meta.unavailable`, `completeness`; ссылка на backend-generated OpenAPI, без копии схемы | contract | Описание HTTP API |
| update | `docs/adr/README.md` | Строка индекса ADR 023 | ADR 023 | Навигация |

## Diagrams

Отдельная диаграмма не переносится. Последовательности чтения и догрузки
остаются в архивированном change. В `docs/integrations/moex.md` достаточно
текстового описания догрузки.

## ADR

- **Создать** ADR 023 (см. таблицу), статус Accepted. Ссылки: Issue
  WealthLedger/main#54 и этот change.
- ADR 019 не переписывается: ADR 023 явно дополняет его исключением для
  публичной истории индексов, по образцу ADR 022.

## Non-Changes

- `docs/domains/instruments/bonds.md`, `stocks.md`: «открытый результат не
  является доходностью к погашению» — другое понятие, текст не меняется.
- `docs/architecture/containers.md`: состав контейнеров не меняется (MOEX
  уже есть).
- `docs/architecture/deployment.md`: конфигурация и сеть не меняются.
- `docs/design/`: новых долговременных визуальных принципов нет; вкладка
  использует существующие паттерны.
- `docs/domains/operations/`: журнал операций не меняется; маппинг типов на
  потоки описывается в новой странице результата.

## Verification

- После `[docs]` tasks выполнить `npm run verify` в `docs/` (markdownlint
  с проверкой относительных ссылок и `git diff --check`).
- Термин «доходность» в `docs/` встречается только в значении «Результат
  инвестирования» или в явных оговорках «не является»:
  `grep -rn "доходност" docs/`.
- Ссылки на specs и OpenAPI ведут на commit после merge реализации.