Backend API для анализа логистики и прибыльности маркетплейсов

REST API для анализа экономической эффективности размещения пунктов выдачи заказов (ПВЗ) на российских маркетплейсах: Wildberries, Ozon и Yandex Market.

Оглавление

• Архитектура
• Структура проекта
• Технологический стек
• Функциональность
• Настройка и запуск
• Разработка
• Тестирование
• API документация
• Деплой

Архитектура

Проект реализует чистую многоуровневую архитектуру с разделением ответственности:

┌─────────────────────────────────────────┐
│     Transport Layer (HTTP/REST)         │
│  • Handlers (Echo)                      │
│  • Middlewares (JWT, CORS, Logging)     │
│  • DTOs (Request/Response models)       │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│        Service Layer                     │
│  • Business Logic                        │
│  • Auth / User / Report Services         │
│  • Calculations & Aggregations           │
└──────────────┬──────────────────────────┘
               │
     ┌─────────┴──────────┐
     │                    │
┌────▼─────────┐    ┌────▼──────────────┐
│ Repository   │    │  External Clients │
│ • User CRUD  │    │  • Wildberries    │
│ • PostgreSQL │    │  • Ozon           │
│              │    │  • Yandex         │
│              │    │  • AI Predict     │
└──────────────┘    └───────────────────┘

Ключевые архитектурные принципы

• Dependency Injection: Uber fx для внедрения зависимостей
• Repository Pattern: Абстракция работы с БД
• Interface-based Design: Все компоненты работают через интерфейсы
• Clean Architecture: Независимость бизнес-логики от инфраструктуры
• Type Safety: sqlc для генерации типобезопасного кода работы с БД

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

/home/heyrey/wow/
├── cmd/
│   └── main.go                 # Точка входа, инициализация зависимостей
├── internal/
│   ├── clients/               # Клиенты внешних API
│   │   ├── wb/               # Wildberries клиент
│   │   ├── ozon/             # Ozon клиент
│   │   ├── yandex/           # Yandex клиент
│   │   ├── predict/          # AI prediction сервис
│   │   └── clients.go        # Интерфейсы клиентов
│   ├── infra/                # Инфраструктура
│   │   ├── config.go         # Конфигурация (env vars)
│   │   ├── db.go             # PostgreSQL подключение
│   │   ├── echo.go           # HTTP роутер (Echo)
│   │   ├── logger.go         # Логирование (Zap)
│   │   └── queries/          # Генерированный код sqlc
│   ├── localize/             # Интернационализация (i18n)
│   ├── metrics/              # OpenTelemetry метрики
│   ├── models/               # Бизнес-модели данных
│   ├── repository/           # Слой доступа к данным
│   │   ├── user/            # User репозиторий
│   │   └── repository.go    # Интерфейсы репозиториев
│   ├── service/             # Бизнес-логика
│   │   ├── auth/            # Аутентификация/авторизация
│   │   ├── user/            # Управление пользователями
│   │   ├── report/          # Генерация отчетов
│   │   └── service.go       # Интерфейсы сервисов
│   └── transport/           # HTTP API
│       └── api/
│           ├── handlers/    # HTTP обработчики
│           ├── middlewares/ # Middleware (auth, logging)
│           └── dto/         # DTO (запросы/ответы)
├── pkg/                     # Общие утилиты
│   ├── metrics/            # Метрики
│   └── utils/              # Вспомогательные функции
├── sql/                     # База данных
│   ├── schema.sql          # Схема БД
│   ├── queries.sql         # SQL запросы для генерации
│   └── migrations/         # Миграции (Goose)
├── tests/e2e/              # E2E тесты (Python/Tavern)
├── docs/                   # Swagger документация
├── localize/               # JSON файлы локализации
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Production compose
├── dev-compose.yml         # Development compose
├── Taskfile.yml            # Task automation
└── .gitlab-ci.yml          # CI/CD pipeline

Технологический стек

Основные технологии

• Go 1.25.4 - язык программирования
• PostgreSQL 18.0 - база данных
• Echo v4 - веб-фреймворк
• Uber fx v1.24 - dependency injection
• sqlc - type-safe SQL код генерация
• Goose v3 - миграции БД

Библиотеки

Аутентификация и безопасность:

• golang-jwt/jwt/v5 - JWT токены
• echo-jwt/v4 - JWT middleware для Echo
• argon2id - хеширование паролей

База данных:

• pgx/v5 - PostgreSQL драйвер
• sqlc - генерация Go кода из SQL
• goose/v3 - миграции

Наблюдаемость:

• uber/zap - структурированное логирование
• OpenTelemetry - метрики и трейсинг
• Prometheus exporter - экспорт метрик

Прочее:

• bytedance/sonic - быстрый JSON парсер
• oklog/ulid/v2 - генерация уникальных ID
• go-i18n/v2 - интернационализация
• swaggo/swag - генерация Swagger документации

Инструменты разработки

• Task - автоматизация задач сборки
• golangci-lint - линтинг кода
• mockery - генерация моков
• gofumpt + gci - форматирование кода
• Tavern - E2E тестирование API

Функциональность

Основные возможности

1. Аутентификация

• POST /api/auth/register - регистрация пользователя (email + password)
• POST /api/auth/login - вход (возвращает JWT токен)
• JWT авторизация с алгоритмом HS256
• Хеширование паролей через Argon2id
• Уникальные ULID в качестве ID пользователей

2. Генерация отчетов

• POST /api/report - создание отчета о прибыльности ПВЗ
• Требует Bearer токен авторизации
• Входные параметры:
  • Геолокация (широта/долгота)
  • Площадь помещения (м²)
• Агрегирует данные от 3 маркетплейсов:
  • Wildberries - прогноз оборота, checkpoint info
  • Ozon - данные о доступности точек
  • Yandex Market - данные о точках выдачи
• Вызывает AI сервис прогнозирования оптимальной аренды
• Рассчитывает для каждого маркетплейса:
  • Ежемесячная прибыль
  • Вознаграждение
  • Период окупаемости
• Предоставляет рекомендации с учетом:
  • Размера площади
  • Наличия субсидий
  • Особенностей каждого маркетплейса

3. Управление пользователями

• POST /api/user/payment - переключение статуса оплаты пользователя
• Отслеживание платных отчетов для аналитики

4. Служебные эндпоинты

• GET /api/ping - health check
• GET /api/metrics - Prometheus метрики
• GET /api/docs - интерактивная API документация (Scalar UI)

Метрики и наблюдаемость

Счетчики OpenTelemetry:

• users - количество запросов на login/register
• reports - количество бесплатных отчетов
• payed_reports - количество платных отчетов

Логирование:

• Структурированные логи через Zap
• Debug режим для разработки
• Production режим для продакшена

Настройка и запуск

Предварительные требования

• Go 1.25.4+
• Docker и Docker Compose
• Task (опционально, для автоматизации)
• PostgreSQL 18+ (если запускаете локально без Docker)

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

Создайте файл .env или dev.env:

# База данных
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=backend

# JWT
JWT_SECRET=your-secret-key-here  # ВАЖНО: измените в продакшене!

# Debug режим
DEBUG=true

# API эндпоинты маркетплейсов
WB_TURNOVER_API=https://...
WB_CHECKPOINT_API=https://...
WB_POINTINFO_API=https://...
OZON_POINT_API=https://...

# OpenTelemetry
OTLP_COLLECTOR_ENDPOINT=otel-collector:4317
OTLP_COLLECTOR_INTERVAL=1m

Быстрый старт с Docker Compose

Разработка

# Запуск инфраструктуры (БД, OTLP collector, Vector)
task dcu
# или
docker compose -f dev-compose.yml up -d

# Запуск приложения локально
go run cmd/main.go

Production

docker compose up -d

Приложение будет доступно на http://localhost:8080

Локальный запуск без Docker

1. Запустите PostgreSQL:

docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=backend \
  -p 5432:5432 \
  postgres:18.0-alpine

2. Установите зависимости:

go mod download

3. Примените миграции (выполняется автоматически при старте):

# Миграции применяются автоматически в internal/infra/db.go

4. Запустите сервер:

go run cmd/main.go

Разработка

Установка инструментов

Task автоматически установит необходимые инструменты в ./bin:

task install-golangci-lint
task install-formatters
task install-swag
task mockery:install

Доступные команды Task

# Линтинг кода
task lint

# Форматирование кода
task format

# Запуск тестов
task test

# Тесты с покрытием (service + repository слои)
task test-coverage

# Генерация Swagger документации
task swag

# Генерация SQL кода (sqlc)
task sqlc

# Генерация моков (mockery)
task mockery:gen

# Docker compose для разработки
task dcu  # up
task dcd  # down

Работа с миграциями

Миграции применяются автоматически при запуске приложения. Для создания новой миграции:

# Установите goose
go install github.com/pressly/goose/v3/cmd/goose@latest

# Создайте миграцию
cd sql/migrations
goose create add_new_table sql

# Миграция будет создана как sql/migrations/YYYYMMDDHHMMSS_add_new_table.sql

Генерация кода из SQL

Используется sqlc для type-safe работы с БД:

1. Определите SQL запросы в sql/queries.sql:

-- name: GetUserByEmail :one
SELECT * FROM users WHERE email = $1 LIMIT 1;

2. Сгенерируйте Go код:

task sqlc

3. Используйте сгенерированные методы:

user, err := q.GetUserByEmail(ctx, email)

Генерация моков

# Сгенерировать моки для всех интерфейсов
task mockery:gen

# Моки создаются в */mocks/ директориях

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

Unit тесты

# Запуск всех тестов
task test

# Запуск с покрытием
task test-coverage

Структура тестов:

• internal/service/auth/auth_test.go - тесты auth сервиса
• internal/service/user/user_test.go - тесты user сервиса
• Используется testify для ассертов
• Моки генерируются mockery

E2E тесты

E2E тесты написаны на Python с использованием Tavern:

cd tests/e2e

# Установка зависимостей
pip install -r requirements.txt
# или с uv
uv run pytest -n auto

# Запуск тестов
pytest -n auto

# Тесты:
# - test_ping.tavern.yml - проверка health check
# - test_auth.tavern.yml - регистрация и логин

CI/CD Pipeline

GitLab CI выполняет:

1. codegen-test-lint - линтинг, тесты, форматирование
2. build-e2e-push - сборка Docker образа, E2E тесты, push в registry
3. deploy - деплой на production сервер (только main ветка)

API документация

Swagger UI

После запуска приложения документация доступна по адресу:

http://localhost:8080/api/docs

Swagger спецификация (JSON):

http://localhost:8080/docs/swagger.json

Генерация документации

# Генерирует docs/swagger.json и docs/swagger.yaml
task swag

Аннотации в коде:

// @Summary      Login user
// @Description  Authenticate user and return JWT token
// @Tags         auth
// @Accept       json
// @Produce      json
// @Param        request body dto.LoginRequest true "Login credentials"
// @Success      200 {object} dto.LoginResponse
// @Failure      400 {object} dto.ErrorResponse
// @Router       /api/auth/login [post]

Деплой

Docker образ

Multi-stage Dockerfile оптимизирован для production:

Stage 1 (Builder):

• Базовый образ: golang:1.25.4
• Кеширование go модулей
• Статическая сборка (CGO_ENABLED=0)

Stage 2 (Runtime):

• Минимальный образ: debian:trixie-slim
• Непривилегированный пользователь (UID 10001)
• Только необходимые файлы (бинарник + docs + localize)

Docker Compose Production

services:
  postgres:     # PostgreSQL 18.0
  otel-collector: # OpenTelemetry collector
  vector:       # Log/metric shipping
  backend:      # Основное приложение

Порты (bind на localhost):

• 8080 - HTTP API
• 5432 - PostgreSQL
• 4317 - OTLP gRPC
• 8889 - Prometheus metrics
• 9010 - Vector metrics

GitLab CI/CD

Автоматический деплой на production:

1. Push в main ветку
2. CI собирает Docker образ с кешированием
3. Запускаются E2E тесты
4. Образ пушится в GitLab Registry
5. SSH подключение к production серверу
6. Pull образа и перезапуск через docker compose

Мониторинг

Метрики:

• Prometheus endpoint: http://localhost:8889/metrics
• OpenTelemetry OTLP экспорт

Логи:

• Структурированные JSON логи
• Vector для агрегации и отправки

Health checks:

• GET /api/ping - liveness probe
• Docker health checks на всех сервисах

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

• JWT аутентификация с Bearer токенами
• Argon2id хеширование паролей
• Prepared statements (sqlc) защита от SQL injection
• CORS middleware
• Case-insensitive уникальность email через индекс
• JWT секрет конфигурируется через переменную окружения JWT_SECRET

Важно: Используйте криптографически стойкий секрет для JWT (минимум 32 байта) в production окружении.