feat(analytics): account commission and investment transfers

Handle cashback commission imports, include commissions in analytics with separate investment metrics, and expose commission/version details in the UI. Made-with: Cursor
2026-04-14 16:15:05 +03:00
parent 495c1e89bb
commit fccde4259d
18 changed files with 502 additions and 80 deletions
--- a/pdf2json.md
+++ b/pdf2json.md
@@ -1,75 +1,231 @@
-Ты — конвертер банковских выписок. Твоя задача: извлечь данные из прикреплённого PDF банковской выписки и вернуть строго один валидный JSON-объект в формате ниже. Никакого текста до или после JSON, только сам объект.
+# Инструкция агента: конвертация банковской выписки ВТБ (PDF → JSON)

-## Структура выходного JSON
+## Цель
+
+Преобразовать PDF-выписку банка ВТБ в JSON-файл строго по схеме 1.0.  
+На выходе — валидный JSON-файл без потерь операций, с правильными суммами в копейках и корректной проверкой баланса.
+
+---
+
+## Схема JSON (schema 1.0)

 ```json
 {
  "schemaVersion": "1.0",
-  "bank": "<название банка из выписки>",
+  "bank": "VTB",
  "statement": {
-    "accountNumber": "<номер счёта, только цифры, без пробелов>",
+    "accountNumber": "string",
    "currency": "RUB",
-    "openingBalance": <число в копейках, целое>,
-    "closingBalance": <число в копейках, целое>,
-    "exportedAt": "<дата экспорта в формате ISO 8601 с offset, например 2026-02-27T13:23:00+03:00>"
+    "openingBalance": integer,
+    "closingBalance": integer,
+    "exportedAt": "ISO 8601 string"
  },
  "transactions": [
    {
-      "operationAt": "<дата и время операции в формате ISO 8601 с offset>",
-      "amountSigned": <число: положительное для прихода, отрицательное для расхода; в копейках>,
-      "commission": <число, целое, >= 0, в копейках>,
-      "description": "<полное описание операции из выписки>"
+      "operationAt": "ISO 8601 string",
+      "amountSigned": integer,
+      "commission": integer,
+      "description": "string"
    }
  ]
 }
 ```

-## Правила конвертации
+---

-1. **Суммы** — всегда в копейках (рубли × 100). Пример: 500,00 ₽ → 50000, -1234,56 ₽ → -123456.
+## Шаг 1. Извлечение данных из PDF

-2. **amountSigned**:
-   - Приход (зачисление, пополнение) — положительное число.
-   - Расход (списание, оплата) — отрицательное число.
-   - Переводы — знак в зависимости от направления движения на счёт.
+### 1.1 Шапка выписки

-3. **operationAt** — дата и время операции. Если время не указано, используй 00:00:00. Обязательно указывай offset (+03:00 для МСК).
+Извлечь из заголовочного блока:

-4. **commission** — комиссия по операции. Если не указана — 0.
+| Поле PDF                  | Поле JSON                        | Примечание                        |
+|---------------------------|----------------------------------|-----------------------------------|
+| Номер счёта               | `statement.accountNumber`        | строка, без пробелов              |
+| Баланс на начало периода  | `statement.openingBalance`       | перевести в копейки (× 100)       |
+| Баланс на конец периода   | `statement.closingBalance`       | перевести в копейки (× 100)       |
+| Поступления               | только для валидации             | не записывать в JSON              |
+| Расходные операции        | только для валидации             | не записывать в JSON              |
+| Период выписки            | используется для валидации       | формат ДД.ММ.ГГГГ – ДД.ММ.ГГГГ   |

-5. **description** — полный текст операции как в выписке (назначение платежа, магазин, получатель и т.п.). Не сокращай и не меняй формулировки.
+### 1.2 Поле `exportedAt`

-6. **accountNumber** — только цифры, без пробелов и дефисов (например: 40817810825104025611).
+Взять дату и время **первой строки таблицы операций** (самая поздняя по дате операции).  
+Формат: ISO 8601 с московским часовым поясом: `YYYY-MM-DDTHH:MM:SS+03:00`

-7. **openingBalance / closingBalance** — начальный и конечный остаток по счёту в копейках.
+---

-8. **bank** — краткое название банка (VTB, Sberbank, Тинькофф и т.п.).
+## Шаг 2. Извлечение операций

-9. **exportedAt** — дата формирования выписки. Если неизвестна — возьми дату последней операции в выписке.
+### 2.1 Столбцы таблицы в PDF

-10. **Порядок транзакций** — сохраняй хронологический порядок из выписки (обычно от старых к новым).
+Каждая строка операции содержит:

-## Требования
+| Столбец PDF                         | Описание                                       |
+|-------------------------------------|------------------------------------------------|
+| Дата и время операции               | дата + время совершения операции               |
+| Дата обработки банком               | дата, когда банк обработал операцию            |
+| Сумма операции в валюте операции    | знаковая сумма (`-` = расход, без знака = приход) |
+| Приход (в валюте счёта)             | сумма, если поступление                        |
+| Расход (в валюте счёта)             | сумма, если списание                           |
+| Комиссия                            | комиссия банка                                 |
+| Описание операции                   | текстовое описание                             |

- Массив `transactions` не должен быть пустым.
- Все числа — целые.
- Даты — строго в формате ISO 8601 с offset.
- currency всегда "RUB".
- schemaVersion всегда "1.0".
+### 2.2 Правила маппинга

-## Пример одной транзакции
+**`operationAt`** — из столбца «Дата и время операции», формат ISO 8601 + московский TZ:
+```
+29.03.2026 20:38:01  →  2026-03-29T20:38:01+03:00
+```

-Выписка: «26.02.2026 14:06 | -500,00 ₽ | 0,00 | Оплата товаров. PAVELETSKAYA по карте *8214»
+**`amountSigned`** — сумма в **копейках** (целое число):
+- Если операция — **приход**: значение **положительное**
+- Если операция — **расход**: значение **отрицательное**
+- Допустим специальный кейс: `amountSigned = 0`, **только если** `commission > 0` и в `description` есть подстрока **«Зачисление»** (без учёта регистра)
+- Определять знак по столбцу «Приход»/«Расход», а не по знаку в PDF (там `-` стоит у расходов, но надёжнее смотреть, в какой колонке стоит сумма)
+- Перевод в копейки: умножить на 100 и округлить до целого (`round(amount * 100)`)
+- Разделитель дробной части в PDF — точка или запятая — оба варианта обрабатывать

-→
+**`commission`** — комиссия в **копейках** (целое число):
+- Если в PDF стоит `0.00` → записать `0`
+- Если указана ненулевая комиссия → перевести в копейки аналогично `amountSigned`
+- Комиссия всегда **неотрицательная**
+
+**`description`** — полный текст описания операции, строка:
+- Убрать лишние пробелы и переносы строк (привести к одной строке)
+- Не обрезать и не сокращать
+- Сохранить кириллицу и спецсимволы как есть
+
+### 2.3 Порядок операций
+
+Операции записывать **в том же порядке, что в PDF** (от новых к старым, сверху вниз).
+
+---
+
+## Шаг 3. Валидация перед записью
+
+### 3.1 Проверка баланса
+
+Вычислить:
+```
+income_sum  = сумма всех amountSigned > 0  (в копейках)
+expense_sum = сумма всех amountSigned < 0  (в копейках, отрицательная)
+```
+
+Проверить, что:
+```
+openingBalance + income_sum + expense_sum == closingBalance
+```
+
+**Если не совпадает** — это нормально и объясняется поведением ВТБ:
+
+> ВТБ формирует итоги в шапке по **дате обработки банком**, а не по дате операции.  
+> Операции с датой обработки **вне периода выписки** включаются в список транзакций, но **не учитываются в строках «Поступления» и «Расходные операции»** в шапке.
+
+Правильная проверка:
+1. Определить границы периода из шапки PDF (`дата_начала`, `дата_конца`)
+2. Из `Поступления` и `Расходные операции` вычислить ожидаемый net:  
+   `expected_net = openingBalance_kopecks + income_pdf_kopecks - expense_pdf_kopecks`
+3. Убедиться, что `expected_net == closingBalance` (это всегда верно если данные из PDF прочитаны правильно)
+4. Разница между суммой всех транзакций и `(closingBalance - openingBalance)` — это сумма операций, обработанных банком вне периода. Это **не ошибка**.
+
+### 3.2 Проверка полноты
+
+- Подсчитать количество извлечённых транзакций
+- Пройтись по всем страницам PDF и убедиться, что ни одна строка таблицы не пропущена
+- Особое внимание: операции в конце страницы и в начале следующей (частые точки потери данных)
+
+### 3.3 Проверка типов
+
+Убедиться, что:
+- `openingBalance`, `closingBalance` — целые числа (`int`)
+- `amountSigned`, `commission` — целые числа (`int`)
+- `operationAt`, `exportedAt` — строки в формате ISO 8601 с `+03:00`
+- `description` — строка (не `null`, не пустая)
+
+---
+
+## Шаг 4. Частые ошибки — предотвращение
+
+| Ошибка | Причина | Как избежать |
+|--------|---------|--------------|
+| Сумма в рублях вместо копеек | Забыли умножить на 100 | Всегда применять `round(x * 100)` |
+| Дробные числа вместо int | Потеря точности float | Использовать `round()`, результат кастовать в `int` |
+| Неверный знак `amountSigned` | Ориентировались на знак в PDF | Определять знак по столбцу «Приход»/«Расход» |
+| Потеря операций на стыке страниц | Парсинг постраничный | Читать PDF целиком, не разбивать по страницам |
+| Обрезанное описание | Перенос строки в ячейке PDF | Объединять строки одной ячейки в одну строку |
+| Комиссия со знаком минус | Перепутали знак | Комиссия всегда `>= 0` |
+| `amountSigned = 0` без условия | Импорт отклонит файл | Разрешать `amountSigned = 0` только при `commission > 0` и наличии «Зачисление» в `description` |
+| Неверный `exportedAt` | Взяли дату начала периода | Брать дату и время **первой (самой новой) операции** в таблице |
+| Расхождение баланса | Не учли операции вне периода | Это не ошибка — см. Шаг 3.1 |
+| Лишние пробелы в описании | PDF добавляет пробелы при переносе | Применять `.strip()` и нормализацию пробелов |
+
+---
+
+## Шаг 5. Запись файла
+
+- Имя файла: то же, что у исходного PDF, с заменой расширения `.pdf` → `.json`  
+  Пример: `file-18.pdf` → `file-18.json`
+- Кодировка: **UTF-8**
+- Формат: JSON с отступами (indent = 2)
+- `ensure_ascii = false` — кириллица записывается как есть, не экранируется
+
+---
+
+## Пример корректной транзакции

 ```json
 {
-  "operationAt": "2026-02-26T14:06:00+03:00",
-  "amountSigned": -50000,
+  "operationAt": "2026-03-29T20:38:01+03:00",
+  "amountSigned": -500000,
  "commission": 0,
-  "description": "Оплата товаров. PAVELETSKAYA по карте *8214"
+  "description": "Оплата товаров и услуг. IP KOVTUN L.B.. по карте *9058"
 }
 ```

-Обработай прикреплённый PDF и верни один JSON-объект.
+Расшифровка: списание 5 000.00 ₽ = -500 000 копеек, комиссии нет.
+
+---
+
+## Пример корректного поступления
+
+```json
+{
+  "operationAt": "2026-03-24T15:09:41+03:00",
+  "amountSigned": 9537522,
+  "commission": 0,
+  "description": "Поступление заработной платы. 0726 НАЦИОНАЛЬНЫЙ ИССЛЕДОВАТЕЛЬСКИЙ УНИВЕРСИТЕТ \"ВЫСША Поступление заработной платы/иных выплат Salary по реестру Z_0000005862_20260323_001_01 от 23.03.2026. Без НДС.."
+}
+```
+
+Расшифровка: поступление 95 375.22 ₽ = +9 537 522 копейки.
+
+---
+
+## Пример корректного кэшбэка (сумма в commission)
+
+```json
+{
+  "operationAt": "2026-04-07T19:56:59+03:00",
+  "amountSigned": 0,
+  "commission": 592000,
+  "description": "Зачисление кешбэка по программе лояльности."
+}
+```
+
+Расшифровка: для такого кейса `amountSigned = 0` допустим, потому что есть `commission > 0` и маркер «Зачисление» в описании.
+
+---
+
+## Итоговый чеклист перед отдачей файла
+
+- [ ] `schemaVersion` = `"1.0"`
+- [ ] `bank` = `"VTB"`
+- [ ] `accountNumber` совпадает с PDF
+- [ ] `openingBalance` и `closingBalance` в копейках, совпадают с PDF
+- [ ] `exportedAt` = дата и время первой операции в таблице, формат ISO 8601 +03:00
+- [ ] Количество транзакций совпадает с количеством строк в PDF
+- [ ] Все `amountSigned` и `commission` — целые числа
+- [ ] Если `amountSigned = 0`, то `commission > 0` и в `description` есть «Зачисление» (без учёта регистра)
+- [ ] Поступления и баланс проверены (Шаг 3.1)
+- [ ] Файл сохранён в UTF-8, кириллица не экранирована