docs: add comprehensive CMS documentation
Add complete documentation for the Content Management System: Feature Documentation (docs/features/): - content-management-system.md - Complete CMS overview * Two-tier architecture explanation * Database schema and relationships * API reference for all endpoints * Usage workflows for admin/vendor/customer * Best practices and examples - cms-implementation-guide.md - Step-by-step implementation * Activation checklist * Code integration instructions * Testing procedures * Troubleshooting guide Quick Start Guide (docs/getting-started/): - cms-quick-start.md - Quick reference * Setup commands * Access URLs * Managing content (API, admin panel, vendor dashboard) * Two-tier system explained with examples * Common tasks and troubleshooting Updated Seeder Docs: - Add CMS to enhanced seeder coverage list - Add dedicated CMS section with table of pages - Document integration with db-setup workflow - Update best practices MkDocs Configuration: - Add "Features" section with CMS documentation - Add CMS Quick Start to "Getting Started" - Add CDN Fallback Strategy to "Frontend Development" - Complete navigation structure All documentation builds cleanly with no warnings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
216
docs/getting-started/cms-quick-start.md
Normal file
216
docs/getting-started/cms-quick-start.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user