98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
# Позиция 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` используется как значение по умолчанию
|
||
(последние операции сверху).
|