order_service¶

1. Назначение¶

order_service управляет корзиной, заказами, статусами оплаты/доставки и выдачей ZIP-файлов цифровых артефактов. Для бесплатных заказов используется асинхронная обработка через order_celery.

2. API-каталог¶

Базовый префикс: /api/.

Cart¶

Метод	Путь	Назначение
GET	`/cart/`	Текущая корзина пользователя
GET	`/cart/{id}/`	Текущая корзина (id игнорируется)
POST	`/cart/{id}/add_item/`	Добавление позиции
POST	`/cart/{id}/items/{item_id}/remove/`	Удаление позиции
DELETE/PATCH/PUT	`/cart/{id}/items/{item_id}/`	Удаление/обновление количества
PATCH	`/cart/{id}/items/{item_id}/update_quantity/`	Обновление количества
POST	`/cart/{id}/checkout/`	Оформление заказа

Orders¶

Метод	Путь	Auth
GET/POST	`/orders/`	IsAuthenticated
GET/PUT/PATCH/DELETE	`/orders/{id}/`	IsAuthenticated
GET	`/orders/seller_orders/`	IsAuthenticated
POST	`/orders/{id}/update_payment_status/`	IsAuthenticated
POST	`/orders/{id}/update_status/`	IsAuthenticated
GET	`/orders/by_number/{order_number}/`	AllowAny
POST	`/orders/update_payment_status_by_number/{order_number}/`	AllowAny
POST	`/orders/update_status_by_number/{order_number}/`	AllowAny
POST	`/orders/upload_zip/{order_number}/{order_item_id}/`	AllowAny

3. Модель данных¶

Cart (OneToOne c пользователем)
CartItem (model_3d_id, quantity, price)
Order (order_number, status, payment_status, total_price)
OrderItem (snapshot товара в заказе)
OrderItemZipFile (файлы выдачи)

4. Бизнес-правила¶

Для одной модели в корзине хранится одна запись.
Количество в корзине ограничено до 1.
Checkout переносит позиции из корзины в заказ и очищает корзину.
При payment_status = paid заказ переводится в processing.
Для бесплатных заказов запускается Celery-задача генерации ZIP.

5. Асинхронный pipeline¶

sequenceDiagram
  participant C as Client
  participant O as order_service
  participant Q as RedisBroker
  participant W as order_celery
  participant P as product_service

  C->>O: POST /api/cart/{id}/checkout
  O->>Q: enqueue process_free_order_zip_files_task
  W->>P: GET /api/models/{id}
  W->>W: build zip from parts
  W->>O: save OrderItemZipFile

6. Интеграции¶

HTTP fallback в product_service для чтения модели/XLSX.
Shared-model интеграция с product_app.Model3D.
Интеграция с admin_app.Notification.

7. Риски и ограничения¶

Публичные bot-endpoint-ы (AllowAny) требуют отдельной защиты.
В checkout нет полной транзакционной обертки.
Используется сравнение суммы через float в части логики бесплатных заказов.
Смешанные return-сигнатуры в ZIP-пайплайне повышают риск runtime-ошибок.

8. Конфигурация¶

Внешний порт: 8004.
Основные env: DATABASE_URL, REDIS_URL, PRODUCT_SERVICE_URL, SECRET_KEY.
Worker order_celery запускается отдельным compose-сервисом.

9. Дополнительная детализация внутренних функций (append-only)¶

9.1 Функции ZIP-pipeline¶

`create_zip_from_parts_xlsx(parts_xlsx_url, model_name, product_service_url)`¶

Источник: order_service/order_app/views.py
Назначение: собрать ZIP-файл STL-деталей на основе XLSX.
Вход:
URL XLSX;
имя модели;
базовый URL product-service.
Выход:
путь к временному ZIP и список отсутствующих деталей (в зависимости от ветки выполнения).
Side effects:
HTTP-запросы в product-service;
чтение локальных STL-файлов;
создание temp-архива на диске.
Edge-cases:
в коде встречаются разные return-формы, что важно учитывать при интеграции.

`process_free_order_zip_files(order_number)`¶

Источник: order_service/order_app/views.py
Назначение: обработать бесплатный заказ и сформировать файлы выдачи.
Вход:
order_number.
Выход:
процедурная функция (основной результат через side effects).
Side effects:
генерация OrderItemZipFile;
смена статуса заказа до delivered при успешной обработке;
очистка временных архивов.
Ошибки:
большинство исключений логируется без re-raise.

`process_free_order_zip_files_task(order_number)`¶

Источник: order_service/order_app/tasks.py
Назначение: Celery-обертка над синхронной ZIP-обработкой.
Side effects:
запуск тяжелой обработки в worker-контуре.

9.2 Функции корзины и checkout¶

`CartViewSet.add_item(self, request, pk=None)`¶

Вход:
model_3d_id, price, опциональный quantity.
Выход:
200 (если item уже был в корзине) или 201 (если создан новый).
Бизнес-правило:
хранится одна запись на товар;
при создании фактическое количество фиксируется как 1.

`CartViewSet.update_item_quantity(self, request, pk=None, item_id=None)`¶

Вход:
quantity.
Выход:
обновленный item или удаление позиции при отдельных сценариях.
Ограничение:
quantity > 1 отклоняется правилами сервиса.

`CartViewSet.checkout(self, request, pk=None)`¶

Вход:
содержимое корзины пользователя;
опционально payment_intent_id.
Выход:
созданный Order и набор OrderItem.
Side effects:
перенос snapshot-данных из корзины в заказ;
очистка корзины;
best-effort создание уведомления;
запуск async ZIP-task для бесплатных заказов (или sync fallback).

9.3 Функции seller-представления заказов¶

`OrderViewSet._get_seller_product_ids(self, user)` и `_is_seller_for_order(self, order, user)`¶

Назначение:
определить, какие позиции заказа относятся к продавцу.
Side effects:
direct import product_app.Model3D или HTTP fallback в product-service.
Edge-cases:
при ошибках интеграции может возвращаться пустой список товаров продавца.

`OrderViewSet.seller_orders(self, request)`¶

Выход:
список заказов с item-фильтрацией по товарам конкретного seller;
агрегат seller_total в ответе.

9.4 Статусные функции заказа¶

`OrderViewSet.update_payment_status(self, request, pk=None)`¶

Вход:
payment_status.
Выход:
обновленный заказ или ошибка валидации/доступа.
Бизнес-правила:
non-staff не может установить paid;
при paid заказ переводится в processing.

`OrderViewSet.update_status(self, request, pk=None)`¶

Вход:
status.
Выход:
обновленный заказ для owner или связанного seller.

9.5 Bot-oriented endpoints¶

by_number, update_payment_status_by_number, update_status_by_number, upload_zip:
предназначены для интеграции с telegram-bot контуром;
в текущем коде доступны с AllowAny, что требует внешней модели доверия и защиты.

10. Соответствие master-документации¶

Источник верхнего уровня: Master-документация проекта.

Контроль	Требование	Проверка	Артефакт
Status workflow	Статусные переходы заказа документированы и тестируемы	проверка инвариантов `payment/status`	integration + QA
Security boundaries	Bot-oriented endpoint-ы защищены внешним контуром доверия	ревью access model и рисков	risk register update
Cross-service sync	Контракты с product/chat/admin не расходятся	межсервисные smoke проверки	test report
Operational readiness	Ошибки оплаты и доставки имеют диагностику	инцидентные проверки	operations docs