# Finance Backend API

API для управления личными финансами с поддержкой русской локализации.

## Возможности

- **Аутентификация**: JWT токены в HTTP-only cookies, refresh token rotation
- **Транзакции**: CRUD операции, фильтрация, импорт, аналитика
- **Категории**: Стандартные русские категории, пользовательские категории
- **Бюджеты**: Правило 50/30/20, отслеживание расходов по категориям
- **Финансовые цели**: Создание целей, отслеживание прогресса, автонакопления
- **Рекомендации**: AI-powered персонализированные советы
- **Аналитика**: Тренды, разбивка по категориям, финансовое здоровье

## Технологии

- **Framework**: NestJS 10.x
- **Database**: PostgreSQL + TypeORM
- **Auth**: Passport.js + JWT
- **Validation**: class-validator
- **Documentation**: Swagger/OpenAPI
- **Containerization**: Docker

## Быстрый старт

### Требования

- Node.js 18+
- Docker & Docker Compose
- PostgreSQL 15+ (или через Docker)

### Установка

```bash
# Клонирование репозитория
git clone <repository-url>
cd finance-backend

# Установка зависимостей
npm install

# Копирование переменных окружения
cp .env.example .env.development
```

### Запуск с Docker

```bash
# Запуск PostgreSQL
docker compose up -d postgres

# Запуск в режиме разработки
npm run start:dev
```

### Запуск без Docker

1. Установите PostgreSQL локально
2. Создайте базу данных `finance_app`
3. Обновите `.env.development` с вашими настройками
4. Запустите приложение:

```bash
npm run start:dev
```

## API Endpoints

После запуска доступны:

- **API**: http://localhost:3000/api/v1
- **Swagger Docs**: http://localhost:3000/api/docs
- **Health Check**: http://localhost:3000/health

### Основные эндпоинты

| Модуль | Путь | Описание |
|--------|------|----------|
| Auth | `/api/v1/auth/*` | Регистрация, вход, токены |
| Transactions | `/api/v1/transactions/*` | CRUD транзакций |
| Categories | `/api/v1/categories/*` | Управление категориями |
| Budgets | `/api/v1/budgets/*` | Бюджеты 50/30/20 |
| Goals | `/api/v1/goals/*` | Финансовые цели |
| Recommendations | `/api/v1/recommendations/*` | AI рекомендации |
| Analytics | `/api/v1/analytics/*` | Аналитика и отчеты |

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

```
src/
├── common/              # Общие утилиты, декораторы, фильтры
│   ├── constants/       # Константы и сообщения об ошибках
│   ├── decorators/      # Кастомные декораторы
│   ├── filters/         # Exception filters
│   ├── guards/          # Auth guards
│   ├── interceptors/    # Response interceptors
│   └── utils/           # Утилиты (дата, валюта, безопасность)
├── config/              # Конфигурация приложения
├── database/            # TypeORM конфигурация и миграции
└── modules/             # Функциональные модули
    ├── auth/            # Аутентификация
    ├── categories/      # Категории
    ├── transactions/    # Транзакции
    ├── budgets/         # Бюджеты
    ├── goals/           # Цели
    ├── recommendations/ # Рекомендации
    ├── analytics/       # Аналитика
    └── ai/              # AI сервис (placeholder)
```

## Скрипты

```bash
# Разработка
npm run start:dev       # Запуск с hot-reload

# Сборка
npm run build           # Сборка проекта
npm run start:prod      # Запуск production

# Тестирование
npm run test            # Unit тесты
npm run test:e2e        # E2E тесты
npm run test:cov        # Coverage отчет

# База данных
npm run migration:generate  # Генерация миграции
npm run migration:run       # Применение миграций
npm run seed               # Заполнение начальными данными

# Линтинг
npm run lint            # Проверка кода
npm run format          # Форматирование
```

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

| Переменная | Описание | По умолчанию |
|------------|----------|--------------|
| `PORT` | Порт сервера | 3000 |
| `NODE_ENV` | Окружение | development |
| `DB_HOST` | Хост PostgreSQL | localhost |
| `DB_PORT` | Порт PostgreSQL | 5432 |
| `DB_USERNAME` | Пользователь БД | finance_user |
| `DB_PASSWORD` | Пароль БД | - |
| `DB_NAME` | Имя базы данных | finance_app |
| `JWT_ACCESS_SECRET` | Секрет access токена | - |
| `JWT_REFRESH_SECRET` | Секрет refresh токена | - |
| `JWT_ACCESS_EXPIRES` | Время жизни access | 15m |
| `JWT_REFRESH_EXPIRES` | Время жизни refresh | 7d |

## Безопасность

- JWT токены хранятся в HTTP-only cookies
- Refresh token rotation при каждом обновлении
- Rate limiting на все эндпоинты
- Bcrypt для хеширования паролей (12 раундов)
- Блокировка аккаунта после 10 неудачных попыток входа
- Аудит логи для критических операций

## Локализация

Все сообщения об ошибках и стандартные категории на русском языке.
Поддержка рублей (RUB) и московского часового пояса (UTC+3).

## License

MIT