spec: plan investment performance vs Moscow Exchange index (WealthLedger/main#54) (#85)

2026-11-08 16:30:32 +03:00
parent 1b20067ca7
commit 892800301b
13 changed files with 1641 additions and 0 deletions
@@ -0,0 +1,64 @@
+# 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 реализации.