Customer Location Update

Author(s)

• Amarnath Garai

Last Updated Date

[2026-07-28]

---

SRS References

• Service Request Management Module
• Realtime Tracking and Notification Module
• Mapbox Routing Integration

---

Version History

Version	Date	Changes	Author
1.0	2026-07-27	Initial feature document for customer service-location updates	Amarnath Garai
1.1	2026-07-28	Updated status validation to use a whitelist and return NOT_ALLOWED for all other statuses	Amarnath Garai

---

Feature Overview

Objective

Allow a customer to update the requested service location after booking a service request, while ensuring the technician route, ETA, realtime broadcasts, and notifications stay synchronized with the latest customer coordinates.

Scope

This feature allows location updates only when the service request is in one of the following states:

1. Pending
2. Assigned
3. EnRoute

The customer cannot update the location when the request is in any other status, including Stopped, InProgress, Completed, or any future non-whitelisted status. Location updates are also blocked when basicInfo.IsReached is true, even if the request status is otherwise eligible.

Dependencies

• servicerequests database table
• RouteOptimizationService
• Mapbox Directions API
• RealTimeHub
• SignalR request groups
• Notification settings
• Push and email notification services

---

Requirements

Functional Requirements

1. The system must allow a customer to update the latitude, longitude, and address for an existing service request.
2. The system must validate that the service request exists before updating the location.
3. The system must allow location updates only when the request status is Pending, Assigned, or EnRoute.
4. The system must block location updates for every other request status, including Stopped, InProgress, and Completed.
5. The system must block location updates when basicInfo.IsReached is true.
6. The system must return the message Cannot update location because the technician has already reached the location. when the technician has already reached the customer location.
7. The system must update the latitude, longitude, location, and updatedat fields in the servicerequests table.
8. When the request is EnRoute, the system must use the latest customer coordinates during the next technician location ping.
9. The system must recalculate the Mapbox route, ETA, encoded polyline, and polyline version after the technician location flow picks up the new customer coordinates.
10. The system must broadcast the updated route and location payload to the technician app and admin dashboard through SignalR.
11. The system must notify admins when a customer updates the location for a service request.
12. The system must notify the assigned technician when the request is already Assigned or EnRoute.
13. Notification actions must route admins and technicians to the updated service request details screen.

Non-Functional Requirements

1. The system must preserve data integrity for service request location updates.
2. The system must avoid changing payment or tracking behavior after the service has moved to InProgress.
3. The route recalculation flow must use the latest stored coordinates without requiring manual refresh.
4. Realtime broadcasts must remain scoped to the related service request.
5. Notification delivery must respect each recipient's configured notification settings.

---

Design Specifications

• UI/UX Design

  Customer apps should allow editing the service location only while the request status is Pending, Assigned, or EnRoute and basicInfo.IsReached is false. For all other statuses, including Stopped, InProgress, and Completed, or after the technician has reached the customer location, the location update action should be hidden or disabled.

• Data Models

  The existing servicerequests table is updated with the new location values.

  Field	Type	Description
  latitude	Numeric	Updated customer latitude
  longitude	Numeric	Updated customer longitude
  location	String	Updated customer address
  updatedat	Timestamp	Last update timestamp

• API Interfaces

  Endpoint	Method	Parameters	Response	Response Status Codes
  /service-request/{requestId}/location	PUT	requestId route parameter, UpdateServiceRequestLocationRequest body	CommonResponse	200, 400

• API Examples

  Headers

  Header	Value
  Authorization	Bearer <token> with customer scope

  Request Parameters

  Name	Location	Type	Description
  requestId	Route	Guid	Service request identifier

  Request Body: UpdateServiceRequestLocationRequest

  {
    "latitude": 34.052235,
    "longitude": -118.243683,
    "location": "123 New Address St, Los Angeles, CA 90012"
  }

  Success Response: 200 OK

  {
    "status": 2000,
    "message": "Location updated successfully"
  }

  Invalid Status Response: NOT_ALLOWED

  {
    "status": "NOT_ALLOWED",
    "message": "Location updates are allowed only when the service request status is Pending, Assigned, or EnRoute."
  }

  Technician Already Reached Response: NOT_ALLOWED

  {
    "status": "NOT_ALLOWED",
    "message": "Cannot update location because the technician has already reached the location."
  }

• Third-Party Integrations

  Integration	Purpose
  Mapbox Directions API	Recalculate the route polyline and ETA using the latest customer coordinates
  SignalR	Broadcast updated location and route payloads to request listeners
  Push and email services	Notify admins and assigned technicians about the updated service location

• SignalR Real-Time Broadcasting

  Location Update Event

  After the customer location is updated, RealTimeService broadcasts Events.CustomerLocationUpdated (customer_location_updated) to the Request-{requestId} and AllAdmins groups. This allows the technician app and admin dashboard to refresh the displayed customer address text and customer map pin immediately, before the next technician location ping occurs.

  Mapbox Route Update

  When the technician is EnRoute, the next SubmitLocation ping reads the updated customer coordinates and triggers route recalculation. Because Mapbox provides a new polyline and ETA, the BuildLocationBroadcastAsync payload contains the new EncodedPolyline and incremented PolylineVersion. The technician app and admin dashboard, listening to the Request-{requestId} and AllAdmins groups, receive the Events.LocationUpdated payload and redraw the route on their maps.

• Workflow

  1. Customer submits a location update using PUT /service-request/{requestId}/location.
  2. The API validates the customer token and resolves the target service request.
  3. The service verifies the request status is Pending, Assigned, or EnRoute.
  4. The service verifies basicInfo.IsReached is false.
  5. If basicInfo.IsReached is true, the update is rejected with Cannot update location because the technician has already reached the location..
  6. The system updates latitude, longitude, location, and updatedat in the servicerequests table.
  7. RealTimeService broadcasts Events.CustomerLocationUpdated (customer_location_updated) to Request-{requestId} and AllAdmins.
  8. Connected clients refresh the customer address text and map pin immediately.
  9. Admins in the dealer network receive a notification that the location was updated.
  10. If a technician is assigned, the technician receives a push notification and/or email based on notification settings.
  11. If the technician is EnRoute, the next SubmitLocation ping reads the updated customer coordinates from the database.
  12. RouteOptimizationService calls Mapbox Directions API with the latest technician and customer coordinates.
  13. Mapbox returns a recalculated route polyline and ETA.
  14. RealTimeHub builds the updated location broadcast payload with the new EncodedPolyline and incremented PolylineVersion.
  15. The technician app and admin dashboard receive Events.LocationUpdated through the Request-{requestId} and AllAdmins groups.
  16. Connected clients redraw the route using the updated location payload.

---

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Add or verify location update API endpoint	2 hours	Service request module	Includes request validation and authorization
2	Add status whitelist validation for eligible updates	1 hour	Service request status model	Allow only Pending, Assigned, and EnRoute; return NOT_ALLOWED for all other statuses
3	Add technician reached-location validation	1 hour	Service request basic info	Block when basicInfo.IsReached is true
4	Persist updated coordinates and address	1 hour	servicerequests table	Update latitude, longitude, location, and updatedat
5	Verify Mapbox route recalculation flow	2 hours	RouteOptimizationService, technician SubmitLocation flow	Ensure latest customer coordinates are used
6	Verify SignalR broadcast payload	2 hours	RealTimeHub	Include updated EncodedPolyline and PolylineVersion
7	Add admin and technician notifications	2 hours	Notification settings, push and email services	Use OPEN_SERVICE_REQUEST action
8	Add tests for valid status, blocked status, and IsReached guard	2 hours	API and service test suite	Cover success, invalid-status, and technician-reached responses
9	Total	13 hours	All above	Estimate can be refined during implementation

---