refactor(customers): migrate routes to module with auto-discovery

- Move customer route implementations to app/modules/customers/routes/
- Convert legacy app/api/v1/{admin,vendor}/customers.py to re-exports
- Update router registrations to use module routers with access control
- Fix CustomerListResponse pagination (page/per_page/total_pages)
- Update URL routing docs to use storefront consistently
- Fix mkdocs.yml nav references (shop -> storefront)
- Fix broken doc links in logging.md and cdn-fallback-strategy.md

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

app/api/v1/admin/__init__.py

@@ -49,7 +49,7 @@ from . import (
     code_quality,
     companies,
     # content_pages - moved to app.modules.cms.routes.api.admin
-    customers,
+    # customers - moved to app.modules.customers.routes.admin
     dashboard,
     email_templates,
     features,
@@ -92,6 +92,9 @@ from app.modules.marketplace.routes.api.admin import admin_letzshop_router as le
 # CMS module router
 from app.modules.cms.routes.api.admin import router as cms_admin_router
 
+# Customers module router
+from app.modules.customers.routes.admin import admin_router as customers_admin_router
+
 # Create admin router
 router = APIRouter()
 
@@ -149,8 +152,9 @@ router.include_router(users.router, tags=["admin-users"])
 # Include admin user management endpoints (super admin only)
 router.include_router(admin_users.router, tags=["admin-admin-users"])
 
-# Include customer management endpoints
-router.include_router(customers.router, tags=["admin-customers"])
+# Include customers module router (with module access control)
+router.include_router(customers_admin_router, tags=["admin-customers"])
+# Legacy: router.include_router(customers.router, tags=["admin-customers"])
 
 
 # ============================================================================

app/api/v1/admin/customers.py

@@ -1,112 +1,31 @@
 # app/api/v1/admin/customers.py
 """
-Customer management endpoints for admin.
+LEGACY LOCATION - Re-exports from module for backwards compatibility.
 
-Provides admin-level access to customer data across all vendors.
+The canonical implementation is now in:
+    app/modules/customers/routes/admin.py
+
+This file exists to maintain backwards compatibility with code that
+imports from the old location. All new code should import directly
+from the module:
+
+    from app.modules.customers.routes.admin import admin_router
 """
 
-from fastapi import APIRouter, Depends, 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.admin_customer_service import admin_customer_service
-from models.schema.auth import UserContext
-from app.modules.customers.schemas import (
-    CustomerDetailResponse,
-    CustomerListResponse,
-    CustomerMessageResponse,
-    CustomerStatisticsResponse,
+from app.modules.customers.routes.admin import (
+    admin_router,
+    router,
+    list_customers,
+    get_customer_stats,
+    get_customer,
+    toggle_customer_status,
 )
 
-router = APIRouter(prefix="/customers")
-
-
-# ============================================================================
-# List Customers
-# ============================================================================
-
-
-@router.get("", response_model=CustomerListResponse)
-def list_customers(
-    vendor_id: int | None = Query(None, description="Filter by vendor ID"),
-    search: str = Query("", description="Search by email, name, or customer number"),
-    is_active: bool | None = Query(None, description="Filter by active status"),
-    skip: int = Query(0, ge=0),
-    limit: int = Query(20, ge=1, le=100),
-    db: Session = Depends(get_db),
-    current_admin: UserContext = Depends(get_current_admin_api),
-) -> CustomerListResponse:
-    """
-    Get paginated list of customers across all vendors.
-
-    Admin can filter by vendor, search, and active status.
-    """
-    customers, total = admin_customer_service.list_customers(
-        db=db,
-        vendor_id=vendor_id,
-        search=search if search else None,
-        is_active=is_active,
-        skip=skip,
-        limit=limit,
-    )
-
-    return CustomerListResponse(
-        customers=customers,
-        total=total,
-        skip=skip,
-        limit=limit,
-    )
-
-
-# ============================================================================
-# Customer Statistics
-# ============================================================================
-
-
-@router.get("/stats", response_model=CustomerStatisticsResponse)
-def get_customer_stats(
-    vendor_id: int | None = Query(None, description="Filter by vendor ID"),
-    db: Session = Depends(get_db),
-    current_admin: UserContext = Depends(get_current_admin_api),
-) -> CustomerStatisticsResponse:
-    """Get customer statistics."""
-    stats = admin_customer_service.get_customer_stats(db=db, vendor_id=vendor_id)
-    return CustomerStatisticsResponse(**stats)
-
-
-# ============================================================================
-# Get Single Customer
-# ============================================================================
-
-
-@router.get("/{customer_id}", response_model=CustomerDetailResponse)
-def get_customer(
-    customer_id: int,
-    db: Session = Depends(get_db),
-    current_admin: UserContext = Depends(get_current_admin_api),
-) -> CustomerDetailResponse:
-    """Get customer details by ID."""
-    customer = admin_customer_service.get_customer(db=db, customer_id=customer_id)
-    return CustomerDetailResponse(**customer)
-
-
-# ============================================================================
-# Toggle Customer Status
-# ============================================================================
-
-
-@router.patch("/{customer_id}/toggle-status", response_model=CustomerMessageResponse)
-def toggle_customer_status(
-    customer_id: int,
-    db: Session = Depends(get_db),
-    current_admin: UserContext = Depends(get_current_admin_api),
-) -> CustomerMessageResponse:
-    """Toggle customer active status."""
-    result = admin_customer_service.toggle_customer_status(
-        db=db,
-        customer_id=customer_id,
-        admin_email=current_admin.email,
-    )
-    db.commit()
-    return CustomerMessageResponse(message=result["message"])
+__all__ = [
+    "admin_router",
+    "router",
+    "list_customers",
+    "get_customer_stats",
+    "get_customer",
+    "toggle_customer_status",
+]