""" @router AdminOrderRouter (Backend/app/api/v1/routers/AdminOrderRouter.py) @purpose CRM Admin endpoint controllers to search, view, and modify storefront customer orders and trigger status transitions. """ from fastapi import APIRouter, Depends, HTTPException, status from sqlalchemy.orm import Session from pydantic import BaseModel from typing import List, Optional, Dict from datetime import datetime import ulid import json 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.OrderModel import Order, OrderItem, OrderStatusHistory from app.models.EcomCustomerModel import EcomCustomer from app.services.InventoryService import record_ledger_entry from app.models.InventoryLedgerModel import InventoryLedger from app.models.InvoiceModel import Invoice from app.models.ProductModel import ProductVariant from app.services.NotificationGatewayService import NotificationGatewayService from app.schemas.NotificationGateway import EntityNotificationDispatchCreate from app.services.WarrantyService import WarrantyService from app.services.CreditService import CreditService from app.services.ShiprocketService import shiprocket_service router = APIRouter(prefix="/api/v1/admin/orders", tags=["Admin CRM Customer Orders"]) # --- Schemas --- class OrderItemDetail(BaseModel): order_item_id: str product_id: str variant_id: str product_name: str sku: str unit_price: float quantity: int total_price: float part_numbers: Optional[List[str]] = [] class StatusHistorySchema(BaseModel): previous_status: Optional[str] new_status: str changed_by: str reason: Optional[str] created_at: datetime class AdminOrderDetailResponse(BaseModel): order_id: str order_no: str customer_id: Optional[str] customer_email: Optional[str] = None customer_name: Optional[str] = None total_amount: float discount_amount: float is_discounted: bool = False discount_type: Optional[str] = None discount_reason: Optional[str] = None coupon_code: Optional[str] = None tax_amount: float shipping_cost: float final_amount: float status: str payment_status: str fulfillment_status: str shipping_address_json: Optional[str] = None billing_address_json: Optional[str] = None tracking_number: Optional[str] = None courier_name: Optional[str] = None shipping_label_url: Optional[str] = None package_weight: Optional[float] = None logistics_provider: Optional[str] = None created_at: datetime items: List[OrderItemDetail] history: List[StatusHistorySchema] class AdminOrderListResponse(BaseModel): order_id: str order_no: str customer_email: Optional[str] = None customer_name: Optional[str] = None customer_phone: Optional[str] = None final_amount: float discount_amount: float = 0.0 is_discounted: bool = False discount_type: Optional[str] = None coupon_code: Optional[str] = None status: str payment_status: str shipping_label_url: Optional[str] = None created_at: datetime class StatusUpdatePayload(BaseModel): status: str tracking_number: Optional[str] = None courier_name: Optional[str] = None package_weight: Optional[float] = None logistics_provider: Optional[str] = "SHIPROCKET" reason: Optional[str] = None part_numbers_mapping: Optional[Dict[str, List[str]]] = None # --- Endpoints --- @router.get("", response_model=List[AdminOrderListResponse]) def list_all_orders( is_discounted: Optional[bool] = None, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ List all customer orders in the system with optional discounted-order filter. """ query = db.query(Order) if is_discounted is not None: query = query.filter(Order.is_discounted == is_discounted) orders = query.order_by(Order.created_at.desc()).all() result = [] for o in orders: cust_email = None cust_name = None cust_phone = None if o.customer: cust_email = o.customer.email cust_name = f"{o.customer.first_name} {o.customer.last_name}".strip() cust_phone = o.customer.phone elif o.shipping_address_json or o.billing_address_json: try: addr = json.loads(o.shipping_address_json or o.billing_address_json or "{}") cust_name = addr.get("full_name") or addr.get("name") cust_phone = addr.get("phone") cust_email = addr.get("email") except Exception: pass result.append( AdminOrderListResponse( order_id=o.order_id, order_no=o.order_no, customer_email=cust_email or "N/A", customer_name=cust_name or "Walk-in Guest", customer_phone=cust_phone or "N/A", final_amount=float(o.final_amount), discount_amount=float(o.discount_amount or 0.0), is_discounted=bool(o.is_discounted), discount_type=o.discount_type, coupon_code=o.coupon_code, status=o.status, payment_status=o.payment_status, shipping_label_url=o.shipping_label_url, created_at=o.created_at ) ) return result @router.get("/{order_id}", response_model=AdminOrderDetailResponse) def get_order_details( order_id: str, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Retrieve full details for any order including items, customer metadata, and status logs. """ order = db.query(Order).filter(Order.order_id == order_id).first() if not order: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail="Order not found" ) cust_email = None cust_name = None if order.customer: cust_email = order.customer.email cust_name = f"{order.customer.first_name} {order.customer.last_name}" return AdminOrderDetailResponse( order_id=order.order_id, order_no=order.order_no, customer_id=order.customer_id, customer_email=cust_email, customer_name=cust_name, total_amount=float(order.total_amount), discount_amount=float(order.discount_amount or 0.0), is_discounted=bool(order.is_discounted), discount_type=order.discount_type, discount_reason=order.discount_reason, coupon_code=order.coupon_code, tax_amount=float(order.tax_amount or 0.0), shipping_cost=float(order.shipping_cost or 0.0), final_amount=float(order.final_amount), status=order.status, payment_status=order.payment_status, fulfillment_status=order.fulfillment_status, shipping_address_json=order.shipping_address_json, billing_address_json=order.billing_address_json, tracking_number=order.tracking_number, courier_name=order.courier_name, shipping_label_url=order.shipping_label_url, package_weight=float(order.package_weight) if order.package_weight else None, logistics_provider=order.logistics_provider, created_at=order.created_at, items=[ OrderItemDetail( order_item_id=item.item_id, product_id=item.product_id, variant_id=item.variant_id, product_name=item.product_name, sku=item.sku, unit_price=float(item.unit_price), quantity=item.quantity, total_price=float(item.total_price), part_numbers=item.part_numbers or [] ) for item in order.items ], history=[ StatusHistorySchema( previous_status=h.previous_status, new_status=h.new_status, changed_by=h.changed_by, reason=h.reason, created_at=h.created_at ) for h in order.history ] ) from fastapi import BackgroundTasks from app.core.events.notification_events import dispatch_internal_notification from app.core.database.db_session import SessionLocal def _dispatch_bg_notification(tenant_id: str, payload: EntityNotificationDispatchCreate): bg_db = SessionLocal() try: NotificationGatewayService.dispatch_entity_notification( db=bg_db, tenant_id=tenant_id, payload=payload ) finally: bg_db.close() @router.put("/{order_id}/status") async def update_order_status( order_id: str, payload: StatusUpdatePayload, background_tasks: BackgroundTasks, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Transition an order status, record timeline logs, write ledger confirmations/releases, and update tracking coordinates. Staff can manually set: PENDING, CONFIRMED, READY_FOR_DELIVERY, CANCELLED. Statuses like SHIPPED, OUT_FOR_DELIVERY, and DELIVERED are strictly managed by Shiprocket webhooks. """ order = db.query(Order).filter(Order.order_id == order_id).first() if not order: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail="Order not found" ) previous_status = order.status raw_status = payload.status.strip() # Normalize status names if raw_status in ["READY_FOR_DELIVERY", "READY FOR DELIVERY", "Ready for delivery"]: new_status = "READY_FOR_DELIVERY" elif raw_status in ["CONFIRMED", "ORDER_CONFIRMED", "Confirmed"]: new_status = "ORDER_CONFIRMED" elif raw_status in ["CANCELLED", "Cancelled"]: new_status = "CANCELLED" elif raw_status in ["PENDING", "Pending"]: new_status = "PENDING" else: new_status = raw_status.upper() # 1. Enforce restriction: Staff cannot manually set carrier-driven statuses if new_status in ["SHIPPED", "OUT_FOR_DELIVERY", "DELIVERED"]: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=f"Status '{new_status}' cannot be set manually. It is automatically updated by Shiprocket when the courier collects and delivers the parcel." ) # 2. Enforce restriction: Cannot revert back to PENDING once confirmed if new_status in ["PENDING", "ORDER_CREATED", "PAYMENT_PENDING"] and previous_status not in ["PENDING", "ORDER_CREATED", "PAYMENT_PENDING"]: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Orders cannot be reverted back to Pending once confirmed." ) # Transition tracking info if provided if payload.tracking_number: order.tracking_number = payload.tracking_number if payload.courier_name: order.courier_name = payload.courier_name if payload.part_numbers_mapping: for item in order.items: if item.item_id in payload.part_numbers_mapping: item.part_numbers = payload.part_numbers_mapping[item.item_id] # Handle READY_FOR_DELIVERY automated logistics dispatch if new_status == "READY_FOR_DELIVERY": order.fulfillment_status = "READY_FOR_DELIVERY" provider = (payload.logistics_provider or "SHIPROCKET").upper() weight = float(payload.package_weight or 0.5) if provider == "SHIPROCKET": try: ship_res = await shiprocket_service.book_and_schedule_pickup( order=order, weight_kg=weight, courier_preference=payload.courier_name ) order.tracking_number = ship_res.get("awb_code") order.courier_name = ship_res.get("courier_name") order.shipping_label_url = ship_res.get("label_url") order.package_weight = weight order.logistics_provider = "SHIPROCKET" order.pickup_scheduled = bool(ship_res.get("pickup_scheduled", True)) except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Shiprocket booking failed: {str(e)}" ) else: order.logistics_provider = "LOCAL_DELIVERY" order.package_weight = weight order.shipping_label_url = f"/api/v1/shipping/label/preview/{order.order_id}" # Set fulfillment status flags if new_status in ["SHIPPED", "DELIVERED"]: order.fulfillment_status = "FULFILLED" elif new_status == "CANCELLED": order.fulfillment_status = "CANCELLED" # --- STOCK CONFIRMATION / RELEASE LOGIC --- # 1. Transition: ORDER_CREATED/PAYMENT_PENDING/PENDING -> CONFIRMED/READY_FOR_DELIVERY if new_status in ["ORDER_CONFIRMED", "CONFIRMED", "READY_FOR_DELIVERY", "PROCESSING", "SHIPPED", "DELIVERED"] and previous_status in ["ORDER_CREATED", "PAYMENT_PENDING", "PENDING"]: # Record the physical sale transition in the ledger by subtracting quantity for item in order.items: record_ledger_entry( variant_id=item.variant_id, event_type="ONLINE_SALE_FROM_RESERVATION", qty=-item.quantity, # Deduct stock upon confirmation reference_id=order.order_id, db=db, notes=f"Physical stock sale confirmed from reservation for order {order.order_no}", commit=False, ) order.payment_status = "PAYMENT_CAPTURED" # 2. Transition: Active -> CANCELLED elif new_status == "CANCELLED" and previous_status != "CANCELLED": # Check if the order was already confirmed was_confirmed = db.query(InventoryLedger).filter( InventoryLedger.reference_id == order.order_id, InventoryLedger.event_type == "ONLINE_SALE_FROM_RESERVATION" ).first() is not None # Check return eligibility: eligible if never delivered, or delivered within last 6 days can_restore = True if previous_status == "DELIVERED": del_history = db.query(OrderStatusHistory).filter( OrderStatusHistory.order_id == order.order_id, OrderStatusHistory.new_status == "DELIVERED" ).order_by(OrderStatusHistory.created_at.desc()).first() del_time = del_history.created_at if del_history else order.updated_at from datetime import datetime now = datetime.now(del_time.tzinfo) if del_time.tzinfo else datetime.now() delta = now - del_time if delta.days >= 6: can_restore = False for item in order.items: if was_confirmed: if can_restore: # Record RETURN (+qty) to restore physical and available stock if within 6 days record_ledger_entry( variant_id=item.variant_id, event_type="RETURN", qty=item.quantity, reference_id=order.order_id, db=db, notes=f"Restored stock from cancelled confirmed order {order.order_no} within 6-day window", commit=False, ) else: # Beyond 6 days, do not restore stock (write 0 delta) record_ledger_entry( variant_id=item.variant_id, event_type="RETURN", qty=0, reference_id=order.order_id, db=db, notes=f"Stock not restored: returned order {order.order_no} was past 6-day return window", commit=False, ) else: # If not confirmed yet, release the ONLINE_RESERVE reservation (qty=0) record_ledger_entry( variant_id=item.variant_id, event_type="ONLINE_RESERVE_RELEASE", qty=0, reference_id=order.order_id, db=db, notes=f"Released reservation for cancelled order {order.order_no}", commit=False, ) if order.payment_status == "PAYMENT_CAPTURED": order.payment_status = "REFUNDED" # Dispatch Refund Notification background_tasks.add_task( _dispatch_bg_notification, tenant_id=current_user.tenant_id if hasattr(current_user, 'tenant_id') else "tenant_default", payload=EntityNotificationDispatchCreate( channel="BOTH", notification_type="REFUND_TRIGGERED", entity_id=order.order_id ) ) else: order.payment_status = "PAYMENT_FAILED" # Add change log history = OrderStatusHistory( history_id=str(ulid.ULID()), order_id=order.order_id, previous_status=previous_status, new_status=new_status, changed_by=current_user.email, reason=payload.reason or "Status updated via CRM Admin Panel" ) db.add(history) # Set status order.status = new_status db.commit() if new_status == "DELIVERED": WarrantyService.generate_warranty_for_order(db, order.order_id) CreditService.create_pending_credit_for_order(db, order.order_id) elif new_status in ["RETURNED", "CANCELLED"]: CreditService.void_pending_credit(db, "ORDER", order.order_id, reason=f"Order marked as {new_status}") CreditService.refund_redeemed_credits(db, order.customer_id, order.order_id, order.order_no) background_tasks.add_task( dispatch_internal_notification, event_type="ORDER_STATUS_CHANGED", message=f"Order {order.order_no} status changed to {new_status}", context={"order_id": order.order_id, "status": new_status} ) background_tasks.add_task( _dispatch_bg_notification, tenant_id="tenant_default", payload=EntityNotificationDispatchCreate( channel="BOTH", notification_type="ORDER_STATUS_CHANGED", entity_id=order.order_id ) ) return { "message": "Order status updated successfully", "order_id": order_id, "new_status": order.status, "shipping_label_url": order.shipping_label_url, "tracking_number": order.tracking_number, "courier_name": order.courier_name, "pickup_scheduled": order.pickup_scheduled } # --- Manual Order Creation Schemas --- class AdminOrderCreateItem(BaseModel): variant_id: str quantity: int unit_price: float class AdminOrderCreateRequest(BaseModel): customer_name: Optional[str] = None customer_email: Optional[str] = None customer_phone: Optional[str] = None items: List[AdminOrderCreateItem] shipping_address: Optional[str] = None payment_status: str = "PAID" payment_method: str = "CASH" # CASH, UPI, CARD, MIXED_PAYMENT cash_amount: Optional[float] = 0.0 digital_amount: Optional[float] = 0.0 digital_method: Optional[str] = None # UPI or CARD razorpay_order_id: Optional[str] = None razorpay_payment_id: Optional[str] = None razorpay_signature: Optional[str] = None notification_channel: Optional[str] = "BOTH" # WHATSAPP, EMAIL, BOTH discount_amount: Optional[float] = 0.0 discount_type: Optional[str] = "FIXED" # FIXED or PERCENT discount_reason: Optional[str] = None coupon_code: Optional[str] = None class PosRazorpayOrderRequest(BaseModel): amount: float @router.post("/create-pos-razorpay-order") def create_pos_razorpay_order( payload: PosRazorpayOrderRequest, current_user: User = Depends(get_current_user) ): """ Creates a Razorpay order for POS walk-in counter checkout. """ from app.core.razorpay import RazorpayService from app.core.config.Config import settings if payload.amount <= 0: raise HTTPException(status_code=400, detail="Amount must be greater than 0") amount_paise = int(round(payload.amount * 100)) rzp = RazorpayService() receipt_id = f"pos_rcpt_{ulid.ULID()}" order = rzp.create_order( amount_paise=amount_paise, receipt=receipt_id, notes={"pos_cashier": current_user.email} ) return { "razorpay_order_id": order["id"], "amount_paise": amount_paise, "amount": payload.amount, "key_id": settings.RAZORPAY_KEY_ID } @router.post("/create") def create_admin_order( payload: AdminOrderCreateRequest, current_user: User = Depends(get_current_user), db: Session = Depends(get_db) ): """ Directly write a manual/offline store walk-in counter order and auto-generate its Sales Invoice. Supports point-of-sale item billing, real-time trade discounts, and coupon code redemptions. """ from app.services.OrderService import OrderService items_dicts = [item.dict() for item in payload.items] return OrderService.create_walk_in_order( db=db, items_payload=items_dicts, customer_name=payload.customer_name, customer_email=payload.customer_email, customer_phone=payload.customer_phone, shipping_address=payload.shipping_address, payment_status=payload.payment_status or "PAID", payment_method=payload.payment_method or "CASH", cash_amount=payload.cash_amount or 0.0, digital_amount=payload.digital_amount or 0.0, digital_method=payload.digital_method, razorpay_order_id=payload.razorpay_order_id, razorpay_payment_id=payload.razorpay_payment_id, razorpay_signature=payload.razorpay_signature, actor_email=current_user.email, actor_user_id=current_user.user_id, notification_channel=payload.notification_channel or "BOTH", discount_amount=payload.discount_amount or 0.0, discount_type=payload.discount_type or "FIXED", discount_reason=payload.discount_reason, coupon_code=payload.coupon_code )