docs: add consolidated dev URL reference and migrate /shop to /storefront

- Add Development URL Quick Reference section to url-routing overview with all login URLs, entry points, and full examples - Replace /shop/ path segments with /storefront/ across 50 docs files - Update file references: shop_pages.py → storefront_pages.py, templates/shop/ → templates/storefront/, api/v1/shop/ → api/v1/storefront/ - Preserve domain references (orion.shop) and /store/ staff dashboard paths - Archive docs left unchanged (historical) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-25 13:23:44 +01:00
parent 3df75e2e78
commit d648c921b7
50 changed files with 1104 additions and 1049 deletions
--- a/docs/architecture/api-migration-status.md
+++ b/docs/architecture/api-migration-status.md
@@ -1,55 +1,55 @@
-# API Migration Status - `/api/v1/shop/*` Consolidation
+# API Migration Status - `/api/v1/storefront/*` Consolidation

 **Date:** 2025-11-22
 **Status:** 🎉 MIGRATION COMPLETE - All Phases Done
-**Decision:** Option 1 - Full Consolidation to `/api/v1/shop/*`
+**Decision:** Option 1 - Full Consolidation to `/api/v1/storefront/*`

 ---

 ## Progress Overview

-### ✅ Phase 1: New Shop API Endpoints (COMPLETE)
+### ✅ Phase 1: New Storefront API Endpoints (COMPLETE)

-All new shop endpoints have been created using middleware-based store context:
+All new storefront endpoints have been created using middleware-based store context:

 ### ✅ Middleware Update: Referer-Based Store Extraction (COMPLETE)

-Updated `StoreContextMiddleware` to support shop API routes:
- Added `is_shop_api_request()` method to detect `/api/v1/shop/*` routes
+Updated `StoreContextMiddleware` to support storefront API routes:
+- Added `is_storefront_api_request()` method to detect `/api/v1/storefront/*` routes
 - Added `extract_store_from_referer()` method to extract store from Referer/Origin headers
- Modified `dispatch()` to handle shop API routes specially (no longer skips them)
- Shop API now receives store context from the page that made the API call
+- Modified `dispatch()` to handle storefront API routes specially (no longer skips them)
+- Storefront API now receives store context from the page that made the API call

 **How it works:**
-1. Browser JavaScript on `/stores/orion/shop/products` calls `/api/v1/shop/products`
-2. Browser automatically sends `Referer: http://localhost:8000/stores/orion/shop/products`
+1. Browser JavaScript on `/storefront/orion/products` calls `/api/v1/storefront/products`
+2. Browser automatically sends `Referer: http://localhost:8000/storefront/orion/products`
 3. Middleware extracts `orion` from Referer path
 4. Queries database to get Store object
 5. Sets `request.state.store` for the API endpoint

 ### ✅ Phase 1a: Endpoint Testing (COMPLETE)

-Tested shop API endpoints with Referer header:
+Tested storefront API endpoints with Referer header:

 | Endpoint | Method | Test Result | Notes |
 |----------|--------|-------------|-------|
-| `/api/v1/shop/products` | GET | ✅ Working | Returns paginated product list |
-| `/api/v1/shop/products?search=Sample` | GET | ✅ Working | Search functionality works |
-| `/api/v1/shop/products?is_featured=true` | GET | ✅ Working | Featured filter works |
-| `/api/v1/shop/products/{id}` | GET | ✅ Working | Product details returned |
-| `/api/v1/shop/cart/{session_id}` | GET | ✅ Working | Empty cart returns correctly |
-| `/api/v1/shop/content-pages/navigation` | GET | ✅ Working | Navigation links returned |
+| `/api/v1/storefront/products` | GET | ✅ Working | Returns paginated product list |
+| `/api/v1/storefront/products?search=Sample` | GET | ✅ Working | Search functionality works |
+| `/api/v1/storefront/products?is_featured=true` | GET | ✅ Working | Featured filter works |
+| `/api/v1/storefront/products/{id}` | GET | ✅ Working | Product details returned |
+| `/api/v1/storefront/cart/{session_id}` | GET | ✅ Working | Empty cart returns correctly |
+| `/api/v1/storefront/content-pages/navigation` | GET | ✅ Working | Navigation links returned |

 **All tested endpoints successfully receive store context from Referer header.**

 | Endpoint File | Status | Routes | Description |
 |--------------|--------|--------|-------------|
-| `shop/products.py` | ✅ Complete | 3 routes | Product catalog, details, search |
-| `shop/cart.py` | ✅ Complete | 5 routes | Cart CRUD operations |
-| `shop/orders.py` | ✅ Complete | 3 routes | Order placement & history |
-| `shop/auth.py` | ✅ Complete | 5 routes | Login, register, password reset |
-| `shop/content_pages.py` | ✅ Existing | 2 routes | CMS pages (already present) |
-| `shop/__init__.py` | ✅ Updated | - | Router aggregation |
+| `storefront/products.py` | ✅ Complete | 3 routes | Product catalog, details, search |
+| `storefront/cart.py` | ✅ Complete | 5 routes | Cart CRUD operations |
+| `storefront/orders.py` | ✅ Complete | 3 routes | Order placement & history |
+| `storefront/auth.py` | ✅ Complete | 5 routes | Login, register, password reset |
+| `storefront/content_pages.py` | ✅ Existing | 2 routes | CMS pages (already present) |
+| `storefront/__init__.py` | ✅ Updated | - | Router aggregation |

 **Total:** 18 new API endpoints created

@@ -57,46 +57,46 @@ Tested shop API endpoints with Referer header:

 ## New API Structure

-### Shop Endpoints (`/api/v1/shop/*`)
+### Storefront Endpoints (`/api/v1/storefront/*`)

 All endpoints use `request.state.store` (injected by `StoreContextMiddleware`).

 #### Products (Public - No Auth)
 ```
-GET  /api/v1/shop/products              → Product catalog (paginated)
-GET  /api/v1/shop/products/{id}         → Product details
-GET  /api/v1/shop/products/search?q=... → Search products
+GET  /api/v1/storefront/products              → Product catalog (paginated)
+GET  /api/v1/storefront/products/{id}         → Product details
+GET  /api/v1/storefront/products/search?q=... → Search products
 ```

 #### Cart (Public - Session Based)
 ```
-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/{id}       → Update item
-DELETE /api/v1/shop/cart/{session_id}/items/{id}       → Remove item
-DELETE /api/v1/shop/cart/{session_id}                  → Clear cart
+GET    /api/v1/storefront/cart/{session_id}                  → Get cart
+POST   /api/v1/storefront/cart/{session_id}/items            → Add to cart
+PUT    /api/v1/storefront/cart/{session_id}/items/{id}       → Update item
+DELETE /api/v1/storefront/cart/{session_id}/items/{id}       → Remove item
+DELETE /api/v1/storefront/cart/{session_id}                  → Clear cart
 ```

 #### Orders (Authenticated - Customer)
 ```
-POST /api/v1/shop/orders         → Place order (auth required)
-GET  /api/v1/shop/orders         → Order history (auth required)
-GET  /api/v1/shop/orders/{id}    → Order details (auth required)
+POST /api/v1/storefront/orders         → Place order (auth required)
+GET  /api/v1/storefront/orders         → Order history (auth required)
+GET  /api/v1/storefront/orders/{id}    → Order details (auth required)
 ```

 #### Authentication (Public)
 ```
-POST /api/v1/shop/auth/register       → Register customer
-POST /api/v1/shop/auth/login          → Customer login
-POST /api/v1/shop/auth/logout         → Customer logout
-POST /api/v1/shop/auth/forgot-password → Request reset
-POST /api/v1/shop/auth/reset-password  → Reset password
+POST /api/v1/storefront/auth/register       → Register customer
+POST /api/v1/storefront/auth/login          → Customer login
+POST /api/v1/storefront/auth/logout         → Customer logout
+POST /api/v1/storefront/auth/forgot-password → Request reset
+POST /api/v1/storefront/auth/reset-password  → Reset password
 ```

 #### CMS Content (Public)
 ```
-GET /api/v1/shop/content-pages/navigation → Navigation links
-GET /api/v1/shop/content-pages/{slug}     → Page content
+GET /api/v1/storefront/content-pages/navigation → Navigation links
+GET /api/v1/storefront/content-pages/{slug}     → Page content
 ```

 ---
@@ -130,7 +130,7 @@ def endpoint_handler(request: Request, ...):

 - **Public endpoints** (products, cart, CMS): No authentication
 - **Authenticated endpoints** (orders): Use `get_current_customer_api` dependency
- **Cookie strategy**: Customer tokens stored at `path=/shop` only
+- **Cookie strategy**: Customer tokens stored at `path=/storefront` only

 ### Error Handling

@@ -145,7 +145,7 @@ def endpoint_handler(request: Request, ...):
 ### Files Created ✨

 ```
-app/api/v1/shop/
+app/api/v1/storefront/
 ├── products.py  (NEW - 182 lines)
 ├── cart.py      (NEW - 242 lines)
 ├── orders.py    (NEW - 193 lines)
@@ -156,9 +156,9 @@ app/api/v1/shop/
 ### Files Modified 🔧

 ```
-app/exceptions/error_renderer.py     → Added base_url calculation for shop context
+app/exceptions/error_renderer.py     → Added base_url calculation for storefront context
 app/routes/store_pages.py           → Added CMS route handler
-app/templates/shop/errors/*.html     → Fixed links to use base_url
+app/templates/storefront/errors/*.html     → Fixed links to use base_url
 docs/architecture/
 ├── api-consolidation-proposal.md    → Analysis & recommendation
 └── api-migration-status.md          → This file
@@ -170,27 +170,27 @@ docs/architecture/

 ### ✅ Phase 2: Frontend Migration (COMPLETE)

-Updated all shop templates to use new API endpoints:
+Updated all storefront templates to use new API endpoints:

 | Template | Old Endpoint | New Endpoint | Status |
 |----------|-------------|--------------|---------|
-| `shop/account/login.html` | `/api/v1/platform/stores/${id}/customers/login` | `/api/v1/shop/auth/login` | ✅ Complete |
-| `shop/account/register.html` | `/api/v1/platform/stores/${id}/customers/register` | `/api/v1/shop/auth/register` | ✅ Complete |
-| `shop/product.html` | `/api/v1/platform/stores/${id}/products/${pid}` | `/api/v1/shop/products/${pid}` | ✅ Complete |
-| `shop/product.html` | `/api/v1/platform/stores/${id}/products?limit=4` | `/api/v1/shop/products?limit=4` | ✅ Complete |
-| `shop/product.html` | `/api/v1/platform/stores/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
-| `shop/product.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items` | `/api/v1/shop/cart/${sid}/items` | ✅ Complete |
-| `shop/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}` | `/api/v1/shop/cart/${sid}` | ✅ Complete |
-| `shop/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items/${pid}` (PUT) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
-| `shop/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items/${pid}` (DELETE) | `/api/v1/shop/cart/${sid}/items/${pid}` | ✅ Complete |
-| `shop/products.html` | Already using `/api/v1/shop/products` | (No change needed) | ✅ Already Updated |
-| `shop/home.html` | Already using `/api/v1/shop/products?featured=true` | (No change needed) | ✅ Already Updated |
+| `storefront/account/login.html` | `/api/v1/platform/stores/${id}/customers/login` | `/api/v1/storefront/auth/login` | ✅ Complete |
+| `storefront/account/register.html` | `/api/v1/platform/stores/${id}/customers/register` | `/api/v1/storefront/auth/register` | ✅ Complete |
+| `storefront/product.html` | `/api/v1/platform/stores/${id}/products/${pid}` | `/api/v1/storefront/products/${pid}` | ✅ Complete |
+| `storefront/product.html` | `/api/v1/platform/stores/${id}/products?limit=4` | `/api/v1/storefront/products?limit=4` | ✅ Complete |
+| `storefront/product.html` | `/api/v1/platform/stores/${id}/cart/${sid}` | `/api/v1/storefront/cart/${sid}` | ✅ Complete |
+| `storefront/product.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items` | `/api/v1/storefront/cart/${sid}/items` | ✅ Complete |
+| `storefront/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}` | `/api/v1/storefront/cart/${sid}` | ✅ Complete |
+| `storefront/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items/${pid}` (PUT) | `/api/v1/storefront/cart/${sid}/items/${pid}` | ✅ Complete |
+| `storefront/cart.html` | `/api/v1/platform/stores/${id}/cart/${sid}/items/${pid}` (DELETE) | `/api/v1/storefront/cart/${sid}/items/${pid}` | ✅ Complete |
+| `storefront/products.html` | Already using `/api/v1/storefront/products` | (No change needed) | ✅ Already Updated |
+| `storefront/home.html` | Already using `/api/v1/storefront/products?featured=true` | (No change needed) | ✅ Already Updated |

 **Total Changes:** 9 API endpoint migrations across 3 template files

 **Verification:**
 ```bash
-grep -r "api/v1/public/stores" app/templates/shop --include="*.html"
+grep -r "api/v1/public/stores" app/templates/storefront --include="*.html"
 # Returns: (no results - all migrated)
 ```

@@ -199,16 +199,16 @@ grep -r "api/v1/public/stores" app/templates/shop --include="*.html"
 Cleaned up old `/api/v1/platform/stores/*` endpoints:

 **Files Removed:**
- ❌ `auth.py` - Migrated to `/api/v1/shop/auth.py`
- ❌ `products.py` - Migrated to `/api/v1/shop/products.py`
- ❌ `cart.py` - Migrated to `/api/v1/shop/cart.py`
- ❌ `orders.py` - Migrated to `/api/v1/shop/orders.py`
+- ❌ `auth.py` - Migrated to `/api/v1/storefront/auth.py`
+- ❌ `products.py` - Migrated to `/api/v1/storefront/products.py`
+- ❌ `cart.py` - Migrated to `/api/v1/storefront/cart.py`
+- ❌ `orders.py` - Migrated to `/api/v1/storefront/orders.py`
 - ❌ `payments.py` - Empty placeholder (removed)
 - ❌ `search.py` - Empty placeholder (removed)
- ❌ `shop.py` - Empty placeholder (removed)
+- ❌ `storefront.py` - Empty placeholder (removed)

 **Files Kept:**
- ✅ `stores.py` - Store lookup endpoints (truly public, not shop-specific)
+- ✅ `stores.py` - Store lookup endpoints (truly public, not storefront-specific)
  - `GET /api/v1/platform/stores/by-code/{store_code}`
  - `GET /api/v1/platform/stores/by-subdomain/{subdomain}`
  - `GET /api/v1/platform/stores/{store_id}/info`
@@ -216,7 +216,7 @@ Cleaned up old `/api/v1/platform/stores/*` endpoints:
 **Updated:**
 - ✅ `/app/api/v1/platform/__init__.py` - Now only includes store lookup endpoints

-**Result:** Old shop endpoints completely removed, only store lookup remains in `/api/v1/platform/stores/*`
+**Result:** Old storefront endpoints completely removed, only store lookup remains in `/api/v1/platform/stores/*`

 ### ⚠️ Phase 4: Deprecation Warnings (SKIPPED - Not Needed)

@@ -291,12 +291,12 @@ Old endpoint cleanup completed immediately (no gradual migration needed):
 ### After (New Pattern)
 ```
 # Clean - store from context
-/api/v1/shop/products
-/api/v1/shop/products/456
-/api/v1/shop/cart/abc-session-id
-/api/v1/shop/cart/abc-session-id/items
-/api/v1/shop/orders
-/api/v1/shop/auth/login
+/api/v1/storefront/products
+/api/v1/storefront/products/456
+/api/v1/storefront/cart/abc-session-id
+/api/v1/storefront/cart/abc-session-id/items
+/api/v1/storefront/orders
+/api/v1/storefront/auth/login
 ```

 **URL Reduction:** ~40% shorter URLs on average
@@ -308,7 +308,7 @@ Old endpoint cleanup completed immediately (no gradual migration needed):
 ### For Frontend Developers
 - ✅ Cleaner, more intuitive URLs
 - ✅ No need to track store_id in state
- ✅ Consistent API pattern across all shop endpoints
+- ✅ Consistent API pattern across all storefront endpoints
 - ✅ Automatic store context from middleware

 ### For Backend Developers
@@ -331,7 +331,7 @@ If issues arise, rollback is simple since old endpoints still exist:

 1. **Revert frontend changes:**
   ```bash
-   git checkout app/templates/shop/*.html
+   git checkout app/templates/storefront/*.html
   ```

 2. **Old endpoints still work:**
@@ -357,7 +357,7 @@ Add logging to track which pattern is being used:
 logger.info(
    "API call",
    extra={
-        "endpoint_pattern": "new" if "/shop/" in request.url.path else "old",
+        "endpoint_pattern": "new" if "/storefront/" in request.url.path else "old",
        "path": request.url.path,
        "store_id": store.id if store else None,
    }
@@ -377,7 +377,7 @@ logger.info(

 ### ✅ Decided

-1. **Use `/api/v1/shop/*` pattern?** → YES (Option 1)
+1. **Use `/api/v1/storefront/*` pattern?** → YES (Option 1)
 2. **Store from middleware?** → YES
 3. **Keep old endpoints during migration?** → YES
 4. **Deprecation period?** → 2-4 weeks
@@ -412,7 +412,7 @@ logger.info(
 Migration is considered successful when:

 - [x] All new endpoints created and tested
- [x] Middleware updated to support shop API routes
+- [x] Middleware updated to support storefront API routes
 - [x] Store context extraction from Referer working
 - [x] All frontend templates updated (9 API calls across 3 files)
 - [x] Old endpoint usage drops to zero (verified with grep)
@@ -432,7 +432,7 @@ Migration is considered successful when:
 - [Middleware Documentation](./middleware.md) - How middleware works

 **Issues?** Review:
- Server logs: Check for `[SHOP_API]` log entries
+- Server logs: Check for `[STOREFRONT_API]` log entries
 - Browser console: Check for failed API calls
 - Network tab: Verify correct endpoints are called