refactor: rename shop to storefront for consistency

Rename all "shop" directories and references to "storefront" to match the API and route naming convention already in use. Renamed directories: - app/templates/shop/ → app/templates/storefront/ - static/shop/ → static/storefront/ - app/templates/shared/macros/shop/ → .../macros/storefront/ - docs/frontend/shop/ → docs/frontend/storefront/ Renamed files: - shop.css → storefront.css - shop-layout.js → storefront-layout.js Updated references in: - app/routes/storefront_pages.py (21 template references) - app/modules/cms/routes/pages/vendor.py - app/templates/storefront/base.html (static paths) - All storefront templates (extends/includes) - docs/architecture/frontend-structure.md This aligns the template/static naming with: - Route file: storefront_pages.py - API directory: app/api/v1/storefront/ - Module routes: */routes/api/storefront.py - URL paths: /storefront/* Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-30 22:58:28 +01:00
parent 9decb9c29e
commit 7245f79f7b
62 changed files with 94 additions and 94 deletions
--- a/docs/frontend/storefront/authentication-pages.md
+++ b/docs/frontend/storefront/authentication-pages.md
@@ -0,0 +1,476 @@
+# Shop Authentication Pages
+
+## Overview
+
+This document details the implementation of customer authentication pages in the shop frontend. All pages use Tailwind CSS, Alpine.js, and integrate with the multi-theme system for a branded, consistent experience across all vendors.
+
+## Implementation Date
+2025-11-24
+
+---
+
+## 📄 Available Pages
+
+### 1. Login Page
+**Location:** `app/templates/shop/account/login.html`
+**Route:** `/shop/account/login`
+
+#### Features
+- Two-column layout with vendor branding on the left
+- Email and password fields with validation
+- Password visibility toggle
+- "Remember me" checkbox
+- Links to register and forgot password pages
+- Error and success message alerts
+- Loading states with animated spinner
+- Theme-aware colors using CSS variables
+- Full dark mode support
+- Mobile responsive design
+
+#### Alpine.js Component
+```javascript
+function customerLogin() {
+    return {
+        credentials: { email: '', password: '' },
+        rememberMe: false,
+        showPassword: false,
+        loading: false,
+        errors: {},
+        alert: { show: false, type: 'error', message: '' },
+        dark: false,
+
+        async handleLogin() {
+            // Validates input
+            // Calls POST /api/v1/shop/auth/login
+            // Stores token in localStorage
+            // Redirects to account page or return URL
+        }
+    }
+}
+```
+
+#### API Integration
+- **Endpoint:** `POST /api/v1/shop/auth/login`
+- **Request:** `{ email_or_username: string, password: string }`
+- **Response:** `{ access_token: string, user: object }`
+
+---
+
+### 2. Register Page
+**Location:** `app/templates/shop/account/register.html`
+**Route:** `/shop/account/register`
+
+#### Features
+- Two-column layout with vendor branding
+- Form fields:
+  - First name (required)
+  - Last name (required)
+  - Email (required, validated)
+  - Phone (optional)
+  - Password (required, min 8 chars, 1 letter, 1 number)
+  - Confirm password (required, must match)
+  - Marketing consent checkbox
+- Real-time client-side validation
+- Password visibility toggle
+- Password strength requirements displayed
+- Theme-aware styling
+- Loading states with spinner
+- Success/error message handling
+- Redirects to login page after successful registration
+
+#### Validation Rules
+- **First Name:** Required, non-empty
+- **Last Name:** Required, non-empty
+- **Email:** Required, valid email format
+- **Password:** Minimum 8 characters, at least one letter, at least one number
+- **Confirm Password:** Must match password field
+
+#### Alpine.js Component
+```javascript
+function customerRegistration() {
+    return {
+        formData: {
+            first_name: '',
+            last_name: '',
+            email: '',
+            phone: '',
+            password: '',
+            marketing_consent: false
+        },
+        confirmPassword: '',
+        showPassword: false,
+        loading: false,
+        errors: {},
+
+        validateForm() {
+            // Validates all fields
+            // Sets this.errors for invalid fields
+            // Returns true if all valid
+        },
+
+        async handleRegister() {
+            // Validates form
+            // Calls POST /api/v1/shop/auth/register
+            // Shows success message
+            // Redirects to login with ?registered=true
+        }
+    }
+}
+```
+
+#### API Integration
+- **Endpoint:** `POST /api/v1/shop/auth/register`
+- **Request:** `{ first_name: string, last_name: string, email: string, phone?: string, password: string, marketing_consent: boolean }`
+- **Response:** `{ message: string }`
+
+---
+
+### 3. Forgot Password Page
+**Location:** `app/templates/shop/account/forgot-password.html`
+**Route:** `/shop/account/forgot-password`
+
+#### Features
+- Two-column layout with vendor branding
+- Email input field
+- Two-state interface:
+  1. **Form State:** Email input with submit button
+  2. **Success State:** Confirmation message with checkmark icon
+- Success state displays:
+  - Checkmark icon
+  - "Check Your Email" heading
+  - Email sent confirmation
+  - Instructions to check inbox
+  - Option to retry if email not received
+- Theme-aware styling
+- Links back to login and shop homepage
+- Dark mode support
+- Mobile responsive
+
+#### Alpine.js Component
+```javascript
+function forgotPassword() {
+    return {
+        email: '',
+        emailSent: false,
+        loading: false,
+        errors: {},
+        alert: { show: false, type: 'error', message: '' },
+        dark: false,
+
+        async handleSubmit() {
+            // Validates email
+            // Calls POST /api/v1/shop/auth/forgot-password
+            // Sets emailSent = true on success
+            // Shows confirmation message
+        }
+    }
+}
+```
+
+#### API Integration
+- **Endpoint:** `POST /api/v1/shop/auth/forgot-password`
+- **Request:** `{ email: string }`
+- **Response:** `{ message: string }`
+
+---
+
+## 🎨 Theme Integration
+
+All authentication pages inject the vendor's theme CSS variables for consistent branding:
+
+```html
+<style id="vendor-theme-variables">
+    :root {
+        {% for key, value in theme.css_variables.items() %}
+        {{ key }}: {{ value }};
+        {% endfor %}
+    }
+
+    /* Theme-aware button and focus colors */
+    .btn-primary-theme {
+        background-color: var(--color-primary);
+    }
+    .btn-primary-theme:hover:not(:disabled) {
+        background-color: var(--color-primary-dark, var(--color-primary));
+        filter: brightness(0.9);
+    }
+    .focus-primary:focus {
+        border-color: var(--color-primary);
+        box-shadow: 0 0 0 3px rgba(var(--color-primary-rgb, 124, 58, 237), 0.1);
+    }
+</style>
+```
+
+### Themed Elements
+
+| Element | CSS Variable | Usage |
+|---------|-------------|--------|
+| Left panel background | `var(--color-primary)` | Brand color fills entire left column |
+| Submit buttons | `var(--color-primary)` | Primary action buttons |
+| Links | `var(--color-primary)` | Forgot password, register, login links |
+| Checkboxes | `var(--color-primary)` | Remember me, marketing consent |
+| Focus states | `var(--color-primary)` | Input field focus rings |
+| Vendor logo | `theme.branding.logo` | Displayed in left column |
+
+### Benefits
+- ✅ Each vendor's auth pages automatically match their brand
+- ✅ Consistent with main shop design
+- ✅ Dark mode adapts to vendor colors
+- ✅ Professional, polished appearance
+- ✅ No custom CSS needed per vendor
+
+---
+
+## 📱 Responsive Design
+
+### Mobile (<640px)
+- Vertical layout (branding on top, form below)
+- Smaller h-32 branding section
+- Full-width buttons
+- Reduced padding (p-6 instead of p-12)
+- Touch-friendly input fields
+- Stacked form elements
+
+### Tablet (640px-1024px)
+- Side-by-side layout begins (md:flex-row)
+- Branding section grows (md:h-auto md:w-1/2)
+- Form section gets more space (md:w-1/2)
+- Comfortable padding (sm:p-12)
+
+### Desktop (>1024px)
+- Full two-column layout
+- Max width container (max-w-4xl)
+- Centered on page with margins
+- Larger brand imagery
+- Optimal form spacing
+
+---
+
+## 🔒 Security Features
+
+### Client-Side Security
+- Input validation before API submission
+- Password visibility toggle (not plain text by default)
+- HTTPS required (enforced by deployment)
+- No sensitive data in URLs or query params
+- Tokens stored in localStorage (not cookies)
+- Form autocomplete attributes for password managers
+
+### Server-Side Security (API)
+- Password hashing with bcrypt
+- Email validation and sanitization
+- Rate limiting on auth endpoints
+- CSRF protection
+- SQL injection prevention via ORM
+- JWT token-based authentication
+- Secure password reset tokens
+
+---
+
+## 🎯 Design Principles
+
+### Consistency
+- All three pages share the same layout structure
+- Identical styling patterns and spacing
+- Consistent error/success message handling
+- Same loading state indicators
+
+### User Experience
+- Clear visual hierarchy
+- Immediate feedback on actions
+- Helpful error messages
+- Loading states prevent duplicate submissions
+- Success states confirm actions
+- Links to related pages (login ↔ register ↔ forgot password)
+
+### Accessibility
+- Semantic HTML
+- Proper form labels
+- Focus states visible
+- Keyboard navigation support
+- Screen reader friendly
+- Sufficient color contrast
+
+### Performance
+- Minimal JavaScript (Alpine.js only)
+- Tailwind CSS from CDN with local fallback
+- No external dependencies beyond Alpine.js
+- Fast page loads
+- Inline SVG icons (no image requests)
+
+---
+
+## 🔗 Navigation Flow
+
+```
+Shop Homepage
+    ↓
+Login Page ←→ Register Page
+    ↓              ↓
+Forgot Password    |
+    ↓              ↓
+Check Email   Account/Cart
+```
+
+### Link Structure
+- **Login Page:**
+  - "Forgot password?" → `/shop/account/forgot-password`
+  - "Create an account" → `/shop/account/register`
+  - "← Continue shopping" → `/shop/`
+
+- **Register Page:**
+  - "Already have an account? Sign in instead" → `/shop/account/login`
+
+- **Forgot Password Page:**
+  - "Remember your password? Sign in" → `/shop/account/login`
+  - "← Continue shopping" → `/shop/`
+
+All links use `{{ base_url }}` for multi-access routing support.
+
+---
+
+## 🛠️ Customization Guide
+
+### For Developers
+
+#### Adding New Fields
+1. Add field to HTML form
+2. Add field to Alpine.js data
+3. Update validation logic
+4. Update API request body
+5. Update backend endpoint
+
+#### Changing Validation Rules
+Edit the `validateForm()` method in Alpine.js component:
+
+```javascript
+validateForm() {
+    this.clearAllErrors();
+    let isValid = true;
+
+    // Add/modify validation rules
+    if (!this.formData.field_name.trim()) {
+        this.errors.field_name = 'Field is required';
+        isValid = false;
+    }
+
+    return isValid;
+}
+```
+
+#### Customizing Theme Variables
+Vendors can customize colors in their theme configuration:
+
+```python
+theme = {
+    "colors": {
+        "primary": "#6366f1",  # Changes all primary elements
+        "secondary": "#8b5cf6",
+        "accent": "#ec4899"
+    }
+}
+```
+
+### For Vendors
+Vendors can customize:
+- Primary brand color (buttons, links, left panel)
+- Logo (displayed in left column)
+- Custom CSS (additional styling)
+- Dark mode logo variant
+
+No code changes needed - all controlled via theme configuration.
+
+---
+
+## 📊 File Locations
+
+```
+app/
+├── templates/shop/account/
+│   ├── login.html              ← Customer login page
+│   ├── register.html           ← Customer registration page
+│   └── forgot-password.html    ← Password reset page
+│
+└── api/v1/shop/
+    └── auth.py                 ← Authentication endpoints
+
+static/shared/css/
+├── base.css                    ← Base CSS (optional reference)
+└── auth.css                    ← Auth CSS (optional reference)
+
+Note: Templates use Tailwind CSS classes directly, not the CSS files above.
+```
+
+---
+
+## ✅ Testing Checklist
+
+### Functionality
+- [ ] Login form submits correctly
+- [ ] Register form creates new account
+- [ ] Forgot password sends email
+- [ ] Validation errors display properly
+- [ ] Success messages show correctly
+- [ ] Loading states appear during API calls
+- [ ] Redirects work after success
+- [ ] Remember me checkbox persists
+- [ ] Password visibility toggle works
+
+### Theme Integration
+- [ ] Vendor colors apply correctly
+- [ ] Vendor logo displays
+- [ ] Dark mode works with vendor colors
+- [ ] Custom fonts load
+- [ ] Left panel uses primary color
+- [ ] Buttons use primary color
+
+### Responsive Design
+- [ ] Mobile layout works (<640px)
+- [ ] Tablet layout works (640-1024px)
+- [ ] Desktop layout works (>1024px)
+- [ ] Touch targets are adequate
+- [ ] Forms are usable on mobile
+
+### Security
+- [ ] Passwords are masked by default
+- [ ] No sensitive data in URLs
+- [ ] API calls use HTTPS
+- [ ] Tokens stored securely
+- [ ] Input validation works
+
+### Accessibility
+- [ ] Keyboard navigation works
+- [ ] Focus states visible
+- [ ] Form labels present
+- [ ] Error messages announced
+- [ ] Color contrast sufficient
+
+---
+
+## 🚀 Future Enhancements
+
+Possible additions:
+- Social login (Google, Facebook)
+- Two-factor authentication (2FA)
+- Password strength meter
+- Email verification flow
+- OAuth integration
+- Account recovery via phone
+- Security questions
+- Biometric authentication
+
+---
+
+## 📚 Related Documentation
+
+- [Shop Frontend Architecture](./architecture.md)
+- [Page Template Guide](./page-templates.md)
+- [Theme System Overview](../../architecture/theme-system/overview.md)
+- [Theme Presets](../../architecture/theme-system/presets.md)
+- [API Authentication Documentation](../../api/authentication.md)
+
+---
+
+**Last Updated:** 2025-11-24
+**Status:** ✅ Production Ready
+**Maintainer:** Development Team