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/agents/agent_architect.md
+++ b/docs/agents/agent_architect.md
@@ -0,0 +1,49 @@
+# Агент: Архитектор SPA семейного бюджета
+
+## Контекст
+
+- Это локальное SPA-приложение для семейного бюджета.
+- Стек: React + TypeScript (FE), Node.js (BE), PostgreSQL (Synology), Git локально.
+- Формальные требования и контракт описаны в файлах:
+  - `format.md` — формат импорта JSON 1.0
+  - `db.md` — модель БД (accounts, transactions, category_rules)
+  - `category.md` — категории и алиасы счетов
+  - `api_history.md` — API истории операций
+  - `edit_and_rules.md` — редактирование и правила категорий
+  - `analytics.md` — аналитика и бюджеты
+  - `auth.md` — авторизация и сессии
+
+## Цели агента
+
+1. Обеспечить целостную архитектуру проекта (папки, модули, naming, структура API).
+2. Следить, чтобы Backend и Frontend строго следовали спецификациям из `positionX_*.md`.
+3. Раскладывать работу на этапы: сначала MVP (импорт + история + базовая категоризация), потом аналитика, бюджеты и т.д.
+4. Давать чёткие задачи Backend- и Frontend-агентам в виде:
+   - какие файлы создать/изменить,
+   - какие эндпоинты/компоненты реализовать,
+   - какие интерфейсы типов (TypeScript) использовать.
+
+## Обязательные ограничения
+
+- Нельзя менять схемы JSON/БД/API, описанные в `./docs/backlog/*.md`, без явной инструкции пользователя.
+- Не использовать SQL-запросы внутри Postgres-ноды n8n (если интеграция с n8n появится позднее).
+- Приоритет — надёжность, предсказуемость и отсутствие “магии”.
+
+## Этапы MVP (для планирования задач)
+
+1. Импорт JSON 1.0:
+   - Эндпоинт для загрузки файла.
+   - Парсинг JSON, валидация, импорт в Postgres с расчётом fingerprint.
+2. История операций:
+   - `GET /api/transactions` по спецификации.
+   - FE-таблица с фильтрами/сортировкой/пагинацией.
+3. Редактирование транзакций и правил:
+   - `PUT /api/transactions/{id}`
+   - CRUD для `category_rules`
+4. Аналитика (Summary, by-category, timeseries).
+5. Авторизация и сессии (`/api/auth/*`) и защита всех API.
+
+Архитектор должен:
+
+- При запуске нового этапа читать соответствующие `*.md` папке `./docs/backlog`.
+- Синхронизировать контракты типов между BE и FE (например, общие TypeScript-интерфейсы).
--- a/docs/agents/agent_backend.md
+++ b/docs/agents/agent_backend.md
@@ -0,0 +1,87 @@
+# Агент: Backend (Node.js + PostgreSQL)
+
+## Стек и требования
+
+- Node.js (Express или Fastify — на усмотрение, но держать код компактным).
+- БД: PostgreSQL (подключение через `pg` или иной официальный драйвер).
+- Типизация: TypeScript.
+- Миграции БД — через миграционный инструмент (например, Knex/Drizzle/TypeORM) или собственные SQL-файлы.
+
+## Обязательные спецификации (читать целиком)
+
+- `format.md`
+- `db.md`
+- `category.md`
+- `api_history.md`
+- `edit_and_rules.md`
+- `analytics.md`
+- `auth.md`
+
+## Основные задачи MVP
+
+1. Структура проекта
+
+- Создать каркас BE: `src/app.ts`, `src/routes/*`, `src/db/*`, `src/middleware/*`, `src/services/*`.
+- Реализовать конфигурацию:
+  - переменные окружения (в т.ч. логин/пароль для авторизации),
+  - строки подключения к Postgres.
+
+1. Миграции БД
+
+- Реализовать таблицы и поля строго по `db.md`, `category.md`, `edit_and_rules.md`, `analytics.md`.
+- Включить все описанные CHECK/UNIQUE/FOREIGN KEY/дополнительные поля (`is_category_confirmed`, `comment`, `alias` для accounts, `budgets` и т.д.).
+
+1. Авторизация и сессии
+
+- Реализовать эндпоинты:
+  - `POST /api/auth/login`
+  - `POST /api/auth/logout`
+  - `GET /api/auth/me`
+- Ввести модель сессий с полями:
+  - `id`, `created_at`, `last_activity_at`, `is_active`
+- Реализовать middleware, которое:
+  - проверяет наличие и валидность session cookie,
+  - проверяет 3-часовой таймаут бездействия,
+  - обнуляет сессию и отдаёт `401` по истечении таймаута.
+
+1. Импорт выписки
+
+- Эндпоинт (например) `POST /api/import/statement`:
+  - Принимает JSON строго формата 1.0 (см. `format.md`).
+  - Валидирует структуру и типы.
+  - Находит или создаёт `accounts` по `bank + accountNumber` и заполняет `alias = NULL`.
+  - Для каждой транзакции:
+    - считает `fingerprint`,
+    - определяет `direction`,
+    - вставляет в `transactions` с учётом уникального индекса `(account_id, fingerprint)`,
+    - по умолчанию `is_category_confirmed = FALSE`, `category_id = NULL`.
+
+1. История операций
+
+- Реализовать `GET /api/transactions` по `api_history.md`:
+  - все фильтры и сортировки,
+  - пагинация,
+  - поля `accountAlias`, `categoryName`, `isCategoryConfirmed`, `comment`.
+
+1. Редактирование транзакций и правила категорий
+
+- Эндпоинт `PUT /api/transactions/{id}`:
+  - Обновляет `category_id`, `comment`, `is_category_confirmed`.
+- Эндпоинты для `category_rules`:
+  - создание правила на основе входных данных (pattern, match_type, category_id, priority),
+  - обновление/деактивация,
+  - опционально — применение правила к истории (bulk-обновление транзакций с `is_category_confirmed = FALSE`).
+
+1. Аналитика
+
+- Реализовать:
+  - `GET /api/analytics/summary`
+  - `GET /api/analytics/by-category`
+  - `GET /api/analytics/timeseries`
+  по агрегатам, описанным в `analytics.md`.
+
+## Ограничения
+
+- Не менять контракты API без явной инструкции пользователя.
+- Все суммы — в копейках (`BIGINT`), все даты/время — `TIMESTAMPTZ`.
+- Обязательно обрабатывать ошибки валидации и возвращать понятные сообщения.
--- a/docs/agents/agent_frontend.md
+++ b/docs/agents/agent_frontend.md
@@ -0,0 +1,81 @@
+# Агент: Frontend (React + TypeScript)
+
+## Стек
+
+- React + TypeScript.
+- Router (React Router или аналог) для экранов: Login, История, Аналитика, Настройки/Правила.
+- Таблицы и графики — на усмотрение (можно использовать готовые компоненты), но без излишней тяжести.
+
+## Обязательные спецификации
+
+- Чтение контрактов API и моделей из:
+  - `api_history.md`
+  - `edit_and_rules.md`
+  - `analytics.md`
+  - `auth.md`
+  - а также модели данных и категорий из `db.md`, `category.md`.
+
+## Основные экраны
+
+1. Логин
+
+- Форма `login/password`, запрос `POST /api/auth/login`.
+- При успехе — переход на Историю.
+- При `401` на любых защищённых запросах — редирект на Login.
+
+1. История операций
+
+- Таблица с колонками:
+  - Дата,
+  - Счёт (alias),
+  - Сумма,
+  - Описание,
+  - Категория,
+  - (иконка/метка неподтверждённой категории),
+  - (иконка комментария).
+- Фильтры:
+  - период (from/to),
+  - быстрые предустановки: неделя/месяц/год с перелистыванием,
+  - счёт,
+  - тип движения (приход/расход/перевод),
+  - категория,
+  - строка поиска,
+  - быстрый фильтр по сумме,
+  - флаг `только неподтверждённые`.
+- Пагинация страницами: 10/50/100.
+
+- Редактирование транзакции (модальное окно):
+  - выбор категории,
+  - поле комментария,
+  - галочка “Создать правило для похожих транзакций в будущем” (по умолчанию включена),
+  - вызов `PUT /api/transactions/{id}` и соответствующего API для правил (если решено вызывать напрямую).
+
+1. Аналитика
+
+- Верхний блок выбора периода: неделя/месяц/год/произвольный + стрелки “←/→” (кроме произвольного).
+- Фильтры:
+  - счёт,
+  - флаг “только подтверждённые”.
+- Блок 1: сводка (`/api/analytics/summary`).
+- Блок 2: график времени (`/api/analytics/timeseries`).
+- Блок 3: диаграмма/таблица по категориям (`/api/analytics/by-category`).
+
+1. Настройки (минимум)
+
+- Список счетов с алиасами:
+  - отображение номера счёта и alias,
+  - возможность поменять alias.
+- Список категорий (только просмотр).
+- Список правил (базово: просмотр, активность, приоритет, тип; редактирование можно отложить на потом).
+
+## Поведение с авторизацией
+
+- При загрузке приложения:
+  - запрос `GET /api/auth/me`, определение, авторизован ли пользователь.
+- Для всех запросов к `/api/*`:
+  - при `401` — сброс локального состояния и редирект на Login.
+
+## Ограничения
+
+- Не менять контракты API, описанные в соответствующих файлах.
+- Настройка видимых колонок в истории должна быть предусмотрена (хотя бы на уровне структуры состояния).
--- a/docs/agents/agent_rules_analytics.md
+++ b/docs/agents/agent_rules_analytics.md
@@ -0,0 +1,29 @@
+# Агент: Правила категорий и аналитика
+
+## Задачи
+
+1. Помогать Backend-агенту проектировать и оптимизировать запросы:
+   - авто-категоризация по `category_rules`,
+   - агрегаты для `/api/analytics/*`,
+   - применение правил к прошлым транзакциям.
+
+2. Следить за тем, чтобы:
+   - все суммы считаются в копейках,
+   - учитывался флаг `is_category_confirmed`,
+   - фильтры по периодам/счётам/категориям корректно отражались в SQL.
+
+3. Подготавливать “чистые” интерфейсы для FE:
+   - структуры ответов уже определены в `api_history.md`, `analytics.md` — не менять.
+
+## Контекст
+
+- Читает:
+  - `db.md`,
+  - `api_history.md`,
+  - `edit_and_rules.md`,
+  - `analytics.md`.
+
+## Ограничения
+
+- Не менять схемы и API.
+- Предлагать решения, которые хорошо работают на локальном PostgreSQL.
--- a/docs/agents/agent_statement_converter.md
+++ b/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`.
+- Конвертер должен корректно работать с русским языком и форматами дат/сумм из российских банковских выписок.