feat: add operations list

2026-08-14 13:42:56 +03:00
parent 1383949dc4
commit d825126920
1 changed files with 36 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Журнал операций брокерского счёта
+
+Авторизованный пользователь просматривает исполненные операции одного доступного брокерского счёта на `/accounts/:accountId/operations`. На обзоре `/accounts/:accountId` отображаются пять последних событий и ссылка на полный журнал. Ошибка или пустой результат этого блока не заменяет Portfolio.
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant F as Frontend
+  participant B as Backend
+  participant D as SQLite
+  participant T as T-Bank gRPC
+  U->>F: Открывает журнал счёта
+  F->>B: GET /api/v1/brokerage-accounts/:accountId/operations
+  B->>D: Читает T-Bank connection
+  B->>T: GetAccounts(OPEN)
+  B->>T: GetOperationsByCursor(EXECUTED)
+  B-->>F: Страница Account Ledger
+  F-->>U: Операции, фильтры и навигация
+```
+
+## API
+
+`GET /api/v1/brokerage-accounts/:accountId/operations` требует Bearer access token. Необязательные `from` и `to` задают включительный период; без периода запрос начинается с 1 января текущего года. `categories` принимает `trade`, `income`, `tax`, `fee`, `transfer`, `other`; `cursor` и `limit` управляют cursor-пагинацией.
+
+Ответ передаёт `accountId`, `items`, `nextCursor`, `hasNext` и `observedAt`. Каждая `Ledger Entry` соответствует ровно одной операции T-Bank и содержит её тип, категорию, описание, дату, доступный инструмент, `payment`, `quantity`, `price`, `accruedInterest` и `commission`.
+
+Деньги передаются decimal strings в исходной ISO-валюте. Frontend только форматирует значения. Комиссия сделки остаётся деталью той же записи; операции без `payment` отображаются как «Без движения денег».
+
+## Поведение и ограничения
+
+- Запрашиваются только исполненные операции T-Bank.
+- Полный журнал фильтруется по периоду и категориям, а изменение фильтра сбрасывает cursor-пагинацию.
+- Полный журнал не показывает цену, количество, НКД и комиссию записи.
+- Backend кэширует точный запрос 30 секунд в памяти процесса; операции не сохраняются и не синхронизируются локально.
+- Журнал не рассчитывает остаток после операции, суммарные доходы или налоги, историческую стоимость Portfolio, конвертацию валют и рыночные изменения цены.
+- `409 TBANK_NOT_CONNECTED`, `400 INVALID_TBANK_TOKEN`, `404` недоступного счёта и `503 TBANK_UNAVAILABLE` используют существующую семантику ошибок T-Bank.