family_budget/docs/agents/agent_backend.md

Агент: 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
• api_reference_accounts_categories.md

Основные задачи MVP

1 Структура проекта

• Создать каркас BE: src/app.ts, src/routes/*, src/db/*, src/middleware/*, src/services/*.
• Реализовать конфигурацию:
  • переменные окружения (в т.ч. логин/пароль для авторизации),
  • строки подключения к Postgres.

2 Миграции БД

• Реализовать таблицы и поля строго по db.md, category.md, edit_and_rules.md, analytics.md.
• Включить все описанные CHECK/UNIQUE/FOREIGN KEY/дополнительные поля (is_category_confirmed, comment, alias для accounts, budgets и т.д.).

3 Авторизация и сессии

• Реализовать эндпоинты:
  • 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 по истечении таймаута.

4 Импорт выписки

• Эндпоинт (например) 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.

5 История операций

• Реализовать GET /api/transactions по api_history.md:
  • все фильтры и сортировки,
  • пагинация,
  • поля accountAlias, categoryName, isCategoryConfirmed, comment.

6 Редактирование транзакций и правила категорий

• Эндпоинт PUT /api/transactions/{id}:
  • Обновляет category_id, comment, is_category_confirmed.
• Эндпоинты для category_rules:
  • создание правила на основе входных данных (pattern, match_type, category_id, priority, requires_confirmation),
  • обновление/деактивация (PATCH),
  • применение правила к прошлым транзакциям (bulk-обновление: только category_id IS NULL или is_category_confirmed = FALSE).

7 Аналитика

• Реализовать:
  • GET /api/analytics/summary
  • GET /api/analytics/by-category
  • GET /api/analytics/timeseries по агрегатам, описанным в analytics.md.

Ограничения

• Не менять контракты API без явной инструкции пользователя.
• Все суммы — в копейках (BIGINT), все даты/время — TIMESTAMPTZ.
• Обязательно обрабатывать ошибки валидации и возвращать понятные сообщения.