# 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 с даты открытия счёта содержит все пополнения и
  выводы рублей. Это проверяется на реальных данных первым запуском.
- Индекс с дивидендами после налогов рассчитан по налоговым ставкам для
  организаций, а не по НДФЛ физлица. Это ориентир альтернативы, а не точная
  модель налогов пользователя. Это фиксируется в методике.
- Публичные данные Мосбиржи используются в личном локальном приложении
  с указанием источника. Публичное распространение не планируется.
- Текущая стоимость портфеля берётся из последней полной оценки. Если
  оценка неполная, результат недоступен.