- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
# Dynamic Delivery Engine & Cash on Delivery (COD) Deprecation Policy
|
|
|
|
## 1. Overview & Policy Rationale
|
|
|
|
As part of the iFixKart Unified Commerce platform hardening:
|
|
1. **Cash on Delivery (COD) is Completely Deprecated & Forbidden**:
|
|
- Cash on Delivery creates severe operational friction, high Return to Origin (RTO) expenses, and courier reconciliation overhead.
|
|
- All e-commerce purchases must be completed via secure online payment gateways (Razorpay: UPI, Credit/Debit Cards, Netbanking, Wallets) or zero-amount checkout covered completely by earned Store Credits.
|
|
- Any order creation request with `payment_method == "COD"` is strictly blocked by the backend with an HTTP 400 Bad Request exception.
|
|
2. **Zero Hardcoded Static Free Delivery**:
|
|
- Static "Free Delivery over ₹999" hardcoded banners and progress bars have been eliminated from all storefront components.
|
|
- Free delivery is **disabled by default** (`shipping_free_delivery_enabled = false`).
|
|
- Standard shipping charges (`shipping_delivery_charge = ₹99.0`) apply to all orders by default.
|
|
- Promotional Free Delivery can only be enabled dynamically through the Admin Settings panel (`/settings` -> Delivery & Shipping blade).
|
|
|
|
---
|
|
|
|
## 2. Dynamic Settings Schema
|
|
|
|
Delivery rules are stored dynamically in the MySQL `settings` table as key-value pairs:
|
|
|
|
| Key | Default Value | Description |
|
|
| :--- | :--- | :--- |
|
|
| `shipping_delivery_charge` | `99.0` | Standard flat delivery fee applied when free delivery is not active or not qualified. |
|
|
| `shipping_free_delivery_enabled` | `false` | Global toggle allowing promotional free shipping. When `false`, all orders incur standard delivery fee regardless of subtotal. |
|
|
| `shipping_free_delivery_min_order_amount` | `999.0` | Minimum order subtotal required to qualify for free shipping when `shipping_free_delivery_enabled` is set to `true`. |
|
|
|
|
---
|
|
|
|
## 3. Backend Architecture & Enforcement
|
|
|
|
### 3.1 Delivery Service (`DeliveryService.py`)
|
|
- Provides `get_delivery_settings(db)` and `update_delivery_settings(db, settings)`.
|
|
- Core calculation engine:
|
|
```python
|
|
def calculate_shipping_cost(db: Session, subtotal: float) -> float:
|
|
settings = get_delivery_settings(db)
|
|
if settings.get("free_delivery_enabled", False):
|
|
min_order = settings.get("free_delivery_min_order_amount", 999.0)
|
|
if subtotal >= min_order:
|
|
return 0.0
|
|
return float(settings.get("delivery_charge", 99.0))
|
|
```
|
|
|
|
### 3.2 Order Creation & Rejection (`OrderService.py`)
|
|
- Explicit COD rejection hook:
|
|
```python
|
|
if payment_method and payment_method.strip().upper() == "COD":
|
|
raise HTTPException(
|
|
status_code=400,
|
|
detail="Cash on Delivery (COD) is not supported. Please complete your payment online using UPI, Card, Netbanking, or Store Credits."
|
|
)
|
|
```
|
|
- Shipping cost calculation is bound to `DeliveryService.calculate_shipping_cost(db, subtotal)`.
|
|
|
|
### 3.3 Dynamic Delivery API Endpoints (`SettingsRouter.py`)
|
|
- **`GET /api/v1/settings/delivery`** (Public): Returns `{ delivery_charge, free_delivery_enabled, free_delivery_min_order_amount }`. Used by Storefront Cart, Drawer, and Checkout pages.
|
|
- **`PUT /api/v1/settings/delivery`** (Admin Authenticated): Allows store administrators to adjust charges, toggle free delivery, and update the qualifying threshold.
|
|
|
|
---
|
|
|
|
## 4. Admin Panel Settings Blade (`/settings`)
|
|
|
|
The Admin Dashboard provides a dedicated **"Delivery & Shipping"** tab under System Settings:
|
|
- **Standard Delivery Charge (₹)**: Numeric input to configure the base delivery cost.
|
|
- **Promotional Free Delivery Toggle**: Switch to toggle free delivery availability.
|
|
- **Free Delivery Minimum Threshold (₹)**: Active when the toggle is enabled to specify the minimum cart amount.
|
|
- **Active Rule Simulator**: Real-time display showing administrators how rules apply to orders below and above the threshold.
|
|
|
|
---
|
|
|
|
## 5. Storefront Frontend Dynamic Adaptation
|
|
|
|
### 5.1 Checkout Page (`app/checkout/page.tsx`)
|
|
- COD radio card and submission branch completely removed.
|
|
- Payment options strictly limited to Online Payment (Razorpay) or Zero-Amount checkout when Store Credits cover 100% of the total amount.
|
|
- Dynamically loads delivery settings on mount and computes shipping dynamically.
|
|
|
|
### 5.2 Cart Page (`app/cart/page.tsx`) & Cart Drawer (`CartDrawer.tsx`)
|
|
- Free shipping progress bar (`"Add ₹X more to get Free Delivery"`) is completely hidden unless `deliverySettings.free_delivery_enabled === true`.
|
|
- When disabled, only the standard delivery fee is reflected in the breakdown with no static promises.
|
|
|
|
### 5.3 Static Text Cleanups
|
|
- Header TopBar: Updated from `"Free Shipping over ₹999!"` to `"Express Pan-India Delivery | 100% Genuine Spare Parts"`.
|
|
- Features section: Changed from `"Free Shipping"` to `"Fast Express Delivery"`.
|
|
- Trust Badges: Dynamically outputs `"Express Delivery"` when free shipping is disabled.
|