diff --git a/docs/api/index.md b/docs/api/index.md index 79638378..92e47bf0 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -26,8 +26,8 @@ All API endpoints are versioned using URL path versioning: ## Endpoint Categories -### Shop API (`/shop/`) - Customer-Facing -Multi-tenant shop endpoints with automatic vendor context from middleware: +### Storefront API (`/storefront/`) - Customer-Facing +Multi-tenant storefront endpoints with automatic vendor context from middleware: - **Products**: Browse catalog, search, product details - **Cart**: Shopping cart operations (session-based) - **Orders**: Order placement and history (authenticated) diff --git a/docs/api/shop-api-reference.md b/docs/api/storefront-api-reference.md similarity index 88% rename from docs/api/shop-api-reference.md rename to docs/api/storefront-api-reference.md index 75e99a57..b919d66a 100644 --- a/docs/api/shop-api-reference.md +++ b/docs/api/storefront-api-reference.md @@ -1,31 +1,31 @@ -# Shop API Reference +# Storefront API Reference -**Last Updated:** 2025-11-23 +**Last Updated:** 2026-01-29 **API Version:** v1 -**Base Path:** `/api/v1/shop` +**Base Path:** `/api/v1/storefront` --- ## Overview -The Shop API provides customer-facing endpoints for browsing products, managing cart, placing orders, and customer authentication. All endpoints use **middleware-based vendor context** - no vendor ID in URLs! +The Storefront API provides customer-facing endpoints for browsing products, managing cart, placing orders, and customer authentication. All endpoints use **middleware-based vendor context** - no vendor ID in URLs! ### Key Features ✅ **Automatic Vendor Detection** - Vendor extracted from Referer header via middleware ✅ **Multi-Tenant** - Each vendor has isolated customer data ✅ **Session-Based Cart** - No authentication required for browsing/cart -✅ **Secure Authentication** - JWT tokens with HTTP-only cookies (path=/shop) +✅ **Secure Authentication** - JWT tokens with HTTP-only cookies (path=/storefront) ✅ **RESTful Design** - Standard HTTP methods and status codes --- ## How Vendor Context Works -All Shop API endpoints automatically receive vendor context from the `VendorContextMiddleware`: +All Storefront API endpoints automatically receive vendor context from the `VendorContextMiddleware`: -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` +1. **Browser makes API call** from storefront page (e.g., `/vendors/wizamart/storefront/products`) +2. **Browser automatically sends Referer header**: `http://localhost:8000/vendors/wizamart/storefront/products` 3. **Middleware extracts vendor** from Referer path/subdomain/domain 4. **Middleware sets** `request.state.vendor = ` 5. **API endpoint accesses vendor**: `vendor = request.state.vendor` @@ -33,7 +33,7 @@ All Shop API endpoints automatically receive vendor context from the `VendorCont ### Supported Vendor Detection Methods -- **Path-based**: `/vendors/wizamart/shop/products` → extracts `wizamart` +- **Path-based**: `/vendors/wizamart/storefront/products` → extracts `wizamart` - **Subdomain**: `wizamart.platform.com` → extracts `wizamart` - **Custom domain**: `customshop.com` → looks up vendor by domain @@ -77,7 +77,7 @@ Cookie: customer_token= Get paginated list of products for current vendor. -**Endpoint:** `GET /api/v1/shop/products` +**Endpoint:** `GET /api/v1/storefront/products` **Query Parameters:** @@ -91,7 +91,7 @@ Get paginated list of products for current vendor. **Request Example:** ```http -GET /api/v1/shop/products?skip=0&limit=20&is_featured=true +GET /api/v1/storefront/products?skip=0&limit=20&is_featured=true Referer: http://localhost:8000/vendors/wizamart/shop/products ``` @@ -130,7 +130,7 @@ Referer: http://localhost:8000/vendors/wizamart/shop/products Get detailed information for a specific product. -**Endpoint:** `GET /api/v1/shop/products/{product_id}` +**Endpoint:** `GET /api/v1/storefront/products/{product_id}` **Path Parameters:** @@ -141,7 +141,7 @@ Get detailed information for a specific product. **Request Example:** ```http -GET /api/v1/shop/products/1 +GET /api/v1/storefront/products/1 Referer: http://localhost:8000/vendors/wizamart/shop/products ``` @@ -188,7 +188,7 @@ Cart operations use session-based tracking (no authentication required). Retrieve cart contents for a session. -**Endpoint:** `GET /api/v1/shop/cart/{session_id}` +**Endpoint:** `GET /api/v1/storefront/cart/{session_id}` **Path Parameters:** @@ -199,7 +199,7 @@ Retrieve cart contents for a session. **Request Example:** ```http -GET /api/v1/shop/cart/session-abc-123 +GET /api/v1/storefront/cart/session-abc-123 Referer: http://localhost:8000/vendors/wizamart/shop/cart ``` @@ -253,7 +253,7 @@ Referer: http://localhost:8000/vendors/wizamart/shop/cart Add a product to the cart. If the product already exists in the cart, the quantity will be incremented. -**Endpoint:** `POST /api/v1/shop/cart/{session_id}/items` +**Endpoint:** `POST /api/v1/storefront/cart/{session_id}/items` **Path Parameters:** @@ -352,7 +352,7 @@ Add a product to the cart. If the product already exists in the cart, the quanti Update the quantity of an existing item in the cart. -**Endpoint:** `PUT /api/v1/shop/cart/{session_id}/items/{product_id}` +**Endpoint:** `PUT /api/v1/storefront/cart/{session_id}/items/{product_id}` **Path Parameters:** @@ -409,7 +409,7 @@ Update the quantity of an existing item in the cart. Remove a specific item from the cart. -**Endpoint:** `DELETE /api/v1/shop/cart/{session_id}/items/{product_id}` +**Endpoint:** `DELETE /api/v1/storefront/cart/{session_id}/items/{product_id}` **Path Parameters:** @@ -437,7 +437,7 @@ Remove a specific item from the cart. Remove all items from the cart. -**Endpoint:** `DELETE /api/v1/shop/cart/{session_id}` +**Endpoint:** `DELETE /api/v1/storefront/cart/{session_id}` **Path Parameters:** @@ -471,7 +471,7 @@ Order endpoints require customer authentication. Create a new order (authenticated). -**Endpoint:** `POST /api/v1/shop/orders` +**Endpoint:** `POST /api/v1/storefront/orders` **Authentication:** Required (customer token) @@ -520,7 +520,7 @@ Create a new order (authenticated). Get list of customer's orders (authenticated). -**Endpoint:** `GET /api/v1/shop/orders` +**Endpoint:** `GET /api/v1/storefront/orders` **Authentication:** Required @@ -556,7 +556,7 @@ Get list of customer's orders (authenticated). Get details of a specific order (authenticated). -**Endpoint:** `GET /api/v1/shop/orders/{order_id}` +**Endpoint:** `GET /api/v1/storefront/orders/{order_id}` **Authentication:** Required @@ -590,7 +590,7 @@ Get details of a specific order (authenticated). Create a new customer account. -**Endpoint:** `POST /api/v1/shop/auth/register` +**Endpoint:** `POST /api/v1/storefront/auth/register` **Request Body:** @@ -629,7 +629,7 @@ Create a new customer account. Authenticate a customer and receive JWT token. -**Endpoint:** `POST /api/v1/shop/auth/login` +**Endpoint:** `POST /api/v1/storefront/auth/login` **Request Body:** @@ -661,7 +661,7 @@ Authenticate a customer and receive JWT token. The endpoint also sets an HTTP-only cookie: ```http -Set-Cookie: customer_token=; Path=/shop; HttpOnly; SameSite=Lax; Secure +Set-Cookie: customer_token=; Path=/storefront; HttpOnly; SameSite=Lax; Secure ``` **Error Responses:** @@ -675,7 +675,7 @@ Set-Cookie: customer_token=; Path=/shop; HttpOnly; SameSite=Lax; Secure Clear customer session. -**Endpoint:** `POST /api/v1/shop/auth/logout` +**Endpoint:** `POST /api/v1/storefront/auth/logout` **Response (200 OK):** @@ -695,7 +695,7 @@ The endpoint clears the `customer_token` cookie. Get CMS pages for header/footer navigation. -**Endpoint:** `GET /api/v1/shop/content-pages/navigation` +**Endpoint:** `GET /api/v1/storefront/content-pages/navigation` **Response (200 OK):** @@ -724,7 +724,7 @@ Get CMS pages for header/footer navigation. Get full content for a specific page. -**Endpoint:** `GET /api/v1/shop/content-pages/{slug}` +**Endpoint:** `GET /api/v1/storefront/content-pages/{slug}` **Path Parameters:** @@ -738,7 +738,7 @@ Get full content for a specific page. { "slug": "about", "title": "About Us", - "content": "

Welcome to our shop...

", + "content": "

Welcome to our store...

", "meta_description": "Learn about our story", "is_published": true, "show_in_header": true, @@ -793,7 +793,7 @@ All endpoints follow standard HTTP error responses: ## Rate Limiting -All Shop API endpoints are rate limited: +All Storefront API endpoints are rate limited: - **Public endpoints**: 100 requests/minute per IP - **Authenticated endpoints**: 200 requests/minute per customer @@ -821,8 +821,8 @@ POST /api/v1/public/vendors/auth/{vendor_id}/customers/login **New Pattern (Current):** ```http -GET /api/v1/shop/products -POST /api/v1/shop/auth/login +GET /api/v1/storefront/products +POST /api/v1/storefront/auth/login ``` **Key Changes:** @@ -846,7 +846,7 @@ const sessionId = localStorage.getItem('session_id') || crypto.randomUUID(); localStorage.setItem('session_id', sessionId); // 2. Add product to cart -const response = await fetch(`/api/v1/shop/cart/${sessionId}/items`, { +const response = await fetch(`/api/v1/storefront/cart/${sessionId}/items`, { method: 'POST', headers: { 'Content-Type': 'application/json' @@ -865,7 +865,7 @@ console.log('Cart updated:', result.cart); ```javascript // 1. Customer logs in -const loginResponse = await fetch('/api/v1/shop/auth/login', { +const loginResponse = await fetch('/api/v1/storefront/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ @@ -878,7 +878,7 @@ const { access_token } = await loginResponse.json(); localStorage.setItem('customer_token', access_token); // 2. Place order -const orderResponse = await fetch('/api/v1/shop/orders', { +const orderResponse = await fetch('/api/v1/storefront/orders', { method: 'POST', headers: { 'Content-Type': 'application/json', @@ -908,4 +908,4 @@ For live API testing and exploration: --- -**Questions?** See the [API Migration Status](../architecture/api-migration-status.md) or [Shop Architecture Guide](../frontend/shop/architecture.md). +**Questions?** See the [API Migration Status](../architecture/api-migration-status.md) or [Storefront Architecture Guide](../frontend/storefront/architecture.md). diff --git a/docs/architecture/module-system.md b/docs/architecture/module-system.md index 543668fa..856f49af 100644 --- a/docs/architecture/module-system.md +++ b/docs/architecture/module-system.md @@ -83,12 +83,15 @@ Core modules are **always enabled** and cannot be disabled. They provide fundame | `cms` | Content pages, media library, themes | Content management | | `customers` | Customer database, profiles, segmentation | Customer data management | -### Optional Modules (7) +### Optional Modules (10) Optional modules can be **enabled or disabled per platform**. They provide additional functionality that may not be needed by all platforms. | Module | Dependencies | Description | |--------|--------------|-------------| +| `cart` | - | Shopping cart management, session-based carts | +| `catalog` | - | Customer-facing product browsing | +| `checkout` | `cart`, `orders`, `payments` | Cart-to-order conversion, checkout flow | | `payments` | - | Payment gateway integrations (Stripe, PayPal, etc.) | | `billing` | `payments` | Platform subscriptions, vendor invoices | | `inventory` | - | Stock management, locations | @@ -283,13 +286,14 @@ The Framework Layer provides infrastructure that modules depend on. These are ** Modules can depend on other modules. When enabling a module, its dependencies are automatically enabled. ``` - payments - ↙ ↘ - billing orders - - inventory - ↓ - marketplace + payments + ↙ ↘ + billing orders ←──┐ + ↑ │ + inventory │ │ + ↓ cart │ + marketplace ↘ │ + checkout ``` **Dependency Rules:** diff --git a/docs/proposals/PLAN_storefront-module-restructure.md b/docs/proposals/PLAN_storefront-module-restructure.md index 01d3df96..f99516a8 100644 --- a/docs/proposals/PLAN_storefront-module-restructure.md +++ b/docs/proposals/PLAN_storefront-module-restructure.md @@ -316,7 +316,7 @@ After migrated to `app/modules/cart/services/cart_service.py`. 4. **Phase 4** - Move routes to modules ✅ COMPLETE 5. **Phase 5** - Fix direct model imports ✅ COMPLETE 6. **Phase 6** - Delete legacy files ✅ COMPLETE -7. **Phase 7** - Update documentation +7. **Phase 7** - Update documentation ✅ COMPLETE ---