Order Service

Тестовое задание: проектирование схемы БД, SQL-запросы и реализация сервиса добавления товара в заказ. Полноценное тестовое задание лежит в файле TZBackend.docx. SQL запросы из второго пункта описаны в sql_queries.md. Реализация выполнена с использованием Clean Architecture, FastAPI, SQLAlchemy и Poetry.

---

Архитектура

Проект построен по принципам Clean Architecture с чётким разделением слоёв:

src/

├── domain/ # Доменные сущности, value objects, ошибки (для дальнейшего развития, сейчас там только исключения)

├── application/ # Use cases, интерфейсы (ports), DTO

├── infrastructure/ # Реализация портов (DB, SQLAlchemy, UoW)

├── presentation/ # FastAPI, роутеры, схемы, зависимости

├── main.py # Entry point

└── config.py # Конфигурация приложения

Ключевые принципы:

• домен не зависит от инфраструктуры
• use cases работают через порты
• транзакционные границы через Unit of Work
• инфраструктура заменяема

---

Модель данных

Реляционная модель БД включает следующие сущности:

• Category — иерархия категорий (adjacency list, неограниченная вложенность)
• Nomenclature — номенклатура (остатки, цена, категория)
• Client — клиенты
• Order — заказы
• OrderItem — позиции заказа (M:N, уникальность (order_id, nomenclature_id))

Для категорий используется adjacency list, что позволяет хранить дерево произвольной глубины.

---

Реализованные бизнес-инварианты

• нельзя добавить товар с количеством ≤ 0
• нельзя добавить товар, если остатка недостаточно
• если товар уже есть в заказе — количество увеличивается
• цена товара фиксируется на момент добавления в заказ (price_at_order)
• остатки товара уменьшаются атомарно в рамках транзакции

---

API

Добавление товара в заказ

Request body:

{
  "nomenclature_id": 1,
  "quantity": 2
}

Ответ (200 OK):

{
  "order_id": 1,
  "nomenclature_id": 1,
  "quantity": 3,
  "price_at_order": "199.99"
}

Ошибки:

• 404 — заказ или номенклатура не найден

• 409 — недостаточно номенклатуры на складе

• 422 — ошибка валидации

Запуск через Docker

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

Создать файл .env на основе .env.example в корне проекта:

2. Сборка и запуск

docker compose build
docker compose up

После запуска API будет доступно по адресу:

http://localhost:8000

Swagger UI:

http://localhost:8000/docs

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

poetry install
poetry run uvicorn src.main:build_app --reload

Качество кода

В проекте настроены:

• ruff - линтер и форматер
• mypy - типизация
• pre-commit — хуки перед коммитом

Установка хуков:

poetry run pre-commit install

Тесты

В проекте реализованы unit-тесты application слоя, покрывающие ключевые бизнес-инварианты use case добавления товара в заказ.

Запуск тестов:

poetry run pytest

Cтек: Python 3.12, FastAPI, SQLAlchemy 2.x (async), PostgreSQL, Poetry, Docker / docker-compose, Alembic, Ruff / MyPy