feat: location trail for visualization

docs/api/projects/field-agent-dashboard.md

@@ -0,0 +1,143 @@
+# Field Agent Project Dashboard
+
+## Endpoint
+
+```http
+GET /api/v1/projects/{project_id}/dashboard
+```
+
+## Response Structure
+
+```json
+{
+  "project_info": {
+    "id": "uuid",
+    "title": "Atomio Fttx",
+    "project_type": "customer_service",
+    "status": "active"
+  },
+  "my_stats": {
+    "tickets": {
+      "total_assigned": 3,
+      "pending": 0,
+      "in_progress": 2,
+      "completed_this_week": 1
+    },
+    "expenses": {
+      "total_amount": 5000.0,
+      "pending_amount": 5000.0,
+      "pending_count": 1
+    },
+    "inventory": {
+      "items_on_hand": 0
+    },
+    "notifications": {
+      "unread": 0,
+      "total": 0
+    }
+  },
+  "work_queue": {
+    "pending_assignments": [...],
+    "total_pending": 2,
+    "high_priority": 0,
+    "due_today": 1
+  },
+  "assignment_history": {
+    "assignments": [
+      {
+        "assignment_id": "uuid",
+        "ticket_id": "uuid",
+        "ticket_name": "John Kamau",
+        "ticket_type": "installation",
+        "service_type": "ftth",
+        "action": "completed",
+        "assigned_at": "2025-11-28T09:00:00Z",
+        "ended_at": "2025-11-28T12:30:00Z",
+        "travel_time_minutes": 15,
+        "work_time_minutes": 45,
+        "total_time_minutes": 60,
+        "journey_distance_km": 2.3,
+        "has_location_trail": true,
+        "reason": null
+      }
+    ],
+    "total": 5,
+    "completed": 4,
+    "dropped": 1,
+    "rejected": 0,
+    "period_days": 7
+  },
+  "cached_at": "2025-12-01T07:00:00Z",
+  "cache_expires_in_seconds": 300
+}
+```
+
+## Assignment History
+
+### What It Shows
+
+- **Last 7 days** of completed work (configurable)
+- Assignments with `ended_at` set (completed, dropped, rejected)
+- Sorted by most recent first
+
+### Assignment Actions
+
+- `completed` - Successfully finished
+- `dropped` - Agent couldn't complete (reason provided)
+- `rejected` - Agent rejected assignment
+
+### Performance Metrics
+
+Each assignment includes:
+- `travel_time_minutes` - Time from acceptance to arrival
+- `work_time_minutes` - Time from arrival to completion
+- `total_time_minutes` - Total assignment duration
+- `journey_distance_km` - Distance traveled (if GPS tracking used)
+- `has_location_trail` - Boolean flag for "View Journey" button
+
+### Frontend Usage
+
+```typescript
+// Display history section
+const history = dashboard.assignment_history;
+
+// Show summary
+showSummary({
+  total: history.total,
+  completed: history.completed,
+  dropped: history.dropped,
+  period: `Last ${history.period_days} days`
+});
+
+// Render list
+history.assignments.forEach(assignment => {
+  renderHistoryCard({
+    ticketName: assignment.ticket_name,
+    action: assignment.action,
+    endedAt: assignment.ended_at,
+    duration: `${assignment.total_time_minutes} min`,
+    distance: assignment.journey_distance_km ? `${assignment.journey_distance_km} km` : null,
+    showJourneyButton: assignment.has_location_trail
+  });
+});
+
+// "View Journey" button
+if (assignment.has_location_trail) {
+  onClickViewJourney(() => {
+    navigateToMap(assignment.assignment_id);
+  });
+}
+```
+
+## Cache
+
+- **TTL**: 5 minutes
+- **Invalidation**: Automatic on data changes
+- **Force refresh**: Add `?force_refresh=true` query param
+
+## Notes
+
+- History period is 7 days by default
+- Only shows agent's own assignments
+- Includes performance metrics for completed work
+- Location trail available if GPS tracking was used

docs/api/ticket-assignments/location-trail.md

@@ -0,0 +1,118 @@
+# Location Trail - Frontend Guide
+
+## What We Built
+
+Agents can now view their journey trail on a map after completing a ticket. The trail shows GPS breadcrumbs collected during travel.
+
+## How It Works
+
+### 1. Ticket Detail Response
+
+Assignment now includes `has_location_trail` flag:
+
+```json
+{
+  "current_assignment": {
+    "id": "assignment-uuid",
+    "has_location_trail": true,
+    "journey_distance_km": 2.3,
+    "travel_time_minutes": 15
+  }
+}
+```
+
+### 2. Show "View Journey" Button
+
+```typescript
+if (assignment.has_location_trail) {
+  // Show "View Journey" button
+  // On click → navigate to map page
+}
+```
+
+### 3. Fetch Location Trail
+
+```http
+GET /api/v1/ticket-assignments/assignments/{assignment_id}/location-trail
+```
+
+**Response:**
+```json
+{
+  "assignment_id": "uuid",
+  "ticket_id": "uuid",
+  "user_id": "uuid",
+  "user_name": "John Doe",
+  "journey_started_at": "2024-03-20T09:00:00Z",
+  "arrived_at": "2024-03-20T09:15:00Z",
+  "journey_start": {
+    "lat": -1.2921,
+    "lng": 36.8219
+  },
+  "arrival_point": {
+    "lat": -1.2930,
+    "lng": 36.8225
+  },
+  "trail": [
+    {
+      "lat": -1.2921,
+      "lng": 36.8219,
+      "timestamp": "2024-03-20T09:00:00Z",
+      "accuracy": 10,
+      "speed": 0
+    },
+    {
+      "lat": -1.2925,
+      "lng": 36.8222,
+      "timestamp": "2024-03-20T09:05:00Z",
+      "accuracy": 8,
+      "speed": 45
+    }
+  ],
+  "total_points": 45,
+  "journey_distance_km": 2.3,
+  "travel_time_minutes": 15
+}
+```
+
+## Map Rendering
+
+```typescript
+// Fetch trail
+const trail = await api.get(`/ticket-assignments/assignments/${assignmentId}/location-trail`);
+
+// Render on map
+const map = initMap();
+
+// Add start marker (green)
+if (trail.journey_start) {
+  addMarker(map, trail.journey_start, 'green', 'Start');
+}
+
+// Add arrival marker (red)
+if (trail.arrival_point) {
+  addMarker(map, trail.arrival_point, 'red', 'Arrival');
+}
+
+// Draw route line
+const coordinates = trail.trail.map(point => [point.lat, point.lng]);
+drawPolyline(map, coordinates, 'blue');
+
+// Show stats
+showStats({
+  distance: `${trail.journey_distance_km} km`,
+  time: `${trail.travel_time_minutes} min`,
+  points: trail.total_points
+});
+```
+
+## Authorization
+
+- Agents can view their own trails
+- PM/Dispatcher/Admin can view any trail
+
+## Notes
+
+- Trail only exists if agent used GPS tracking during journey
+- Empty trail = agent didn't update location during travel
+- Trail data is lazy-loaded (not in ticket detail response)

docs/devlogs/browser/response.json

@@ -1,183 +1,67 @@
 {
-    "ticket": {
-        "id": "0fd3ee15-5e7d-465a-b377-155f9bdb7e70",
-        "project_id": "0ade6bd1-e492-4e25-b681-59f42058d29a",
-        "source": "sales_order",
-        "source_id": "f40b7d15-01f3-4dbc-9fd5-3f9114db5439",
-        "ticket_name": "John Kamau",
-        "ticket_type": "installation",
-        "service_type": "ftth",
-        "work_description": "Install Premium Fiber 50Mbps for John Kamau",
-        "status": "completed",
-        "priority": "normal",
-        "scheduled_date": "2025-12-01",
-        "scheduled_time_slot": "Morning 9AM-12PM",
-        "due_date": "2025-12-01T07:52:17.445636Z",
-        "sla_target_date": "2025-12-01T07:52:17.445636Z",
-        "sla_violated": false,
-        "started_at": "2025-12-01T05:52:03.358706Z",
-        "completed_at": "2025-12-01T05:54:37.178415Z",
-        "is_invoiced": false,
-        "invoiced_at": null,
-        "project_region_id": "4cd27765-5720-4cc0-872e-bf0da3cd1898",
-        "work_location_latitude": "-1.2200285",
-        "work_location_longitude": "36.8770248",
-        "work_location_verified": true,
-        "notes": "[COMPLETION] Hhhdg",
-        "version": 1,
-        "created_at": "2025-11-28T07:52:17.445636Z",
-        "updated_at": "2025-12-01T05:54:37.233167Z",
-        "project_title": null,
-        "region_name": null,
-        "customer_name": null,
-        "is_open": false,
-        "is_assigned": false,
-        "is_in_progress": false,
-        "is_completed": true,
-        "is_cancelled": false,
-        "is_active": false,
-        "is_overdue": false,
-        "has_region": true,
-        "has_schedule": true,
-        "can_be_assigned": false,
-        "can_be_started": false,
-        "can_be_completed": false,
-        "can_be_cancelled": false
+    "project_info": {
+        "id": "0ade6bd1-e492-4e25-b681-59f42058d29a",
+        "title": "Atomio Fttx",
+        "project_type": "customer_service",
+        "status": "active"
     },
-    "available_actions": [],
-    "current_assignment": {
-        "id": "d6f25868-5117-4b85-8bb3-44314144ef6e",
-        "action": "completed",
-        "status": "CLOSED",
-        "journey_started": true,
-        "arrived": true,
-        "ended": true,
-        "can_drop": false
-    },
-    "team_info": {
-        "required_size": 1,
-        "assigned_size": 0,
-        "is_full": false,
-        "assigned_agents": []
-    },
-    "message": "Ticket TicketStatus.COMPLETED",
-    "source_data": {
-        "type": "sales_order",
-        "id": "f40b7d15-01f3-4dbc-9fd5-3f9114db5439",
-        "order_number": "ORD-2025-001",
-        "customer_preferred_package": "Premium Fiber 50Mbps",
-        "package_price": 5000.0,
-        "installation_address": "123 Kilimani Road, Apt 4B",
-        "installation_latitude": -1.286389,
-        "installation_longitude": 36.817223,
-        "preferred_visit_date": "2025-12-01",
-        "status": "processed"
-    },
-    "customer": {
-        "id": "5daadd72-7e1c-454b-8a7a-50e50a28e7ba",
-        "name": "John Kamau",
-        "phone": "+254712345678",
-        "email": "john.kamau@email.com",
-        "address": null,
-        "location_latitude": null,
-        "location_longitude": null
-    },
-    "expenses": [],
-    "images": [
-        {
-            "id": "286bc35f-0154-46a7-b9c5-411bc7e4cf3e",
-            "image_url": "https://res.cloudinary.com/dnhajmziu/image/upload/v1764568434/ticket_0fd3ee15_ticket_photo_airtel_network_airtel_network_20251201_055353_176456838428265210116379744783.jpg",
-            "image_type": "completion",
-            "description": "[Airtel network] Completion photo for ticket",
-            "captured_at": "2025-12-01T05:53:54.723185+00:00",
-            "uploaded_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "created_at": "2025-12-01T05:53:54.723853+00:00"
+    "my_stats": {
+        "tickets": {
+            "total_assigned": 3,
+            "pending": 0,
+            "in_progress": 2,
+            "completed_this_week": 1
         },
-        {
-            "id": "e66c9611-010b-44c0-8210-a96d6bc3a40a",
-            "image_url": "https://res.cloudinary.com/dnhajmziu/image/upload/v1764568433/ticket_0fd3ee15_ticket_photo_speedtest_speedtest_20251201_055353_176456840453490667282686508717.jpg",
-            "image_type": "completion",
-            "description": "[Speedtest] Completion photo for ticket",
-            "captured_at": "2025-12-01T05:53:53.881645+00:00",
-            "uploaded_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "created_at": "2025-12-01T05:53:53.882301+00:00"
+        "expenses": {
+            "total_amount": 5000.0,
+            "pending_amount": 5000.0,
+            "pending_count": 1
         },
-        {
-            "id": "2caeb3e0-ba66-4a71-aaa0-19f8fb5a6fc7",
-            "image_url": "https://res.cloudinary.com/dnhajmziu/image/upload/v1764568432/ticket_0fd3ee15_ticket_photo_odu_outdoor_image_odu_outdoor_image_20251201_055352_176456841641438038017979239093.jpg",
-            "image_type": "completion",
-            "description": "[ODU outdoor image] Completion photo for ticket",
-            "captured_at": "2025-12-01T05:53:53.064280+00:00",
-            "uploaded_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "created_at": "2025-12-01T05:53:53.096941+00:00"
-        }
-    ],
-    "comments": [],
-    "assignments": [
-        {
-            "id": "d6f25868-5117-4b85-8bb3-44314144ef6e",
-            "user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "user_name": "Viyisa Sasa",
-            "action": "completed",
-            "status": "CLOSED",
-            "assigned_at": "2025-12-01T05:50:51.219042+00:00",
-            "responded_at": "2025-12-01T05:50:51.219044+00:00",
-            "journey_started_at": "2025-12-01T05:52:03.358665+00:00",
-            "arrived_at": "2025-12-01T05:52:35.847093+00:00",
-            "ended_at": "2025-12-01T05:54:37.183538+00:00"
-        }
-    ],
-    "status_history": [
-        {
-            "id": "e8de766c-14f9-4425-8c67-a77fa671b16f",
-            "old_status": "in_progress",
-            "new_status": "completed",
-            "changed_at": "2025-12-01T05:54:37.189824+00:00",
-            "changed_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "changed_by_user_name": "Viyisa Sasa",
-            "assignment_id": "d6f25868-5117-4b85-8bb3-44314144ef6e",
-            "change_reason": "Ticket completed with all requirements satisfied",
-            "notes": "Hhhdg",
-            "location_latitude": null,
-            "location_longitude": null,
-            "location_accuracy": null,
-            "location_verified": false,
-            "communication_method": "app",
-            "additional_metadata": {}
-        },
-        {
-            "id": "48ef8f9d-731d-4e74-b2ed-136f3bd1d026",
-            "old_status": "assigned",
-            "new_status": "in_progress",
-            "changed_at": "2025-12-01T05:52:03.358718+00:00",
-            "changed_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "changed_by_user_name": "Viyisa Sasa",
-            "assignment_id": "d6f25868-5117-4b85-8bb3-44314144ef6e",
-            "change_reason": "Agent started journey to site",
-            "notes": null,
-            "location_latitude": -1.2200188,
-            "location_longitude": 36.8770193,
-            "location_accuracy": null,
-            "location_verified": false,
-            "communication_method": "app",
-            "additional_metadata": {}
+        "inventory": {
+            "items_on_hand": 0
         },
-        {
-            "id": "096f3c95-b8fb-4fa8-9602-9f5f0da467d8",
-            "old_status": "open",
-            "new_status": "assigned",
-            "changed_at": "2025-12-01T05:50:51.241567+00:00",
-            "changed_by_user_id": "43b778b0-2062-4724-abbb-916a4835a9b0",
-            "changed_by_user_name": "Viyisa Sasa",
-            "assignment_id": "d6f25868-5117-4b85-8bb3-44314144ef6e",
-            "change_reason": "Self-assigned by agent",
-            "notes": null,
-            "location_latitude": null,
-            "location_longitude": null,
-            "location_accuracy": null,
-            "location_verified": false,
-            "communication_method": "app",
-            "additional_metadata": {}
+        "notifications": {
+            "unread": 0,
+            "total": 0
         }
-    ]
-}
+    },
+    "work_queue": {
+        "pending_assignments": [
+            {
+                "assignment_id": "b3a83bd0-d287-4cea-a1c8-8bef145c1296",
+                "ticket_id": "8f08ad14-df8b-4780-84e7-0d45e133f2a6",
+                "ticket_name": "Catherine Njoki",
+                "ticket_type": "installation",
+                "service_type": "ftth",
+                "work_description": "Install Basic 10Mbps for Catherine Njoki",
+                "status": "ON_SITE",
+                "priority": "normal",
+                "due_date": "2025-12-01T07:52:17.604326+00:00",
+                "scheduled_date": "2025-12-28",
+                "scheduled_time_slot": "Afternoon 1PM-4PM",
+                "execution_order": null,
+                "assigned_at": "2025-11-28T09:27:41.952753+00:00"
+            },
+            {
+                "assignment_id": "a82a3824-f4f1-4283-a2e3-8c348dbb28ce",
+                "ticket_id": "f59b29fc-d0b9-4618-b0d1-889e340da612",
+                "ticket_name": "Elizabeth Muthoni",
+                "ticket_type": "installation",
+                "service_type": "ftth",
+                "work_description": "Install Premium Fiber 100Mbps for Elizabeth Muthoni",
+                "status": "ON_SITE",
+                "priority": "normal",
+                "due_date": "2025-11-29T13:24:19.212882+00:00",
+                "scheduled_date": "2025-12-11",
+                "scheduled_time_slot": null,
+                "execution_order": null,
+                "assigned_at": "2025-11-30T10:21:10.085152+00:00"
+            }
+        ],
+        "total_pending": 2,
+        "high_priority": 0,
+        "due_today": 1
+    },
+    "cached_at": "2025-12-01T07:00:02.307362Z",
+    "cache_expires_in_seconds": 300
+}

src/app/api/v1/ticket_assignments.py

@@ -654,6 +654,56 @@ def get_assignment(
     return service.get_assignment(assignment_id)
 
 
+@router.get(
+    "/assignments/{assignment_id}/location-trail",
+    summary="Get Location Trail for Map",
+    description="""
+    Get GPS location trail for map visualization.
+    
+    **Returns:**
+    - Journey start point
+    - Arrival point
+    - GPS breadcrumb trail (array of coordinates with timestamps)
+    - Journey stats (distance, travel time)
+    
+    **Authorization:**
+    - Agent can view their own trail
+    - PM/Dispatcher/Admin can view any trail
+    
+    **Use Case:**
+    - Frontend shows "View Journey" button if `has_location_trail: true`
+    - Button opens map page
+    - Map page calls this endpoint to get coordinates
+    - Renders route on map with start/end markers
+    
+    **Example Response:**
+    ```json
+    {
+      "assignment_id": "uuid",
+      "journey_start": {"lat": -1.2921, "lng": 36.8219},
+      "arrival_point": {"lat": -1.2930, "lng": 36.8225},
+      "trail": [
+        {"lat": -1.2921, "lng": 36.8219, "timestamp": "2024-03-20T09:00:00Z"},
+        {"lat": -1.2925, "lng": 36.8222, "timestamp": "2024-03-20T09:05:00Z"}
+      ],
+      "total_points": 45,
+      "journey_distance_km": 2.3,
+      "travel_time_minutes": 15
+    }
+    ```
+    """,
+    tags=["Ticket Assignments - Queries"]
+)
+def get_location_trail(
+    assignment_id: UUID,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+):
+    from app.schemas.ticket_assignment import LocationTrailResponse
+    service = TicketAssignmentService(db)
+    return service.get_location_trail(assignment_id, current_user)
+
+
 @router.get(
     "/tickets/{ticket_id}/assignments",
     summary="Get Ticket Assignments",

src/app/schemas/ticket_assignment.py

@@ -295,6 +295,7 @@ class TicketAssignmentResponse(BaseModel):
     arrival_longitude: Optional[Decimal] = None
     arrival_verified: bool = False
     journey_location_history: List[Dict[str, Any]] = []
+    has_location_trail: bool = False  # True if journey_location_history has data
     
     # Computed
     status: str  # PENDING, ACCEPTED, IN_TRANSIT, ON_SITE, CLOSED
@@ -335,6 +336,33 @@ class TicketAssignmentBriefResponse(BaseModel):
         from_attributes = True
 
 
+class LocationTrailResponse(BaseModel):
+    """GPS location trail for map visualization"""
+    assignment_id: UUID
+    ticket_id: UUID
+    user_id: UUID
+    user_name: str
+    
+    # Journey timeline
+    journey_started_at: Optional[datetime] = None
+    arrived_at: Optional[datetime] = None
+    
+    # Start and end points
+    journey_start: Optional[Dict[str, Any]] = None  # {"lat": float, "lng": float}
+    arrival_point: Optional[Dict[str, Any]] = None  # {"lat": float, "lng": float}
+    
+    # GPS breadcrumb trail
+    trail: List[LocationBreadcrumb] = []
+    
+    # Stats
+    total_points: int = 0
+    journey_distance_km: Optional[float] = None
+    travel_time_minutes: Optional[int] = None
+
+    class Config:
+        from_attributes = True
+
+
 class TicketWithAssignmentsResponse(BaseModel):
     """Ticket with assignment info"""
     id: UUID

src/app/services/dashboard_service.py

@@ -125,6 +125,7 @@ class DashboardService:
                     "notifications": DashboardService._get_notification_stats(db, current_user)
                 },
                 "work_queue": DashboardService._get_project_work_queue(db, project_id, current_user, limit=50),
+                "assignment_history": DashboardService._get_assignment_history(db, project_id, current_user, days=7),
                 "cached_at": datetime.utcnow().isoformat() + "Z",
                 "cache_expires_in_seconds": 300
             }
@@ -856,6 +857,99 @@ class DashboardService:
                 "due_today": 0
             }
     
+    @staticmethod
+    def _get_assignment_history(db: Session, project_id: str, current_user: User, days: int = 7) -> Dict:
+        """
+        Get field agent's completed assignment history for specific project.
+        
+        Returns assignments that have ended (completed, dropped, rejected) within the last N days.
+        Default is 7 days (weekly history).
+        
+        Args:
+            db: Database session
+            project_id: Project ID
+            current_user: Current user (field agent)
+            days: Number of days to look back (default: 7)
+        """
+        try:
+            from app.models.ticket_assignment import TicketAssignment
+            
+            # Calculate date threshold
+            date_threshold = datetime.utcnow() - timedelta(days=days)
+            
+            # Query completed assignments (ended_at is set)
+            assignments = db.query(TicketAssignment).options(
+                joinedload(TicketAssignment.ticket)
+            ).join(
+                Ticket
+            ).filter(
+                Ticket.project_id == project_id,
+                TicketAssignment.user_id == current_user.id,
+                TicketAssignment.ended_at.isnot(None),  # Assignment ended
+                TicketAssignment.ended_at >= date_threshold,  # Within last N days
+                TicketAssignment.deleted_at.is_(None)
+            ).order_by(
+                TicketAssignment.ended_at.desc()  # Most recent first
+            ).all()
+            
+            # Build history items
+            history_items = []
+            completed_count = 0
+            dropped_count = 0
+            rejected_count = 0
+            
+            for assignment in assignments:
+                ticket = assignment.ticket
+                
+                # Count by action
+                if assignment.action == "completed":
+                    completed_count += 1
+                elif assignment.action == "dropped":
+                    dropped_count += 1
+                elif assignment.action == "rejected":
+                    rejected_count += 1
+                
+                item = {
+                    "assignment_id": str(assignment.id),
+                    "ticket_id": str(ticket.id) if ticket else None,
+                    "ticket_name": ticket.ticket_name if ticket else "Unknown Ticket",
+                    "ticket_type": ticket.ticket_type if ticket else None,
+                    "service_type": ticket.service_type if ticket else None,
+                    "action": assignment.action,  # completed, dropped, rejected
+                    "assigned_at": assignment.assigned_at.isoformat() if assignment.assigned_at else None,
+                    "ended_at": assignment.ended_at.isoformat() if assignment.ended_at else None,
+                    "travel_time_minutes": assignment.travel_time_minutes,
+                    "work_time_minutes": assignment.work_time_minutes,
+                    "total_time_minutes": assignment.total_time_minutes,
+                    "journey_distance_km": assignment.journey_distance_km,
+                    "has_location_trail": (
+                        isinstance(assignment.journey_location_history, list) and 
+                        len(assignment.journey_location_history) > 0
+                    ),
+                    "reason": assignment.reason  # For dropped/rejected
+                }
+                
+                history_items.append(item)
+            
+            return {
+                "assignments": history_items,
+                "total": len(assignments),
+                "completed": completed_count,
+                "dropped": dropped_count,
+                "rejected": rejected_count,
+                "period_days": days
+            }
+        except Exception as e:
+            logger.error(f"Error getting assignment history: {e}")
+            return {
+                "assignments": [],
+                "total": 0,
+                "completed": 0,
+                "dropped": 0,
+                "rejected": 0,
+                "period_days": days
+            }
+    
     @staticmethod
     def _get_inventory_stats(db: Session, project_id: str) -> Dict:
         """Get inventory stats for project"""

src/app/services/ticket_assignment_service.py

@@ -976,6 +976,81 @@ class TicketAssignmentService:
         assignment = self._get_assignment_or_404(assignment_id)
         return self._to_response(assignment)
     
+    def get_location_trail(self, assignment_id: UUID, current_user: User):
+        """
+        Get GPS location trail for map visualization.
+        
+        Authorization:
+        - Agent can view their own trail
+        - PM/Dispatcher/Admin can view any trail
+        """
+        from app.schemas.ticket_assignment import LocationTrailResponse, LocationBreadcrumb
+        
+        assignment = self.db.query(TicketAssignment).options(
+            joinedload(TicketAssignment.user)
+        ).filter(
+            TicketAssignment.id == assignment_id,
+            TicketAssignment.deleted_at.is_(None)
+        ).first()
+        
+        if not assignment:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Assignment not found"
+            )
+        
+        # Authorization check
+        is_own_assignment = assignment.user_id == current_user.id
+        is_authorized_role = current_user.role in [
+            AppRole.PLATFORM_ADMIN,
+            AppRole.PROJECT_MANAGER,
+            AppRole.DISPATCHER
+        ]
+        
+        if not (is_own_assignment or is_authorized_role):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not authorized to view this location trail"
+            )
+        
+        # Build journey start point
+        journey_start = None
+        if assignment.journey_start_latitude and assignment.journey_start_longitude:
+            journey_start = {
+                "lat": float(assignment.journey_start_latitude),
+                "lng": float(assignment.journey_start_longitude)
+            }
+        
+        # Build arrival point
+        arrival_point = None
+        if assignment.arrival_latitude and assignment.arrival_longitude:
+            arrival_point = {
+                "lat": float(assignment.arrival_latitude),
+                "lng": float(assignment.arrival_longitude)
+            }
+        
+        # Convert trail to LocationBreadcrumb objects
+        trail = []
+        if isinstance(assignment.journey_location_history, list):
+            for point in assignment.journey_location_history:
+                if isinstance(point, dict) and "lat" in point and "lng" in point:
+                    trail.append(LocationBreadcrumb(**point))
+        
+        return LocationTrailResponse(
+            assignment_id=assignment.id,
+            ticket_id=assignment.ticket_id,
+            user_id=assignment.user_id,
+            user_name=assignment.user.full_name if assignment.user else "Unknown",
+            journey_started_at=assignment.journey_started_at,
+            arrived_at=assignment.arrived_at,
+            journey_start=journey_start,
+            arrival_point=arrival_point,
+            trail=trail,
+            total_points=len(trail),
+            journey_distance_km=assignment.journey_distance_km,
+            travel_time_minutes=assignment.travel_time_minutes
+        )
+    
     def get_ticket_assignments(self, ticket_id: UUID) -> dict:
         """Get all assignments for ticket (current + past)"""
         assignments = self.db.query(TicketAssignment).options(
@@ -1242,6 +1317,12 @@ class TicketAssignmentService:
                 phone=assignment.assigned_by.phone
             )
         
+        # Check if location trail exists
+        has_location_trail = (
+            isinstance(assignment.journey_location_history, list) and 
+            len(assignment.journey_location_history) > 0
+        )
+        
         return TicketAssignmentResponse(
             id=assignment.id,
             ticket_id=assignment.ticket_id,
@@ -1262,6 +1343,7 @@ class TicketAssignmentService:
             arrival_longitude=assignment.arrival_longitude,
             arrival_verified=assignment.arrival_verified,
             journey_location_history=assignment.journey_location_history,
+            has_location_trail=has_location_trail,
             status=assignment.status,
             is_active=assignment.is_active,
             travel_time_minutes=assignment.travel_time_minutes,