65 lines
8.2 KiB
Markdown
65 lines
8.2 KiB
Markdown
# 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 реализации.
|