feat: creates backend for the project
This commit is contained in:
vakabunga
135
backend/README.md
Normal file
135
backend/README.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Family Budget — Backend
|
||||
|
||||
API-сервер на Express + TypeScript + PostgreSQL.
|
||||
|
||||
## Запуск
|
||||
|
||||
```bash
|
||||
# 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-сервера |
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
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, атомарный импорт
|
||||
│ ├── 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` | Импорт банковской выписки (JSON 1.0) |
|
||||
|
||||
### Транзакции
|
||||
|
||||
| Метод | 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** — серверные сессии с таймаутом по бездействию
|
||||
Reference in New Issue
Block a user