Complete shop API consolidation to /api/v1/shop/* with middleware-based vendor context

## API Migration (Complete) ### New Shop API Endpoints Created - **Products API** (app/api/v1/shop/products.py) - GET /api/v1/shop/products - Product catalog with pagination/search/filters - GET /api/v1/shop/products/{id} - Product details - **Cart API** (app/api/v1/shop/cart.py) - GET /api/v1/shop/cart/{session_id} - Get cart - POST /api/v1/shop/cart/{session_id}/items - Add to cart - PUT /api/v1/shop/cart/{session_id}/items/{product_id} - Update quantity - DELETE /api/v1/shop/cart/{session_id}/items/{product_id} - Remove item - DELETE /api/v1/shop/cart/{session_id} - Clear cart - **Orders API** (app/api/v1/shop/orders.py) - POST /api/v1/shop/orders - Place order (authenticated) - GET /api/v1/shop/orders - Order history (authenticated) - GET /api/v1/shop/orders/{id} - Order details (authenticated) - **Auth API** (app/api/v1/shop/auth.py) - POST /api/v1/shop/auth/register - Customer registration - POST /api/v1/shop/auth/login - Customer login (sets cookie at path=/shop) - POST /api/v1/shop/auth/logout - Customer logout - POST /api/v1/shop/auth/forgot-password - Password reset request - POST /api/v1/shop/auth/reset-password - Password reset **Total: 18 new shop API endpoints** ### Middleware Enhancement Updated VendorContextMiddleware (middleware/vendor_context.py): - Added is_shop_api_request() to detect /api/v1/shop/* routes - Added extract_vendor_from_referer() to extract vendor from Referer header - Supports path-based: /vendors/wizamart/shop/* → wizamart - Supports subdomain: wizamart.platform.com → wizamart - Supports custom domain: customshop.com → customshop.com - Modified dispatch() to handle shop API specially (no longer skips) - Vendor context now injected into request.state.vendor for shop API calls ### Frontend Migration (Complete) Updated all shop templates to use new API endpoints: - app/templates/shop/account/login.html - Updated login endpoint - app/templates/shop/account/register.html - Updated register endpoint - app/templates/shop/product.html - Updated 4 API calls (products, cart) - app/templates/shop/cart.html - Updated 3 API calls (get, update, delete) - app/templates/shop/products.html - Activated product loading from API **Total: 9 API endpoint migrations across 5 templates** ### Old Endpoint Cleanup (Complete) Removed deprecated /api/v1/public/vendors/* shop endpoints: - Deleted app/api/v1/public/vendors/auth.py - Deleted app/api/v1/public/vendors/products.py - Deleted app/api/v1/public/vendors/cart.py - Deleted app/api/v1/public/vendors/orders.py - Deleted app/api/v1/public/vendors/payments.py (empty) - Deleted app/api/v1/public/vendors/search.py (empty) - Deleted app/api/v1/public/vendors/shop.py (empty) Updated app/api/v1/public/__init__.py to only include vendor lookup endpoints: - GET /api/v1/public/vendors/by-code/{code} - GET /api/v1/public/vendors/by-subdomain/{subdomain} - GET /api/v1/public/vendors/{id}/info **Result: Only 3 truly public endpoints remain** ### Error Page Improvements Updated all shop error templates to use base_url: - app/templates/shop/errors/*.html (10 files) - Updated error_renderer.py to calculate base_url from vendor context - Links now work correctly for path-based, subdomain, and custom domain access ### CMS Route Handler Added catch-all CMS route to app/routes/vendor_pages.py: - Handles /{vendor_code}/{slug} for content pages - Uses content_page_service for two-tier lookup (vendor override → platform default) ### Template Architecture Fix Updated app/templates/shop/base.html: - Changed x-data to use {% block alpine_data %} for component override - Allows pages to specify custom Alpine.js components - Enables page-specific state while extending shared shopLayoutData() ### Documentation (Complete) Created comprehensive documentation: - docs/api/shop-api-reference.md - Complete API reference with examples - docs/architecture/API_CONSOLIDATION_PROPOSAL.md - Analysis of 3 options - docs/architecture/API_MIGRATION_STATUS.md - Migration tracking (100% complete) - Updated docs/api/index.md - Added Shop API section - Updated docs/frontend/shop/architecture.md - New API structure and component pattern ## Benefits Achieved ### Cleaner URLs (~40% shorter) Before: /api/v1/public/vendors/{vendor_id}/products After: /api/v1/shop/products ### Better Architecture - Middleware-driven vendor context (no manual vendor_id passing) - Proper separation of concerns (public vs shop vs vendor APIs) - Consistent authentication pattern - RESTful design ### Developer Experience - No need to track vendor_id in frontend state - Automatic vendor context from Referer header - Simpler API calls - Better documentation ## Testing - Verified middleware extracts vendor from Referer correctly - Tested all shop API endpoints with vendor context - Confirmed products page loads and displays products - Verified error pages show correct links - No old API references remain in templates Migration Status: ✅ 100% Complete (8/8 success criteria met) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-22 23:03:05 +01:00
parent 0d7915c275
commit 5a9f44f3d1
38 changed files with 3322 additions and 875 deletions
--- a/docs/frontend/shop/architecture.md
+++ b/docs/frontend/shop/architecture.md
@@ -289,8 +289,13 @@ Example from base.html:
  <script src="{{ url_for('static', path='shared/js/api-client.js') }}"></script>
  <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

-Alpine.js Component (shop-layout.js):
+Alpine.js Component Architecture:
 ──────────────────────────────────────────────────────────────────
+
+⭐ BASE COMPONENT (shop-layout.js):
+
+Provides shared functionality for all shop pages:
+
  function shopLayoutData() {
      return {
          // Theme state
@@ -339,6 +344,10 @@ Alpine.js Component (shop-layout.js):
              localStorage.setItem('shop-theme',
                  this.dark ? 'dark' : 'light');
              shopLog.debug('Theme toggled:', this.dark ? 'dark' : 'light');
+          },
+
+          showToast(message, type = 'info') {
+              // Toast notification implementation
          }
      };
  }
@@ -346,13 +355,76 @@ Alpine.js Component (shop-layout.js):
  // Make globally available
  window.shopLayoutData = shopLayoutData;

+⭐ PAGE-SPECIFIC COMPONENTS:
+
+Each page extends shopLayoutData() for page-specific functionality:
+
+  // Example: products.html
+  document.addEventListener('alpine:init', () => {
+      Alpine.data('shopProducts', () => ({
+          ...shopLayoutData(),  // Extend base component
+
+          // Page-specific state
+          products: [],
+          loading: true,
+          filters: { search: '', category: '' },
+
+          // Override init to add page-specific initialization
+          async init() {
+              shopLog.info('Products page initializing...');
+              this.loadCart();  // From shopLayoutData
+              await this.loadProducts();  // Page-specific
+          },
+
+          // Page-specific methods
+          async loadProducts() {
+              const response = await fetch('/api/v1/shop/products');
+              const data = await response.json();
+              this.products = data.products;
+              this.loading = false;
+          }
+      }));
+  });
+
 Template Usage:
 ──────────────────────────────────────────────────────────────────
-  {# In base.html #}
-  <html x-data="shopLayoutData()" x-bind:class="{ 'dark': dark }">

-  {# In page templates #}
-  {% block alpine_data %}shopLayoutData(){% endblock %}
+  {# In base.html - uses block to allow override #}
+  <html x-data="{% block alpine_data %}shopLayoutData(){% endblock %}"
+        x-bind:class="{ 'dark': dark }">
+
+  {# In products.html - overrides to use page-specific component #}
+  {% block alpine_data %}shopProducts(){% endblock %}
+
+  {# In home.html - uses default base component #}
+  {# No block override needed, inherits shopLayoutData() #}
+
+⭐ COMPONENT HIERARCHY:
+
+  shopLayoutData()           ← Base component (shared state & methods)
+      ↓
+  shopProducts()             ← Products page (extends base + products state)
+  shopCart()                 ← Cart page (extends base + cart state)
+  shopCheckout()             ← Checkout page (extends base + order state)
+  shopAccount()              ← Account page (extends base + user state)
+
+Benefits:
+  ✅ Shared functionality (theme, cart, toasts) available on all pages
+  ✅ Each page has its own state and methods
+  ✅ DRY - base functionality defined once
+  ✅ Flexible - pages can override init() or add new methods
+
+Tradeoffs:
+  ⚠️  One component per page (not multiple components)
+  ⚠️  All page state is at root level
+  ⚠️  Can't easily split page into independent sub-components
+
+Best Practices:
+  1. Always extend shopLayoutData() in page components
+  2. Override init() if you need page-specific initialization
+  3. Call parent methods when needed (this.loadCart(), this.showToast())
+  4. Keep page-specific state in the page component
+  5. Keep shared state in shopLayoutData()

 Responsibilities:
  ✅ Load products from API
@@ -367,14 +439,34 @@ Responsibilities:
 Layer 5: API (REST)
 ──────────────────────────────────────────────────────────────────
 Purpose: Product Data + Cart + Orders
-Location: app/api/v1/shop/*.py (not pages.py)
+Location: app/api/v1/shop/*.py
+
+⭐ NEW API STRUCTURE (as of 2025-11-22):
+All shop endpoints use middleware-based vendor context.
+NO vendor_id or vendor_code in URLs!

 Example Endpoints:
-  GET    /api/v1/shop/{vendor_code}/products
-  GET    /api/v1/shop/{vendor_code}/products/{id}
-  GET    /api/v1/shop/{vendor_code}/categories
-  POST   /api/v1/shop/{vendor_code}/search
-  POST   /api/v1/shop/{vendor_code}/cart/checkout
+  GET    /api/v1/shop/products              ← Product catalog
+  GET    /api/v1/shop/products/{id}         ← Product details
+  GET    /api/v1/shop/products?search=...   ← Search products
+  GET    /api/v1/shop/cart/{session_id}     ← Get cart
+  POST   /api/v1/shop/cart/{session_id}/items  ← Add to cart
+  PUT    /api/v1/shop/cart/{session_id}/items/{product_id}  ← Update item
+  DELETE /api/v1/shop/cart/{session_id}/items/{product_id}  ← Remove item
+  POST   /api/v1/shop/orders                ← Place order (auth required)
+  GET    /api/v1/shop/orders                ← Order history (auth required)
+  POST   /api/v1/shop/auth/login            ← Customer login
+  POST   /api/v1/shop/auth/register         ← Customer registration
+  GET    /api/v1/shop/content-pages/navigation  ← CMS navigation
+  GET    /api/v1/shop/content-pages/{slug}  ← CMS page content
+
+How Vendor Context Works:
+  1. Browser makes API call from shop page (e.g., /vendors/wizamart/shop/products)
+  2. Browser automatically sends Referer header: http://localhost:8000/vendors/wizamart/shop/products
+  3. VendorContextMiddleware extracts vendor from Referer header
+  4. Middleware sets request.state.vendor = <Vendor: wizamart>
+  5. API endpoint accesses vendor: vendor = request.state.vendor
+  6. No vendor_id needed in URL!


 🔄 DATA FLOW
@@ -382,16 +474,17 @@ Example Endpoints:

 Page Load Flow:
 ──────────────────────────────────────────────────────────────────
-  1. Customer → visits acme-shop.com
-  2. Vendor Middleware → Identifies "ACME" vendor
+  1. Customer → visits acme-shop.com (or /vendors/acme/shop/products)
+  2. Vendor Middleware → Identifies "ACME" vendor from domain/path
  3. Theme Middleware → Loads ACME's theme config
-  4. FastAPI → Renders shop/home.html
+  4. FastAPI → Renders shop/products.html
  5. Browser → Receives HTML with theme CSS variables
  6. Alpine.js → init() executes
-  7. JavaScript → GET /api/v1/shop/ACME/products
-  8. API → Returns product list JSON
-  9. Alpine.js → Updates products array
-  10. Browser → DOM updates with product cards
+  7. JavaScript → GET /api/v1/shop/products (with Referer header)
+  8. Middleware → Extracts vendor from Referer, injects into request.state
+  9. API → Returns product list JSON for ACME vendor
+  10. Alpine.js → Updates products array
+  11. Browser → DOM updates with product cards

 Add to Cart Flow:
 ──────────────────────────────────────────────────────────────────
@@ -408,11 +501,12 @@ Checkout Flow:
  1. Customer → Goes to /cart
  2. Page → Loads cart from localStorage
  3. Customer → Fills checkout form
-  4. Alpine.js → POST /api/v1/shop/ACME/cart/checkout
-  5. API → Creates order + payment intent
-  6. Alpine.js → Redirects to payment
-  7. Payment → Completes
-  8. Redirect → /order/{order_id}/confirmation
+  4. Alpine.js → POST /api/v1/shop/orders (with Referer header)
+  5. Middleware → Extracts vendor from Referer
+  6. API → Creates order + payment intent for vendor
+  7. Alpine.js → Redirects to payment
+  8. Payment → Completes
+  9. Redirect → /order/{order_id}/confirmation


 🎨 MULTI-THEME SYSTEM
@@ -621,11 +715,13 @@ Account Features:
  ✅ Profile management

 Auth Flow:
-  1. Login/Register → POST /api/v1/shop/auth/login
-  2. API → Return JWT token
-  3. JavaScript → Store in localStorage
-  4. API Client → Add to authenticated requests
-  5. Optional → Use account features
+  1. Login/Register → POST /api/v1/shop/auth/login (with Referer header)
+  2. Middleware → Extracts vendor from Referer
+  3. API → Validates credentials for vendor's customers
+  4. API → Returns JWT token + sets cookie (path=/shop)
+  5. JavaScript → Store token in localStorage
+  6. API Client → Add token to authenticated requests
+  7. Optional → Use account features (orders, profile, etc.)


 📡 API CLIENT
@@ -633,15 +729,26 @@ Auth Flow:

 Location: app/static/shared/js/api-client.js

+⭐ NEW USAGE (as of 2025-11-22):
+No vendor_code needed! Vendor extracted from Referer header automatically.
+
 Usage:
-  const products = await apiClient.get(
-      `/api/v1/shop/${vendorCode}/products`
-  );
-  
-  const order = await apiClient.post(
-      `/api/v1/shop/${vendorCode}/checkout`,
-      orderData
-  );
+  // Product catalog
+  const products = await fetch('/api/v1/shop/products');
+
+  // Add to cart
+  const response = await fetch('/api/v1/shop/cart/session123/items', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ product_id: 1, quantity: 2 })
+  });
+
+  // Place order
+  const order = await fetch('/api/v1/shop/orders', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(orderData)
+  });

 Features:
  ✅ Automatic error handling
@@ -734,8 +841,7 @@ Components:
  • Category cards
  • About vendor section
 Data Sources:
-  • GET /api/v1/shop/{code}/products?featured=true
-  • GET /api/v1/shop/{code}/categories
+  • GET /api/v1/shop/products?is_featured=true

 /products
 ──────────────────────────────────────────────────────────────────
@@ -746,7 +852,8 @@ Components:
  • Sort dropdown
  • Pagination
 Data Sources:
-  • GET /api/v1/shop/{code}/products
+  • GET /api/v1/shop/products?skip=0&limit=20
+  • GET /api/v1/shop/products?search=query
  • Filters applied client-side or server-side

 /products/{product_id}
@@ -759,8 +866,8 @@ Components:
  • Related products
  • Reviews (optional)
 Data Sources:
-  • GET /api/v1/shop/{code}/products/{id}
-  • GET /api/v1/shop/{code}/products/{id}/related
+  • GET /api/v1/shop/products/{id}
+  • GET /api/v1/shop/products?limit=4 (related products)

 /cart
 ──────────────────────────────────────────────────────────────────
@@ -784,7 +891,7 @@ Components:
  • Order summary
  • Submit button
 Data Sources:
-  • POST /api/v1/shop/{code}/checkout
+  • POST /api/v1/shop/orders
  • Stripe/PayPal integration

 /search
@@ -796,7 +903,7 @@ Components:
  • Filter options
  • Sort options
 Data Sources:
-  • POST /api/v1/shop/{code}/search
+  • GET /api/v1/shop/products?search=query

 /category/{category_slug}
 ──────────────────────────────────────────────────────────────────
@@ -807,7 +914,7 @@ Components:
  • Subcategories
  • Filters
 Data Sources:
-  • GET /api/v1/shop/{code}/categories/{slug}/products
+  • GET /api/v1/shop/products?category={slug}

 /about
 ──────────────────────────────────────────────────────────────────
@@ -830,7 +937,8 @@ Components:
  • Business hours
  • Social links
 Data Sources:
-  • POST /api/v1/shop/{code}/contact
+  • CMS content page (GET /api/v1/shop/content-pages/contact)
+  • Form submission to vendor email


 🎓 LEARNING PATH