docs: adds rules and agents specs

2026-02-27 19:08:55 +03:00
commit 9551b93a09
12 changed files with 1151 additions and 0 deletions
--- a/docs/backlog/api_history.md
+++ b/docs/backlog/api_history.md
@@ -0,0 +1,98 @@
+# Позиция 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` — переводы между счетами;
+  - `internal` — внутренние движения (если будут использоваться).
+  Пример: `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` / `internal`).
+- `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` используется как значение по умолчанию
+  (последние операции сверху).