80e5f318a9
All checks were successful
Deploy Smart Search Backend Test / deploy (push) Successful in 1m24s
195 lines
6.4 KiB
Markdown
195 lines
6.4 KiB
Markdown
# 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 - экспорт поставщиков
|