docs(portfolio): document investment performance vs index (WealthLedger/main#54)

2026-11-08 14:21:08 +03:00
parent e1981a24bf
commit 3c9efcba03
11 changed files with 187 additions and 16 deletions
@@ -59,6 +59,12 @@ Backend публикует статические маршруты под `/api/
  состав счетов влияет только на фактические выплаты выбранного периода.
 - Будущие события сортируются по дате и сохраняют отдельную строку каждого счёта.
  Прогноз не включается в реализованные доходы.
+- [Результат инвестирования](investment-performance.md) складывает потоки и
+  стоимость только рублёвых счетов с полной историей. Счёт с причиной
+  недоступности исключается, сводка помечается неполной. Похожие на перевод
+  между своими счетами операции без подтверждённой связи исключают оба счёта
+  (`UNCONFIRMED_TRANSFER`). Если оценки оставшихся счетов сделаны в разные
+  московские дни, сводка недоступна: стоимости разных дат не складываются.

 ## Полнота, свежесть и доступ

@@ -46,6 +46,18 @@
 отдельного счёта не создают валютные карточки. Если `totalsByCurrency` пуст,
 но позиции или деньги присутствуют, это не пустой портфель.

+## Результат инвестирования
+
+| Поле | Смысл | Ограничение |
+| --- | --- | --- |
+| `netInvested`, `currentValue`, `profit` | Чистые внешние потоки, сумма RUB-оценок, их разность | Только RUB, копейки |
+| `return.value` | Доля XIRR (`0.151` = 15,1 %) | `null` с `unavailableReason`; при `basis = period` — за весь период |
+| `benchmark`, `reference` | Те же потоки в MCFTRR и IMOEX | IMOEX только справка |
+| `outperformance` | Разница долей и стоимостей с MCFTRR | `null`, если любая сторона недоступна |
+| `series` | Точки торговых дней MCFTRR | Пусто без истории индекса |
+
+Подробнее — [результат инвестирования](investment-performance.md).
+
 ## Идентификация и оформление инструмента

 UID определяет конкретный инструмент брокера и используется для перехода
@@ -0,0 +1,68 @@
+# Результат инвестирования
+
+Вкладка «Результат» на странице брокерского счёта и в режиме
+[«Все счета»](all-accounts.md) отвечает на два вопроса:
+
+- сколько заработали вложенные деньги;
+- обогнал ли пользователь рынок.
+
+Результат считается за всё время истории счёта, только в рублях. Решение и
+отклонённые альтернативы описаны в
+[ADR 023](../../adr/023-investment-performance-vs-index.md).
+
+## Показатели
+
+| Показатель | Смысл |
+| --- | --- |
+| Вложено (нетто) | Сумма пополнений минус сумма выводов рублей |
+| Прибыль | Текущая стоимость портфеля минус чистые вложения |
+| Доходность | Ставка XIRR с учётом сумм и дат пополнений и выводов |
+| Те же деньги в индексе Мосбиржи | Стоимость и доходность тех же пополнений и выводов, вложенных в индекс полной доходности MCFTRR (с дивидендами после налогов) |
+| Опережение или отставание рынка | Разница доходностей в процентных пунктах и разница стоимостей в рублях |
+
+Ценовой индекс IMOEX не учитывает дивиденды. Он показан на графике только
+для справки и в сравнении не участвует.
+
+Период начинается с первого пополнения, а не с открытия счёта. Если деньги
+вложены меньше 365 дней, проценты показаны за фактическое число дней и не
+пересчитываются в годовые.
+
+## Какие операции считаются потоками
+
+Внешние потоки — только пополнения и выводы рублей (типы T-Bank `INPUT`,
+`INPUT_ACQUIRING`, `INPUT_SWIFT`, `INP_MULTI` и соответствующие `OUTPUT`).
+Сделки, купоны, дивиденды, погашения, налоги и комиссии уже отражены в
+текущей стоимости и потоками не являются. Учитываются только операции до
+момента последней полной оценки портфеля.
+
+## Когда результата нет
+
+Число не подменяется нулём: вместо него показывается причина.
+
+| Причина | Когда возникает |
+| --- | --- |
+| `HISTORY_START_UNKNOWN` | Неизвестна дата открытия счёта |
+| `OPERATIONS_HISTORY_INCOMPLETE` | История операций не получена полностью до момента оценки |
+| `PORTFOLIO_VALUATION_INCOMPLETE` | Нет полной оценки портфеля |
+| `NON_RUB_ACTIVITY` | Есть потоки или остатки не в рублях |
+| `UNVALUED_SECURITIES_TRANSFER` | Бумаги введены или выведены без денежной оценки |
+| `UNCONFIRMED_TRANSFER` | В «Все счета» есть похожие на перевод между своими счетами операции, связь которых источник не подтверждает |
+| `ACCOUNT_VALUATION_DATES_DIFFER` | В «Все счета» последние оценки счетов сделаны в разные московские дни |
+| `NO_SOLUTION` | Уравнение доходности не имеет решения; прибыль остаётся |
+| `AMBIGUOUS_RETURN` | Потоки меняют знак больше одного раза, и единственность ставки не доказана; прибыль остаётся |
+| `INDEX_HISTORY_UNAVAILABLE` | Нет истории индекса за период; прибыль и доходность остаются, сравнения нет |
+
+В «Все счета» счёт с причиной исключается, а результат помечается
+неполным со списком исключённых счетов. Если считать не по чему, результат
+недоступен целиком.
+
+## График
+
+На графике показаны ступенчатая линия чистых вложений, стоимость тех же
+денег в индексе по закрытиям торговых дней, справочная линия индекса без
+дивидендов и отметка текущей стоимости портфеля на конец периода. Линии
+прошлой стоимости портфеля нет: такая история пока не хранится.
+
+Нормативное поведение задаёт change
+`2026-11-07-investment-performance-vs-index` в репозитории specs, форму
+ответа — [HTTP API](../../architecture/http-api.md#investment-performance).
@@ -29,6 +29,8 @@ Backend получает данные через серверную
 самостоятельно: его ошибка или отсутствие данных не скрывает основной
 портфель. Полученные выплаты и прогноз не добавляются к текущей стоимости
 повторно и не превращают результат открытой позиции в полную доходность.
+Полную доходность с учётом пополнений и выводов показывает вкладка
+[«Результат»](investment-performance.md).

 ## Как читать экран