diff --git a/features/brokerage-account-ledger.md b/features/brokerage-account-ledger.md new file mode 100644 index 0000000..8b4b854 --- /dev/null +++ b/features/brokerage-account-ledger.md @@ -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.