# Журнал операций

Журнал отвечает на вопрос «какие события брокер исполнил по счёту».
Каждая запись соответствует одной операции 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).
Фильтр конкретной бумаги и общий режим расширяют исходное описание отдельного
счёта; их механизм раскрыт на страницах инструментов и общего портфеля.