family_budget/docs/agents/agent_statement_converter.md

Агент: Конвертер выписок (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-выписку в структурированный текст/табличное представление:
  • заголовочная часть (счёт, валюта, баланс на начало/конец, дата выгрузки),
  • таблица операций (дата/время, сумма, комиссия, описание и т.п.).
• Корректно обрабатывать переносы строк в описании операции.

2 Маппинг полей в JSON 1.0

• Извлечь из заголовка:
  • accountNumber,
  • currency,
  • openingBalance, closingBalance,
  • exportedAt (если нет — использовать время генерации конвертера как суррогат и явно помечать это в комментариях/логах).
• Для каждой строки операции:
  • собрать operationAt (дата+время) и добавить таймзону +03:00, если она не указана явно;
  • преобразовать сумму в amountSigned (в копейках, с учётом знака прихода/расхода);
  • выделить commission (если в выписке отдельная колонка, иначе 0);
  • сформировать description как максимально близкое к тексту из выписки поле.

3 Нормализация сумм

• Все суммы, которые приходят в формате 12345.67, должны быть преобразованы в целое число копеек:
  • 12345.67 → 1234567.
• Важно избегать ошибок округления (использовать работу со строками, а не float).

4 Проверка целостности (по возможности)

• При наличии openingBalance и closingBalance:
  • проверить, что openingBalance + Σ(amountSigned) == closingBalance (с допустимой погрешностью, если есть комиссии/особые операции);
  • если проверка не проходит, вернуть предупреждение вместе с JSON (или отдельный отчёт).

5 Выходной результат

• Агент должен возвращать один JSON-объект строго по схеме 1.0.
• Дополнительно может возвращаться диагностическая информация (лог), но она должна быть отделена от финального JSON.

Взаимодействие с локальным ИИ

• Допускается использование API к локальной LLM/модели для:
  • структурирования текстовых фрагментов из PDF (определение границ колонок, восстановление строк операций),
  • распознавания сложных описаний, если PDF в виде "сырого текста".
• Важно:
  • всегда явно проверять и постпроцессить результат LLM, чтобы привести его к строгому формату 1.0;
  • не полагаться на LLM для вычислений сумм — только для парсинга структуры.

Ограничения

• Агент не взаимодействует напрямую с БД или HTTP API SPA:
  • его задача — чистый конвертер файла → JSON.
• Нельзя менять схему JSON 1.0 без обновления docs/backlog/format.md.
• Конвертер должен корректно работать с русским языком и форматами дат/сумм из российских банковских выписок.