orion/CHANGELOG_2025-11-23.md

Changelog - November 23, 2025

Summary

Major improvements to shop frontend functionality, landing pages, and cart system. Fixed critical issues preventing products from being added to cart, refactored templates for proper styling, and established comprehensive navigation architecture.

Landing Page System

Features Added

• ✅ Store landing pages at root URLs (/, /stores/{code}/)
• ✅ Four template options: default, minimal, modern, full
• ✅ CMS-powered content management via ContentPage model
• ✅ Auto-redirect to /shop/ when no landing page exists
• ✅ Two-tier navigation: landing page (/) + shop (/shop/)

Templates Created

1. app/templates/store/landing-default.html - Clean professional layout
2. app/templates/store/landing-minimal.html - Ultra-simple centered design
3. app/templates/store/landing-modern.html - Full-screen with animations
4. app/templates/store/landing-full.html - Split-screen with maximum features

Supporting Files

• scripts/create_landing_page.py - Interactive landing page creator
• docs/features/store-landing-pages.md - Complete usage guide
• docs/frontend/shop/navigation-flow.md - Navigation architecture
• TEST_LANDING_PAGES.md - Testing guide

Database Changes

• Migration f68d8da5315a: Added template field to content_pages table
• Supports values: default, minimal, modern, full

Shop Template Refactoring

Problem Fixed

Pages displayed without styling due to:

• Standalone HTML structure (not extending base template)
• Hardcoded CSS references to non-existent files
• Missing header, footer, and navigation

Templates Refactored

1. Product Detail Page (shop/product.html)

Before: 770 lines of standalone HTML with custom CSS After: 403 lines extending base template

Changes:

• Extends shop/base.html for consistent styling
• Removed hardcoded CSS files
• Added breadcrumbs with landing page navigation
• Integrated with shopLayoutData() for cart functionality
• Uses Tailwind classes + theme CSS variables
• Proper Alpine.js component inheritance

2. Shopping Cart Page (shop/cart.html)

Before: 489 lines standalone HTML After: 319 lines extending base template

Changes:

• Extends shop/base.html
• Modern responsive grid layout
• Integrated toast notifications
• Proper session management
• Breadcrumbs and navigation
• Removed 437 lines of redundant custom CSS

Benefits

• ✅ Consistent styling across all pages
• ✅ Automatic header/footer/navigation
• ✅ Theme variables applied correctly
• ✅ Mobile responsive out of the box
• ✅ Dark mode support
• ✅ Reduced code duplication

Cart Functionality Fixes

Critical Issue: Products Can't Be Added to Cart

Root Cause:

• Products had available_inventory: 0
• inventory table was empty
• available_inventory is calculated from inventory_entries
• canAddToCart check failed

Solution:

• Created scripts/create_inventory.py
• Populates inventory table with 100 units per product
• Now products can be added to cart successfully

Session Management Issue

Root Cause:

• sessionId was undefined in cart/product components
• Parent shopLayoutData() init not being called
• Alpine.js inheritance wasn't working correctly

Solution:

• Store reference to baseData before spreading
• Explicitly call baseData.init.call(this) in child components
• Session ID now properly initialized across all pages

Code Pattern:

const baseData = shopLayoutData();
return {
    ...baseData,
    async init() {
        if (baseData.init) {
            baseData.init.call(this);  // Initialize session
        }
        await this.loadData();
    }
};

Routing and Navigation Fixes

Duplicate /shop/ Prefix

Problem: Routes like /stores/orion/shop/shop/products/4

Root Cause:

# Router mounted with prefix
app.include_router(router, prefix="/shop")

# Routes incorrectly repeated prefix
@router.get("/shop/products/{id}")  # ❌ Wrong

Fix:

@router.get("/products/{id}")  # ✅ Correct

All routes in shop_pages.py fixed.

Missing /shop/ in Template Links

Problem: Links went to /stores/orion/products instead of /shop/products

Fix: Updated all templates:

• shop/base.html - Header, footer, navigation
• shop/products.html - Product links
• shop/product.html - Breadcrumbs, related products
• shop/cart.html - Continue shopping, checkout
• shop/errors/404.html - All fallback links
• shop/account/*.html - Login, register links

Navigation Architecture

Established two-tier system:

• Landing Page (/) - Marketing, branding, store story
• Shop (/shop/) - E-commerce, products, cart, checkout

Navigation Pattern:

• Logo → /shop/ (stay in shop for convenience)
• Breadcrumb "Home" → / (return to landing page)
• Header "Home" → / (return to landing page)

Placeholder Image System

Problem

• Missing images showed broken icon
• Placeholder was .jpg file containing SVG content
• Browsers won't render SVG from non-SVG file

Solution

• Created proper /static/shop/img/placeholder.svg
• Added @error handlers to all image tags
• Automatic fallback when images fail to load

<img
    :src="product.image_link || '/static/shop/img/placeholder.svg'"
    @error="$el.src = '/static/shop/img/placeholder.svg'"
    alt="Product"
>

Updated templates:

• shop/product.html - Main image, thumbnails, related products
• shop/products.html - Product grid
• shop/cart.html - Cart item images

Documentation Updates

New Documentation

1. Shop Frontend Troubleshooting (docs/troubleshooting/shop-frontend.md) Comprehensive guide covering:

• Cart and product issues (inventory, sessions)
• Styling and layout issues (base template, CSS)
• Navigation and routing issues (URLs, links)
• Landing page issues (404s, redirects)
• Alpine.js issues (component data, initialization)
• Debugging tips and console commands

2. Navigation Flow Guide (docs/frontend/shop/navigation-flow.md)

• Complete URL hierarchy
• Navigation patterns (with/without landing page)
• Link reference guide
• User journey examples
• Best practices

Updated Documentation

Database Setup (docs/getting-started/database-setup.md)

• Added data seeding section
• Documented all three seeding scripts
• Complete setup workflow
• Common issues and solutions
• Database reset instructions

Scripts Created

1. Create Inventory (scripts/create_inventory.py)

• Creates inventory entries for products without inventory
• Sets 100 units in "Main Warehouse"
• Can run multiple times (only creates missing entries)
• Required for cart functionality

2. Create Landing Page (scripts/create_landing_page.py)

• Interactive landing page creation
• Template selection (default, minimal, modern, full)
• Updates existing or creates new
• Store listing and status

Commits Summary

1. b7bf505 - feat: implement store landing pages with multi-template support and fix shop routing
2. 1df4f12 - fix: refactor product detail page to extend base template and use correct paths
3. e94b3f9 - fix: resolve product detail page data access and add placeholder image
4. 6fa9ccb - fix: use proper SVG placeholder image across all shop templates
5. 8c9190b - feat: add automatic fallback to placeholder for broken product images
6. 651e58a - fix: refactor cart page to extend base template and fix styling
7. 84c6c38 - fix: add sessionId to shopLayoutData for cart functionality
8. 4c69a94 - fix: properly call parent init in cart and product components
9. b4e52f5 - feat: add detailed logging to add to cart functionality for debugging
10. 3d585e5 - feat: add script to create inventory entries for products
11. f217def - docs: comprehensive updates for today's shop frontend improvements

Files Changed

Modified

• main.py - Root handler for landing pages
• app/routes/shop_pages.py - Fixed duplicate /shop prefix
• app/templates/shop/base.html - Updated header home link
• app/templates/shop/product.html - Complete refactor
• app/templates/shop/cart.html - Complete refactor
• app/templates/shop/products.html - Fixed links and placeholder
• app/templates/shop/content-page.html - Fixed breadcrumbs
• static/shop/js/shop-layout.js - Added sessionId management
• models/database/content_page.py - Added template field

Created

• app/templates/store/landing-default.html
• app/templates/store/landing-minimal.html
• app/templates/store/landing-modern.html
• app/templates/store/landing-full.html
• static/shop/img/placeholder.svg
• scripts/create_landing_page.py
• scripts/create_inventory.py
• docs/features/store-landing-pages.md
• docs/frontend/shop/navigation-flow.md
• docs/troubleshooting/shop-frontend.md
• TEST_LANDING_PAGES.md
• alembic/versions/f68d8da5315a_add_template_field_to_content_pages_for_.py

Deleted

• app/api/v1/public/__init__.py - Unused endpoints
• app/api/v1/public/stores/__init__.py - Unused endpoints
• app/api/v1/public/stores/stores.py - Unused endpoints
• app/templates/store/admin/*.html - Moved to root store/

Testing

Verified Functionality

• ✅ Landing pages display correctly (all 4 templates)
• ✅ Auto-redirect when no landing page exists
• ✅ Products can be added to cart
• ✅ Cart displays items correctly
• ✅ Cart count updates in header
• ✅ Session persists across page loads
• ✅ Placeholder images display for broken URLs
• ✅ All navigation links work correctly
• ✅ Breadcrumb navigation to landing page works
• ✅ Dark mode toggle works
• ✅ Mobile responsive design works

Test URLs

Landing Pages:
- http://localhost:8000/stores/orion/
- http://localhost:8000/stores/fashionhub/
- http://localhost:8000/stores/bookstore/

Shop Pages:
- http://localhost:8000/stores/orion/shop/
- http://localhost:8000/stores/orion/shop/products
- http://localhost:8000/stores/orion/shop/products/1
- http://localhost:8000/stores/orion/shop/cart

Breaking Changes

None. All changes are backwards compatible.

Known Issues

None identified.

Next Steps

Suggested improvements for future work:

1. Checkout page implementation
2. Customer account dashboard
3. Order management system
4. Payment integration
5. Visual landing page builder (Phase 2)
6. Email notifications
7. Product reviews and ratings

Performance

No significant performance impact. Template consolidation actually improves performance by:

• Reducing duplicate CSS
• Shared base template caching
• Fewer HTTP requests for styles

Security

No security implications. All changes maintain existing authentication and authorization.