feat: Add mandatory expected delivery time and SLA tracking to order management

- Implemented expected_delivery_time as a required field when creating orders.
- Added delivery_status and sla_grace_period_minutes to track delivery performance.
- Updated relevant functions and tests to ensure proper handling of new fields.
- Enhanced validation for expected delivery time to ensure it is in the future.

MCP_TOOLS_SUMMARY.md

@@ -8,10 +8,10 @@
 
 ## Order Management (8 tools)
 
-4. **`create_order`** - Create new delivery order
+4. **`create_order`** - Create new delivery order with **MANDATORY expected_delivery_time** and SLA tracking
 5. **`count_orders`** - Count orders by status (pending/assigned/in_transit/delivered)
 6. **`fetch_orders`** - Get list of orders with filters and pagination
-7. **`get_order_details`** - Get full details of specific order by ID
+7. **`get_order_details`** - Get full details of specific order by ID including timing and SLA data
 8. **`search_orders`** - Search orders by customer name, address, or order ID
 9. **`get_incomplete_orders`** - Get all pending/assigned/in_transit orders
 10. **`update_order`** - Update order status, driver, location, notes (with assignment cascading)
@@ -58,6 +58,9 @@
 - ✅ Toll detection & avoidance
 - ✅ Complete fleet management (orders + drivers + assignments)
 - ✅ Assignment system with automatic route calculation
+- ✅ **Mandatory delivery deadline (expected_delivery_time) when creating orders**
+- ✅ **Automatic SLA tracking with grace period**
+- ✅ **Delivery performance status: on_time, late, very_late, failed_on_time, failed_late**
 - ✅ **Automatic driver location updates on delivery completion**
 - ✅ **Mandatory location + reason tracking for failed deliveries**
 - ✅ **Structured failure reasons for analytics and reporting**
@@ -71,7 +74,14 @@
 - **Manual assignment** with validation (pending orders + active drivers only)
 - **Automatic route calculation** from driver location to delivery address
 - **Delivery completion** with automatic driver location update to delivery address
+- **SLA & Timing Tracking**:
+  - Mandatory `expected_delivery_time` when creating orders
+  - Automatic comparison of actual vs expected delivery time
+  - Grace period support (default: 15 minutes)
+  - Performance statuses: `on_time`, `late` (within grace), `very_late` (SLA violation)
+  - `delivered_at` field automatically populated on completion/failure
 - **Delivery failure handling** with mandatory GPS location and failure reason
+- **Failure timing tracking**: `failed_on_time` vs `failed_late` status
 - **Structured failure reasons**: customer_not_available, wrong_address, refused_delivery, damaged_goods, payment_issue, vehicle_breakdown, access_restricted, weather_conditions, other
 - **Status management** with cascading updates across orders/drivers/assignments
 - **Safety checks** preventing deletion of orders/drivers with active assignments

chat/tools.py

@@ -1332,7 +1332,7 @@ def handle_create_order(tool_input: dict) -> dict:
     Execute order creation tool
 
     Args:
-        tool_input: Dict with order fields
+        tool_input: Dict with order fields (expected_delivery_time now REQUIRED)
 
     Returns:
         Order creation result
@@ -1344,30 +1344,48 @@ def handle_create_order(tool_input: dict) -> dict:
     delivery_address = tool_input.get("delivery_address")
     delivery_lat = tool_input.get("delivery_lat")
     delivery_lng = tool_input.get("delivery_lng")
+    expected_delivery_time_str = tool_input.get("expected_delivery_time")
     priority = tool_input.get("priority", "standard")
     special_instructions = tool_input.get("special_instructions")
     weight_kg = tool_input.get("weight_kg", 5.0)
+    sla_grace_period_minutes = tool_input.get("sla_grace_period_minutes", 15)
 
-    # Validate required fields
-    if not all([customer_name, delivery_address, delivery_lat, delivery_lng]):
+    # Validate required fields (expected_delivery_time is now MANDATORY)
+    if not all([customer_name, delivery_address, delivery_lat, delivery_lng, expected_delivery_time_str]):
         return {
             "success": False,
-            "error": "Missing required fields: customer_name, delivery_address, delivery_lat, delivery_lng"
+            "error": "Missing required fields: customer_name, delivery_address, delivery_lat, delivery_lng, expected_delivery_time"
         }
 
     # Generate order ID with microseconds to prevent collisions
     now = datetime.now()
     order_id = f"ORD-{now.strftime('%Y%m%d%H%M%S%f')[:18]}"  # YYYYMMDDHHMMSSμμμμμμ (18 chars)
 
-    # Handle time window
+    # Parse and validate expected_delivery_time
+    try:
+        expected_delivery_time = datetime.fromisoformat(expected_delivery_time_str.replace('Z', '+00:00'))
+
+        # Validate it's in the future
+        if expected_delivery_time <= now:
+            return {
+                "success": False,
+                "error": f"expected_delivery_time must be in the future. Provided: {expected_delivery_time_str}, Current time: {now.isoformat()}"
+            }
+    except (ValueError, AttributeError) as e:
+        return {
+            "success": False,
+            "error": f"Invalid expected_delivery_time format. Must be ISO 8601 format (e.g., '2025-11-15T18:00:00'). Error: {str(e)}"
+        }
+
+    # Handle time window (kept for backward compatibility)
     time_window_end_str = tool_input.get("time_window_end")
     if time_window_end_str:
         try:
             time_window_end = datetime.fromisoformat(time_window_end_str.replace('Z', '+00:00'))
         except:
-            time_window_end = now + timedelta(hours=6)
+            time_window_end = expected_delivery_time  # Use expected time as fallback
     else:
-        time_window_end = now + timedelta(hours=6)
+        time_window_end = expected_delivery_time  # Default to expected delivery time
 
     time_window_start = now + timedelta(hours=2)
 
@@ -1376,9 +1394,9 @@ def handle_create_order(tool_input: dict) -> dict:
         INSERT INTO orders (
             order_id, customer_name, customer_phone, customer_email,
             delivery_address, delivery_lat, delivery_lng,
-            time_window_start, time_window_end,
-            priority, weight_kg, status, special_instructions
-        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
+            time_window_start, time_window_end, expected_delivery_time,
+            priority, weight_kg, status, special_instructions, sla_grace_period_minutes
+        ) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
     """
 
     params = (
@@ -1391,15 +1409,17 @@ def handle_create_order(tool_input: dict) -> dict:
         delivery_lng,
         time_window_start,
         time_window_end,
+        expected_delivery_time,
         priority,
         weight_kg,
         "pending",
-        special_instructions
+        special_instructions,
+        sla_grace_period_minutes
     )
 
     try:
         execute_write(query, params)
-        logger.info(f"Order created: {order_id}")
+        logger.info(f"Order created: {order_id}, expected delivery: {expected_delivery_time.strftime('%Y-%m-%d %H:%M')}")
 
         return {
             "success": True,
@@ -1407,9 +1427,10 @@ def handle_create_order(tool_input: dict) -> dict:
             "status": "pending",
             "customer": customer_name,
             "address": delivery_address,
-            "deadline": time_window_end.strftime("%Y-%m-%d %H:%M"),
+            "expected_delivery": expected_delivery_time.strftime("%Y-%m-%d %H:%M"),
+            "sla_grace_period_minutes": sla_grace_period_minutes,
             "priority": priority,
-            "message": f"Order {order_id} created successfully!"
+            "message": f"Order {order_id} created successfully! Expected delivery: {expected_delivery_time.strftime('%Y-%m-%d %H:%M')}"
         }
     except Exception as e:
         logger.error(f"Database error creating order: {e}")
@@ -1433,10 +1454,12 @@ def handle_create_driver(tool_input: dict) -> dict:
     name = tool_input.get("name")
     phone = tool_input.get("phone")
     email = tool_input.get("email")
-    vehicle_type = tool_input.get("vehicle_type", "van")
+    vehicle_type = tool_input.get("vehicle_type")  # No default - REQUIRED
     vehicle_plate = tool_input.get("vehicle_plate")
     capacity_kg = tool_input.get("capacity_kg", 1000.0)
     capacity_m3 = tool_input.get("capacity_m3", 12.0)
+    current_lat = tool_input.get("current_lat")  # No default - REQUIRED
+    current_lng = tool_input.get("current_lng")  # No default - REQUIRED
 
     # Convert skills to regular list (handles protobuf RepeatedComposite)
     skills_raw = tool_input.get("skills", [])
@@ -1444,21 +1467,40 @@ def handle_create_driver(tool_input: dict) -> dict:
 
     status = tool_input.get("status", "active")
 
-    # Validate required fields
-    if not name:
+    # Validate ALL required fields (name, vehicle_type, current_lat, current_lng)
+    if not all([name, vehicle_type, current_lat is not None, current_lng is not None]):
+        return {
+            "success": False,
+            "error": "Missing required fields: name, vehicle_type, current_lat, current_lng. All fields are mandatory."
+        }
+
+    # Validate coordinates are valid numbers
+    try:
+        current_lat = float(current_lat)
+        current_lng = float(current_lng)
+    except (ValueError, TypeError):
+        return {
+            "success": False,
+            "error": "current_lat and current_lng must be valid numbers"
+        }
+
+    # Validate coordinates are within valid ranges
+    if not (-90 <= current_lat <= 90):
+        return {
+            "success": False,
+            "error": f"Invalid latitude {current_lat}. Must be between -90 and 90"
+        }
+
+    if not (-180 <= current_lng <= 180):
         return {
             "success": False,
-            "error": "Missing required field: name"
+            "error": f"Invalid longitude {current_lng}. Must be between -180 and 180"
         }
 
     # Generate driver ID with microseconds to prevent collisions
     now = datetime.now()
     driver_id = f"DRV-{now.strftime('%Y%m%d%H%M%S%f')[:18]}"  # YYYYMMDDHHMMSSμμμμμμ (18 chars)
 
-    # Default location (San Francisco)
-    current_lat = tool_input.get("current_lat", 37.7749)
-    current_lng = tool_input.get("current_lng", -122.4194)
-
     # Insert into database
     query = """
         INSERT INTO drivers (
@@ -2478,10 +2520,10 @@ def handle_get_order_details(tool_input: dict) -> dict:
             order_id, customer_name, customer_phone, customer_email,
             pickup_address, pickup_lat, pickup_lng,
             delivery_address, delivery_lat, delivery_lng,
-            time_window_start, time_window_end,
+            time_window_start, time_window_end, expected_delivery_time,
             priority, weight_kg, volume_m3, special_instructions,
-            status, assigned_driver_id,
-            created_at, updated_at, delivered_at,
+            status, assigned_driver_id, delivery_status,
+            created_at, updated_at, delivered_at, sla_grace_period_minutes,
             order_value, payment_status,
             requires_signature, is_fragile, requires_cold_storage
         FROM orders
@@ -2527,6 +2569,12 @@ def handle_get_order_details(tool_input: dict) -> dict:
                 "volume_m3": float(row['volume_m3']) if row['volume_m3'] else None,
                 "special_instructions": row['special_instructions']
             },
+            "delivery_status": row['delivery_status'],
+            "timing": {
+                "expected_delivery_time": str(row['expected_delivery_time']) if row['expected_delivery_time'] else None,
+                "delivered_at": str(row['delivered_at']) if row['delivered_at'] else None,
+                "sla_grace_period_minutes": row['sla_grace_period_minutes']
+            },
             "flags": {
                 "requires_signature": row['requires_signature'],
                 "is_fragile": row['is_fragile'],
@@ -2539,8 +2587,7 @@ def handle_get_order_details(tool_input: dict) -> dict:
             "assigned_driver_id": row['assigned_driver_id'],
             "timestamps": {
                 "created_at": str(row['created_at']),
-                "updated_at": str(row['updated_at']) if row['updated_at'] else None,
-                "delivered_at": str(row['delivered_at']) if row['delivered_at'] else None
+                "updated_at": str(row['updated_at']) if row['updated_at'] else None
             }
         }
 
@@ -3918,12 +3965,12 @@ def handle_complete_delivery(tool_input: dict) -> dict:
         conn = get_db_connection()
         cursor = conn.cursor()
 
-        # Get assignment details
+        # Get assignment and order details including timing fields
         cursor.execute("""
             SELECT
                 a.status, a.order_id, a.driver_id,
                 a.delivery_location_lat, a.delivery_location_lng, a.delivery_address,
-                o.customer_name,
+                o.customer_name, o.expected_delivery_time, o.sla_grace_period_minutes,
                 d.name as driver_name
             FROM assignments a
             JOIN orders o ON a.order_id = o.order_id
@@ -3948,6 +3995,8 @@ def handle_complete_delivery(tool_input: dict) -> dict:
         delivery_address = assignment_row['delivery_address']
         customer_name = assignment_row['customer_name']
         driver_name = assignment_row['driver_name']
+        expected_delivery_time = assignment_row['expected_delivery_time']
+        sla_grace_period_minutes = assignment_row['sla_grace_period_minutes'] or 15
 
         # Validate status
         if status not in ["active", "in_progress"]:
@@ -4002,12 +4051,45 @@ def handle_complete_delivery(tool_input: dict) -> dict:
 
         logger.info(f"Driver {driver_id} location updated to delivery address: ({delivery_lat}, {delivery_lng})")
 
-        # Step 3: Update order status to delivered
+        # Step 3: Calculate delivery performance status
+        delivery_status = "on_time"  # Default
+        timing_info = {
+            "expected_delivery_time": expected_delivery_time.isoformat() if expected_delivery_time else None,
+            "actual_delivery_time": completion_time.isoformat(),
+            "sla_grace_period_minutes": sla_grace_period_minutes
+        }
+
+        if expected_delivery_time:
+            # Calculate grace period deadline
+            from datetime import timedelta
+            grace_deadline = expected_delivery_time + timedelta(minutes=sla_grace_period_minutes)
+
+            if completion_time <= expected_delivery_time:
+                delivery_status = "on_time"
+                timing_info["status"] = "On-time delivery"
+                timing_info["delay_minutes"] = 0
+            elif completion_time <= grace_deadline:
+                delivery_status = "late"
+                delay_minutes = int((completion_time - expected_delivery_time).total_seconds() / 60)
+                timing_info["status"] = f"Late (within grace period)"
+                timing_info["delay_minutes"] = delay_minutes
+            else:
+                delivery_status = "very_late"
+                delay_minutes = int((completion_time - expected_delivery_time).total_seconds() / 60)
+                timing_info["status"] = f"Very late (SLA violation)"
+                timing_info["delay_minutes"] = delay_minutes
+
+        # Step 4: Update order status to delivered with timing info
         cursor.execute("""
             UPDATE orders
-            SET status = 'delivered', updated_at = %s
+            SET status = 'delivered',
+                delivered_at = %s,
+                delivery_status = %s,
+                updated_at = %s
             WHERE order_id = %s
-        """, (completion_time, order_id))
+        """, (completion_time, delivery_status, completion_time, order_id))
+
+        logger.info(f"Order {order_id} marked as delivered with status '{delivery_status}'")
 
         # Step 4: Check if driver has other active assignments
         cursor.execute("""
@@ -4044,6 +4126,8 @@ def handle_complete_delivery(tool_input: dict) -> dict:
             "customer_name": customer_name,
             "driver_name": driver_name,
             "completed_at": completion_time.isoformat(),
+            "delivery_status": delivery_status,
+            "timing": timing_info,
             "delivery_location": {
                 "lat": float(delivery_lat),
                 "lng": float(delivery_lng),
@@ -4054,7 +4138,7 @@ def handle_complete_delivery(tool_input: dict) -> dict:
                 "location_updated_at": completion_time.isoformat()
             },
             "cascading_actions": cascading_actions,
-            "message": f"Delivery completed! Order {order_id} delivered by {driver_name}. Driver location updated to delivery address."
+            "message": f"Delivery completed! Order {order_id} delivered by {driver_name}. Status: {timing_info.get('status', delivery_status)}. Driver location updated to delivery address."
         }
 
     except Exception as e:
@@ -4153,12 +4237,12 @@ def handle_fail_delivery(tool_input: dict) -> dict:
         conn = get_db_connection()
         cursor = conn.cursor()
 
-        # Get assignment details
+        # Get assignment and order details including timing fields
         cursor.execute("""
             SELECT
                 a.status, a.order_id, a.driver_id,
                 a.delivery_address,
-                o.customer_name,
+                o.customer_name, o.expected_delivery_time, o.sla_grace_period_minutes,
                 d.name as driver_name
             FROM assignments a
             JOIN orders o ON a.order_id = o.order_id
@@ -4181,6 +4265,8 @@ def handle_fail_delivery(tool_input: dict) -> dict:
         delivery_address = assignment_row['delivery_address']
         customer_name = assignment_row['customer_name']
         driver_name = assignment_row['driver_name']
+        expected_delivery_time = assignment_row['expected_delivery_time']
+        sla_grace_period_minutes = assignment_row['sla_grace_period_minutes'] or 15
 
         # Validate status
         if status not in ["active", "in_progress"]:
@@ -4227,12 +4313,35 @@ def handle_fail_delivery(tool_input: dict) -> dict:
 
         logger.info(f"Driver {driver_id} location updated to reported position: ({current_lat}, {current_lng})")
 
-        # Step 3: Update order status to failed
+        # Step 3: Calculate delivery performance status for failure
+        delivery_status = "failed_on_time"  # Default - failed but before deadline
+        timing_info = {
+            "expected_delivery_time": expected_delivery_time.isoformat() if expected_delivery_time else None,
+            "failure_time": failure_time.isoformat(),
+            "sla_grace_period_minutes": sla_grace_period_minutes
+        }
+
+        if expected_delivery_time:
+            if failure_time <= expected_delivery_time:
+                delivery_status = "failed_on_time"
+                timing_info["status"] = "Failed before deadline (attempted delivery on time)"
+            else:
+                delivery_status = "failed_late"
+                delay_minutes = int((failure_time - expected_delivery_time).total_seconds() / 60)
+                timing_info["status"] = f"Failed after deadline (late attempt)"
+                timing_info["delay_minutes"] = delay_minutes
+
+        # Step 4: Update order status to failed with timing info
         cursor.execute("""
             UPDATE orders
-            SET status = 'failed', updated_at = %s
+            SET status = 'failed',
+                delivered_at = %s,
+                delivery_status = %s,
+                updated_at = %s
             WHERE order_id = %s
-        """, (failure_time, order_id))
+        """, (failure_time, delivery_status, failure_time, order_id))
+
+        logger.info(f"Order {order_id} marked as failed with status '{delivery_status}'")
 
         # Step 4: Check if driver has other active assignments
         cursor.execute("""
@@ -4274,6 +4383,8 @@ def handle_fail_delivery(tool_input: dict) -> dict:
             "failed_at": failure_time.isoformat(),
             "failure_reason": failure_reason,
             "failure_reason_display": reason_display,
+            "delivery_status": delivery_status,
+            "timing": timing_info,
             "delivery_address": delivery_address,
             "driver_location": {
                 "lat": current_lat,
@@ -4281,7 +4392,7 @@ def handle_fail_delivery(tool_input: dict) -> dict:
                 "updated_at": failure_time.isoformat()
             },
             "cascading_actions": cascading_actions,
-            "message": f"Delivery failed for order {order_id}. Reason: {reason_display}. Driver {driver_name} location updated to ({current_lat}, {current_lng})."
+            "message": f"Delivery failed for order {order_id}. Reason: {reason_display}. Timing: {timing_info.get('status', delivery_status)}. Driver {driver_name} location updated to ({current_lat}, {current_lng})."
         }
 
     except Exception as e:

database/migrations/006_add_delivery_timing.py

@@ -0,0 +1,106 @@
+"""
+Migration 006: Add delivery timing and SLA tracking fields to orders table
+Adds expected_delivery_time (mandatory), delivery_status, and sla_grace_period_minutes
+"""
+
+import sys
+import os
+
+# Add parent directory to path for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
+
+from database.connection import get_db_connection
+
+MIGRATION_SQL = """
+-- Add expected delivery time (mandatory deadline promised to customer)
+ALTER TABLE orders
+ADD COLUMN IF NOT EXISTS expected_delivery_time TIMESTAMP;
+
+-- Add delivery performance status
+ALTER TABLE orders
+ADD COLUMN IF NOT EXISTS delivery_status VARCHAR(20)
+CHECK(delivery_status IN ('on_time', 'late', 'very_late', 'failed_on_time', 'failed_late'));
+
+-- Add SLA grace period (minutes after expected time that's still acceptable)
+ALTER TABLE orders
+ADD COLUMN IF NOT EXISTS sla_grace_period_minutes INTEGER DEFAULT 15;
+
+-- Add comments
+COMMENT ON COLUMN orders.expected_delivery_time IS 'Required delivery deadline promised to customer (mandatory when creating order)';
+COMMENT ON COLUMN orders.delivery_status IS 'Delivery performance: on_time, late (within grace), very_late (SLA violation), failed_on_time, failed_late';
+COMMENT ON COLUMN orders.sla_grace_period_minutes IS 'Grace period in minutes after expected_delivery_time (default: 15 mins)';
+
+-- Create index for querying by expected delivery time
+CREATE INDEX IF NOT EXISTS idx_orders_expected_delivery ON orders(expected_delivery_time);
+"""
+
+ROLLBACK_SQL = """
+-- Drop indexes
+DROP INDEX IF EXISTS idx_orders_expected_delivery;
+
+-- Drop columns
+ALTER TABLE orders
+DROP COLUMN IF EXISTS expected_delivery_time,
+DROP COLUMN IF EXISTS delivery_status,
+DROP COLUMN IF EXISTS sla_grace_period_minutes;
+"""
+
+
+def up():
+    """Apply migration - add delivery timing fields"""
+    print("Running migration 006: Add delivery timing and SLA tracking fields...")
+
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        # Execute migration SQL
+        cursor.execute(MIGRATION_SQL)
+
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        print("SUCCESS: Migration 006 applied successfully")
+        print("  - Added expected_delivery_time TIMESTAMP column")
+        print("  - Added delivery_status VARCHAR(20) column")
+        print("  - Added sla_grace_period_minutes INTEGER column (default: 15)")
+        print("  - Created index on expected_delivery_time")
+        print("  - Valid delivery statuses: on_time, late, very_late, failed_on_time, failed_late")
+        return True
+
+    except Exception as e:
+        print(f"ERROR: Migration 006 failed: {e}")
+        return False
+
+
+def down():
+    """Rollback migration - drop delivery timing fields"""
+    print("Rolling back migration 006: Drop delivery timing fields...")
+
+    try:
+        conn = get_db_connection()
+        cursor = conn.cursor()
+
+        # Execute rollback SQL
+        cursor.execute(ROLLBACK_SQL)
+
+        conn.commit()
+        cursor.close()
+        conn.close()
+
+        print("SUCCESS: Migration 006 rolled back successfully")
+        return True
+
+    except Exception as e:
+        print(f"ERROR: Migration 006 rollback failed: {e}")
+        return False
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "down":
+        down()
+    else:
+        up()

server.py

@@ -299,27 +299,38 @@ def create_order(
     delivery_address: str,
     delivery_lat: float,
     delivery_lng: float,
+    expected_delivery_time: str,
     customer_phone: str | None = None,
     customer_email: str | None = None,
     priority: Literal["standard", "express", "urgent"] = "standard",
     weight_kg: float = 5.0,
     special_instructions: str | None = None,
+    sla_grace_period_minutes: int = 15,
     time_window_end: str | None = None
 ) -> dict:
     """
-    Create a new delivery order in the database. Only call this after geocoding the address successfully.
+    Create a new delivery order in the database with MANDATORY delivery deadline.
+
+    IMPORTANT: expected_delivery_time is REQUIRED. This is the promised delivery time to the customer.
+    Only call this after geocoding the address successfully.
 
     Args:
         customer_name: Full name of the customer
         delivery_address: Complete delivery address
         delivery_lat: Latitude from geocoding
         delivery_lng: Longitude from geocoding
+        expected_delivery_time: REQUIRED - Promised delivery deadline in ISO 8601 format
+                               Must be future timestamp. Examples:
+                               - '2025-11-15T18:00:00' (6 PM today)
+                               - '2025-11-16T12:00:00' (noon tomorrow)
         customer_phone: Customer phone number (optional)
         customer_email: Customer email address (optional)
         priority: Delivery priority level (default: standard)
         weight_kg: Package weight in kilograms (default: 5.0)
         special_instructions: Special delivery instructions (optional)
-        time_window_end: Delivery deadline in ISO format (default: 6 hours from now)
+        sla_grace_period_minutes: Grace period after deadline (default: 15 mins)
+                                  Deliveries within grace period marked as 'late' but acceptable
+        time_window_end: Legacy field, defaults to expected_delivery_time if not provided
 
     Returns:
         dict: {
@@ -328,23 +339,26 @@ def create_order(
             status: str,
             customer: str,
             address: str,
-            deadline: str,
+            expected_delivery: str (new),
+            sla_grace_period_minutes: int (new),
             priority: str,
             message: str
         }
     """
     from chat.tools import handle_create_order
-    logger.info(f"Tool: create_order(customer='{customer_name}', address='{delivery_address}')")
+    logger.info(f"Tool: create_order(customer='{customer_name}', expected_delivery='{expected_delivery_time}')")
     return handle_create_order({
         "customer_name": customer_name,
         "delivery_address": delivery_address,
         "delivery_lat": delivery_lat,
         "delivery_lng": delivery_lng,
+        "expected_delivery_time": expected_delivery_time,
         "customer_phone": customer_phone,
         "customer_email": customer_email,
         "priority": priority,
         "weight_kg": weight_kg,
         "special_instructions": special_instructions,
+        "sla_grace_period_minutes": sla_grace_period_minutes,
         "time_window_end": time_window_end
     })
 

test_delivery_timing.py

@@ -0,0 +1,273 @@
+"""
+Test script for delivery timing and SLA tracking
+Verifies:
+- expected_delivery_time is mandatory when creating orders
+- On-time delivery detection
+- Late delivery detection
+- Very late delivery detection (SLA violation)
+- Failed delivery timing tracking
+"""
+
+import sys
+import os
+from datetime import datetime, timedelta
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from chat.tools import (
+    handle_create_order,
+    handle_create_driver,
+    handle_create_assignment,
+    handle_complete_delivery,
+    handle_fail_delivery,
+    handle_get_order_details
+)
+
+print("=" * 70)
+print("Testing Delivery Timing & SLA Tracking")
+print("=" * 70)
+
+# Test 1: Create order WITHOUT expected_delivery_time (should fail)
+print("\n[1] Testing: Create order WITHOUT expected_delivery_time (should fail)...")
+result = handle_create_order({
+    "customer_name": "Test Customer",
+    "delivery_address": "Test Address",
+    "delivery_lat": 23.7808,
+    "delivery_lng": 90.4130,
+    "priority": "standard"
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "expected_delivery_time" in result.get('error', '').lower():
+        print("SUCCESS: Correctly requires expected_delivery_time!")
+    else:
+        print("WARNING: Error message should mention expected_delivery_time")
+else:
+    print("FAILED: Should have required expected_delivery_time!")
+    sys.exit(1)
+
+# Test 2: Create order with PAST expected_delivery_time (should fail)
+print("\n[2] Testing: Create order with PAST delivery time (should fail)...")
+past_time = (datetime.now() - timedelta(hours=2)).isoformat()
+result = handle_create_order({
+    "customer_name": "Test Customer",
+    "delivery_address": "Test Address",
+    "delivery_lat": 23.7808,
+    "delivery_lng": 90.4130,
+    "expected_delivery_time": past_time,
+    "priority": "standard"
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "future" in result.get('error', '').lower():
+        print("SUCCESS: Correctly validates expected_delivery_time must be in future!")
+    else:
+        print("WARNING: Error should mention time must be in future")
+else:
+    print("FAILED: Should have rejected past delivery time!")
+    sys.exit(1)
+
+# Test 3: Create valid order with expected_delivery_time
+print("\n[3] Creating valid order with expected_delivery_time...")
+# Set deadline to 2 hours from now
+expected_time = datetime.now() + timedelta(hours=2)
+order_result = handle_create_order({
+    "customer_name": "Timing Test Customer",
+    "customer_phone": "+8801712345678",
+    "delivery_address": "Bashundhara, Dhaka",
+    "delivery_lat": 23.8223,
+    "delivery_lng": 90.4259,
+    "expected_delivery_time": expected_time.isoformat(),
+    "priority": "standard",
+    "weight_kg": 2.5,
+    "sla_grace_period_minutes": 15
+})
+
+if not order_result.get("success"):
+    print(f"FAILED: {order_result.get('error')}")
+    sys.exit(1)
+
+order_id = order_result["order_id"]
+print(f"SUCCESS: Order created: {order_id}")
+print(f"  Expected delivery: {order_result.get('expected_delivery')}")
+print(f"  SLA grace period: {order_result.get('sla_grace_period_minutes')} minutes")
+
+# Test 4: Create driver
+print("\n[4] Creating test driver...")
+import time
+time.sleep(0.1)  # Avoid ID collision
+driver_result = handle_create_driver({
+    "name": "Timing Test Driver",
+    "phone": "+8801812345678",
+    "vehicle_type": "motorcycle",
+    "current_lat": 23.7549,
+    "current_lng": 90.3909
+})
+
+if not driver_result.get("success"):
+    print(f"FAILED: {driver_result.get('error')}")
+    sys.exit(1)
+
+driver_id = driver_result["driver_id"]
+print(f"SUCCESS: Driver created: {driver_id}")
+
+# Test 5: Create assignment
+print("\n[5] Creating assignment...")
+assignment_result = handle_create_assignment({
+    "order_id": order_id,
+    "driver_id": driver_id
+})
+
+if not assignment_result.get("success"):
+    print(f"FAILED: {assignment_result.get('error')}")
+    sys.exit(1)
+
+assignment_id = assignment_result["assignment_id"]
+print(f"SUCCESS: Assignment created: {assignment_id}")
+
+# Test 6: Simulate ON-TIME delivery (complete before expected_delivery_time)
+print("\n[6] Testing ON-TIME delivery (before deadline)...")
+# Since we can't control system time, we check the logic exists
+completion_result = handle_complete_delivery({
+    "assignment_id": assignment_id,
+    "confirm": True,
+    "notes": "Delivered on time"
+})
+
+if not completion_result.get("success"):
+    print(f"FAILED: {completion_result.get('error')}")
+    sys.exit(1)
+
+print(f"SUCCESS: Delivery completed!")
+print(f"  Delivery status: {completion_result.get('delivery_status')}")
+print(f"  Timing info: {completion_result.get('timing', {})}")
+
+# Check timing fields
+timing = completion_result.get('timing', {})
+if 'expected_delivery_time' in timing and 'actual_delivery_time' in timing:
+    print("SUCCESS: Timing information tracked correctly!")
+    print(f"    Expected: {timing.get('expected_delivery_time')}")
+    print(f"    Actual: {timing.get('actual_delivery_time')}")
+    print(f"    Status: {timing.get('status')}")
+    if 'delay_minutes' in timing:
+        print(f"    Delay: {timing.get('delay_minutes')} minutes")
+else:
+    print("FAILED: Missing timing information!")
+
+# Test 7: Verify delivered_at was set (BUG FIX)
+print("\n[7] Verifying delivered_at field was set (BUG FIX test)...")
+order_details = handle_get_order_details({"order_id": order_id})
+if order_details.get("success"):
+    order = order_details.get("order", {})
+    timing_data = order.get("timing", {})
+    delivered_at = timing_data.get("delivered_at")
+    delivery_status = order.get("delivery_status")
+
+    if delivered_at:
+        print(f"SUCCESS: delivered_at field was set: {delivered_at}")
+    else:
+        print("FAILED: delivered_at field was NOT set (BUG NOT FIXED!)")
+
+    if delivery_status:
+        print(f"SUCCESS: delivery_status field was set: {delivery_status}")
+    else:
+        print("WARNING: delivery_status field was NOT set")
+else:
+    print(f"FAILED to get order details: {order_details.get('error')}")
+
+# Cleanup
+print("\n" + "=" * 70)
+print("Cleaning up test data...")
+from chat.tools import handle_delete_order, handle_delete_driver
+
+handle_delete_order({"order_id": order_id, "confirm": True})
+handle_delete_driver({"driver_id": driver_id, "confirm": True})
+print("Cleanup complete!")
+
+# Test 8: Test failed delivery timing
+print("\n" + "=" * 70)
+print("[8] Testing FAILED delivery with timing tracking...")
+
+# Create new order
+time.sleep(0.1)
+expected_time2 = datetime.now() + timedelta(hours=1)
+order_result2 = handle_create_order({
+    "customer_name": "Failed Timing Test",
+    "customer_phone": "+8801712345679",
+    "delivery_address": "Mirpur, Dhaka",
+    "delivery_lat": 23.8103,
+    "delivery_lng": 90.4125,
+    "expected_delivery_time": expected_time2.isoformat(),
+    "priority": "standard"
+})
+
+if not order_result2.get("success"):
+    print(f"FAILED: {order_result2.get('error')}")
+    sys.exit(1)
+
+order_id2 = order_result2["order_id"]
+print(f"Order created: {order_id2}")
+
+# Create driver
+time.sleep(0.1)
+driver_result2 = handle_create_driver({
+    "name": "Failed Test Driver",
+    "phone": "+8801812345679",
+    "vehicle_type": "car",
+    "current_lat": 23.7465,
+    "current_lng": 90.3760
+})
+
+driver_id2 = driver_result2["driver_id"]
+print(f"Driver created: {driver_id2}")
+
+# Create assignment
+assignment_result2 = handle_create_assignment({
+    "order_id": order_id2,
+    "driver_id": driver_id2
+})
+
+assignment_id2 = assignment_result2["assignment_id"]
+print(f"Assignment created: {assignment_id2}")
+
+# Fail delivery
+failure_result = handle_fail_delivery({
+    "assignment_id": assignment_id2,
+    "current_lat": 23.7600,
+    "current_lng": 90.3850,
+    "failure_reason": "customer_not_available",
+    "confirm": True,
+    "notes": "Customer phone was off"
+})
+
+if failure_result.get("success"):
+    print(f"SUCCESS: Failure recorded!")
+    print(f"  Delivery status: {failure_result.get('delivery_status')}")
+    print(f"  Timing info: {failure_result.get('timing', {})}")
+
+    timing = failure_result.get('timing', {})
+    if 'expected_delivery_time' in timing and 'failure_time' in timing:
+        print("SUCCESS: Failure timing information tracked!")
+        print(f"    Expected: {timing.get('expected_delivery_time')}")
+        print(f"    Failed at: {timing.get('failure_time')}")
+        print(f"    Status: {timing.get('status')}")
+else:
+    print(f"FAILED: {failure_result.get('error')}")
+
+# Cleanup
+print("\nCleaning up failed delivery test data...")
+handle_delete_order({"order_id": order_id2, "confirm": True})
+handle_delete_driver({"driver_id": driver_id2, "confirm": True})
+print("Cleanup complete!")
+
+print("\n" + "=" * 70)
+print("Delivery Timing & SLA Tracking Test Complete!")
+print("=" * 70)
+print("\nSummary:")
+print("  - expected_delivery_time is mandatory: YES")
+print("  - Past delivery times rejected: YES")
+print("  - delivered_at field gets set: YES (BUG FIXED)")
+print("  - delivery_status tracked: YES")
+print("  - Timing information returned: YES")
+print("  - Failed delivery timing tracked: YES")

test_driver_validation.py

@@ -0,0 +1,187 @@
+"""
+Test script for driver creation validation
+Verifies that drivers cannot be created without required fields:
+- name
+- vehicle_type
+- current_lat
+- current_lng
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from chat.tools import handle_create_driver
+
+print("=" * 70)
+print("Testing Driver Creation Validation")
+print("=" * 70)
+
+# Test 1: Create driver WITHOUT name (should fail)
+print("\n[1] Testing: Create driver WITHOUT name (should fail)...")
+result = handle_create_driver({
+    "vehicle_type": "motorcycle",
+    "current_lat": 23.8103,
+    "current_lng": 90.4125
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "name" in result.get('error', '').lower():
+        print("SUCCESS: Correctly requires name!")
+    else:
+        print("WARNING: Error message should mention 'name'")
+else:
+    print(f"FAILED: Should have required name! Created: {result.get('driver_id')}")
+    sys.exit(1)
+
+# Test 2: Create driver WITHOUT vehicle_type (should fail)
+print("\n[2] Testing: Create driver WITHOUT vehicle_type (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "current_lat": 23.8103,
+    "current_lng": 90.4125
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "vehicle_type" in result.get('error', '').lower():
+        print("SUCCESS: Correctly requires vehicle_type!")
+    else:
+        print("WARNING: Error message should mention 'vehicle_type'")
+else:
+    print(f"FAILED: Should have required vehicle_type! Created: {result.get('driver_id')}")
+    sys.exit(1)
+
+# Test 3: Create driver WITHOUT current_lat (should fail)
+print("\n[3] Testing: Create driver WITHOUT current_lat (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "vehicle_type": "motorcycle",
+    "current_lng": 90.4125
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "current_lat" in result.get('error', '').lower():
+        print("SUCCESS: Correctly requires current_lat!")
+    else:
+        print("WARNING: Error message should mention 'current_lat'")
+else:
+    print(f"FAILED: Should have required current_lat! Created: {result.get('driver_id')}")
+    sys.exit(1)
+
+# Test 4: Create driver WITHOUT current_lng (should fail)
+print("\n[4] Testing: Create driver WITHOUT current_lng (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "vehicle_type": "motorcycle",
+    "current_lat": 23.8103
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "current_lng" in result.get('error', '').lower():
+        print("SUCCESS: Correctly requires current_lng!")
+    else:
+        print("WARNING: Error message should mention 'current_lng'")
+else:
+    print(f"FAILED: Should have required current_lng! Created: {result.get('driver_id')}")
+    sys.exit(1)
+
+# Test 5: Create driver with INVALID latitude (should fail)
+print("\n[5] Testing: Create driver with invalid latitude (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "vehicle_type": "motorcycle",
+    "current_lat": 95.0,  # Invalid - must be -90 to 90
+    "current_lng": 90.4125
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "latitude" in result.get('error', '').lower() or "-90" in result.get('error', ''):
+        print("SUCCESS: Correctly validates latitude range!")
+    else:
+        print("WARNING: Error message should mention latitude validation")
+else:
+    print(f"FAILED: Should have rejected invalid latitude!")
+    sys.exit(1)
+
+# Test 6: Create driver with INVALID longitude (should fail)
+print("\n[6] Testing: Create driver with invalid longitude (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "vehicle_type": "motorcycle",
+    "current_lat": 23.8103,
+    "current_lng": 200.0  # Invalid - must be -180 to 180
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "longitude" in result.get('error', '').lower() or "-180" in result.get('error', ''):
+        print("SUCCESS: Correctly validates longitude range!")
+    else:
+        print("WARNING: Error message should mention longitude validation")
+else:
+    print(f"FAILED: Should have rejected invalid longitude!")
+    sys.exit(1)
+
+# Test 7: Create driver with NON-NUMERIC coordinates (should fail)
+print("\n[7] Testing: Create driver with non-numeric coordinates (should fail)...")
+result = handle_create_driver({
+    "name": "Test Driver",
+    "vehicle_type": "motorcycle",
+    "current_lat": "not a number",
+    "current_lng": 90.4125
+})
+
+if not result.get("success"):
+    print(f"EXPECTED FAILURE: {result.get('error')}")
+    if "number" in result.get('error', '').lower() or "valid" in result.get('error', '').lower():
+        print("SUCCESS: Correctly validates coordinates are numbers!")
+    else:
+        print("WARNING: Error message should mention coordinates must be numbers")
+else:
+    print(f"FAILED: Should have rejected non-numeric coordinates!")
+    sys.exit(1)
+
+# Test 8: Create driver WITH all required fields (should succeed)
+print("\n[8] Testing: Create driver with ALL required fields (should succeed)...")
+result = handle_create_driver({
+    "name": "Valid Test Driver",
+    "phone": "+8801812345678",
+    "vehicle_type": "motorcycle",
+    "current_lat": 23.8103,
+    "current_lng": 90.4125
+})
+
+if result.get("success"):
+    driver_id = result.get("driver_id")
+    print(f"SUCCESS: Driver created: {driver_id}")
+    print(f"  Name: {result.get('name')}")
+    print(f"  Vehicle: {result.get('vehicle_type')}")
+    print(f"  Location: ({result.get('location', {}).get('latitude')}, {result.get('location', {}).get('longitude')})")
+
+    # Cleanup
+    print("\nCleaning up test driver...")
+    from chat.tools import handle_delete_driver
+    handle_delete_driver({"driver_id": driver_id, "confirm": True})
+    print("Cleanup complete!")
+else:
+    print(f"FAILED: Should have created driver with all required fields!")
+    print(f"Error: {result.get('error')}")
+    sys.exit(1)
+
+print("\n" + "=" * 70)
+print("Driver Creation Validation Test Complete!")
+print("=" * 70)
+print("\nSummary:")
+print("  - name is mandatory: YES")
+print("  - vehicle_type is mandatory: YES")
+print("  - current_lat is mandatory: YES")
+print("  - current_lng is mandatory: YES")
+print("  - Latitude range validated (-90 to 90): YES")
+print("  - Longitude range validated (-180 to 180): YES")
+print("  - Coordinates must be numeric: YES")
+print("  - Valid driver can be created: YES")