feat: implement GET /trips endpoint with optimizations

- Add GET /trips endpoint to fetch user trips from last 7 days
- Format duration as human-readable string (e.g., '8h 30m', '45m')
- Optimize query with composite index on (user_id, merchant_id, created_at)
- Remove redundant indexes to improve write performance
- Extract helper functions for duration calculation and formatting
- Fix attendance location_id type from string to UUID
- Add MS_PER_MINUTE constant for better code clarity
- Use integer division for duration calculations

app/tracker/attendance/schemas.py

@@ -2,6 +2,7 @@
 Pydantic schemas for attendance module.
 """
 from typing import Optional
+from uuid import UUID
 from pydantic import BaseModel, Field, field_validator
 from datetime import datetime
 
@@ -10,7 +11,7 @@ class CheckInRequest(BaseModel):
     """Request schema for check-in"""
     latitude: float = Field(..., description="GPS latitude", ge=-90, le=90)
     longitude: float = Field(..., description="GPS longitude", ge=-180, le=180)
-    location_id: Optional[str] = Field(None, description="Geofence location ID if inside a geofence")
+    location_id: Optional[UUID] = Field(None, description="Geofence location UUID if inside a geofence")
     
     @field_validator('latitude')
     @classmethod
@@ -33,7 +34,7 @@ class CheckInRequest(BaseModel):
             "example": {
                 "latitude": 19.0760,
                 "longitude": 72.8777,
-                "location_id": "loc_mumbai_office_001"
+                "location_id": "550e8400-e29b-41d4-a716-446655440000"
             }
         }
     }

app/tracker/trips/router.py

@@ -10,6 +10,8 @@ from app.tracker.trips.schemas import (
     StartTripResponse,
     StopTripRequest,
     StopTripResponse,
+    GetTripsResponse,
+    TripItem,
     ErrorResponse
 )
 
@@ -422,3 +424,162 @@ async def stop_trip(
                 "error_code": "INTERNAL_ERROR"
             }
         )
+
+
+@router.get(
+    "",
+    response_model=GetTripsResponse,
+    status_code=status.HTTP_200_OK,
+    responses={
+        200: {
+            "description": "Trips retrieved successfully",
+            "model": GetTripsResponse
+        },
+        401: {
+            "description": "Unauthorized - invalid or missing JWT token",
+            "model": ErrorResponse
+        },
+        500: {
+            "description": "Internal server error",
+            "model": ErrorResponse
+        }
+    },
+    summary="Get User Trips",
+    description="""
+    Retrieve list of trips for the authenticated user from the last 7 days.
+    
+    **Use Cases:**
+    - View trip history
+    - Track business travel
+    - Generate trip reports
+    - Monitor active trips
+    - Analyze travel patterns
+    
+    **Business Rules:**
+    - ✅ Returns trips from last 7 days only
+    - ✅ Ordered by creation date (newest first)
+    - ✅ Includes both active and completed trips
+    - ✅ User can only see their own trips
+    - ✅ Trips are merchant-scoped (multi-tenant isolation)
+    
+    **Response Fields:**
+    - tripId: Unique trip identifier (UUID)
+    - tripDate: Trip creation date (YYYY-MM-DD)
+    - status: Trip status (active/completed)
+    - distanceKm: Distance traveled in kilometers
+    - duration: Human-readable duration (e.g., "8h 30m" or "45m")
+    - startedAt: Start timestamp in milliseconds
+    - stoppedAt: Stop timestamp in milliseconds (null for active trips)
+    
+    **Duration Format:**
+    - >= 1 hour: "Xh Ym" (e.g., "8h 30m", "2h 15m")
+    - Exact hours: "Xh" (e.g., "3h")
+    - < 1 hour: "Xm" (e.g., "45m", "5m")
+    
+    **Duration Calculation:**
+    - Completed trips: stoppedAt - startedAt
+    - Active trips: currentTime - startedAt
+    
+    **Distance Calculation:**
+    - Converted from meters to kilometers
+    - Rounded to 2 decimal places
+    - 0.0 for trips without distance data
+    
+    **Performance:**
+    - Indexed by user_id and created_at
+    - Limited to 7 days for optimal performance
+    - Efficient query with proper filtering
+    
+    **Error Handling:**
+    - 401 Unauthorized: If JWT invalid
+    - 500 Internal Error: If database operation fails
+    """
+)
+async def get_trips(
+    current_user: TokenUser = Depends(get_current_user),
+    service: TripService = Depends(get_trip_service)
+) -> GetTripsResponse:
+    """
+    Get list of trips for the authenticated user from the last 7 days.
+    
+    Args:
+        current_user: Authenticated user from JWT token
+        service: Trip service instance
+        
+    Returns:
+        GetTripsResponse with list of trips
+        
+    Raises:
+        HTTPException 401: If authentication fails
+        HTTPException 500: If internal error occurs
+    """
+    try:
+        logger.info(
+            "Fetching trips",
+            extra={
+                "user_id": current_user.user_id,
+                "merchant_id": current_user.merchant_id
+            }
+        )
+        
+        # Get trips from service
+        # Security: user_id and merchant_id come from validated JWT token
+        trips_data = await service.get_trips(
+            user_id=str(current_user.user_id),
+            merchant_id=str(current_user.merchant_id),
+            days=7
+        )
+        
+        # Convert to response format
+        trips = [
+            TripItem(
+                tripId=trip["trip_id"],
+                tripDate=trip["trip_date"],
+                status=trip["status"],
+                distanceKm=trip["distance_km"],
+                duration=trip["duration"],
+                startedAt=trip["started_at"],
+                stoppedAt=trip["stopped_at"]
+            )
+            for trip in trips_data
+        ]
+        
+        logger.info(
+            f"Retrieved {len(trips)} trips successfully",
+            extra={
+                "user_id": current_user.user_id,
+                "merchant_id": current_user.merchant_id,
+                "trip_count": len(trips)
+            }
+        )
+        
+        return GetTripsResponse(
+            success=True,
+            trips=trips,
+            count=len(trips)
+        )
+        
+    except HTTPException:
+        # Re-raise HTTP exceptions (already formatted)
+        raise
+        
+    except Exception as e:
+        # Unexpected errors
+        logger.error(
+            f"Failed to fetch trips: {str(e)}",
+            extra={
+                "user_id": current_user.user_id,
+                "merchant_id": current_user.merchant_id,
+                "error": str(e)
+            },
+            exc_info=True
+        )
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail={
+                "success": False,
+                "error": "Internal Server Error",
+                "detail": "Failed to fetch trips. Please try again later.",
+                "error_code": "INTERNAL_ERROR"
+            }
+        )

app/tracker/trips/schemas.py

@@ -198,3 +198,62 @@ class StopTripResponse(BaseModel):
                 "durationMinutes": 45
             }
         }
+
+
+class TripItem(BaseModel):
+    """Individual trip item in list"""
+    tripId: str = Field(..., description="UUID of the trip")
+    tripDate: str = Field(..., description="Trip date in YYYY-MM-DD format")
+    status: str = Field(..., description="Trip status (active/completed)")
+    distanceKm: float = Field(..., description="Distance traveled in kilometers")
+    duration: str = Field(..., description="Trip duration as human-readable string (e.g., '8h 30m' or '45m')")
+    startedAt: int = Field(..., description="Trip start timestamp in milliseconds")
+    stoppedAt: Optional[int] = Field(None, description="Trip stop timestamp in milliseconds (null if active)")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "tripId": "550e8400-e29b-41d4-a716-446655440000",
+                "tripDate": "2026-03-13",
+                "status": "completed",
+                "distanceKm": 15.5,
+                "duration": "8h 30m",
+                "startedAt": 1678901234567,
+                "stoppedAt": 1678905234567
+            }
+        }
+
+
+class GetTripsResponse(BaseModel):
+    """Response for get trips list"""
+    success: bool = Field(True, description="Whether the request was successful")
+    trips: list[TripItem] = Field(..., description="List of trips")
+    count: int = Field(..., description="Total number of trips returned")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "success": True,
+                "count": 2,
+                "trips": [
+                    {
+                        "tripId": "550e8400-e29b-41d4-a716-446655440000",
+                        "tripDate": "2026-03-13",
+                        "status": "completed",
+                        "distanceKm": 15.5,
+                        "duration": "8h 30m",
+                        "startedAt": 1678901234567,
+                        "stoppedAt": 1678905234567
+                    },
+                    {
+                        "tripId": "550e8400-e29b-41d4-a716-446655440001",
+                        "tripDate": "2026-03-12",
+                        "status": "active",
+                        "distanceKm": 0.0,
+                        "duration": "45m",
+                        "startedAt": 1678801234567,
+                        "stoppedAt": None
+                    }
+                ]
+            }
+        }

app/tracker/trips/service.py

@@ -2,6 +2,7 @@
 Service layer for trip operations.
 Handles business logic and database interactions for trips.
 """
+import time
 from typing import Optional
 from uuid import UUID, uuid4
 from app.postgres import get_postgres_connection, release_postgres_connection
@@ -9,6 +10,57 @@ from app.core.logging import get_logger
 
 logger = get_logger(__name__)
 
+# Constants
+MS_PER_MINUTE = 60000  # Milliseconds in one minute
+
+
+def _format_duration(duration_minutes: int) -> str:
+    """
+    Format duration in minutes to human-readable string.
+    
+    Args:
+        duration_minutes: Duration in minutes
+        
+    Returns:
+        Formatted string (e.g., "8h 30m", "3h", "45m")
+    """
+    if duration_minutes >= 60:
+        hours = duration_minutes // 60
+        minutes = duration_minutes % 60
+        if minutes > 0:
+            return f"{hours}h {minutes}m"
+        else:
+            return f"{hours}h"
+    else:
+        return f"{duration_minutes}m"
+
+
+def _calculate_duration_minutes(
+    status: str,
+    started_at: Optional[int],
+    stopped_at: Optional[int],
+    current_time_ms: int
+) -> int:
+    """
+    Calculate trip duration in minutes.
+    
+    Args:
+        status: Trip status (active/completed)
+        started_at: Start timestamp in milliseconds
+        stopped_at: Stop timestamp in milliseconds (None for active trips)
+        current_time_ms: Current time in milliseconds
+        
+    Returns:
+        Duration in minutes
+    """
+    if status == 'completed' and stopped_at and started_at:
+        duration_ms = stopped_at - started_at
+        return duration_ms // MS_PER_MINUTE
+    elif status == 'active' and started_at:
+        duration_ms = current_time_ms - started_at
+        return duration_ms // MS_PER_MINUTE
+    return 0
+
 
 class TripService:
     """Service for handling trip operations"""
@@ -313,7 +365,7 @@ class TripService:
             
             # Calculate duration in minutes
             duration_ms = stopped_at - trip['started_at']
-            duration_minutes = int(duration_ms / 60000)
+            duration_minutes = duration_ms // MS_PER_MINUTE
             
             # Update trip
             update_query = """
@@ -375,6 +427,107 @@ class TripService:
         finally:
             if conn:
                 await release_postgres_connection(conn)
+    
+    async def get_trips(
+        self,
+        user_id: str,
+        merchant_id: str,
+        days: int = 7
+    ) -> list[dict]:
+        """
+        Get list of trips for a user in the last N days.
+        
+        Args:
+            user_id: User UUID
+            merchant_id: Merchant UUID (for security validation)
+            days: Number of days to look back (default: 7)
+            
+        Returns:
+            List of trip dictionaries with:
+            - trip_id: Trip UUID
+            - trip_date: Created date (YYYY-MM-DD)
+            - status: Trip status (active/completed)
+            - distance_km: Distance in kilometers
+            - duration_minutes: Total trip time in minutes
+            - started_at: Start timestamp
+            - stopped_at: Stop timestamp (null if active)
+            
+        Raises:
+            Exception: If database operation fails
+        """
+        conn = None
+        try:
+            conn = await get_postgres_connection()
+            
+            query = """
+                SELECT 
+                    id,
+                    started_at,
+                    stopped_at,
+                    distance_meters,
+                    status,
+                    created_at
+                FROM trans.scm_trips
+                WHERE user_id = $1
+                AND merchant_id = $2
+                AND created_at >= NOW() - INTERVAL '1 day' * $3
+                ORDER BY created_at DESC
+            """
+            
+            rows = await conn.fetch(query, user_id, merchant_id, days)
+            
+            # Calculate current time once for all active trips
+            current_time_ms = int(time.time() * 1000)
+            
+            trips = []
+            for row in rows:
+                # Calculate distance in km
+                distance_km = round(row['distance_meters'] / 1000.0, 2) if row['distance_meters'] else 0.0
+                
+                # Calculate duration
+                duration_minutes = _calculate_duration_minutes(
+                    status=row['status'],
+                    started_at=row['started_at'],
+                    stopped_at=row['stopped_at'],
+                    current_time_ms=current_time_ms
+                )
+                
+                trips.append({
+                    "trip_id": str(row['id']),
+                    "trip_date": row['created_at'].strftime("%Y-%m-%d"),
+                    "status": row['status'],
+                    "distance_km": distance_km,
+                    "duration": _format_duration(duration_minutes),
+                    "started_at": row['started_at'],
+                    "stopped_at": row['stopped_at']
+                })
+            
+            logger.info(
+                f"Retrieved {len(trips)} trips",
+                extra={
+                    "user_id": user_id,
+                    "merchant_id": merchant_id,
+                    "days": days,
+                    "trip_count": len(trips)
+                }
+            )
+            
+            return trips
+            
+        except Exception as e:
+            logger.error(
+                f"Failed to fetch trips: {str(e)}",
+                extra={
+                    "user_id": user_id,
+                    "merchant_id": merchant_id,
+                    "error": str(e)
+                },
+                exc_info=True
+            )
+            raise
+        finally:
+            if conn:
+                await release_postgres_connection(conn)
 
 
 def get_trip_service() -> TripService:

migrate_all_tables.py

@@ -269,14 +269,23 @@ async def create_trips_table(conn):
         )
     """)
     
+    # Drop old redundant indexes if they exist
     await conn.execute("""
-        CREATE INDEX IF NOT EXISTS idx_scm_trips_user_status
-        ON trans.scm_trips (user_id, status)
+        DROP INDEX IF EXISTS trans.idx_scm_trips_user_status
     """)
     
     await conn.execute("""
-        CREATE INDEX IF NOT EXISTS idx_scm_trips_merchant_date
-        ON trans.scm_trips (merchant_id, created_at DESC)
+        DROP INDEX IF EXISTS trans.idx_scm_trips_merchant_date
+    """)
+    
+    await conn.execute("""
+        DROP INDEX IF EXISTS trans.idx_scm_trips_status
+    """)
+    
+    # Create optimized composite index that covers all query patterns
+    await conn.execute("""
+        CREATE INDEX IF NOT EXISTS idx_scm_trips_user_merchant_created
+        ON trans.scm_trips (user_id, merchant_id, created_at DESC)
     """)
     
     await conn.execute("""