# Smart Search Backend Service

Backend микросервис для системы поиска поставщиков с AI интеграцией.

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

- **Go 1.21+** - основной язык
- **rk-boot** - фреймворк для микросервисов (автоматическая настройка gRPC, логирование, метрики)
- **PostgreSQL 15** - база данных
- **pgx/v5** - нативный драйвер PostgreSQL (высокая производительность)
- **gRPC** - межсервисное взаимодействие
- **Squirrel** - SQL query builder
- **Goose** - миграции БД
- **JWT (HS256)** - аутентификация
- **AES-256-GCM** - шифрование PII данных
- **OpenAI API** - генерация ТЗ (gpt-4o-mini)
- **Perplexity API** - поиск поставщиков

### rk-boot + pgx

Сервис использует комбинацию rk-boot и pgx:

**rk-boot** обеспечивает:
- ✅ Автоматическое управление gRPC сервером
- ✅ Структурированное логирование (zap)
- ✅ Prometheus метрики
- ✅ Distributed tracing
- ✅ Health checks
- ✅ Graceful shutdown

**pgx/v5** обеспечивает:
- ✅ Нативный драйвер PostgreSQL (в 2-3 раза быстрее database/sql)
- ✅ Connection pooling из коробки
- ✅ Batch operations
- ✅ Prepared statements
- ✅ Context support

### gRPC Services

**5 gRPC сервисов с 17 методами**:
- `AuthService` - аутентификация (Register, Login, Refresh, Validate, Logout)
- `UserService` - информация о пользователе и статистика
- `InviteService` - управление инвайт-кодами
- `RequestService` - создание и управление заявками с AI
- `SupplierService` - экспорт данных поставщиков

Подробнее: [GRPC_SERVICES.md](GRPC_SERVICES.md)

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

```
smart-search-back/
├── cmd/server/          # Точка входа
├── internal/            # Внутренняя логика
│   ├── grpc/           # gRPC server
│   ├── service/        # Бизнес-логика
│   ├── repository/     # Слой данных
│   ├── model/          # Domain модели
│   ├── worker/         # Background workers
│   └── ai/             # AI интеграция
├── api/proto/          # Proto файлы (только .proto)
├── migrations/         # SQL миграции
├── pkg/                # Общие утилиты
│   ├── pb/             # Сгенерированные proto файлы
│   ├── crypto/         # Шифрование
│   ├── jwt/            # JWT токены
│   └── errors/         # Обработка ошибок
└── config/             # Конфигурация

## Установка

```bash
# Установить зависимости
go mod download

# Применить миграции
make migrate-up

# Запустить сервис
make run
```

### 🧪 Mock-режим

Для тестирования без реальных API ключей сервис поддерживает mock-режим:

- Если `OPENAI_API_KEY` не указан → возвращается тестовое ТЗ
- Если `PERPLEXITY_API_KEY` не указан → возвращается 15 mock поставщиков

Просто запустите без экспорта API ключей:
```bash
make run  # Mock-режим активируется автоматически
```

## Миграции

```bash
# Применить миграции
make migrate-up

# Откатить миграции
make migrate-down
```

## Proto файлы

⚠️ **Важно:** Директория `api/proto/` является **единственным источником истины** для всех Proto-контрактов.

**Структура:**

```
smart-search-back/
├── api/proto/           # Исходные .proto (источник истины)
│   ├── auth/auth.proto
│   ├── user/user.proto
│   └── ...
└── pkg/pb/              # Сгенерированные .pb.go
    ├── auth/
    ├── user/
    └── ...
```

**Генерация proto кода:**

```bash
make proto
```

Генерирует в `pkg/pb/`:
- `*.pb.go` - Protocol Buffers структуры
- `*_grpc.pb.go` - gRPC server/client код

**Импорты в коде:**

```go
import (
    authpb "git.techease.ru/Smart-search/smart-search-back/pkg/pb/auth"
    userpb "git.techease.ru/Smart-search/smart-search-back/pkg/pb/user"
)
```

**При изменении proto файлов:**
1. Внесите изменения в `api/proto/**/*.proto`
2. Запустите `make proto` для регенерации
3. Клиентские сервисы (gateway) синхронизируют изменения через `make proto`

## Разработка

```bash
# Запустить линтер
make lint

# Сгенерировать proto файлы
make proto

# Собрать проект
make build

# Запустить тесты
go test ./...

# С покрытием
go test ./... -cover
```

### Тестирование

Проект полностью подготовлен для тестирования:

- ✅ **Интерфейсы** для всех репозиториев и сервисов
- ✅ **Context** создается один раз в `main.go` и прокидывается через все слои
- ✅ **Приватные структуры** возвращают публичные интерфейсы
- ✅ **Примеры тестов** с моками в `internal/service/tests/`
- ✅ **Graceful shutdown** через context cancellation

Подробнее см. [TESTING.md](TESTING.md)

## Docker

```bash
# Запустить все сервисы
docker-compose up -d
```

## API

gRPC сервер запускается на порту 9091.

Доступные сервисы:
- AuthService - аутентификация
- UserService - управление пользователями
- InviteService - инвайт-коды
- RequestService - запросы на поставщиков
- SupplierService - экспорт поставщиков