feat(loyalty): implement Phase 2 - company-wide points system

Complete implementation of loyalty module Phase 2 features:

Database & Models:
- Add company_id to LoyaltyProgram for chain-wide loyalty
- Add company_id to LoyaltyCard for multi-location support
- Add CompanyLoyaltySettings model for admin-controlled settings
- Add points expiration, welcome bonus, and minimum redemption fields
- Add POINTS_EXPIRED, WELCOME_BONUS transaction types

Services:
- Update program_service for company-based queries
- Update card_service with enrollment and welcome bonus
- Update points_service with void_points for returns
- Update stamp_service for company context
- Update pin_service for company-wide operations

API Endpoints:
- Admin: Program listing with stats, company detail views
- Vendor: Terminal operations, card management, settings
- Storefront: Customer card/transactions, self-enrollment

UI Templates:
- Admin: Programs dashboard, company detail, settings
- Vendor: Terminal, cards list, card detail, settings, stats, enrollment
- Storefront: Dashboard, history, enrollment, success pages

Background Tasks:
- Point expiration task (daily, based on inactivity)
- Wallet sync task (hourly)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/modules/loyalty/routes/pages/__init__.py

@@ -1,8 +1,15 @@
 # app/modules/loyalty/routes/pages/__init__.py
 """
-Loyalty module page routes.
+Loyalty module page routes (HTML rendering).
 
-Reserved for future HTML page endpoints (enrollment pages, etc.).
+Provides Jinja2 template rendering for:
+- Admin pages: Platform loyalty programs dashboard and company management
+- Vendor pages: Loyalty terminal, cards management, settings
+- Storefront pages: Customer loyalty dashboard, self-enrollment
 """
 
-__all__: list[str] = []
+from app.modules.loyalty.routes.pages.admin import router as admin_router
+from app.modules.loyalty.routes.pages.vendor import router as vendor_router
+from app.modules.loyalty.routes.pages.storefront import router as storefront_router
+
+__all__ = ["admin_router", "vendor_router", "storefront_router"]

app/modules/loyalty/routes/pages/admin.py

@@ -0,0 +1,124 @@
+# app/modules/loyalty/routes/pages/admin.py
+"""
+Loyalty Admin Page Routes (HTML rendering).
+
+Admin pages for:
+- Platform loyalty programs dashboard
+- Company loyalty program detail/configuration
+- Platform-wide loyalty statistics
+"""
+
+from fastapi import APIRouter, Depends, Path, Request
+from fastapi.responses import HTMLResponse
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_db, require_menu_access
+from app.templates_config import templates
+from app.modules.enums import FrontendType
+from app.modules.tenancy.models import User
+
+router = APIRouter()
+
+# Route configuration for module route discovery
+ROUTE_CONFIG = {
+    "prefix": "/loyalty",
+    "tags": ["admin-loyalty"],
+}
+
+
+# ============================================================================
+# LOYALTY PROGRAMS DASHBOARD
+# ============================================================================
+
+
+@router.get("/programs", response_class=HTMLResponse, include_in_schema=False)
+async def admin_loyalty_programs(
+    request: Request,
+    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty programs dashboard.
+    Shows all companies with loyalty programs and platform-wide statistics.
+    """
+    return templates.TemplateResponse(
+        "loyalty/admin/programs.html",
+        {
+            "request": request,
+            "user": current_user,
+        },
+    )
+
+
+@router.get("/analytics", response_class=HTMLResponse, include_in_schema=False)
+async def admin_loyalty_analytics(
+    request: Request,
+    current_user: User = Depends(require_menu_access("loyalty-analytics", FrontendType.ADMIN)),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty analytics dashboard.
+    Shows platform-wide loyalty statistics and trends.
+    """
+    return templates.TemplateResponse(
+        "loyalty/admin/analytics.html",
+        {
+            "request": request,
+            "user": current_user,
+        },
+    )
+
+
+# ============================================================================
+# COMPANY LOYALTY DETAIL
+# ============================================================================
+
+
+@router.get(
+    "/companies/{company_id}",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def admin_loyalty_company_detail(
+    request: Request,
+    company_id: int = Path(..., description="Company ID"),
+    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
+    db: Session = Depends(get_db),
+):
+    """
+    Render company loyalty program detail page.
+    Shows company's loyalty program configuration and location breakdown.
+    """
+    return templates.TemplateResponse(
+        "loyalty/admin/company-detail.html",
+        {
+            "request": request,
+            "user": current_user,
+            "company_id": company_id,
+        },
+    )
+
+
+@router.get(
+    "/companies/{company_id}/settings",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def admin_loyalty_company_settings(
+    request: Request,
+    company_id: int = Path(..., description="Company ID"),
+    current_user: User = Depends(require_menu_access("loyalty-programs", FrontendType.ADMIN)),
+    db: Session = Depends(get_db),
+):
+    """
+    Render company loyalty settings page.
+    Admin-controlled settings like staff PIN policy.
+    """
+    return templates.TemplateResponse(
+        "loyalty/admin/company-settings.html",
+        {
+            "request": request,
+            "user": current_user,
+            "company_id": company_id,
+        },
+    )

app/modules/loyalty/routes/pages/storefront.py

@@ -0,0 +1,151 @@
+# app/modules/loyalty/routes/pages/storefront.py
+"""
+Loyalty Storefront Page Routes (HTML rendering).
+
+Customer-facing pages for:
+- Loyalty dashboard (view points, rewards, history)
+- Self-service enrollment
+- Digital card display
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, Query, Request
+from fastapi.responses import HTMLResponse
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_customer_from_cookie_or_header, get_db
+from app.modules.core.utils.page_context import get_storefront_context
+from app.modules.customers.models import Customer
+from app.templates_config import templates
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# No custom prefix - routes are mounted directly at /storefront/
+# Following same pattern as customers module
+
+
+# ============================================================================
+# CUSTOMER LOYALTY DASHBOARD (Authenticated)
+# ============================================================================
+
+
+@router.get(
+    "/account/loyalty",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def customer_loyalty_dashboard(
+    request: Request,
+    current_customer: Customer = Depends(get_current_customer_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render customer loyalty dashboard.
+    Shows points balance, available rewards, and transaction history.
+    """
+    logger.debug(
+        "[STOREFRONT] customer_loyalty_dashboard REACHED",
+        extra={
+            "path": request.url.path,
+            "customer_id": current_customer.id if current_customer else None,
+        },
+    )
+
+    context = get_storefront_context(request, db=db)
+    return templates.TemplateResponse(
+        "loyalty/storefront/dashboard.html",
+        context,
+    )
+
+
+@router.get(
+    "/account/loyalty/history",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def customer_loyalty_history(
+    request: Request,
+    current_customer: Customer = Depends(get_current_customer_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render full transaction history page.
+    """
+    logger.debug(
+        "[STOREFRONT] customer_loyalty_history REACHED",
+        extra={
+            "path": request.url.path,
+            "customer_id": current_customer.id if current_customer else None,
+        },
+    )
+
+    context = get_storefront_context(request, db=db)
+    return templates.TemplateResponse(
+        "loyalty/storefront/history.html",
+        context,
+    )
+
+
+# ============================================================================
+# SELF-SERVICE ENROLLMENT (Public - No Authentication)
+# ============================================================================
+
+
+@router.get(
+    "/loyalty/join",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def loyalty_self_enrollment(
+    request: Request,
+    db: Session = Depends(get_db),
+):
+    """
+    Render self-service enrollment page.
+    Public page - customers can sign up via QR code at store counter.
+    """
+    logger.debug(
+        "[STOREFRONT] loyalty_self_enrollment REACHED",
+        extra={
+            "path": request.url.path,
+        },
+    )
+
+    context = get_storefront_context(request, db=db)
+    return templates.TemplateResponse(
+        "loyalty/storefront/enroll.html",
+        context,
+    )
+
+
+@router.get(
+    "/loyalty/join/success",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def loyalty_enrollment_success(
+    request: Request,
+    card: str = Query(None, description="Card number"),
+    db: Session = Depends(get_db),
+):
+    """
+    Render enrollment success page.
+    Shows card number and next steps.
+    """
+    logger.debug(
+        "[STOREFRONT] loyalty_enrollment_success REACHED",
+        extra={
+            "path": request.url.path,
+            "card": card,
+        },
+    )
+
+    context = get_storefront_context(request, db=db)
+    context["enrolled_card_number"] = card
+    return templates.TemplateResponse(
+        "loyalty/storefront/enroll-success.html",
+        context,
+    )

app/modules/loyalty/routes/pages/vendor.py

@@ -0,0 +1,226 @@
+# app/modules/loyalty/routes/pages/vendor.py
+"""
+Loyalty Vendor Page Routes (HTML rendering).
+
+Vendor pages for:
+- Loyalty terminal (primary daily interface for staff)
+- Loyalty members management
+- Program settings
+- Stats dashboard
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends, Path, Request
+from fastapi.responses import HTMLResponse
+from sqlalchemy.orm import Session
+
+from app.api.deps import get_current_vendor_from_cookie_or_header, get_db
+from app.modules.core.services.platform_settings_service import platform_settings_service
+from app.templates_config import templates
+from app.modules.tenancy.models import User, Vendor
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+# Route configuration for module route discovery
+ROUTE_CONFIG = {
+    "prefix": "/loyalty",
+    "tags": ["vendor-loyalty"],
+}
+
+
+# ============================================================================
+# HELPER: Build Vendor Context
+# ============================================================================
+
+
+def get_vendor_context(
+    request: Request,
+    db: Session,
+    current_user: User,
+    vendor_code: str,
+    **extra_context,
+) -> dict:
+    """Build template context for vendor loyalty pages."""
+    # Load vendor from database
+    vendor = db.query(Vendor).filter(Vendor.subdomain == vendor_code).first()
+
+    # Get platform defaults
+    platform_config = platform_settings_service.get_storefront_config(db)
+
+    # Resolve with vendor override
+    storefront_locale = platform_config["locale"]
+    storefront_currency = platform_config["currency"]
+
+    if vendor and vendor.storefront_locale:
+        storefront_locale = vendor.storefront_locale
+
+    context = {
+        "request": request,
+        "user": current_user,
+        "vendor": vendor,
+        "vendor_code": vendor_code,
+        "storefront_locale": storefront_locale,
+        "storefront_currency": storefront_currency,
+        "dashboard_language": vendor.dashboard_language if vendor else "en",
+    }
+
+    # Add any extra context
+    if extra_context:
+        context.update(extra_context)
+
+    return context
+
+
+# ============================================================================
+# LOYALTY TERMINAL (Primary Daily Interface)
+# ============================================================================
+
+
+@router.get(
+    "/{vendor_code}/terminal",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_terminal(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty terminal page.
+    Primary interface for staff to look up customers, award points, and process redemptions.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/terminal.html",
+        get_vendor_context(request, db, current_user, vendor_code),
+    )
+
+
+# ============================================================================
+# LOYALTY MEMBERS
+# ============================================================================
+
+
+@router.get(
+    "/{vendor_code}/cards",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_cards(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty members list page.
+    Shows all loyalty card holders for this company.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/cards.html",
+        get_vendor_context(request, db, current_user, vendor_code),
+    )
+
+
+@router.get(
+    "/{vendor_code}/cards/{card_id}",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_card_detail(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    card_id: int = Path(..., description="Loyalty card ID"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty card detail page.
+    Shows card holder info, transaction history, and actions.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/card-detail.html",
+        get_vendor_context(request, db, current_user, vendor_code, card_id=card_id),
+    )
+
+
+# ============================================================================
+# PROGRAM SETTINGS
+# ============================================================================
+
+
+@router.get(
+    "/{vendor_code}/settings",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_settings(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty program settings page.
+    Allows vendor to configure points rate, rewards, branding, etc.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/settings.html",
+        get_vendor_context(request, db, current_user, vendor_code),
+    )
+
+
+# ============================================================================
+# STATS DASHBOARD
+# ============================================================================
+
+
+@router.get(
+    "/{vendor_code}/stats",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_stats(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render loyalty statistics dashboard.
+    Shows vendor's loyalty program metrics and trends.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/stats.html",
+        get_vendor_context(request, db, current_user, vendor_code),
+    )
+
+
+# ============================================================================
+# ENROLLMENT
+# ============================================================================
+
+
+@router.get(
+    "/{vendor_code}/enroll",
+    response_class=HTMLResponse,
+    include_in_schema=False,
+)
+async def vendor_loyalty_enroll(
+    request: Request,
+    vendor_code: str = Path(..., description="Vendor code"),
+    current_user: User = Depends(get_current_vendor_from_cookie_or_header),
+    db: Session = Depends(get_db),
+):
+    """
+    Render customer enrollment page.
+    Staff interface for enrolling new customers into the loyalty program.
+    """
+    return templates.TemplateResponse(
+        "loyalty/vendor/enroll.html",
+        get_vendor_context(request, db, current_user, vendor_code),
+    )