ifixkart-backend/app/api/v1/routers/AdminCouponRouter.py

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
]
}