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/features/cms-implementation-guide.md
+++ b/docs/features/cms-implementation-guide.md
@@ -10,7 +10,7 @@ This guide shows you how to implement the Content Management System for static p
 ✅ **Service Layer**: `app/services/content_page_service.py`
 ✅ **Admin API**: `app/api/v1/admin/content_pages.py`
 ✅ **Store API**: `app/api/v1/store/content_pages.py`
-✅ **Shop API**: `app/api/v1/shop/content_pages.py`
+✅ **Storefront API**: `app/api/v1/storefront/content_pages.py`
 ✅ **Documentation**: Full CMS documentation in `docs/features/content-management-system.md`

 ## Next Steps to Activate
@@ -65,20 +65,20 @@ api_router.include_router(
 )
 ```

-**Shop Router** (`app/api/v1/shop/__init__.py` or create if doesn't exist):
+**Storefront Router** (`app/api/v1/storefront/__init__.py` or create if doesn't exist):
 ```python
-from app.api.v1.shop import content_pages
+from app.api.v1.storefront import content_pages

 api_router.include_router(
    content_pages.router,
    prefix="/content-pages",
-    tags=["shop-content-pages"]
+    tags=["storefront-content-pages"]
 )
 ```

-### 4. Update Shop Routes to Use CMS
+### 4. Update Storefront Routes to Use CMS

-Edit `app/routes/shop_pages.py` to add a generic content page handler:
+Edit `app/routes/storefront_pages.py` to add a generic content page handler:

 ```python
 from app.services.content_page_service import content_page_service
@@ -107,18 +107,18 @@ async def generic_content_page(
        raise HTTPException(status_code=404, detail=f"Page not found: {slug}")

    return templates.TemplateResponse(
-        "shop/content-page.html",
-        get_shop_context(request, page=page)
+        "storefront/content-page.html",
+        get_storefront_context(request, page=page)
    )
 ```

 ### 5. Create Generic Content Page Template

-Create `app/templates/shop/content-page.html`:
+Create `app/templates/storefront/content-page.html`:

 ```jinja2
-{# app/templates/shop/content-page.html #}
-{% extends "shop/base.html" %}
+{# app/templates/storefront/content-page.html #}
+{% extends "storefront/base.html" %}

 {% block title %}{{ page.title }}{% endblock %}

@@ -159,14 +159,14 @@ Create `app/templates/shop/content-page.html`:

 ### 6. Update Footer to Load Navigation Dynamically

-Edit `app/templates/shop/base.html` to load navigation from database.
+Edit `app/templates/storefront/base.html` to load navigation from database.

 First, update the context helper to include footer pages:

 ```python
-# app/routes/shop_pages.py
+# app/routes/storefront_pages.py

-def get_shop_context(request: Request, **extra_context) -> dict:
+def get_storefront_context(request: Request, **extra_context) -> dict:
    # ... existing code ...

    # Load footer navigation pages
@@ -198,7 +198,7 @@ def get_shop_context(request: Request, **extra_context) -> dict:
 Then update the footer template:

 ```jinja2
-{# app/templates/shop/base.html - Footer section #}
+{# app/templates/storefront/base.html - Footer section #}

 <div>
    <h4 class="font-semibold mb-4">Quick Links</h4>
@@ -367,7 +367,7 @@ curl -X POST http://localhost:8000/api/v1/admin/content-pages/platform \
    "show_in_footer": true
  }'

-# View in shop
+# View in storefront
 curl http://localhost:8000/store/orion/about
 ```

@@ -385,7 +385,7 @@ curl -X POST http://localhost:8000/api/v1/store/orion/content-pages/ \
    "is_published": true
  }'

-# View in shop (should show store content)
+# View in storefront (should show store content)
 curl http://localhost:8000/store/orion/about
 ```

@@ -396,7 +396,7 @@ curl http://localhost:8000/store/orion/about
 curl -X DELETE http://localhost:8000/api/v1/store/orion/content-pages/{id} \
  -H "Authorization: Bearer <store_token>"

-# View in shop (should fall back to platform default)
+# View in storefront (should fall back to platform default)
 curl http://localhost:8000/store/orion/about
 ```

--- a/docs/features/content-management-system.md
+++ b/docs/features/content-management-system.md
@@ -204,12 +204,12 @@ DELETE /api/v1/store/{code}/content-pages/15

 After deletion, platform default will be shown again.

-### Shop Frontend (Public)
+### Storefront (Public)

 **1. Get Page Content**

 ```bash
-GET /api/v1/shop/content-pages/about
+GET /api/v1/storefront/content-pages/about
 ```

 Automatically uses store context from middleware:
@@ -221,12 +221,12 @@ Automatically uses store context from middleware:

 ```bash
 # Get all navigation pages
-GET /api/v1/shop/content-pages/navigation
+GET /api/v1/storefront/content-pages/navigation

 # Filter by placement
-GET /api/v1/shop/content-pages/navigation?header_only=true
-GET /api/v1/shop/content-pages/navigation?footer_only=true
-GET /api/v1/shop/content-pages/navigation?legal_only=true
+GET /api/v1/storefront/content-pages/navigation?header_only=true
+GET /api/v1/storefront/content-pages/navigation?footer_only=true
+GET /api/v1/storefront/content-pages/navigation?legal_only=true
 ```

 Returns published pages filtered by navigation placement.
@@ -246,10 +246,10 @@ app/
 │   │   └── content_pages.py      ← Admin API endpoints
 │   ├── store/
 │   │   └── content_pages.py      ← Store API endpoints
-│   └── shop/
+│   └── storefront/
 │       └── content_pages.py      ← Public API endpoints
 │
-└── templates/shop/
+└── templates/storefront/
    ├── about.html                ← Content page template
    ├── faq.html
    ├── contact.html
@@ -263,8 +263,8 @@ app/
 Create a reusable template for all content pages:

 ```jinja2
-{# app/templates/shop/content-page.html #}
-{% extends "shop/base.html" %}
+{# app/templates/storefront/content-page.html #}
+{% extends "storefront/base.html" %}

 {% block title %}{{ page.title }}{% endblock %}

@@ -310,7 +310,7 @@ Create a reusable template for all content pages:
 ### Route Handler

 ```python
-# app/routes/shop_pages.py
+# app/routes/storefront_pages.py

 from app.services.content_page_service import content_page_service

@@ -339,8 +339,8 @@ async def content_page(
        raise HTTPException(status_code=404, detail=f"Page not found: {slug}")

    return templates.TemplateResponse(
-        "shop/content-page.html",
-        get_shop_context(request, page=page)
+        "storefront/content-page.html",
+        get_storefront_context(request, page=page)
    )
 ```

@@ -349,7 +349,7 @@ async def content_page(
 Update footer to load links from database:

 ```jinja2
-{# app/templates/shop/base.html #}
+{# app/templates/storefront/base.html #}

 <footer>
  <div class="grid grid-cols-3">
@@ -552,11 +552,11 @@ PUT    /api/v1/store/{code}/content-pages/{id}       # Update store page
 DELETE /api/v1/store/{code}/content-pages/{id}       # Delete store page
 ```

-### Shop (Public) Endpoints
+### Storefront (Public) Endpoints

 ```
-GET /api/v1/shop/content-pages/navigation  # Get navigation links
-GET /api/v1/shop/content-pages/{slug}      # Get page content
+GET /api/v1/storefront/content-pages/navigation  # Get navigation links
+GET /api/v1/storefront/content-pages/{slug}      # Get page content
 ```

 ## Example: Complete Workflow
--- a/docs/features/platform-homepage.md
+++ b/docs/features/platform-homepage.md
@@ -497,12 +497,12 @@ content_page_service.create_page(

 **Get page content:**
 ```bash
-GET /api/v1/shop/content-pages/about
+GET /api/v1/storefront/content-pages/about
 ```

 **Get navigation:**
 ```bash
-GET /api/v1/shop/content-pages/navigation
+GET /api/v1/storefront/content-pages/navigation
 ```

 ---
@@ -681,11 +681,11 @@ PUT    /api/v1/admin/content-pages/{id}         # Update page
 DELETE /api/v1/admin/content-pages/{id}         # Delete page
 ```

-### Shop (Public) Endpoints
+### Storefront (Public) Endpoints

 ```
-GET /api/v1/shop/content-pages/navigation       # Get nav links
-GET /api/v1/shop/content-pages/{slug}           # Get page content
+GET /api/v1/storefront/content-pages/navigation       # Get nav links
+GET /api/v1/storefront/content-pages/{slug}           # Get page content
 ```

 ---
--- a/docs/features/store-landing-pages.md
+++ b/docs/features/store-landing-pages.md
@@ -4,7 +4,7 @@ Complete guide to creating custom landing pages for store storefronts.

 ## Overview

-Each store can have a custom landing page at their root URL with different design templates. This landing page serves as the store's homepage, separate from the e-commerce shop section.
+Each store can have a custom landing page at their root URL with different design templates. This landing page serves as the store's homepage, separate from the e-commerce storefront section.

 ### URL Structure

@@ -14,10 +14,10 @@ Root Landing Page:
 - Subdomain:       https://orion.platform.com/      → Landing Page
 - Path-based:      http://localhost:8000/stores/orion/ → Landing Page

-E-commerce Shop:
- Custom Domain:   https://customdomain.com/shop/      → Shop Homepage
- Subdomain:       https://orion.platform.com/shop/ → Shop Homepage
- Path-based:      http://localhost:8000/stores/orion/shop/ → Shop Homepage
+E-commerce Storefront:
+- Custom Domain:   https://customdomain.com/storefront/      → Storefront Homepage
+- Subdomain:       https://orion.platform.com/storefront/ → Storefront Homepage
+- Path-based:      http://localhost:8000/storefront/orion/ → Storefront Homepage
 ```

 ## Features
@@ -25,7 +25,7 @@ E-commerce Shop:
 ✅ **Multiple Templates**: Choose from 4 different landing page designs
 ✅ **CMS-Powered**: Content managed through ContentPage model
 ✅ **Per-Store Customization**: Each store can have unique design
-✅ **Auto-Fallback**: Redirects to shop if no landing page exists
+✅ **Auto-Fallback**: Redirects to storefront if no landing page exists
 ✅ **Theme-Aware**: Uses store's theme colors and branding

 ## Available Templates
@@ -112,7 +112,7 @@ Set `is_published=True` to make the landing page live.
 If no landing page exists:
 1. System checks for `slug="landing"`
 2. If not found, checks for `slug="home"`
-3. If neither exists, **redirects to `/shop/`**
+3. If neither exists, **redirects to `/storefront/`**

 This ensures stores always have a working homepage even without a landing page.

@@ -169,7 +169,7 @@ ADD COLUMN template VARCHAR(50) NOT NULL DEFAULT 'default';

 ### Get Landing Page
 ```http
-GET /api/v1/shop/content-pages/landing
+GET /api/v1/storefront/content-pages/landing
 Referer: https://orion.platform.com/

 Response:
@@ -195,7 +195,7 @@ Response:
 ### Test Fallback
 1. Delete or unpublish landing page
 2. Access store root URL
-3. Should redirect to `/shop/`
+3. Should redirect to `/storefront/`

 ## Customization Guide

@@ -206,9 +206,9 @@ Response:
   app/templates/store/landing-{name}.html
   ```

-2. Extend shop base:
+2. Extend storefront base:
   ```jinja2
-   {% extends "shop/base.html" %}
+   {% extends "storefront/base.html" %}
   ```

 3. Use template variables as needed
@@ -238,7 +238,7 @@ Edit directly and changes apply immediately (no rebuild needed).

 2. **Keep Content Concise**: Landing pages should be scannable

-3. **Strong CTAs**: Always link to `/shop/` for e-commerce
+3. **Strong CTAs**: Always link to `/storefront/` for e-commerce

 4. **Use Theme Colors**: Templates automatically use store theme