refactor: rename public routes and templates to platform
Complete the public -> platform naming migration across the codebase. This aligns with the naming convention where "platform" refers to the marketing/public-facing pages of the platform itself. Changes: - Update all imports from public to platform modules - Update template references from public/ to platform/ - Update route registrations to use platform prefix - Update documentation to reflect new naming - Update test files for platform API endpoints Files affected: - app/api/main.py - router imports - app/modules/*/routes/*/platform.py - route definitions - app/modules/*/templates/*/platform/ - template files - app/modules/routes.py - route discovery - docs/* - documentation updates - tests/integration/api/v1/platform/ - test files Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -7,7 +7,7 @@
|
||||
## Executive Summary
|
||||
|
||||
The platform currently has **two parallel API structures** for shop/customer-facing endpoints:
|
||||
1. **Original:** `/api/v1/public/vendors/{vendor_id}/*`
|
||||
1. **Original:** `/api/v1/platform/vendors/{vendor_id}/*`
|
||||
2. **New:** `/api/v1/shop/*`
|
||||
|
||||
This divergence creates confusion, maintenance overhead, and potential bugs. This document analyzes the situation and proposes a consolidation strategy.
|
||||
@@ -16,19 +16,19 @@ This divergence creates confusion, maintenance overhead, and potential bugs. Thi
|
||||
|
||||
## Current State Analysis
|
||||
|
||||
### 1. Original Architecture (`/api/v1/public/vendors/`)
|
||||
### 1. Original Architecture (`/api/v1/platform/vendors/`)
|
||||
|
||||
**Location:** `app/api/v1/public/vendors/`
|
||||
**Location:** `app/api/v1/platform/vendors/`
|
||||
|
||||
**Endpoints:**
|
||||
```
|
||||
GET /api/v1/public/vendors → List active vendors
|
||||
GET /api/v1/public/vendors/{vendor_id}/products → Product catalog
|
||||
GET /api/v1/public/vendors/{vendor_id}/products/{product_id} → Product detail
|
||||
POST /api/v1/public/vendors/{vendor_id}/cart → Cart operations
|
||||
GET /api/v1/public/vendors/{vendor_id}/orders → Customer orders
|
||||
POST /api/v1/public/vendors/auth/login → Customer authentication
|
||||
POST /api/v1/public/vendors/auth/register → Customer registration
|
||||
GET /api/v1/platform/vendors → List active vendors
|
||||
GET /api/v1/platform/vendors/{vendor_id}/products → Product catalog
|
||||
GET /api/v1/platform/vendors/{vendor_id}/products/{product_id} → Product detail
|
||||
POST /api/v1/platform/vendors/{vendor_id}/cart → Cart operations
|
||||
GET /api/v1/platform/vendors/{vendor_id}/orders → Customer orders
|
||||
POST /api/v1/platform/vendors/auth/login → Customer authentication
|
||||
POST /api/v1/platform/vendors/auth/register → Customer registration
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
@@ -60,7 +60,7 @@ GET /api/v1/shop/content-pages/{slug} → CMS page content
|
||||
**Characteristics:**
|
||||
- ✅ **Vendor-agnostic URLs:** Clean paths without vendor_id
|
||||
- ✅ **Middleware-driven:** Relies on `VendorContextMiddleware` to inject vendor
|
||||
- ✅ **Simpler URLs:** `/api/v1/shop/products` vs `/api/v1/public/vendors/123/products`
|
||||
- ✅ **Simpler URLs:** `/api/v1/shop/products` vs `/api/v1/platform/vendors/123/products`
|
||||
- ❌ **Incomplete:** Only CMS endpoints implemented
|
||||
- ❌ **Divergent:** Not consistent with existing public API
|
||||
|
||||
@@ -80,7 +80,7 @@ GET /api/v1/shop/content-pages/{slug} → CMS page content
|
||||
fetch('/api/v1/shop/content-pages/about')
|
||||
|
||||
// Products use old pattern
|
||||
fetch('/api/v1/public/vendors/123/products')
|
||||
fetch('/api/v1/platform/vendors/123/products')
|
||||
```
|
||||
|
||||
### Confusion
|
||||
@@ -143,7 +143,7 @@ Developers must remember:
|
||||
**Implementation:**
|
||||
- Vendor extracted by `VendorContextMiddleware` from request
|
||||
- All endpoints use `request.state.vendor` instead of path parameter
|
||||
- URLs are cleaner: `/api/v1/shop/products` instead of `/api/v1/public/vendors/123/products`
|
||||
- URLs are cleaner: `/api/v1/shop/products` instead of `/api/v1/platform/vendors/123/products`
|
||||
|
||||
**Pros:**
|
||||
- ✅ Clean, consistent API structure
|
||||
@@ -162,18 +162,18 @@ Developers must remember:
|
||||
|
||||
---
|
||||
|
||||
### Option 2: Keep `/api/v1/public/vendors/*` and Deprecate `/api/v1/shop/*`
|
||||
### Option 2: Keep `/api/v1/platform/vendors/*` and Deprecate `/api/v1/shop/*`
|
||||
|
||||
**Approach:** Move CMS endpoints to `/api/v1/public/vendors/{vendor_id}/content-pages/*`
|
||||
**Approach:** Move CMS endpoints to `/api/v1/platform/vendors/{vendor_id}/content-pages/*`
|
||||
|
||||
**Proposed Changes:**
|
||||
```
|
||||
# Move CMS endpoints
|
||||
FROM: /api/v1/shop/content-pages/navigation
|
||||
TO: /api/v1/public/vendors/{vendor_id}/content-pages/navigation
|
||||
TO: /api/v1/platform/vendors/{vendor_id}/content-pages/navigation
|
||||
|
||||
FROM: /api/v1/shop/content-pages/{slug}
|
||||
TO: /api/v1/public/vendors/{vendor_id}/content-pages/{slug}
|
||||
TO: /api/v1/platform/vendors/{vendor_id}/content-pages/{slug}
|
||||
```
|
||||
|
||||
**Pros:**
|
||||
@@ -240,7 +240,7 @@ async def get_products_legacy(vendor_id: int, db: Session = Depends(get_db)):
|
||||
fetch('/api/v1/shop/products')
|
||||
|
||||
// ❌ BAD
|
||||
fetch('/api/v1/public/vendors/123/products')
|
||||
fetch('/api/v1/platform/vendors/123/products')
|
||||
```
|
||||
|
||||
3. **Multi-Tenant Best Practice**: Vendor context should be implicit (from domain/path), not explicit in every API call.
|
||||
@@ -258,7 +258,7 @@ async def get_products_legacy(vendor_id: int, db: Session = Depends(get_db)):
|
||||
**Day 1-2: Move Products**
|
||||
```bash
|
||||
# Copy and adapt
|
||||
app/api/v1/public/vendors/products.py → app/api/v1/shop/products.py
|
||||
app/api/v1/platform/vendors/products.py → app/api/v1/shop/products.py
|
||||
|
||||
# Changes:
|
||||
- Remove vendor_id path parameter
|
||||
@@ -268,24 +268,24 @@ app/api/v1/public/vendors/products.py → app/api/v1/shop/products.py
|
||||
|
||||
**Day 3: Move Cart**
|
||||
```bash
|
||||
app/api/v1/public/vendors/cart.py → app/api/v1/shop/cart.py
|
||||
app/api/v1/platform/vendors/cart.py → app/api/v1/shop/cart.py
|
||||
```
|
||||
|
||||
**Day 4: Move Orders**
|
||||
```bash
|
||||
app/api/v1/public/vendors/orders.py → app/api/v1/shop/orders.py
|
||||
app/api/v1/platform/vendors/orders.py → app/api/v1/shop/orders.py
|
||||
```
|
||||
|
||||
**Day 5: Move Auth**
|
||||
```bash
|
||||
app/api/v1/public/vendors/auth.py → app/api/v1/shop/auth.py
|
||||
app/api/v1/platform/vendors/auth.py → app/api/v1/shop/auth.py
|
||||
```
|
||||
|
||||
### Phase 2: Update Frontend (Week 1)
|
||||
|
||||
**Templates:**
|
||||
- Update all `fetch()` calls in shop templates
|
||||
- Change from `/api/v1/public/vendors/${vendorId}/...` to `/api/v1/shop/...`
|
||||
- Change from `/api/v1/platform/vendors/${vendorId}/...` to `/api/v1/shop/...`
|
||||
|
||||
**JavaScript:**
|
||||
- Update any shop-related API client code
|
||||
@@ -316,10 +316,10 @@ app/api/v1/public/vendors/auth.py → app/api/v1/shop/auth.py
|
||||
|
||||
## Code Examples
|
||||
|
||||
### Before (Current - `/api/v1/public/vendors`)
|
||||
### Before (Current - `/api/v1/platform/vendors`)
|
||||
|
||||
```python
|
||||
# app/api/v1/public/vendors/products.py
|
||||
# app/api/v1/platform/vendors/products.py
|
||||
@router.get("/{vendor_id}/products")
|
||||
def get_public_product_catalog(
|
||||
vendor_id: int = Path(...),
|
||||
@@ -332,7 +332,7 @@ def get_public_product_catalog(
|
||||
```javascript
|
||||
// Frontend
|
||||
const vendorId = 123;
|
||||
fetch(`/api/v1/public/vendors/${vendorId}/products`)
|
||||
fetch(`/api/v1/platform/vendors/${vendorId}/products`)
|
||||
```
|
||||
|
||||
### After (Proposed - `/api/v1/shop`)
|
||||
@@ -358,14 +358,14 @@ fetch('/api/v1/shop/products') // Vendor context automatic
|
||||
## Impact Assessment
|
||||
|
||||
### Breaking Changes
|
||||
- All frontend code calling `/api/v1/public/vendors/*` must update
|
||||
- All frontend code calling `/api/v1/platform/vendors/*` must update
|
||||
- Mobile apps (if any) must update
|
||||
- Third-party integrations (if any) must update
|
||||
|
||||
### Non-Breaking
|
||||
- Admin APIs: `/api/v1/admin/*` → No changes
|
||||
- Vendor APIs: `/api/v1/vendor/*` → No changes
|
||||
- Vendor listing: Keep `/api/v1/public/vendors` (list all vendors for marketplace)
|
||||
- Vendor listing: Keep `/api/v1/platform/vendors` (list all vendors for marketplace)
|
||||
|
||||
### Risk Mitigation
|
||||
1. **Deprecation Period**: Keep old endpoints for 2-4 weeks
|
||||
@@ -383,7 +383,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
|
||||
|
||||
```python
|
||||
# Move: app/api/v1/shop/content_pages.py
|
||||
# To: app/api/v1/public/vendors/content_pages.py
|
||||
# To: app/api/v1/platform/vendors/content_pages.py
|
||||
|
||||
# Update routes:
|
||||
@router.get("/{vendor_id}/content-pages/navigation")
|
||||
@@ -402,7 +402,7 @@ If full migration is not approved immediately, we can do a **minimal fix** for t
|
||||
|
||||
Should we:
|
||||
1. ✅ **Consolidate to `/api/v1/shop/*`** (Recommended)
|
||||
2. ❌ **Keep `/api/v1/public/vendors/*`** and move CMS there
|
||||
2. ❌ **Keep `/api/v1/platform/vendors/*`** and move CMS there
|
||||
3. ❌ **Hybrid approach** with both patterns
|
||||
4. ❌ **Quick fix only** - move CMS, address later
|
||||
|
||||
@@ -412,7 +412,7 @@ Should we:
|
||||
|
||||
## Appendix: Current Endpoint Inventory
|
||||
|
||||
### `/api/v1/public/vendors/*`
|
||||
### `/api/v1/platform/vendors/*`
|
||||
- ✅ `vendors.py` - Vendor listing
|
||||
- ✅ `auth.py` - Customer authentication
|
||||
- ✅ `products.py` - Product catalog
|
||||
|
||||
Reference in New Issue
Block a user