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/cart/schemas/__init__.py

@@ -0,0 +1,20 @@
+# app/modules/cart/schemas/__init__.py
+"""Cart module Pydantic schemas."""
+
+from app.modules.cart.schemas.cart import (
+    AddToCartRequest,
+    UpdateCartItemRequest,
+    CartItemResponse,
+    CartResponse,
+    CartOperationResponse,
+    ClearCartResponse,
+)
+
+__all__ = [
+    "AddToCartRequest",
+    "UpdateCartItemRequest",
+    "CartItemResponse",
+    "CartResponse",
+    "CartOperationResponse",
+    "ClearCartResponse",
+]

app/modules/cart/schemas/cart.py

@@ -0,0 +1,91 @@
+# app/modules/cart/schemas/cart.py
+"""
+Pydantic schemas for shopping cart operations.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ============================================================================
+# Request Schemas
+# ============================================================================
+
+
+class AddToCartRequest(BaseModel):
+    """Request model for adding items to cart."""
+
+    product_id: int = Field(..., description="Product ID to add", gt=0)
+    quantity: int = Field(1, ge=1, description="Quantity to add")
+
+
+class UpdateCartItemRequest(BaseModel):
+    """Request model for updating cart item quantity."""
+
+    quantity: int = Field(..., ge=1, description="New quantity (must be >= 1)")
+
+
+# ============================================================================
+# Response Schemas
+# ============================================================================
+
+
+class CartItemResponse(BaseModel):
+    """Response model for a single cart item."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    product_id: int = Field(..., description="Product ID")
+    product_name: str = Field(..., description="Product name")
+    quantity: int = Field(..., description="Quantity in cart")
+    price: float = Field(..., description="Price per unit when added to cart")
+    line_total: float = Field(
+        ..., description="Total price for this line (price * quantity)"
+    )
+    image_url: str | None = Field(None, description="Product image URL")
+
+
+class CartResponse(BaseModel):
+    """Response model for shopping cart."""
+
+    vendor_id: int = Field(..., description="Vendor ID")
+    session_id: str = Field(..., description="Shopping session ID")
+    items: list[CartItemResponse] = Field(
+        default_factory=list, description="Cart items"
+    )
+    subtotal: float = Field(..., description="Subtotal of all items")
+    total: float = Field(..., description="Total amount (currently same as subtotal)")
+    item_count: int = Field(..., description="Total number of items in cart")
+
+    @classmethod
+    def from_service_dict(cls, cart_dict: dict) -> "CartResponse":
+        """
+        Create CartResponse from service layer dictionary.
+
+        This is a convenience method to convert the dictionary format
+        returned by cart_service into a proper Pydantic model.
+        """
+        items = [CartItemResponse(**item) for item in cart_dict.get("items", [])]
+        return cls(
+            vendor_id=cart_dict["vendor_id"],
+            session_id=cart_dict["session_id"],
+            items=items,
+            subtotal=cart_dict["subtotal"],
+            total=cart_dict["total"],
+            item_count=len(items),
+        )
+
+
+class CartOperationResponse(BaseModel):
+    """Response model for cart operations (add, update, remove)."""
+
+    message: str = Field(..., description="Operation result message")
+    product_id: int = Field(..., description="Product ID affected")
+    quantity: int | None = Field(
+        None, description="New quantity (for add/update operations)"
+    )
+
+
+class ClearCartResponse(BaseModel):
+    """Response model for clearing cart."""
+
+    message: str = Field(..., description="Operation result message")
+    items_removed: int = Field(..., description="Number of items removed from cart")