# Позиция 3: API истории операций (GET /api/transactions)

## Назначение

Эндпоинт `/api/transactions` предоставляет список транзакций с учётом фильтров, сортировки и пагинации
для отображения в SPA (таблица "История операций").

## Метод и URL

- Метод: `GET`
- URL: `/api/transactions`

## Параметры запроса (query)

Все параметры опциональны, если не указано иное.

- `accountId: number` — идентификатор счёта (`accounts.id`). Если не передан, выбираются транзакции по всем счетам.
- `from: string` — дата начала периода (включительно) в формате `YYYY-MM-DD`.
- `to: string` — дата конца периода (включительно) в формате `YYYY-MM-DD`.
- `direction: string` — направления движения, одно или несколько значений через запятую:
  - `income` — приход;
  - `expense` — расход;
  - `transfer` — переводы между счетами.
  Пример: `direction=income,expense`.
- `categoryId: number` — идентификатор категории (`categories.id`).
- `search: string` — строка поиска по полю `description` (поиск по подстроке, регистронезависимый).
- `amountMin: number` — минимальная сумма операции в копейках (`BIGINT`).
- `amountMax: number` — максимальная сумма операции в копейках (`BIGINT`).
- `onlyUnconfirmed: boolean` — если `true`, возвращаются только транзакции с неподтверждённой категорией (`is_category_confirmed = FALSE`).
- `sortBy: string` — поле сортировки:
  - `date` — сортировка по `operation_at`;
  - `amount` — сортировка по `amount_signed`.
- `sortOrder: string` — порядок сортировки: `asc` или `desc`.
- `page: number` — номер страницы, начиная с `1`. По умолчанию `1`.
- `pageSize: number` — размер страницы (количество записей на странице). Допустимые значения: `10`, `50`, `100`. По умолчанию `50`.

## Структура ответа

Ответ содержит массив транзакций и данные пагинации.

```json
{
  "items": [
    {
      "id": 123,
      "operationAt": "2026-02-26T14:06:57+03:00",
      "accountId": 1,
      "accountAlias": "Текущий",
      "amountSigned": -50000,
      "commission": 0,
      "description": "Оплата товаров и услуг. OZON.RU. по карте *2249",
      "direction": "expense",
      "categoryId": 5,
      "categoryName": "Дом",
      "isCategoryConfirmed": false,
      "comment": "еда"
    }
  ],
  "page": 1,
  "pageSize": 50,
  "totalItems": 874,
  "totalPages": 18
}
```

Поля элементов `items`:

- `id` — идентификатор транзакции (`transactions.id`).
- `operationAt` — дата и время операции в формате ISO 8601 (из `transactions.operation_at`).
- `accountId` — идентификатор счёта (`accounts.id`).
- `accountAlias` — алиас счёта (`accounts.alias`). Если алиас не задан, можно возвращать `null` или сгенерированное значение.
- `amountSigned` — сумма операции в копейках.
- `commission` — комиссия по операции в копейках.
- `description` — описание операции из банка.
- `direction` — направление транзакции (`income` / `expense` / `transfer`).
- `categoryId` — идентификатор категории (`categories.id`), может быть `null`.
- `categoryName` — имя категории (`categories.name`), может быть `null`.
- `isCategoryConfirmed` — признак того, что категория подтверждена пользователем.
- `comment` — пользовательский комментарий к транзакции.

Поля пагинации:

- `page` — текущая страница.
- `pageSize` — размер страницы.
- `totalItems` — общее количество транзакций, удовлетворяющих фильтрам.
- `totalPages` — общее количество страниц при заданном `pageSize`.

## Замечания по реализации

- Справочные данные (`accountAlias`, `categoryName`) могут возвращаться либо сразу в ответе,
  либо SPA может подставлять их по `accountId` и `categoryId` из кэшированных справочников,
  полученных через отдельные эндпоинты (`/api/accounts`, `/api/categories`).
- Фильтрация по `search` выполняется по полю `description` (ILIKE `%search%`).
- Фильтры по сумме (`amountMin`, `amountMax`) применяются к `amount_signed`.
- Параметр `onlyUnconfirmed=true` добавляет условие `is_category_confirmed = FALSE`.
- Комбинация `sortBy=date&sortOrder=desc` используется как значение по умолчанию
  (последние операции сверху).