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/catalog/services/__init__.py

@@ -0,0 +1,6 @@
+# app/modules/catalog/services/__init__.py
+"""Catalog module services."""
+
+from app.modules.catalog.services.catalog_service import catalog_service
+
+__all__ = ["catalog_service"]

app/modules/catalog/services/catalog_service.py

@@ -0,0 +1,183 @@
+# app/modules/catalog/services/catalog_service.py
+"""
+Catalog service for storefront product browsing.
+
+This module provides:
+- Public product catalog retrieval
+- Product search functionality
+- Product detail retrieval
+
+Note: This is distinct from the product_service which handles
+vendor product management. The catalog service is for public
+storefront operations only.
+"""
+
+import logging
+
+from sqlalchemy import or_
+from sqlalchemy.orm import Session, joinedload
+
+from app.exceptions import ProductNotFoundException, ValidationException
+from models.database.product import Product
+from models.database.product_translation import ProductTranslation
+
+logger = logging.getLogger(__name__)
+
+
+class CatalogService:
+    """Service for public catalog browsing operations."""
+
+    def get_product(self, db: Session, vendor_id: int, product_id: int) -> Product:
+        """
+        Get a product from vendor catalog.
+
+        Args:
+            db: Database session
+            vendor_id: Vendor ID
+            product_id: Product ID
+
+        Returns:
+            Product object
+
+        Raises:
+            ProductNotFoundException: If product not found
+        """
+        product = (
+            db.query(Product)
+            .filter(Product.id == product_id, Product.vendor_id == vendor_id)
+            .first()
+        )
+
+        if not product:
+            raise ProductNotFoundException(f"Product {product_id} not found")
+
+        return product
+
+    def get_catalog_products(
+        self,
+        db: Session,
+        vendor_id: int,
+        skip: int = 0,
+        limit: int = 100,
+        is_featured: bool | None = None,
+    ) -> tuple[list[Product], int]:
+        """
+        Get products in vendor catalog for public display.
+
+        Only returns active products visible to customers.
+
+        Args:
+            db: Database session
+            vendor_id: Vendor ID
+            skip: Pagination offset
+            limit: Pagination limit
+            is_featured: Filter by featured status
+
+        Returns:
+            Tuple of (products, total_count)
+        """
+        try:
+            # Always filter for active products only
+            query = db.query(Product).filter(
+                Product.vendor_id == vendor_id,
+                Product.is_active == True,
+            )
+
+            if is_featured is not None:
+                query = query.filter(Product.is_featured == is_featured)
+
+            total = query.count()
+            products = query.offset(skip).limit(limit).all()
+
+            return products, total
+
+        except Exception as e:
+            logger.error(f"Error getting catalog products: {str(e)}")
+            raise ValidationException("Failed to retrieve products")
+
+    def search_products(
+        self,
+        db: Session,
+        vendor_id: int,
+        query: str,
+        skip: int = 0,
+        limit: int = 50,
+        language: str = "en",
+    ) -> tuple[list[Product], int]:
+        """
+        Search products in vendor catalog.
+
+        Searches across:
+        - Product title and description (from translations)
+        - Product SKU, brand, and GTIN
+
+        Args:
+            db: Database session
+            vendor_id: Vendor ID
+            query: Search query string
+            skip: Pagination offset
+            limit: Pagination limit
+            language: Language for translation search (default: 'en')
+
+        Returns:
+            Tuple of (products, total_count)
+        """
+        try:
+            # Prepare search pattern for LIKE queries
+            search_pattern = f"%{query}%"
+
+            # Use subquery to get distinct IDs (PostgreSQL can't compare JSON for DISTINCT)
+            id_subquery = (
+                db.query(Product.id)
+                .outerjoin(
+                    ProductTranslation,
+                    (Product.id == ProductTranslation.product_id)
+                    & (ProductTranslation.language == language),
+                )
+                .filter(
+                    Product.vendor_id == vendor_id,
+                    Product.is_active == True,
+                )
+                .filter(
+                    or_(
+                        # Search in translations
+                        ProductTranslation.title.ilike(search_pattern),
+                        ProductTranslation.description.ilike(search_pattern),
+                        ProductTranslation.short_description.ilike(search_pattern),
+                        # Search in product fields
+                        Product.vendor_sku.ilike(search_pattern),
+                        Product.brand.ilike(search_pattern),
+                        Product.gtin.ilike(search_pattern),
+                    )
+                )
+                .distinct()
+                .subquery()
+            )
+
+            base_query = db.query(Product).filter(
+                Product.id.in_(db.query(id_subquery.c.id))
+            )
+
+            # Get total count
+            total = base_query.count()
+
+            # Get paginated results with eager loading for performance
+            products = (
+                base_query.options(joinedload(Product.translations))
+                .offset(skip)
+                .limit(limit)
+                .all()
+            )
+
+            logger.debug(
+                f"Search '{query}' for vendor {vendor_id}: {total} results"
+            )
+            return products, total
+
+        except Exception as e:
+            logger.error(f"Error searching products: {str(e)}")
+            raise ValidationException("Failed to search products")
+
+
+# Create service instance
+catalog_service = CatalogService()