docs: reorganize system knowledge by domain
This commit is contained in:
@@ -0,0 +1,117 @@
|
||||
# Журнал операций
|
||||
|
||||
Журнал отвечает на вопрос «какие события брокер исполнил по счёту».
|
||||
Каждая запись соответствует одной операции 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).
|
||||
Фильтр конкретной бумаги и общий режим расширяют исходное описание отдельного
|
||||
счёта; их механизм раскрыт на страницах инструментов и общего портфеля.
|
||||
Reference in New Issue
Block a user