family_budget/backend

Family Budget — Backend

API-сервер на Express + TypeScript + PostgreSQL.

Запуск

# 1. Установить зависимости (из корня монорепо)
npm install

# 2. Собрать shared-типы
npm run build -w shared

# 3. Скопировать и заполнить .env
cp .env.example .env

# 4. Создать БД PostgreSQL
createdb family_budget

# 5. Запустить в dev-режиме (миграции применяются автоматически при старте)
npm run dev -w backend

Сервер стартует на http://localhost:3000 (или на порту из PORT).

Скрипты

Скрипт	Команда	Описание
dev	npm run dev -w backend	Запуск с hot-reload (tsx watch)
build	npm run build -w backend	Компиляция TypeScript → dist/
start	npm run start -w backend	Запуск скомпилированного сервера
migrate	npm run migrate -w backend	Применить миграции вручную (без старта)

Переменные окружения

Переменная	По умолчанию	Описание
DB_HOST	localhost	Хост PostgreSQL
DB_PORT	5432	Порт PostgreSQL
DB_NAME	family_budget	Имя базы данных
DB_USER	postgres	Пользователь БД
DB_PASSWORD	postgres	Пароль БД
APP_USER_LOGIN	admin	Логин для входа в приложение
APP_USER_PASSWORD	changeme	Пароль для входа в приложение
SESSION_TIMEOUT_MS	10800000	Таймаут сессии по бездействию (3 часа)
PORT	3000	Порт HTTP-сервера
LLM_API_KEY	—	Ключ OpenAI API для конвертации PDF в JSON; без него импорт PDF возвращает 503
LLM_API_BASE_URL	https://api.openai.com/v1	Адрес LLM API (OpenAI-совместимый); для локальной модели, напр. Ollama: http://localhost:11434/v1

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

backend/src/
├── app.ts                  — точка входа: Express, миграции, монтирование роутов
├── config.ts               — чтение переменных окружения
├── utils.ts                — утилиты (maskAccountNumber, asyncHandler)
├── db/
│   ├── pool.ts             — пул подключений pg
│   └── migrate.ts          — миграции (встроенный SQL) + seed 23 категорий
├── middleware/
│   └── auth.ts             — проверка сессии, таймаут 3 ч, обновление last_activity_at
├── services/
│   ├── auth.ts             — login / logout / me
│   ├── import.ts           — валидация, fingerprint, direction, атомарный импорт
│   ├── pdfToStatement.ts   — конвертация PDF → JSON 1.0 через LLM (OpenAI)
│   ├── transactions.ts     — список с фильтрами + обновление (categoryId, comment)
│   ├── accounts.ts         — список счетов, обновление алиаса
│   ├── categories.ts       — список категорий (фильтр isActive)
│   ├── categoryRules.ts    — CRUD правил + apply к прошлым транзакциям
│   └── analytics.ts        — summary, by-category, timeseries
└── routes/
    ├── auth.ts             — POST login/logout, GET me
    ├── import.ts           — POST /api/import/statement
    ├── transactions.ts     — GET /api/transactions, PUT /api/transactions/:id
    ├── accounts.ts         — GET /api/accounts, PUT /api/accounts/:id
    ├── categories.ts       — GET /api/categories
    ├── categoryRules.ts    — GET/POST/PATCH /api/category-rules, POST :id/apply
    └── analytics.ts        — GET summary, by-category, timeseries

API-эндпоинты

Авторизация

Метод	URL	Описание
POST	/api/auth/login	Вход (login + password)
POST	/api/auth/logout	Выход (инвалидация сессии)
GET	/api/auth/me	Текущий пользователь

Импорт

Метод	URL	Описание
POST	/api/import/statement	Импорт банковской выписки (PDF или JSON 1.0; PDF конвертируется через LLM)

Транзакции

Метод	URL	Описание
GET	/api/transactions	Список с фильтрами и пагинацией
PUT	/api/transactions/:id	Обновить категорию / комментарий

Справочники

Метод	URL	Описание
GET	/api/accounts	Список счетов
PUT	/api/accounts/:id	Обновить алиас счёта
GET	/api/categories	Список категорий

Правила категоризации

Метод	URL	Описание
GET	/api/category-rules	Список правил
POST	/api/category-rules	Создать правило
PATCH	/api/category-rules/:id	Частичное обновление / деактивация
POST	/api/category-rules/:id/apply	Применить к прошлым транзакциям

Аналитика

Метод	URL	Описание
GET	/api/analytics/summary	Сводка: расходы, доходы, топ-5
GET	/api/analytics/by-category	Расходы по категориям
GET	/api/analytics/timeseries	Динамика (day / week / month)

База данных

Миграции применяются автоматически при старте сервера. Таблицы:

• accounts — банковские счета (bank, account_number, currency, alias)
• categories — 23 категории с типами expense / income / transfer (seed)
• transactions — операции с fingerprint-дедупликацией, привязкой к счёту и категории
• category_rules — правила авто-категоризации (pattern, match_type, priority)
• sessions — серверные сессии с таймаутом по бездействию