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

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

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 ключей:

make run  # Mock-режим активируется автоматически

Миграции

# Применить миграции
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 кода:

make proto

Генерирует в pkg/pb/:

• *.pb.go - Protocol Buffers структуры
• *_grpc.pb.go - gRPC server/client код

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

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

Разработка

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

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

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

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

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

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

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

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

Подробнее см. TESTING.md

Docker

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

API

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

Доступные сервисы:

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