feat: add partial shipment support (Phase 3)

- Add shipped_quantity field to OrderItem for tracking partial fulfillment
- Add partially_shipped order status for orders with partial shipments
- Add fulfill_item method for shipping individual items with quantities
- Add get_shipment_status method for detailed shipment tracking
- Add vendor API endpoints for partial shipment operations:
  - GET /orders/{id}/shipment-status - Get item-level shipment status
  - POST /orders/{id}/items/{item_id}/ship - Ship specific item quantity
- Automatic status updates: partially_shipped when some items shipped,
  shipped when all items fully shipped
- Migration to add shipped_quantity column with upgrade for existing data
- Update documentation with partial shipment usage examples

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/api/v1/vendor/orders.py

@@ -9,10 +9,12 @@ The get_current_vendor_api dependency guarantees token_vendor_id is present.
 import logging
 
 from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel, Field
 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_inventory_service import order_inventory_service
 from app.services.order_service import order_service
 from models.database.user import User
 from models.schema.order import (
@@ -114,3 +116,154 @@ def update_order_status(
     )
 
     return OrderResponse.model_validate(order)
+
+
+# ============================================================================
+# Partial Shipment Endpoints
+# ============================================================================
+
+
+class ShipItemRequest(BaseModel):
+    """Request to ship specific quantity of an order item."""
+
+    quantity: int | None = Field(
+        None, ge=1, description="Quantity to ship (default: remaining quantity)"
+    )
+
+
+class ShipItemResponse(BaseModel):
+    """Response from shipping an item."""
+
+    order_id: int
+    item_id: int
+    fulfilled_quantity: int
+    shipped_quantity: int | None = None
+    remaining_quantity: int | None = None
+    is_fully_shipped: bool | None = None
+    message: str | None = None
+
+
+class ShipmentStatusItemResponse(BaseModel):
+    """Item-level shipment status."""
+
+    item_id: int
+    product_id: int
+    product_name: str
+    quantity: int
+    shipped_quantity: int
+    remaining_quantity: int
+    is_fully_shipped: bool
+    is_partially_shipped: bool
+
+
+class ShipmentStatusResponse(BaseModel):
+    """Order shipment status response."""
+
+    order_id: int
+    order_number: str
+    order_status: str
+    is_fully_shipped: bool
+    is_partially_shipped: bool
+    shipped_item_count: int
+    total_item_count: int
+    total_shipped_units: int
+    total_ordered_units: int
+    items: list[ShipmentStatusItemResponse]
+
+
+@router.get("/{order_id}/shipment-status", response_model=ShipmentStatusResponse)
+def get_shipment_status(
+    order_id: int,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Get detailed shipment status for an order.
+
+    Returns item-level shipment status showing what has been shipped
+    and what remains. Useful for partial shipment tracking.
+
+    Requires Authorization header (API endpoint).
+    """
+    result = order_inventory_service.get_shipment_status(
+        db=db,
+        vendor_id=current_user.token_vendor_id,
+        order_id=order_id,
+    )
+
+    return ShipmentStatusResponse(
+        order_id=result["order_id"],
+        order_number=result["order_number"],
+        order_status=result["order_status"],
+        is_fully_shipped=result["is_fully_shipped"],
+        is_partially_shipped=result["is_partially_shipped"],
+        shipped_item_count=result["shipped_item_count"],
+        total_item_count=result["total_item_count"],
+        total_shipped_units=result["total_shipped_units"],
+        total_ordered_units=result["total_ordered_units"],
+        items=[ShipmentStatusItemResponse(**item) for item in result["items"]],
+    )
+
+
+@router.post("/{order_id}/items/{item_id}/ship", response_model=ShipItemResponse)
+def ship_order_item(
+    order_id: int,
+    item_id: int,
+    request: ShipItemRequest | None = None,
+    current_user: User = Depends(get_current_vendor_api),
+    db: Session = Depends(get_db),
+):
+    """
+    Ship a specific order item (supports partial shipment).
+
+    Fulfills inventory and updates the item's shipped quantity.
+    If quantity is not specified, ships the remaining quantity.
+
+    Example use cases:
+    - Ship all of an item: POST /orders/{id}/items/{item_id}/ship
+    - Ship partial: POST /orders/{id}/items/{item_id}/ship with {"quantity": 2}
+
+    Requires Authorization header (API endpoint).
+    """
+    quantity = request.quantity if request else None
+
+    result = order_inventory_service.fulfill_item(
+        db=db,
+        vendor_id=current_user.token_vendor_id,
+        order_id=order_id,
+        item_id=item_id,
+        quantity=quantity,
+        skip_missing=True,
+    )
+
+    # Update order status based on shipment state
+    order = order_service.get_order(db, current_user.token_vendor_id, order_id)
+
+    if order.is_fully_shipped and order.status != "shipped":
+        order_service.update_order_status(
+            db=db,
+            vendor_id=current_user.token_vendor_id,
+            order_id=order_id,
+            order_update=OrderUpdate(status="shipped"),
+        )
+        logger.info(f"Order {order.order_number} fully shipped")
+    elif order.is_partially_shipped and order.status not in (
+        "partially_shipped",
+        "shipped",
+    ):
+        order_service.update_order_status(
+            db=db,
+            vendor_id=current_user.token_vendor_id,
+            order_id=order_id,
+            order_update=OrderUpdate(status="partially_shipped"),
+        )
+        logger.info(f"Order {order.order_number} partially shipped")
+
+    db.commit()
+
+    logger.info(
+        f"Shipped item {item_id} of order {order_id}: "
+        f"{result.get('fulfilled_quantity', 0)} units"
+    )
+
+    return ShipItemResponse(**result)