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

openspec/changes/2026-11-07-investment-performance-vs-index/proposal.md

@@ -0,0 +1,121 @@
+# Proposal
+
+Issue: WealthLedger/main#54
+
+## Why
+
+Пользователь хочет знать, насколько хорошо у него получается инвестировать.
+Конкретно: какой процент приносят вложенные деньги и обгоняет ли он индекс
+Московской биржи. Сейчас приложение показывает только нереализованный результат
+открытых позиций относительно средней цены покупки. Этот показатель не учитывает:
+
+- когда и сколько денег вносилось и выводилось;
+- результат закрытых позиций;
+- купоны, дивиденды, налоги и комиссии.
+
+Поэтому из него нельзя получить ни честный процент годовых, ни сравнение с
+рынком. Текущие принципы продукта прямо запрещают называть показатели
+«доходностью», потому что честного расчёта не было. Это изменение вводит
+такой расчёт с явной методикой.
+
+## What Changes
+
+- Для брокерского счёта и режима «Все счета» появляется результат
+  инвестирования за всё время. В него входят:
+  - **прибыль** в рублях: текущая стоимость минус чистые внешние пополнения;
+  - **доходность** с учётом сумм и дат пополнений и выводов (money-weighted, XIRR).
+- Появляется сравнение с альтернативой «те же деньги в индексе Мосбиржи». Те же
+  пополнения и выводы в те же даты применяются к индексу Мосбиржи с учётом
+  дивидендов после налогов. Показываются его стоимость, его доходность и
+  **опережение или отставание** пользователя в процентных пунктах и рублях.
+- Привычный ценовой индекс Мосбиржи (без дивидендов) показывается только для
+  справки и в сравнении не участвует.
+- Пока история короче года, проценты показываются за фактический период, без
+  пересчёта в годовые.
+- Когда честный расчёт невозможен, результат помечается как «недоступно» или
+  «неполный» с конкретной причиной, а не показывается нулём или
+  приблизительным числом.
+- На странице счёта появляется вкладка «Результат»: ключевые показатели,
+  график «вложено / те же деньги в индексе / справочный индекс / текущая
+  стоимость» и пояснение «Как считали». Утверждённый вид — вариант A прототипа
+  `prototype/index.html`.
+- Термин «доходность» разрешается для этой метрики с точным определением.
+  Остальные запреты на этот термин сохраняются.
+
+## Scope
+
+### In Scope
+
+- Результат за всё время для одного брокерского счёта и для «Все счета».
+- Только рублёвые счета и потоки. В «Все счета» счёт, который нельзя посчитать,
+  исключается с явной пометкой о неполноте результата. Если не осталось ни
+  одного счёта, который можно посчитать, результат «недоступен».
+- Переводы денег и бумаг между счетами, включёнными в «Все счета», не считаются
+  внешними пополнениями и выводами.
+- Получение и локальное хранение дневной истории двух индексов Мосбиржи: с
+  дивидендами после налогов и ценового. Недоступность источника не мешает
+  остальным разделам счёта.
+- Нормативное поведение, публичный контракт для интерфейса, вкладка
+  «Результат», методика и глоссарий в документации.
+
+### Out of Scope / Non-Goals
+
+- Доходность, взвешенная по времени (TWR), периоды «с начала года», «за год» и
+  произвольные, а также восстановление прошлой стоимости портфеля. Линия
+  стоимости портфеля в прошлом на графике не появляется.
+- Валютная конвертация и счета с потоками или позициями не в рублях.
+- Выбор другого ориентира (облигации, инфляция, депозит, составной индекс).
+- Доходность отдельных позиций, налоговый расчёт, прогнозы, риск-метрики,
+  доказательство «альфы».
+- Таблица пополнений и выводов с расчётом паёв индекса.
+- Изменение существующих показателей «нереализованный результат» и «Доход».
+
+## Capabilities
+
+### New Capabilities
+
+- `specs/portfolio/investment-performance/spec.md`: результат инвестирования
+  счёта и «Все счета», сравнение с индексом Мосбиржи, состояния неполноты и
+  недоступности, вкладка «Результат».
+- `specs/instruments/market-index-history/spec.md`: получение и хранение
+  дневной истории индексов Мосбиржи и поведение при недоступности источника.
+
+### Modified Capabilities
+
+Нет. Существующие требования к портфелю, доходу и истории оценок не меняются.
+
+## Impact
+
+- **Пользователь:** получает ответ на вопросы «сколько % годовых» и «обгоняю ли
+  я рынок» на странице счёта.
+- **Домены:** портфель (новая метрика), операции брокерского счёта (источник
+  внешних денежных потоков), инструменты и рыночные данные (история индексов).
+- **Внешние системы:** новая зависимость от публичных исторических данных
+  Московской биржи (индексы) и от полноты истории операций T-Bank.
+- **Затрагиваемые области:** behavioral specs, backend (расчёт, данные индексов,
+  публичный контракт), frontend (вкладка), docs (ADR о методике и термине,
+  глоссарий, домены, интеграция с биржей).
+
+## Success Criteria
+
+- Для рублёвого счёта с известным началом истории пользователь видит прибыль,
+  доходность, результат «тех же денег в индексе» и опережение. Значения
+  совпадают с независимым расчётом XIRR на тех же потоках с точностью до 0,1 п.п.
+- При истории короче года ни один процент не подписан как «годовых».
+- Ни в одном из случаев «начало истории неизвестно», «операции не в рублях»,
+  «ввод бумаг без денежной оценки», «расчёт не сходится», «история индекса
+  недоступна» не показывается число, выдаваемое за результат. Причина видна
+  пользователю.
+- Отказ источника индексов не ломает другие вкладки счёта.
+
+## Assumptions / Dependencies
+
+- История операций T-Bank с даты открытия счёта содержит все пополнения и
+  выводы рублей. Это проверяется на реальных данных первым запуском.
+- Индекс с дивидендами после налогов рассчитан по налоговым ставкам для
+  организаций, а не по НДФЛ физлица. Это ориентир альтернативы, а не точная
+  модель налогов пользователя. Это фиксируется в методике.
+- Публичные данные Мосбиржи используются в личном локальном приложении
+  с указанием источника. Публичное распространение не планируется.
+- Текущая стоимость портфеля берётся из последней полной оценки. Если
+  оценка неполная, результат недоступен.