""" @router AdminCouponRouter (Backend/app/api/v1/routers/AdminCouponRouter.py) @purpose CRM Admin management of promotional coupons, rule engines, and usage audits. """ from fastapi import APIRouter, Depends, HTTPException, status, Query from sqlalchemy.orm import Session from pydantic import BaseModel, Field from typing import List, Optional, Dict, Any from datetime import datetime import json import ulid from app.core.database.db_session import get_db from app.core.permissions.RoleChecker import get_current_user from app.models.UserModel import User from app.models.CouponModel import Coupon, CouponUsage from app.services.CouponService import CouponService router = APIRouter(prefix="/api/v1/admin/coupons", tags=["Admin Promotional Coupons"]) # --- Pydantic Schemas --- class CouponCreateRequest(BaseModel): code: str = Field(..., min_length=2, max_length=50) description: Optional[str] = None discount_type: str = Field(..., pattern="^(PERCENT|FIXED)$") discount_value: float = Field(..., gt=0) min_order_amount: Optional[float] = 0.0 max_discount_cap: Optional[float] = None first_order_only: bool = False channel_scope: str = Field(default="ALL", pattern="^(ALL|STOREFRONT|STORE_POS)$") usage_limit_total: Optional[int] = None usage_limit_per_customer: Optional[int] = 1 applicable_category_ids: Optional[List[str]] = None applicable_brand_ids: Optional[List[str]] = None applicable_model_ids: Optional[List[str]] = None start_date: Optional[datetime] = None end_date: Optional[datetime] = None is_active: bool = True class CouponUpdateRequest(BaseModel): description: Optional[str] = None discount_type: Optional[str] = Field(None, pattern="^(PERCENT|FIXED)$") discount_value: Optional[float] = Field(None, gt=0) min_order_amount: Optional[float] = None max_discount_cap: Optional[float] = None first_order_only: Optional[bool] = None channel_scope: Optional[str] = Field(None, pattern="^(ALL|STOREFRONT|STORE_POS)$") usage_limit_total: Optional[int] = None usage_limit_per_customer: Optional[int] = None applicable_category_ids: Optional[List[str]] = None applicable_brand_ids: Optional[List[str]] = None applicable_model_ids: Optional[List[str]] = None start_date: Optional[datetime] = None end_date: Optional[datetime] = None is_active: Optional[bool] = None class CouponUsageSummary(BaseModel): usage_id: str coupon_id: str customer_id: str order_id: str discount_amount: float used_at: datetime class CouponResponse(BaseModel): coupon_id: str code: str description: Optional[str] discount_type: str discount_value: float min_order_amount: float max_discount_cap: Optional[float] first_order_only: bool channel_scope: str usage_limit_total: Optional[int] usage_limit_per_customer: int current_usage_count: int applicable_category_ids: Optional[List[str]] applicable_brand_ids: Optional[List[str]] applicable_model_ids: Optional[List[str]] start_date: Optional[datetime] end_date: Optional[datetime] is_active: bool created_at: datetime updated_at: datetime def _normalize_channel_in(val: Optional[str]) -> str: if not val: return "OMNICHANNEL" u = val.strip().upper() if u in ["STOREFRONT", "ONLINE", "ONLINE_ONLY"]: return "ONLINE_ONLY" if u in ["STORE_POS", "POS", "POS_ONLY"]: return "POS_ONLY" return "OMNICHANNEL" def _normalize_channel_out(val: Optional[str]) -> str: if not val: return "ALL" u = val.strip().upper() if u == "ONLINE_ONLY": return "STOREFRONT" if u == "POS_ONLY": return "STORE_POS" return "ALL" def _normalize_discount_type_in(val: str) -> str: u = val.strip().upper() if u in ["PERCENT", "PERCENTAGE"]: return "PERCENTAGE" return "FIXED" def _normalize_discount_type_out(val: str) -> str: u = val.strip().upper() if u in ["PERCENTAGE", "PERCENT"]: return "PERCENT" return "FIXED" def _coupon_to_response(coupon: Coupon) -> Dict[str, Any]: def _parse_json_list(val): if not val: return [] if isinstance(val, list): return val try: return json.loads(val) except Exception: return [] return { "coupon_id": coupon.coupon_id, "code": coupon.code, "description": coupon.description or coupon.title, "discount_type": _normalize_discount_type_out(coupon.discount_type), "discount_value": float(coupon.discount_value), "min_order_amount": float(coupon.min_order_amount or 0.0), "max_discount_cap": float(coupon.max_discount_cap) if coupon.max_discount_cap is not None else None, "first_order_only": bool(coupon.first_order_only), "channel_scope": _normalize_channel_out(coupon.channel_scope), "usage_limit_total": coupon.usage_limit_total, "usage_limit_per_customer": coupon.usage_limit_per_customer or 1, "current_usage_count": coupon.times_used or 0, "applicable_category_ids": _parse_json_list(coupon.applicable_category_ids), "applicable_brand_ids": _parse_json_list(coupon.applicable_brand_ids), "applicable_model_ids": _parse_json_list(coupon.applicable_model_ids), "start_date": coupon.valid_from, "end_date": coupon.valid_to, "is_active": bool(coupon.is_active), "created_at": coupon.created_at, "updated_at": coupon.updated_at } # --- Router Endpoints --- @router.get("", response_model=List[CouponResponse]) def list_coupons( search: Optional[str] = Query(None, description="Search by code or description"), channel: Optional[str] = Query(None, description="Filter by channel scope"), is_active: Optional[bool] = Query(None, description="Filter by active status"), first_order_only: Optional[bool] = Query(None, description="Filter 1st-time customer rules"), current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ List all promotion coupons with optional filtering. """ query = db.query(Coupon) if search: s = f"%{search.strip().upper()}%" query = query.filter((Coupon.code.like(s)) | (Coupon.description.like(f"%{search.strip()}%")) | (Coupon.title.like(f"%{search.strip()}%"))) if channel: norm_chan = _normalize_channel_in(channel) query = query.filter(Coupon.channel_scope == norm_chan) if is_active is not None: query = query.filter(Coupon.is_active == is_active) if first_order_only is not None: query = query.filter(Coupon.first_order_only == first_order_only) coupons = query.order_by(Coupon.created_at.desc()).all() return [_coupon_to_response(c) for c in coupons] @router.get("/{coupon_id}", response_model=CouponResponse) def get_coupon( coupon_id: str, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Get a single coupon by ID. """ coupon = db.query(Coupon).filter(Coupon.coupon_id == coupon_id).first() if not coupon: raise HTTPException(status_code=404, detail="Coupon not found") return _coupon_to_response(coupon) @router.post("", response_model=CouponResponse, status_code=status.HTTP_201_CREATED) def create_coupon( payload: CouponCreateRequest, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Create a new promotional coupon with targeting rules. """ clean_code = payload.code.strip().upper() existing = db.query(Coupon).filter(Coupon.code == clean_code).first() if existing: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=f"Coupon code '{clean_code}' already exists" ) now = datetime.now() valid_from = payload.start_date if payload.start_date else now valid_to = payload.end_date if payload.end_date else datetime(2035, 12, 31, 23, 59, 59) coupon = Coupon( coupon_id=str(ulid.ULID()), code=clean_code, title=payload.description or clean_code, description=payload.description, discount_type=_normalize_discount_type_in(payload.discount_type), discount_value=payload.discount_value, min_order_amount=payload.min_order_amount or 0.0, max_discount_cap=payload.max_discount_cap, first_order_only=payload.first_order_only, channel_scope=_normalize_channel_in(payload.channel_scope), usage_limit_total=payload.usage_limit_total, usage_limit_per_customer=payload.usage_limit_per_customer or 1, times_used=0, applicable_category_ids=json.dumps(payload.applicable_category_ids) if payload.applicable_category_ids else None, applicable_brand_ids=json.dumps(payload.applicable_brand_ids) if payload.applicable_brand_ids else None, applicable_model_ids=json.dumps(payload.applicable_model_ids) if payload.applicable_model_ids else None, valid_from=valid_from, valid_to=valid_to, is_active=payload.is_active ) db.add(coupon) db.commit() db.refresh(coupon) return _coupon_to_response(coupon) @router.put("/{coupon_id}", response_model=CouponResponse) def update_coupon( coupon_id: str, payload: CouponUpdateRequest, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Update rules and constraints for an existing coupon. """ coupon = db.query(Coupon).filter(Coupon.coupon_id == coupon_id).first() if not coupon: raise HTTPException(status_code=404, detail="Coupon not found") if payload.description is not None: coupon.description = payload.description coupon.title = payload.description or coupon.code if payload.discount_type is not None: coupon.discount_type = _normalize_discount_type_in(payload.discount_type) if payload.discount_value is not None: coupon.discount_value = payload.discount_value if payload.min_order_amount is not None: coupon.min_order_amount = payload.min_order_amount if payload.max_discount_cap is not None: coupon.max_discount_cap = payload.max_discount_cap if payload.first_order_only is not None: coupon.first_order_only = payload.first_order_only if payload.channel_scope is not None: coupon.channel_scope = _normalize_channel_in(payload.channel_scope) if payload.usage_limit_total is not None: coupon.usage_limit_total = payload.usage_limit_total if payload.usage_limit_per_customer is not None: coupon.usage_limit_per_customer = payload.usage_limit_per_customer if payload.applicable_category_ids is not None: coupon.applicable_category_ids = json.dumps(payload.applicable_category_ids) if payload.applicable_category_ids else None if payload.applicable_brand_ids is not None: coupon.applicable_brand_ids = json.dumps(payload.applicable_brand_ids) if payload.applicable_brand_ids else None if payload.applicable_model_ids is not None: coupon.applicable_model_ids = json.dumps(payload.applicable_model_ids) if payload.applicable_model_ids else None if payload.start_date is not None: coupon.valid_from = payload.start_date if payload.end_date is not None: coupon.valid_to = payload.end_date if payload.is_active is not None: coupon.is_active = payload.is_active db.commit() db.refresh(coupon) return _coupon_to_response(coupon) @router.delete("/{coupon_id}") def delete_coupon( coupon_id: str, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Deactivates or permanently deletes a coupon if never used. """ coupon = db.query(Coupon).filter(Coupon.coupon_id == coupon_id).first() if not coupon: raise HTTPException(status_code=404, detail="Coupon not found") usage_count = db.query(CouponUsage).filter(CouponUsage.coupon_id == coupon_id).count() if usage_count > 0: # Soft delete / deactivate to preserve historical ledger records coupon.is_active = False db.commit() return {"message": "Coupon has existing redemptions and was deactivated instead of deleted", "coupon_id": coupon_id, "is_active": False} db.delete(coupon) db.commit() return {"message": "Coupon successfully deleted", "coupon_id": coupon_id} @router.get("/{coupon_id}/usages") def get_coupon_usages( coupon_id: str, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Audit redemptions for a specific coupon. """ usages = db.query(CouponUsage).filter(CouponUsage.coupon_id == coupon_id).order_by(CouponUsage.used_at.desc()).all() total_savings = sum(float(u.discount_amount or 0.0) for u in usages) return { "coupon_id": coupon_id, "total_usages": len(usages), "total_discount_given": round(total_savings, 2), "usages": [ { "usage_id": u.usage_id, "customer_id": u.customer_id, "order_id": u.order_id, "discount_amount": float(u.discount_amount), "used_at": u.used_at } for u in usages ] }