docs: reorganize system knowledge by domain

2026-09-12 14:45:42 +03:00
parent 3a99af1a6e
commit f20c3f47bc
83 changed files with 2229 additions and 7335 deletions
@@ -0,0 +1,109 @@
+# Будущие события
+
+Будущие события помогают увидеть известные выплаты и даты по текущим
+позициям счёта. Обзор `/accounts/:accountId` показывает до пяти ближайших
+событий, полный список находится на `/accounts/:accountId/events`.
+[Общий режим](../portfolio/all-accounts.md) сохраняет отдельные строки
+событий каждого доступного счёта. Ошибка или пустой результат превью
+не заменяет основной портфель.
+
+Прогноз отличается от [полученного дохода](overview.md): он основан
+на текущем количестве бумаг и опубликованных условиях, не подтверждает
+будущее зачисление и не входит в итоги исполненных выплат.
+
+## Смысл события
+
+| Событие | Источник и дата | Денежная оценка |
+| --- | --- | --- |
+| Купон | Календарь облигации из MOEX `bondization` | Известная выплата на бумагу × текущая позиция |
+| Дивиденд | T-Bank `GetDividends`, дата реестра `record_date` | `dividend_net` на бумагу × текущая позиция |
+| Полное погашение | MOEX `bondization` | Известные условия погашения × текущая позиция |
+| Оферта | MOEX `bondization` | Сумма не синтезируется, `projectedAmount: null` |
+
+Для дивиденда `dateKind: registry` явно означает дату закрытия реестра,
+а не гарантированную дату поступления денег. Отменённые выплаты `Cancelled`
+не включаются. Будущие частичные погашения и амортизация не синтезируются
+без надёжного расписания. Неизвестные или неприменимые денежные условия
+остаются `null`, а не заменяются нулём.
+
+Суммы рассчитаны по количеству на `calculatedAt`. Они не учитывают будущие
+сделки, право владения на дату реестра и персональный налоговый расчёт.
+Есть неразрешённое ограничение интерпретации:
+[основная спецификация](../../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-forecasts-preserve-event-meaning-and-uncertainty)
+и текущая подсказка экрана называют прогноз суммой «до налогов», но для
+дивиденда реализация только умножает `dividend_net` на количество.
+Налоговый смысл этого поля не подтверждён локальными материалами; на
+[странице акции](../instruments/stocks.md#дивиденды-и-финансовые-показатели)
+он также не трактуется как персональная сумма до или после налога.
+Расчёт подтверждён, налоговую формулировку требуется согласовать отдельно.
+
+## Период и список
+
+Без фильтра период начинается сегодня в UTC и заканчивается через 30 дней
+после начала, обе даты включены. Поля «С» и «По» позволяют изменить период:
+«Применить» сохраняет выбранные календарные даты в URL и запрашивает результат,
+«Сбросить» возвращает период по умолчанию. Обзор счёта сохраняет прогноз
+на текущую дату и следующие 30 дней.
+
+События упорядочены по календарной дате. У каждой строки видны тип,
+инструмент, дата и доступная сумма в исходной валюте. Список не имеет
+пагинации и не конвертирует валюты. Пустой результат означает отсутствие
+известных поддерживаемых событий в выбранном окне, а не доказательство
+отсутствия всех будущих выплат. Инструмент без поддерживаемых данных
+не получает искусственную строку «нет данных».
+
+API принимает необязательные `from` и `to` в формате `YYYY-MM-DD` для
+отдельного и общего счёта. Без `from` используется сегодня в UTC,
+без `to` — 30 дней после начала. Неверный формат или несуществующая дата
+дают `400`; обратный период — `400 INVALID_EVENTS_PERIOD`.
+Фильтрация на сервере предшествует сортировке и вычислению
+`incomeTotalsByCurrency`, включающего только купоны и дивиденды.
+Итоги остаются в ответе API; полный экран показывает список без общего итога.
+
+Текущие controller, сервис и экран поддерживают выбор периода, тогда как
+[основная спецификация](../../../specs/openspec/specs/brokerage-account-upcoming-events/spec.md#requirement-account-page-presents-an-upcoming-events-list)
+описывает фиксированные 30 дней и экран без фильтров. Документация отражает
+реализованный выбор периода, не изменяя это несогласованное требование.
+
+## Получение и отказы
+
+```mermaid
+sequenceDiagram
+  participant F as Frontend
+  participant B as Backend
+  participant T as T-Bank
+  participant M as MOEX ISS
+  F->>B: Счёт и выбранный период событий
+  B->>B: Проверяет сессию и текущее подключение
+  B->>T: Получает открытые счета и позиции доступного счёта
+  par События акций
+    B->>T: GetDividends за выбранный период
+    T-->>B: Известные дивиденды
+  and События облигаций
+    B->>M: Календарь bondization
+    M-->>B: Купоны, погашения и оферты
+  end
+  B->>B: Применяет период и текущее количество бумаг
+  B-->>F: Полный список известных событий либо ошибка
+```
+
+Запрос требует действующей сессии и подключения T-Bank. Получение
+необходимых финансовых данных брокера или календаря MOEX завершается ошибкой
+`503`, если источник недоступен: частичный список не выдаётся как полный.
+Доступные метаданные инструментов дополняют название и логотип; когда
+исходного тикера достаточно для календаря, ошибка дополнительного поиска
+метаданных не скрывает события.
+
+При первом открытии показан каркас заголовка и строк, без интерактивных
+заглушек. Пустой ответ сохраняет возможность изменить период.
+При обычном фоновом обновлении уже полученные данные остаются на экране,
+ошибка получает предупреждение и повторную попытку. Без выбранного счёта
+запрос не выполняется. Смена сессии и подключения следует
+[общим правилам финансовых данных](../../architecture/cross-cutting/data-freshness.md).
+
+Внешние границы объясняют интеграции [T-Bank](../../integrations/tbank.md)
+и [MOEX ISS](../../integrations/moex.md),
+точные транспортные поля — [HTTP API](../../architecture/http-api.md).
+Календарь конкретного выпуска и личные исполненные операции доступны
+на страницах [акций](../instruments/stocks.md) и
+[облигаций](../instruments/bonds.md), где их смысл также разделён.