343 lines
13 KiB
Python
343 lines
13 KiB
Python
"""
|
|
@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
|
|
]
|
|
}
|