Order Management Service

Сервис для управления заказами в пункте выдачи заказов (ПВЗ) маркетплейса.

Ключевая функциональность

• Управление жизненным циклом заказов:
  • Прием заказов от курьера с указанием срока хранения и типа упаковки.
  • Выдача заказов клиентам.
  • Возврат невостребованных заказов курьеру.
  • Прием возвратов от клиентов.
• API:
  • gRPC API: Основной интерфейс для взаимодействия с сервисом.
  • HTTP Gateway: RESTful-обертка над gRPC API для удобства интеграции.
  • Swagger UI: Интерактивная документация для HTTP API.
• Асинхронная обработка событий:
  • Использование Apache Kafka для логирования всех операций с заказами (прием, выдача, возврат).
  • Отдельный сервис-консьюмер для обработки и логирования событий из Kafka.
• Хранение данных:
  • PostgreSQL в качестве основной базы данных.
  • Управление миграциями схемы данных с помощью goose.
• Производительность и надежность:
  • Кэширование: In-memory кэш (с LRU-стратегией) для снижения нагрузки на базу данных.
  • Конкурентная обработка: Использование воркер-пула для эффективной обработки запросов.
  • Graceful Shutdown: Корректное завершение работы сервиса с ожиданием завершения всех активных задач.
• Наблюдаемость (Observability):
  • Сбор и экспорт метрик в формате Prometheus.
  • Кастомные метрики, например, количество выданных заказов.

Архитектура

Система состоит из следующих компонентов:

1. Order Service (order-service): Основной сервис, реализующий всю бизнес-логику. Предоставляет gRPC и HTTP API.
2. CLI (order-manager-cli): Консольный клиент для администраторов ПВЗ, который взаимодействует с order-service по gRPC.
3. PostgreSQL
4. Apache Kafka
5. Redis: Кэширование.
6. Prometheus

Все компоненты запускаются в Docker-контейнерах и управляются через docker-compose.yml.

Используемые технологии

• Язык: Go
• База данных: PostgreSQL
• Брокер сообщений: Apache Kafka
• Кэш: Redis
• API: gRPC, gRPC-Gateway, Protobuf
• Мониторинг: Prometheus
• Контейнеризация: Docker, Docker Compose
• Миграции: goose
• Тестирование: testify, minimock
• CLI: cobra

Начало работы

Запуск проекта

1. git clone <repository-url>
   cd <project-directory>

2. docker-compose up --build

3. Для взаимодействия с сервисом можно использовать CLI. Примеры команд будут доступны после запуска.

Основные команды Makefile

• make all: Собрать и запустить все.
• make build: Собрать бинарные файлы приложения.
• make run: Запустить сервисы (используя docker-compose).
• make deps: Установить зависимости.
• make generate: Сгенерировать код из .proto файлов.
• make test: Запустить тесты.
• make lint: Запустить линтеры.

Использование API

CLI (gRPC)

После запуска сервиса можно использовать CLI для управления заказами.

Пример:

# Принять заказ
./order-manager-cli accept --order-id=1 --customer-id=123 --storage-until=2025-12-31T10:00:00Z

# Выдать заказ
./order-manager-cli issue --order-ids=1,2,3

HTTP API (Swagger)

Интерактивная документация Swagger UI доступна по адресу: http://localhost:8081/swagger-ui/ (порт может отличаться, см. docker-compose.yml).

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

• api/: Контракты Protobuf для gRPC.
• cmd/: Точки входа для бинарных файлов (order-service, order-manager-cli).
• configs/: Файлы конфигурации.
• internal/: Вся основная бизнес-логика
• migrations/: SQL-скрипты миграций базы данных.
• pkg/: Сгенерированный из .proto файлов код.
• test/: E2E и интеграционные тесты.