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 реализации.

8.2 KiB Raw Blame History Unescape Escape