sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: add order item exception system for graceful product matching

Browse Source 
Replaces the "fail on missing product" behavior with graceful handling:
- Orders import even when products aren't found by GTIN
- Unmatched items link to a per-vendor placeholder product
- Exceptions tracked in order_item_exceptions table for QC resolution
- Order confirmation blocked until exceptions are resolved
- Auto-matching when products are imported via catalog sync

New files:
- OrderItemException model and migration
- OrderItemExceptionService with CRUD and resolution logic
- Admin and vendor API endpoints for exception management
- Domain exceptions for error handling

Modified:
- OrderItem: added needs_product_match flag and exception relationship
- OrderService: graceful handling with placeholder products
- MarketplaceProductService: auto-match on product import
- Letzshop confirm endpoints: blocking check for unresolved exceptions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Samir Boulahtit
2025-12-20 13:11:47 +01:00
parent e0a0da85f8
commit d6d658dd85
19 changed files with 2215 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
app/api/v1/admin/__init__.py
View File

@@ -38,6 +38,7 @@ from . import (
marketplace,
monitoring,
notifications,
order_item_exceptions,
orders,
products,
settings,
@@ -115,6 +116,11 @@ router.include_router(inventory.router, tags=["admin-inventory"])
# Include order management endpoints
router.include_router(orders.router, tags=["admin-orders"])
# Include order item exception management endpoints
router.include_router(
order_item_exceptions.router, tags=["admin-order-exceptions"]
)
# ============================================================================
# Marketplace & Imports

29
app/api/v1/admin/letzshop.py
View File

@@ -16,7 +16,12 @@ from sqlalchemy.orm import Session
from app.api.deps import get_current_admin_api
from app.core.database import get_db
from app.exceptions import ResourceNotFoundException, ValidationException
from app.exceptions import (
OrderHasUnresolvedExceptionsException,
ResourceNotFoundException,
ValidationException,
)
from app.services.order_item_exception_service import order_item_exception_service
from app.services.letzshop import (
CredentialsNotFoundError,
LetzshopClientError,
@@ -783,6 +788,9 @@ def confirm_order(
Confirm all inventory units for a Letzshop order.
Sends confirmInventoryUnits mutation with isAvailable=true for all items.
Raises:
OrderHasUnresolvedExceptionsException: If order has unresolved product exceptions
"""
order_service = get_order_service(db)
creds_service = get_credentials_service(db)
@@ -792,6 +800,13 @@ def confirm_order(
except OrderNotFoundError:
raise ResourceNotFoundException("Order", str(order_id))
# Check for unresolved exceptions (blocks confirmation)
unresolved_count = order_item_exception_service.get_unresolved_exception_count(
db, order_id
)
if unresolved_count > 0:
raise OrderHasUnresolvedExceptionsException(order_id, unresolved_count)
# Get inventory unit IDs from order items
items = order_service.get_order_items(order)
if not items:
@@ -933,6 +948,9 @@ def confirm_single_item(
Confirm a single inventory unit in an order.
Sends confirmInventoryUnits mutation with isAvailable=true for one item.
Raises:
OrderHasUnresolvedExceptionsException: If the specific item has an unresolved exception
"""
order_service = get_order_service(db)
creds_service = get_credentials_service(db)
@@ -942,6 +960,15 @@ def confirm_single_item(
except OrderNotFoundError:
raise ResourceNotFoundException("Order", str(order_id))
# Check if this specific item has an unresolved exception
# Find the order item by external_item_id
item = next(
(i for i in order.items if i.external_item_id == item_id),
None
)
if item and item.needs_product_match:
raise OrderHasUnresolvedExceptionsException(order_id, 1)
try:
with creds_service.create_client(vendor_id) as client:
result = client.confirm_inventory_units([item_id])

249
app/api/v1/admin/order_item_exceptions.py Normal file
View File

@@ -0,0 +1,249 @@
# app/api/v1/admin/order_item_exceptions.py
"""
Admin API endpoints for order item exception management.
Provides admin-level management of:
- Listing exceptions across all vendors
- Resolving exceptions by assigning products
- Bulk resolution by GTIN
- Exception statistics
"""
import logging
from fastapi import APIRouter, Depends, Path, Query
from sqlalchemy.orm import Session
from app.api.deps import get_current_admin_api
from app.core.database import get_db
from app.services.order_item_exception_service import order_item_exception_service
from models.database.user import User
from models.schema.order_item_exception import (
BulkResolveRequest,
BulkResolveResponse,
IgnoreExceptionRequest,
OrderItemExceptionListResponse,
OrderItemExceptionResponse,
OrderItemExceptionStats,
ResolveExceptionRequest,
)
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/order-exceptions", tags=["Order Item Exceptions"])
# ============================================================================
# Exception Listing and Stats
# ============================================================================
@router.get("", response_model=OrderItemExceptionListResponse)
def list_exceptions(
vendor_id: int | None = Query(None, description="Filter by vendor"),
status: str | None = Query(
None,
pattern="^(pending|resolved|ignored)$",
description="Filter by status"
),
search: str | None = Query(
None,
description="Search in GTIN, product name, SKU, or order number"
),
skip: int = Query(0, ge=0),
limit: int = Query(50, ge=1, le=200),
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
List order item exceptions with filtering and pagination.
Returns exceptions for unmatched products during marketplace order imports.
"""
exceptions, total = order_item_exception_service.get_pending_exceptions(
db=db,
vendor_id=vendor_id,
status=status,
search=search,
skip=skip,
limit=limit,
)
# Enrich with order info
response_items = []
for exc in exceptions:
item = OrderItemExceptionResponse.model_validate(exc)
if exc.order_item and exc.order_item.order:
order = exc.order_item.order
item.order_number = order.order_number
item.order_id = order.id
item.order_date = order.order_date
item.order_status = order.status
response_items.append(item)
return OrderItemExceptionListResponse(
exceptions=response_items,
total=total,
skip=skip,
limit=limit,
)
@router.get("/stats", response_model=OrderItemExceptionStats)
def get_exception_stats(
vendor_id: int | None = Query(None, description="Filter by vendor"),
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
Get exception statistics.
Returns counts of pending, resolved, and ignored exceptions.
"""
stats = order_item_exception_service.get_exception_stats(db, vendor_id)
return OrderItemExceptionStats(**stats)
# ============================================================================
# Exception Details
# ============================================================================
@router.get("/{exception_id}", response_model=OrderItemExceptionResponse)
def get_exception(
exception_id: int = Path(..., description="Exception ID"),
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
Get details of a single exception.
"""
exception = order_item_exception_service.get_exception_by_id(db, exception_id)
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
return response
# ============================================================================
# Exception Resolution
# ============================================================================
@router.post("/{exception_id}/resolve", response_model=OrderItemExceptionResponse)
def resolve_exception(
exception_id: int = Path(..., description="Exception ID"),
request: ResolveExceptionRequest = ...,
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
Resolve an exception by assigning a product.
This updates the order item's product_id and marks the exception as resolved.
"""
exception = order_item_exception_service.resolve_exception(
db=db,
exception_id=exception_id,
product_id=request.product_id,
resolved_by=current_admin.id,
notes=request.notes,
)
db.commit()
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
logger.info(
f"Admin {current_admin.id} resolved exception {exception_id} "
f"with product {request.product_id}"
)
return response
@router.post("/{exception_id}/ignore", response_model=OrderItemExceptionResponse)
def ignore_exception(
exception_id: int = Path(..., description="Exception ID"),
request: IgnoreExceptionRequest = ...,
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
Mark an exception as ignored.
Note: Ignored exceptions still block order confirmation.
Use this when a product will never be matched (e.g., discontinued).
"""
exception = order_item_exception_service.ignore_exception(
db=db,
exception_id=exception_id,
resolved_by=current_admin.id,
notes=request.notes,
)
db.commit()
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
logger.info(
f"Admin {current_admin.id} ignored exception {exception_id}: {request.notes}"
)
return response
# ============================================================================
# Bulk Operations
# ============================================================================
@router.post("/bulk-resolve", response_model=BulkResolveResponse)
def bulk_resolve_by_gtin(
request: BulkResolveRequest,
vendor_id: int = Query(..., description="Vendor ID"),
db: Session = Depends(get_db),
current_admin: User = Depends(get_current_admin_api),
):
"""
Bulk resolve all pending exceptions for a GTIN.
Useful when a new product is imported and multiple orders have
items with the same unmatched GTIN.
"""
resolved_count = order_item_exception_service.bulk_resolve_by_gtin(
db=db,
vendor_id=vendor_id,
gtin=request.gtin,
product_id=request.product_id,
resolved_by=current_admin.id,
notes=request.notes,
)
db.commit()
logger.info(
f"Admin {current_admin.id} bulk resolved {resolved_count} exceptions "
f"for GTIN {request.gtin} with product {request.product_id}"
)
return BulkResolveResponse(
resolved_count=resolved_count,
gtin=request.gtin,
product_id=request.product_id,
)

2
app/api/v1/vendor/__init__.py vendored
View File

@@ -25,6 +25,7 @@ from . import (
marketplace,
media,
notifications,
order_item_exceptions,
orders,
payments,
products,
@@ -56,6 +57,7 @@ router.include_router(settings.router, tags=["vendor-settings"])
# Business operations (with prefixes: /products/*, /orders/*, etc.)
router.include_router(products.router, tags=["vendor-products"])
router.include_router(orders.router, tags=["vendor-orders"])
router.include_router(order_item_exceptions.router, tags=["vendor-order-exceptions"])
router.include_router(customers.router, tags=["vendor-customers"])
router.include_router(team.router, tags=["vendor-team"])
router.include_router(inventory.router, tags=["vendor-inventory"])

21
app/api/v1/vendor/letzshop.py vendored
View File

@@ -18,7 +18,12 @@ from sqlalchemy.orm import Session
from app.api.deps import get_current_vendor_api
from app.core.database import get_db
from app.exceptions import ResourceNotFoundException, ValidationException
from app.exceptions import (
OrderHasUnresolvedExceptionsException,
ResourceNotFoundException,
ValidationException,
)
from app.services.order_item_exception_service import order_item_exception_service
from app.services.letzshop import (
CredentialsNotFoundError,
LetzshopClientError,
@@ -434,7 +439,12 @@ def confirm_order(
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""Confirm inventory units for a Letzshop order."""
"""
Confirm inventory units for a Letzshop order.
Raises:
OrderHasUnresolvedExceptionsException: If order has unresolved product exceptions
"""
vendor_id = current_user.token_vendor_id
order_service = get_order_service(db)
creds_service = get_credentials_service(db)
@@ -444,6 +454,13 @@ def confirm_order(
except OrderNotFoundError:
raise ResourceNotFoundException("LetzshopOrder", str(order_id))
# Check for unresolved exceptions (blocks confirmation)
unresolved_count = order_item_exception_service.get_unresolved_exception_count(
db, order_id
)
if unresolved_count > 0:
raise OrderHasUnresolvedExceptionsException(order_id, unresolved_count)
# Get inventory unit IDs from request or order
if confirm_request and confirm_request.inventory_unit_ids:
inventory_unit_ids = confirm_request.inventory_unit_ids

261
app/api/v1/vendor/order_item_exceptions.py vendored Normal file
View File

@@ -0,0 +1,261 @@
# app/api/v1/vendor/order_item_exceptions.py
"""
Vendor API endpoints for order item exception management.
Provides vendor-level management of:
- Listing vendor's own exceptions
- Resolving exceptions by assigning products
- Exception statistics for vendor dashboard
"""
import logging
from fastapi import APIRouter, Depends, Path, Query
from sqlalchemy.orm import Session
from app.api.deps import get_current_vendor_api
from app.core.database import get_db
from app.services.order_item_exception_service import order_item_exception_service
from models.database.user import User
from models.schema.order_item_exception import (
BulkResolveRequest,
BulkResolveResponse,
IgnoreExceptionRequest,
OrderItemExceptionListResponse,
OrderItemExceptionResponse,
OrderItemExceptionStats,
ResolveExceptionRequest,
)
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/order-exceptions", tags=["Vendor Order Item Exceptions"])
# ============================================================================
# Exception Listing and Stats
# ============================================================================
@router.get("", response_model=OrderItemExceptionListResponse)
def list_vendor_exceptions(
status: str | None = Query(
None,
pattern="^(pending|resolved|ignored)$",
description="Filter by status"
),
search: str | None = Query(
None,
description="Search in GTIN, product name, SKU, or order number"
),
skip: int = Query(0, ge=0),
limit: int = Query(50, ge=1, le=200),
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
List order item exceptions for the authenticated vendor.
Returns exceptions for unmatched products during marketplace order imports.
"""
vendor_id = current_user.token_vendor_id
exceptions, total = order_item_exception_service.get_pending_exceptions(
db=db,
vendor_id=vendor_id,
status=status,
search=search,
skip=skip,
limit=limit,
)
# Enrich with order info
response_items = []
for exc in exceptions:
item = OrderItemExceptionResponse.model_validate(exc)
if exc.order_item and exc.order_item.order:
order = exc.order_item.order
item.order_number = order.order_number
item.order_id = order.id
item.order_date = order.order_date
item.order_status = order.status
response_items.append(item)
return OrderItemExceptionListResponse(
exceptions=response_items,
total=total,
skip=skip,
limit=limit,
)
@router.get("/stats", response_model=OrderItemExceptionStats)
def get_vendor_exception_stats(
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
Get exception statistics for the authenticated vendor.
Returns counts of pending, resolved, and ignored exceptions.
"""
vendor_id = current_user.token_vendor_id
stats = order_item_exception_service.get_exception_stats(db, vendor_id)
return OrderItemExceptionStats(**stats)
# ============================================================================
# Exception Details
# ============================================================================
@router.get("/{exception_id}", response_model=OrderItemExceptionResponse)
def get_vendor_exception(
exception_id: int = Path(..., description="Exception ID"),
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
Get details of a single exception (vendor-scoped).
"""
vendor_id = current_user.token_vendor_id
# Pass vendor_id for scoped access
exception = order_item_exception_service.get_exception_by_id(
db, exception_id, vendor_id
)
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
return response
# ============================================================================
# Exception Resolution
# ============================================================================
@router.post("/{exception_id}/resolve", response_model=OrderItemExceptionResponse)
def resolve_vendor_exception(
exception_id: int = Path(..., description="Exception ID"),
request: ResolveExceptionRequest = ...,
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
Resolve an exception by assigning a product (vendor-scoped).
This updates the order item's product_id and marks the exception as resolved.
"""
vendor_id = current_user.token_vendor_id
exception = order_item_exception_service.resolve_exception(
db=db,
exception_id=exception_id,
product_id=request.product_id,
resolved_by=current_user.id,
notes=request.notes,
vendor_id=vendor_id, # Vendor-scoped access
)
db.commit()
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
logger.info(
f"Vendor user {current_user.id} resolved exception {exception_id} "
f"with product {request.product_id}"
)
return response
@router.post("/{exception_id}/ignore", response_model=OrderItemExceptionResponse)
def ignore_vendor_exception(
exception_id: int = Path(..., description="Exception ID"),
request: IgnoreExceptionRequest = ...,
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
Mark an exception as ignored (vendor-scoped).
Note: Ignored exceptions still block order confirmation.
Use this when a product will never be matched (e.g., discontinued).
"""
vendor_id = current_user.token_vendor_id
exception = order_item_exception_service.ignore_exception(
db=db,
exception_id=exception_id,
resolved_by=current_user.id,
notes=request.notes,
vendor_id=vendor_id, # Vendor-scoped access
)
db.commit()
response = OrderItemExceptionResponse.model_validate(exception)
if exception.order_item and exception.order_item.order:
order = exception.order_item.order
response.order_number = order.order_number
response.order_id = order.id
response.order_date = order.order_date
response.order_status = order.status
logger.info(
f"Vendor user {current_user.id} ignored exception {exception_id}: {request.notes}"
)
return response
# ============================================================================
# Bulk Operations
# ============================================================================
@router.post("/bulk-resolve", response_model=BulkResolveResponse)
def bulk_resolve_vendor_exceptions(
request: BulkResolveRequest,
current_user: User = Depends(get_current_vendor_api),
db: Session = Depends(get_db),
):
"""
Bulk resolve all pending exceptions for a GTIN (vendor-scoped).
Useful when a new product is imported and multiple orders have
items with the same unmatched GTIN.
"""
vendor_id = current_user.token_vendor_id
resolved_count = order_item_exception_service.bulk_resolve_by_gtin(
db=db,
vendor_id=vendor_id,
gtin=request.gtin,
product_id=request.product_id,
resolved_by=current_user.id,
notes=request.notes,
)
db.commit()
logger.info(
f"Vendor user {current_user.id} bulk resolved {resolved_count} exceptions "
f"for GTIN {request.gtin} with product {request.product_id}"
)
return BulkResolveResponse(
resolved_count=resolved_count,
gtin=request.gtin,
product_id=request.product_id,
)