orion/docs/getting-started/cms-quick-start.md

# CMS Quick Start Guide

A quick reference for setting up and using the Content Management System.

## What is the CMS?

The CMS allows you to manage static content pages (About, Contact, FAQ, etc.) with:
- **Platform defaults** - Base content for all vendors
- **Vendor overrides** - Custom content per vendor
- **Automatic fallback** - Vendors inherit platform defaults unless overridden

## Quick Setup

### 1. Create Default Content Pages

After running migrations, create the default CMS pages:

```bash
make create-cms-defaults
```

This creates 7 platform default pages:
- About Us (`/about`)
- Contact Us (`/contact`)
- FAQ (`/faq`)
- Shipping Policy (`/shipping`)
- Return & Refund Policy (`/returns`)
- Privacy Policy (`/privacy`)
- Terms of Service (`/terms`)

### 2. Full Database Setup

For a complete setup including CMS:

```bash
make db-setup
# Runs: migrations → admin user → CMS pages → demo data
```

## Accessing Pages

All CMS pages are accessible on your shop frontend:

```
# For domain/subdomain access
https://wizamart.shop/about
https://fashionhub.store/contact

# For path-based access
http://localhost:8000/vendor/wizamart/faq
http://localhost:8000/vendors/fashionhub/shipping
```

## Managing Content

### Via Admin Panel

1. Log in to admin panel: `/admin/login`
2. Navigate to **Content Pages** section
3. Create/edit platform defaults (visible to all vendors)

### Via Vendor Dashboard

1. Log in to vendor dashboard: `/vendor/{code}/login`
2. Navigate to **Content Pages** section
3. View platform defaults
4. Create vendor-specific overrides

### Via API

**Admin - Create Platform Default:**
```bash
POST /api/v1/admin/content-pages/platform
{
  "slug": "about",
  "title": "About Us",
  "content": "<p>...</p>",
  "is_published": true,
  "show_in_footer": true
}
```

**Vendor - Create Override:**
```bash
POST /api/v1/vendor/{vendor_code}/content-pages
{
  "slug": "about",
  "title": "About Our Store",
  "content": "<p>Custom content...</p>",
  "is_published": true
}
```

**Public - Retrieve Page:**
```bash
GET /api/v1/shop/content-pages/{slug}
```

## How the Two-Tier System Works

### Lookup Priority

When a customer visits `/about`:

1. **Check vendor override** - Does this vendor have a custom "about" page?
2. **Fallback to platform** - If not, use the platform default "about" page
3. **404 if neither** - Return 404 if no page exists

### Example Scenario

**Platform Default:**
- Slug: `about`
- Title: "About Our Platform"
- Content: Generic platform description

**WizaMart Override:**
- Slug: `about`
- Title: "About WizaMart"
- Content: WizaMart-specific content

**Result:**
- `wizamart.shop/about` → Shows WizaMart custom version
- `fashionhub.store/about` → Shows platform default (no override)

## Footer Navigation

Pages marked with `show_in_footer: true` automatically appear in the shop footer:

```html
<!-- Footer automatically loads from database -->
<footer>
  <div>Quick Links</div>
  <ul>
    <li><a href="/products">Products</a></li>
    <li><a href="/about">About Us</a></li>  <!-- From CMS -->
    <li><a href="/contact">Contact</a></li>  <!-- From CMS -->
  </ul>
</footer>
```

## Common Tasks

### Add a New Default Page

```bash
python -c "
from app.core.database import SessionLocal
from app.services.content_page_service import content_page_service

db = SessionLocal()
content_page_service.create_page(
    db,
    slug='careers',
    title='Careers',
    content='<h1>Join Our Team</h1>...',
    is_published=True,
    show_in_footer=True
)
db.close()
"
```

### Create Vendor Override

Via vendor API or dashboard - vendors can override any platform default by creating a page with the same slug.

### Update Platform Default

Via admin panel or API - updates affect all vendors who haven't created an override.

## Re-running the Script

The script is **idempotent** - safe to run multiple times:

```bash
make create-cms-defaults
# Output: "Skipped: About Us (/about) - already exists"
```

Existing pages are never overwritten.

## Documentation

For complete CMS documentation, see:
- [CMS Feature Documentation](../features/content-management-system.md)
- [CMS Implementation Guide](../features/cms-implementation-guide.md)
- [Database Seeder Guide](../development/database-seeder/database-seeder-documentation.md)

## Troubleshooting

### Pages not showing in footer

Check `show_in_footer` flag:
```sql
SELECT slug, title, show_in_footer FROM content_pages WHERE vendor_id IS NULL;
```

### Vendor override not working

Verify slug matches exactly:
```sql
SELECT vendor_id, slug, title FROM content_pages WHERE slug = 'about';
```

### 404 on content pages

1. Check page is published: `is_published = true`
2. Verify migration was applied: `make migrate-status`
3. Run CMS defaults: `make create-cms-defaults`

## Next Steps

- Customize default content via admin panel
- Create vendor-specific overrides
- Add new custom pages as needed
- Update footer navigation preferences