118 lines
10 KiB
Markdown
118 lines
10 KiB
Markdown
# Журнал операций
|
|
|
|
Журнал отвечает на вопрос «какие события брокер исполнил по счёту».
|
|
Каждая запись соответствует одной операции T-Bank, а не вычисленному
|
|
приложением изменению стоимости портфеля. Пользователь открывает полный
|
|
журнал на `/accounts/:accountId/operations`; обзор счёта показывает пять
|
|
последних записей и ссылку на него. Ошибка этого блока не скрывает портфель.
|
|
[Общий режим](../portfolio/all-accounts.md#общая-пагинация-операций)
|
|
объединяет операции доступных счетов, сохраняя источник каждой записи.
|
|
|
|
## Что означает запись
|
|
|
|
Исполненная операция содержит тип события, его категорию, описание,
|
|
момент совершения, доступные сведения об инструменте и денежное движение.
|
|
Запросы отменённых или ожидающих исполнения поручений не образуют этот журнал.
|
|
Суммы остаются точными десятичными строками в исходной валюте; frontend
|
|
только форматирует их. Положительное и отрицательное движение сохраняют
|
|
знак. Отсутствие `payment` означает «Без движения денег», а не нулевую сумму.
|
|
|
|
Категории объединяют разные события для фильтрации: сделка (`trade`),
|
|
доход (`income`), налог (`tax`), комиссия (`fee`), перевод (`transfer`)
|
|
и прочее (`other`). Принадлежность к категории дохода сама по себе не
|
|
означает включение в [пассивный доход](../income/overview.md): тот использует
|
|
только точные типы исполненных купонов и дивидендов.
|
|
|
|
Количество сделки берётся из исполненного `quantityDone`; если его нет,
|
|
количество неизвестно и не заменяется порученным. Цена, НКД и комиссия
|
|
сохраняются как доступные детали операции. Комиссия сделки не создаёт
|
|
дубликат отдельной записи журнала. Метаданные логотипа дополняют представление,
|
|
но их недоступность не меняет финансовое событие.
|
|
|
|
Журнал не вычисляет остаток после операции, историческую стоимость портфеля,
|
|
совокупный налог или валютную конвертацию. Изменение рыночной цены не становится
|
|
операцией. Переводы между счетами не схлопываются в одну запись; одинаковые
|
|
ID операций разных счетов не означают дубликат.
|
|
|
|
## Период и навигация
|
|
|
|
Полный журнал позволяет выбрать период включительно и несколько категорий.
|
|
Без периода начало — 1 января текущего года в UTC, конец — текущее время.
|
|
Поля «С» и «По» используют формат `ДД.ММ.ГГГГ`, русский календарь и взаимные
|
|
ограничения дат. Изменение полей меняет только черновик. «Применить» сохраняет
|
|
его в URL, загружает результат и сбрасывает пагинацию; «Сбросить» очищает
|
|
фильтры и сразу возвращает период по умолчанию и все категории.
|
|
«Назад» и «Далее» используют последний применённый фильтр.
|
|
|
|
На [страницах акций](../instruments/stocks.md) и
|
|
[облигаций](../instruments/bonds.md) этот же журнал становится личной историей
|
|
конкретной бумаги. Фильтр `instrumentUid` передаётся брокеру и проверяется
|
|
в ответе. Без явного начала периода он охватывает историю с открытия счёта;
|
|
в общем режиме — с самой ранней известной даты открытия доступных счетов.
|
|
Если даты открытия неполны, нижняя граница — Unix epoch. Это позволяет
|
|
видеть прошлые операции уже проданной бумаги, но не обещает историю
|
|
закрытых и недоступных счетов.
|
|
|
|
## Получение и полнота
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant F as Frontend
|
|
participant B as Backend
|
|
participant T as T-Bank
|
|
F->>B: Запрашивает применённый период и страницу операций
|
|
B->>B: Проверяет сессию и текущее подключение
|
|
B->>T: Получает открытые счета
|
|
T-->>B: Подтверждает доступность счёта
|
|
alt Подходящая страница есть в кэше
|
|
B-->>F: Сохранённая страница
|
|
else Нужна загрузка
|
|
B->>T: GetOperationsByCursor, только исполненные операции
|
|
T-->>B: Страница операций
|
|
B->>B: Нормализует записи и применяет фильтры
|
|
B-->>F: Записи и продолжение либо ошибка
|
|
end
|
|
```
|
|
|
|
`GET /api/v1/brokerage-accounts/:accountId/operations` требует Bearer token.
|
|
Период, категории, необязательный UID, курсор и размер страницы задают запрос;
|
|
ответ содержит записи, время наблюдения и сведения о продолжении.
|
|
Точные поля и допустимые значения задаёт [HTTP API](../../architecture/http-api.md).
|
|
|
|
Backend хранит не более 100 страниц в памяти процесса. Свежая страница
|
|
живёт до 30 секунд; при переполнении вытесняется давно не использовавшаяся.
|
|
Ключ разделяет пользователя, поколение подключения, счёт, нормализованный
|
|
период и категории, UID инструмента, курсор и размер страницы.
|
|
Отсутствующий конец периода приводится к текущему 30-секундному интервалу.
|
|
Текущее подключение и доступ к счёту проверяются до выдачи страницы из кэша.
|
|
|
|
После успешного изменения подключения страницы предыдущего поколения,
|
|
в том числе поздно завершившиеся запросы, не выдаются журналу или аналитике
|
|
дохода. Они удаляются по обычным ограничениям времени и объёма.
|
|
Локальной синхронизации и долговременного хранения операций нет.
|
|
Продолжения [общего журнала](../portfolio/all-accounts.md#общая-пагинация-операций)
|
|
имеют собственные ограничения и восстановление после истечения.
|
|
|
|
## Представление и ошибки
|
|
|
|
Полный журнал и превью используют одинаковую компактную строку: логотип
|
|
или буквенная заглушка, описание, дата, инструмент и денежное движение.
|
|
Для купона и дивиденда денежная метка называет точное событие; для прочих
|
|
операций — категорию. Она показывается один раз, без повтора рядом с датой.
|
|
Знак и цвет обозначают направление денег; отсутствие движения нейтрально.
|
|
Если описание отсутствует, показывается локализованный тип операции.
|
|
|
|
Полный журнал не выводит цену, количество, НКД и комиссию; личная история
|
|
инструмента добавляет количество, цену и ссылку на счёт. Даты показываются
|
|
как `ДД.ММ.ГГГГ`, время операций явно обозначено UTC.
|
|
|
|
При первом открытии виден каркас фильтров и строк. Уже полученный результат
|
|
не заменяется каркасом при применении действий или фоновом обновлении.
|
|
Ошибки `TBANK_NOT_CONNECTED`, `INVALID_TBANK_TOKEN`, недоступный счёт (`404`)
|
|
и `TBANK_UNAVAILABLE` сохраняют [общую семантику API](../../architecture/http-api.md).
|
|
Пустой успешный ответ означает отсутствие подходящих операций, а не сбой.
|
|
|
|
Согласованное поведение описано в [спецификации журнала](../../../specs/openspec/specs/brokerage-account-ledger/spec.md).
|
|
Фильтр конкретной бумаги и общий режим расширяют исходное описание отдельного
|
|
счёта; их механизм раскрыт на страницах инструментов и общего портфеля.
|