feat(modules): create cart, catalog, and checkout e-commerce modules

Phase 3 of storefront restructure plan - create dedicated modules for
e-commerce functionality:

- cart: Shopping cart management with storefront API routes
  - CartItem model with cents-based pricing
  - CartService for cart operations
  - Storefront routes for cart CRUD operations

- catalog: Product catalog browsing for customers
  - CatalogService for public product queries
  - Storefront routes for product listing/search/details

- checkout: Order creation from cart (placeholder)
  - CheckoutService stub for future cart-to-order conversion
  - Schemas for checkout flow

These modules separate e-commerce concerns from core platform
concerns (customer auth), enabling non-commerce platforms.

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

app/modules/checkout/routes/api/__init__.py

@@ -0,0 +1,9 @@
+# app/modules/checkout/routes/api/__init__.py
+"""Checkout module API routes."""
+
+from app.modules.checkout.routes.api.storefront import router as storefront_router
+
+# Tag for OpenAPI documentation
+STOREFRONT_TAG = "Checkout (Storefront)"
+
+__all__ = ["storefront_router", "STOREFRONT_TAG"]

app/modules/checkout/routes/api/storefront.py

@@ -0,0 +1,99 @@
+# app/modules/checkout/routes/api/storefront.py
+"""
+Checkout Module - Storefront API Routes
+
+Public endpoints for checkout in storefront.
+Uses vendor from middleware context (VendorContextMiddleware).
+
+Note: These endpoints are placeholders for future checkout functionality.
+
+Vendor Context: require_vendor_context() - detects vendor from URL/subdomain/domain
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.orm import Session
+
+from app.core.database import get_db
+from app.modules.checkout.schemas import (
+    CheckoutRequest,
+    CheckoutResponse,
+    CheckoutSessionResponse,
+)
+from app.modules.checkout.services import checkout_service
+from middleware.vendor_context import require_vendor_context
+from models.database.vendor import Vendor
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+@router.post("/checkout/session", response_model=CheckoutSessionResponse)
+def create_checkout_session(
+    checkout_data: CheckoutRequest,
+    vendor: Vendor = Depends(require_vendor_context()),
+    db: Session = Depends(get_db),
+) -> CheckoutSessionResponse:
+    """
+    Create a checkout session from cart.
+
+    Validates the cart and prepares for checkout.
+    Vendor is automatically determined from request context.
+
+    Request Body:
+    - session_id: Cart session ID
+    - shipping_address: Shipping address details
+    - billing_same_as_shipping: Use shipping for billing (default: true)
+    - billing_address: Billing address if different
+    - customer_email: Email for order confirmation
+    - customer_note: Optional note
+    """
+    logger.info(
+        f"[CHECKOUT_STOREFRONT] create_checkout_session for vendor {vendor.id}",
+        extra={
+            "vendor_id": vendor.id,
+            "session_id": checkout_data.session_id,
+        },
+    )
+
+    result = checkout_service.create_checkout_session(
+        db=db,
+        vendor_id=vendor.id,
+        session_id=checkout_data.session_id,
+    )
+
+    return CheckoutSessionResponse(**result)
+
+
+@router.post("/checkout/complete", response_model=CheckoutResponse)
+def complete_checkout(
+    checkout_session_id: str,
+    vendor: Vendor = Depends(require_vendor_context()),
+    db: Session = Depends(get_db),
+) -> CheckoutResponse:
+    """
+    Complete checkout and create order.
+
+    Converts the cart to an order and processes payment.
+    Vendor is automatically determined from request context.
+
+    Query Parameters:
+    - checkout_session_id: The checkout session ID from create_checkout_session
+    """
+    logger.info(
+        f"[CHECKOUT_STOREFRONT] complete_checkout for vendor {vendor.id}",
+        extra={
+            "vendor_id": vendor.id,
+            "checkout_session_id": checkout_session_id,
+        },
+    )
+
+    result = checkout_service.complete_checkout(
+        db=db,
+        vendor_id=vendor.id,
+        checkout_session_id=checkout_session_id,
+    )
+    db.commit()
+
+    return CheckoutResponse(**result)