docs: adds rules and agents specs

docs/agents/agent_statement_converter.md

@@ -0,0 +1,79 @@
+# Агент: Конвертер выписок (PDF/XLSX → JSON 1.0)
+
+## Контекст
+
+Цель: по входному файлу выписки (PDF, в будущем XLSX) сформировать JSON строго
+по схеме 1.0, описанной в `docs/backlog/format.md`, для дальнейшего импорта
+в SPA через backend-эндпоинт.
+
+Формат JSON 1.0:
+
+- `schemaVersion = "1.0"`
+- `bank = "VTB"` (на старте)
+- `statement`:
+  - `accountNumber: string`
+  - `currency: string`
+  - `openingBalance: integer` (копейки)
+  - `closingBalance: integer` (копейки)
+  - `exportedAt: string` (ISO 8601 + TZ)
+- `transactions[]`:
+  - `operationAt: string` (ISO 8601 + TZ)
+  - `amountSigned: integer` (копейки, >0 приход, <0 расход)
+  - `commission: integer` (копейки)
+  - `description: string`
+
+## Задачи агента
+
+1. Конвертация PDF → сырые строки
+
+- Использовать доступный инструмент (локальный ИИ/LLM API или библиотеку),
+  чтобы преобразовать PDF-выписку в структурированный текст/табличное представление:
+  - заголовочная часть (счёт, валюта, баланс на начало/конец, дата выгрузки),
+  - таблица операций (дата/время, сумма, комиссия, описание и т.п.).
+- Корректно обрабатывать переносы строк в описании операции.
+
+1. Маппинг полей в JSON 1.0
+
+- Извлечь из заголовка:
+  - `accountNumber`,
+  - `currency`,
+  - `openingBalance`, `closingBalance`,
+  - `exportedAt` (если нет — использовать время генерации конвертера как суррогат и явно помечать это в комментариях/логах).
+- Для каждой строки операции:
+  - собрать `operationAt` (дата+время) и добавить таймзону `+03:00`, если она не указана явно;
+  - преобразовать сумму в `amountSigned` (в копейках, с учётом знака прихода/расхода);
+  - выделить `commission` (если в выписке отдельная колонка, иначе `0`);
+  - сформировать `description` как максимально близкое к тексту из выписки поле.
+
+1. Нормализация сумм
+
+- Все суммы, которые приходят в формате `12345.67`, должны быть преобразованы в целое число копеек:
+  - `12345.67 → 1234567`.
+- Важно избегать ошибок округления (использовать работу со строками, а не float).
+
+1. Проверка целостности (по возможности)
+
+- При наличии `openingBalance` и `closingBalance`:
+  - проверить, что `openingBalance + Σ(amountSigned) == closingBalance` (с допустимой погрешностью, если есть комиссии/особые операции);
+  - если проверка не проходит, вернуть предупреждение вместе с JSON (или отдельный отчёт).
+
+1. Выходной результат
+
+- Агент должен возвращать один JSON-объект строго по схеме 1.0.
+- Дополнительно может возвращаться диагностическая информация (лог), но она должна быть отделена от финального JSON.
+
+## Взаимодействие с локальным ИИ
+
+- Допускается использование API к локальной LLM/модели для:
+  - структурирования текстовых фрагментов из PDF (определение границ колонок, восстановление строк операций),
+  - распознавания сложных описаний, если PDF в виде "сырого текста".
+- Важно:
+  - всегда явно проверять и постпроцессить результат LLM, чтобы привести его к строгому формату 1.0;
+  - не полагаться на LLM для вычислений сумм — только для парсинга структуры.
+
+## Ограничения
+
+- Агент **не взаимодействует** напрямую с БД или HTTP API SPA:
+  - его задача — чистый конвертер файла → JSON.
+- Нельзя менять схему JSON 1.0 без обновления `docs/backlog/format.md`.
+- Конвертер должен корректно работать с русским языком и форматами дат/сумм из российских банковских выписок.