Customer Vehicle Service Booking

Author(s)

• Amarnath Garai
• Sanket Mal
• ...

Last Updated Date

[2026-01-13]

---

SRS References

• 2.1.2
• 2.1.3

---

Version History

Version	Date	Changes	Author
1.0	2026-01-13	Initial draft	Amarnath Garai , Sanket Mal
...	...	...	...

---

Feature Overview

Objective The objective of this feature is to enable customers to book vehicle service requests and allow multiple technicians to receive, respond to, and compete for those requests in real time. The system ensures that only one technician can successfully accept a service request while maintaining a complete audit trail of all technician interactions, service execution, and billing.

This feature supports both on-demand and scheduled service workflows and enables location-based technician assignment for efficient dispatch.

Scope This feature covers the full lifecycle of a service request, including:

• Service request creation by customers
• Technician notification, acceptance, rejection, and cancellation
• Technician assignment and tracking
• Service execution and completion
• Per-service pricing and billing

---

Requirements

Functional Requirements

1. The system must allow customers to create a service request with vehicle, location, and service details.
2. The system must support both ON_DEMAND and SCHEDULED service types.
3. The system must allow customers to choose service location preference (Customer Location or Service Center).
4. The system must notify multiple nearby technicians when a service request is created.
5. The system must allow technicians to Accept, Reject, or Ignore a service request.
6. The system must ensure that only one technician can successfully accept a service request.
7. When a technician accepts a request, all other technicians must be blocked from accepting the same request.
8. The system must record all technician actions (Notified, Accepted, Rejected, Canceled) for each request.
9. The system must assign the accepting technician as the current technician for the service request.
10. The system must allow the assigned technician to cancel the request if needed.
11. The system must track the service status (Pending, In-Progress, Completed).
12. The system must allow multiple services to be attached to a single service request.
13. The system must track per-service status (Pending, Completed, Rejected).
14. The system must calculate the total price of a request based on completed services.
15. The system must allow customers to provide ratings and feedback after completion.

---

Non-Functional Requirements

1. The system must handle concurrent technician acceptance attempts without data conflicts.
2. The system must ensure data integrity through foreign keys and transactional updates.
3. The system must maintain a complete audit trail of technician actions.
4. The system must support location-based searching for technicians using latitude and longitude.
5. The system must be optimized for high-volume real-time requests.
6. The system must be resilient to partial failures (e.g., technician app crashes during acceptance).
7. The system must support future scalability for thousands of technicians and service requests.

---

Design Specifications

• UI/UX Design:
  (Include wireframes, mockups, or links to design files.)

• SQL Data Models:

      CREATE TABLE IF NOT EXISTS servicerequests (
        requestid UUID PRIMARY KEY DEFAULT gen_random_uuid(),
        requestnumber VARCHAR(50),
        customerid UUID NOT NULL,
        vehicleid UUID NOT NULL,
        vanid UUID,
        currenttechnicianid UUID,
  
        servicescheduletype VARCHAR(20) NOT NULL, -- ('OnDemand', 'Scheduled')
        locationpreference VARCHAR(30) NOT NULL, -- ('CustomerLocation', 'ServiceCenter')
  
        estimatedprice NUMERIC(10,2),
        paymentstatus VARCHAR(20),
        paymentmethod VARCHAR(20),
        description TEXT,
  
        rating INT,
        feedback TEXT,
  
        scheduledat TIMESTAMP,
  
        requeststatus VARCHAR(20) NOT NULL, -- ('Pending', 'Accepted', 'InProgress', 'Completed', 'Canceled')
  
        latitude NUMERIC(9,6),
        longitude NUMERIC(9,6),
        location TEXT,
  
        requestedat TIMESTAMP NOT NULL DEFAULT NOW(),
        updatedat TIMESTAMP NOT NULL DEFAULT NOW(),
  
        CONSTRAINT fk_request_customer
            FOREIGN KEY (customerid)
            REFERENCES customermaster(customerid)
            ON DELETE CASCADE,
  
        CONSTRAINT fk_request_vehicle
            FOREIGN KEY (vehicleid)
            REFERENCES customervehicles(customervehicleid)
            ON DELETE CASCADE,
  
        CONSTRAINT fk_request_van
            FOREIGN KEY (vanid)
            REFERENCES vanmaster(vanid)
            ON DELETE SET NULL,
  
        CONSTRAINT fk_request_technician
            FOREIGN KEY (currenttechnicianid)
            REFERENCES technicianmaster(technicianid)
            ON DELETE SET NULL
      );
  
  
        CREATE TABLE IF NOT EXISTS servicemaster (
          serviceid UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  
          servicecode VARCHAR(50) NOT NULL UNIQUE,
          servicename VARCHAR(150) NOT NULL UNIQUE,
          servicedescription TEXT,
          servicecategory VARCHAR(20), -- ('Maintenance', 'Repair', 'Inspection', 'Diagnostic', 'Detailing', 'Customization', 'Emergency')
  
          estimatedduration INTERVAL,
          baseprice NUMERIC(10,2),
  
          serviceavailablein VARCHAR(20), -- ('Van', 'ServiceCenter', 'Both')
  
          isactive BOOLEAN NOT NULL DEFAULT TRUE,
  
          createdat TIMESTAMP NOT NULL DEFAULT NOW(),
          updatedat TIMESTAMP NOT NULL DEFAULT NOW()
        );
  
        CREATE TABLE IF NOT EXISTS requestedservices (
          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  
          requestid UUID NOT NULL,
          serviceid UUID NOT NULL,
  
          serviceprice NUMERIC(10,2),
  
          servicestatus VARCHAR(20) NOT NULL, -- ('Pending', 'Completed', 'Rejected')
          reasonofrejection TEXT,
  
          CONSTRAINT fk_requested_request
              FOREIGN KEY (requestid)
              REFERENCES servicerequests(requestid)
              ON DELETE CASCADE,
  
          CONSTRAINT fk_requested_service
              FOREIGN KEY (serviceid)
              REFERENCES servicemaster(serviceid),
  
          CONSTRAINT uq_request_service UNIQUE (requestid, serviceid)
          );
  
  
      CREATE TABLE IF NOT EXISTS technicianengagementdetails (
        engagementid UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  
        requestid UUID NOT NULL,
        technicianid UUID NOT NULL,
  
        action VARCHAR(20) NOT NULL, -- ('NOTIFIED', 'ACCEPTED', 'REJECTED', 'CANCELED')
        time TIMESTAMP NOT NULL DEFAULT NOW(),
  
        CONSTRAINT fk_engagement_request
            FOREIGN KEY (requestid)
            REFERENCES servicerequests(requestid)
            ON DELETE CASCADE,
  
        CONSTRAINT fk_engagement_technician
            FOREIGN KEY (technicianid)
            REFERENCES technicianmaster(technicianid)
            ON DELETE CASCADE
        );
  
  
        // INDEXS
        CREATE INDEX idx_servicerequests_status ON servicerequests(requeststatus);
        CREATE INDEX idx_servicerequests_location ON servicerequests(latitude, longitude);
        CREATE INDEX idx_servicerequests_customer_requestedat ON servicerequests(customerid, requestedat DESC);
  
  
        CREATE INDEX idx_requestedservices_request ON requestedservices(requestid);
        CREATE INDEX idx_requestedservices_service ON requestedservices(serviceid);
        
  
        CREATE INDEX idx_technicianengagement_request ON technicianengagementdetails(requestid);
        CREATE INDEX idx_technicianengagement_technician ON technicianengagementdetails(technicianid);
  

• C# Data Models:

  
  public enum ServiceScheduleType{
    OnDemand = 1,
    Scheduled
  }
  
  public enum LocationPreference{
    CustomerLocation = 1,
    ServiceCenter
  }
  
  public enum RequestStatus{
    Pending = 1,
    Accepted,
    InProgress,
    Completed,
    Canceled,
    Ringing
  }
  
  public enum ServiceAvailableIn{
    Van = 1,
    ServiceCenter,
    Both
  }
  
  public enum ServiceStatus{
    Pending = 1,
    Completed,
    Rejected
  }
  
  public enum TechnicianEngagementAction{
    Accepted = 1,
    Rejected,
    Canceled
  }
  
  public enum ServiceCategory
  {
      Maintenance = 1,      // Oil change, filter replacement, routine service
      Repair = 2,           // Brake repair, engine repair, parts replacement
      Inspection = 3,       // Safety inspection, pre-purchase inspection
      Diagnostic = 4,       // Electrical diagnostic, engine diagnostic
      Detailing = 5,        // Cleaning, polishing, interior detailing
      Customization = 6,    // Modifications, upgrades, accessories
      Emergency = 7         // Roadside assistance, towing, urgent repairs
  }
  
  public enum PaymentStatus{
    Pending = 1,
    Paid
  }
  
  public enum TechnicianWorkAction{
    Start = 1,
    Complete
  }
  
  public record CommonResponse
  {
      public int Status { get; init; }
      public string? Message { get; init; }
  }
  
  public record ServerPaginatedData<T>
  {
      public List<T> Data { get; init; } = [];
      public int TotalNumber { get; init; }
      public bool HasPreviousPage { get; init; }
      public bool HasNextPage { get; init; }
      public int TotalPages { get; init; }
      public int PageNumber { get; init; }
      public int RowsPerPage { get; init; }
  }
  
      public record CreateServiceRequest
    {
        // Required
        public Guid VehicleId { get; init; }
  
        public ServiceScheduleType ServiceScheduleType { get; init; } = ServiceScheduleType.OnDemand; // OnDemand / Scheduled
        public LocationPreference LocationPreference { get; init; } = LocationPreference.CustomerLocation; // CustomerLocation / ServiceCenter , Also OnDemand is Always CustomerLocation
  
        // Only required when ServiceScheduleType == Scheduled
        public DateTime? ScheduledAt { get; init; }
  
        // Location
        public required decimal Latitude { get; init; }
        public required decimal Longitude { get; init; }
        public string? Location { get; init; }
  
        // Description
        public string? Description { get; init; }
        // List of service IDs (from servicemaster) that the customer is requesting
        public required List<Guid> Services { get; init; }
  
        // System controlled — NOT sent by client
        [JsonIgnore]
        public Guid CustomerId { get; init; }
        // System controlled — NOT sent by client
        [JsonIgnore]
        public decimal? EstimatedPrice { get; init; }
  
        // System controlled — NOT sent by client
        [JsonIgnore]
        public RequestStatus RequestStatus { get; init; } = RequestStatus.Pending;
    }
  
  
      public record ServiceRequestDetailedResponse
    {
        // --- Request Core ---
        public Guid RequestId { get; init; }
        public Guid CustomerId { get; init; }
        public Guid VehicleId { get; init; }
  
        public required string RequestNumber { get; set; }
  
        public ServiceScheduleType ServiceScheduleType { get; init; }      // OnDemand / Scheduled
        public LocationPreference LocationPreference { get; init; }       // CustomerLocation / ServiceCenter
        public RequestStatus RequestStatus { get; init; }                 // Pending / InProgress / Completed / Canceled
  
        public DateTime RequestedAt { get; init; }
        public DateTime? ScheduledAt { get; init; }
  
        // --- Location ---
        public required decimal Latitude { get; init; }
        public required decimal Longitude { get; init; }
        public string? Location { get; init; }
  
        // --- Description ---
        public string? Description { get; init; }
  
        // --- Payment ---
        public decimal? EstimatedPrice { get; init; }
        public PaymentStatus PaymentStatus { get; init; }
        public string? PaymentMethod { get; init; }
  
        // --- Feedback ---
        public int? Rating { get; init; }
        public string? Feedback { get; init; }
  
        // --- Nested objects ---
        public required CustomerBasicInfo Customer { get; set; }
  
        public required VehicleBasicInfo Vehicle { get; set; }
  
        public VanInfo? Van { get; init; }
        public TechnicianBasicInfo? Technician { get; init; }
  
        public List<RequestedServiceInfo> Services { get; init; } = new();
    }
  
    public record CustomerBasicInfo
    {
        public Guid UserId { get; init; }
  
        // Customer identification
        public Guid CustomerId { get; init; }
        public string CustomerCode { get; init; } = string.Empty;
  
        // User information
        public string Email { get; init; } = string.Empty;
        public string FirstName { get; init; } = string.Empty;
        public string LastName { get; init; } = string.Empty;
        public string PhoneNumber { get; init; } = string.Empty;
  
        public Gender? Gender { get; init; }
    }
  
    
    public record VehicleBasicInfo
    {
        public required string Vin { get; init; }
  
        // Basic Identity
        public string? Make { get; init; }
        public string? Model { get; init; }
        public int? Year { get; init; }
        public string? Trim { get; init; }
  
        // Body
        public string? VehicleType { get; init; }   // Passenger Car
        public string? BodyType { get; init; }     // Coupe, Sedan
    }
  
    public record TechnicianBasicInfo
    {
        public Guid TechnicianId { get; init; }
        public string TechnicianCode { get; init; } = string.Empty;
        public string FirstName { get; init; } = string.Empty;
        public string LastName { get; init; } = string.Empty;
        public string? Email { get; init; }
        public string? PhoneNumber { get; init; }
    }
  
    public record VanInfo
    {
        public Guid VanId { get; init; }
        public string VanNumber { get; init; } = string.Empty;
        public string RegistrationNumber { get; init; } = string.Empty;
        public string VIN { get; init; } = string.Empty;
        public string Make { get; init; } = string.Empty;
        public string Model { get; init; } = string.Empty;
        public int Year { get; init; }
    }
  
  public record RequestedServiceInfo
  {
      public Guid ServiceId { get; init; }
      public string ServiceName { get; init; }
      public string ServiceCode {get; init;}
      public string ServiceDescription { get; init; }
      public decimal? ServicePrice { get; init; }
      public ServiceStatus ServiceStatus { get; init; }              // Pending / Completed / Rejected
      public string ReasonOfRejection { get; init; }
  }
  
    public record GetServiceRequestsFilter
    {
        // Status filters
        public RequestStatus? RequestStatus { get; init; }                // Pending / Accepted / InProgress / Completed / Canceled
        public PaymentStatus? PaymentStatus { get; init; }                // Pending / Paid
        public TechnicianEngagementAction? Action { get; init; }
  
        // Type filters
        public ServiceScheduleType? ServiceScheduleType { get; init; }    // OnDemand / Scheduled
        public LocationPreference? LocationPreference { get; init; }      // CustomerLocation / ServiceCenter
  
        // Date filters
        public DateTime? FromDate { get; init; }
        public DateTime? ToDate { get; init; }
  
        // Paging
        public int RowsPerPage { get; init; } = 10;
        public int PageNumber { get; init; } = 1;
    }
  
  
  public record GetServicesFilter
  {
      public ServiceAvailableIn? ServiceAvailableIn { get; init; }
      public string? SearchKeyword { get; init; }
  
      public ServiceCategory? ServiceCategory { get; init; }
  
      // Paging
      public int RowsPerPage { get; init; } = 10;
      public int PageNumber { get; init; } = 1;
  
  }
  
  public record ServiceMasterResponse
  {
      public Guid ServiceId { get; init; }
      public string ServiceCode { get; init; } = string.Empty;
      public string ServiceName { get; init; } = string.Empty;
      public ServiceCategory ServiceCategory { get; init; }
      public string? ServiceDescription { get; init; }
      public TimeSpan? EstimatedDuration { get; init; }
      public decimal? BasePrice { get; init; }
      public ServiceAvailableIn ServiceAvailableIn { get; init; }
      public bool IsActive { get; init; }
      public DateTime CreatedAt { get; init; }
      public DateTime UpdatedAt { get; init; }
  }
  
  public record CreateServiceMaster
  {
      public string ServiceName { get; init; } = string.Empty;
      public ServiceCategory ServiceCategory { get; init; }
      public string? ServiceDescription { get; init; }
      public TimeSpan? EstimatedDuration { get; init; }
      public decimal? BasePrice { get; init; }
      public ServiceAvailableIn ServiceAvailableIn { get; init; }
      public bool IsActive { get; init; } = true;
  }
  
  public record SubmitFeedback
  {
      public int Rating { get; init; }  // 1-5 star rating
      public string? Feedback { get; init; }
  }
  
  public record ServiceSuggestionRequest
  {
      public ServiceAvailableIn? ServiceAvailableIn { get; init; }
      public ServiceCategory? ServiceCategory { get; init; }
  }
  
  public record UpdateServiceMaster
  {
      public string? ServiceName { get; set; }
      public ServiceCategory? ServiceCategory { get; set; }
      public string? ServiceDescription { get; set; }
      public TimeSpan? EstimatedDuration { get; set; }
      public decimal? BasePrice { get; set; }
      public ServiceAvailableIn? ServiceAvailableIn { get; set; }
      public bool? IsActive { get; set; }
  }
  
  public record TechnicianSuggestionFilter
  {
      public string? SearchKeyword { get; init; } // Global search
      public UserStatus Status { get; init; }
      public bool HasVanAssigned { get; init; }
  }
  
  public record CreateServiceRequestResponse
  {
      public Guid RequestId { get; init; }
      public string RequestNumber { get; init; } = string. Empty;
  }
  
  public record ResponseWithData<T> : CommonResponse
  {
      public T? Data { get; init; }
  }
  
  actionType = TechnicianEngagementAction (Mean same Values)
  

• API Interfaces:
  (Define the APIs required for this feature, including endpoints, methods, request/response formats.)

  Endpoint	Method	Parameters	Response	Response Status Codes
  /service-request	POST	CreateServiceRequest	ResponseWithData<CreateServiceRequestResponse>	200, 204, 500
  /services	GET	GetServicesFilter	ServerPaginatedData<ServiceMasterResponse>	200, 204, 500
  /service-suggestions	GET	ServiceSuggestionRequest	List<ServiceMasterResponse>	200, 204, 500
  /service/{ServiceId}	GET	ServiceId	ServiceMasterResponse	200, 404, 500
  /service/{serviceId}	PUT	serviceId, UpdateServiceMaster	CommonResponse	200, 404, 500
  /service	POST	CreateServiceMaster	CommonResponse	200, 400, 403, 409, 500
  /service-request/{requestId}/{actionType}	PUT	requestId actionType	CommonResponse	200, 204, 500
  /service-request/{requestId}?workAction=TechnicianWorkAction	PUT	requestId, workAction	CommonResponse	200, 400, 401, 403, 404, 500
  /service-request/{requestId}	POST	requestId, SubmitFeedback	CommonResponse	200, 400, 403, 500
  /service-requests	GET	GetServiceRequestsFilter	ServerPaginatedData<ServiceRequestDetailedResponse>	200, 204, 500
  /service-request/{requestId}	GET	requestId	ServiceRequestDetailedResponse	200, 204, 500
  /technician-suggestions	GET	TechnicianSuggestionFilter	List<TechnicianBasicInfo>	200, 204, 500

---

API Endpoints With Request & Response

1. Create Service Request

Endpoint: POST /service-request

Request:

{
  "vehicleId": "550e8400-e29b-41d4-a716-446655440000",
  "serviceScheduleType": "OnDemand",
  "locationPreference": "CustomerLocation",
  "scheduledAt": null,
  "latitude": 40.7128,
  "longitude": -74.0060,
  "location": "123 Main St, New York, NY",
  "description": "Full vehicle service including oil change and inspection",
  "services": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ]
}

Response (Success - 200):

{
  "status": 200,
  "message": "Service request created successfully"
}

Response (Server Error - 500):

{
  "status": 500,
  "message": "An error occurred while creating the service request"
}

---

2. Get Services List

Endpoint: GET /services

Request Parameters:

{
  "serviceAvailableIn": "Both",
  "searchKeyword": "oil",
  "serviceCategory": "Maintenance",
  "rowsPerPage": 10,
  "pageNumber": 1
}

Response (Success - 200):

{
  "data": [
    {
      "serviceId": "550e8400-e29b-41d4-a716-446655440001",
      "serviceCode": "OIL-001",
      "serviceName": "Oil Change",
      "serviceCategory": "Maintenance",
      "serviceDescription": "Premium oil change service with filter replacement",
      "estimatedDuration": "00:30:00",
      "basePrice": 49.99,
      "serviceAvailableIn": "Both",
      "isActive": true,
      "createdAt": "2026-01-13T10:30:00Z",
      "updatedAt": "2026-01-13T10:30:00Z"
    }
  ],
  "totalNumber": 1,
  "hasPreviousPage": false,
  "hasNextPage": false,
  "totalPages": 1,
  "pageNumber": 1,
  "rowsPerPage": 10
}

Response (No Content - 204):

---

3. Get Service Suggestions

Endpoint: GET /service-suggestions

Request Parameters:

{
  "serviceAvailableIn": "Van",
  "serviceCategory": "Maintenance"
}

Response (Success - 200):

[
  {
    "serviceId": "550e8400-e29b-41d4-a716-446655440001",
    "serviceCode": "OIL-001",
    "serviceName": "Oil Change",
    "serviceCategory": "Maintenance",
    "serviceDescription": "Premium oil change service with filter replacement",
    "estimatedDuration": "00:30:00",
    "basePrice": 49.99,
    "serviceAvailableIn": "Both",
    "isActive": true,
    "createdAt": "2026-01-13T10:30:00Z",
    "updatedAt": "2026-01-13T10:30:00Z"
  },
  {
    "serviceId": "550e8400-e29b-41d4-a716-446655440002",
    "serviceCode": "FILTER-001",
    "serviceName": "Air Filter Replacement",
    "serviceCategory": "Maintenance",
    "serviceDescription": "Air filter replacement and cabin filter check",
    "estimatedDuration": "00:20:00",
    "basePrice": 29.99,
    "serviceAvailableIn": "Both",
    "isActive": true,
    "createdAt": "2026-01-13T10:30:00Z",
    "updatedAt": "2026-01-13T10:30:00Z"
  }
]

---

4. Get Service by ID

Endpoint: GET /service/{ServiceId}

Path Parameters:

• ServiceId: 550e8400-e29b-41d4-a716-446655440001

Response (Success - 200):

{
  "serviceId": "550e8400-e29b-41d4-a716-446655440001",
  "serviceCode": "OIL-001",
  "serviceName": "Oil Change",
  "serviceCategory": "Maintenance",
  "serviceDescription": "Premium oil change service with filter replacement",
  "estimatedDuration": "00:30:00",
  "basePrice": 49.99,
  "serviceAvailableIn": "Both",
  "isActive": true,
  "createdAt": "2026-01-13T10:30:00Z",
  "updatedAt": "2026-01-13T10:30:00Z"
}

Response (Not Found - 404):

{
  "status": 404,
  "message": "Service not found"
}

---

5. Update Service by ID

Endpoint: PUT /service/{serviceId}

Path Parameters:

• serviceId: 550e8400-e29b-41d4-a716-446655440001

Request:

{
  "serviceName": "Oil Change Premium",
  "serviceCategory": "Maintenance",
  "serviceDescription": "Premium oil change service with synthetic oil and filter replacement",
  "estimatedDuration": "00:45:00",
  "basePrice": 59.99,
  "serviceAvailableIn": "Both",
  "isActive": true
}

Response (Success - 200):

{
  "status": 200,
  "message": "Service updated successfully"
}

Response (Not Found - 404):

{
  "status": 404,
  "message": "Service not found"
}

Response (Conflict - 409):

{
  "status": 409,
  "message": "Service with this name already exists"
}

Response (Bad Request - 400):

{
  "status": 400,
  "message": "Invalid input parameters"
}

Response (Server Error - 500):

{
  "status": 500,
  "message": "An error occurred while updating the service"
}

---

6. Create Service Master

Endpoint: POST /service

Request:

{
  "serviceName": "Brake Pad Replacement",
  "serviceCategory": "Repair",
  "serviceDescription": "Complete brake pad replacement with inspection",
  "estimatedDuration": "01:00:00",
  "basePrice": 199.99,
  "serviceAvailableIn": "Both",
  "isActive": true
}

Response (Success - 200):

{
  "status": 200,
  "message": "Service created successfully"
}

Response (Conflict - 409):

{
  "status": 409,
  "message": "Service with this name already exists"
}

Response (Bad Request - 400):

{
  "status": 400,
  "message": "Invalid input parameters"
}

Response (Forbidden - 403):

{
  "status": 403,
  "message": "You do not have permission to create services"
}

---

7. Technician Accept/Reject Service Request

Endpoint: PUT /service-request/{requestId}/{actionType}

Path Parameters:

• requestId: 550e8400-e29b-41d4-a716-446655440003

Request:

**Response (Success - 200):**
```json
{
  "status": 200,
  "message": "Service request accepted successfully"
}

Response (No Content - 204):

Response (Conflict - already accepted):

{
  "status": 409,
  "message": "Service request has already been accepted by another technician"
}

---

8. Technician Work Action (Start/Complete)

Endpoint: PUT /service-request/{requestId:guid}

Summary: Start or Complete Service Request Work

Description: Allows technicians to start or complete work on service requests they are assigned to. Requires technician authorization.

Path Parameters:

• requestId (guid): 550e8400-e29b-41d4-a716-446655440003

Query Parameters:

• workAction (enum): The action to perform. Allowed values: Start (1), Complete (2)

Response (Success - 200):

{
  "status": 200,
  "message": "Work action completed successfully"
}

Response (Bad Request - 400):

{
  "status": 400,
  "message": "Invalid parameters or status transition not allowed"
}

Response (Unauthorized - 401):

{
  "status": 401,
  "message": "User not authenticated"
}

Response (Forbidden - 403):

{
  "status": 403,
  "message": "User is not a technician or not assigned to this request"
}

Response (Not Found - 404):

{
  "status": 404,
  "message": "Service request not found"
}

Response (Internal Server Error - 500):

{
  "status": 500,
  "message": "Internal server error"
}

---

9. Submit Feedback for Service Request

Endpoint: POST /service-request/{requestId}

Path Parameters:

• requestId: 550e8400-e29b-41d4-a716-446655440003

Request:

{
  "rating": 5,
  "feedback": "Excellent service! The technician was professional and efficient."
}

Response (Success - 200):

{
  "status": 200,
  "message": "Feedback submitted successfully"
}

Response (Bad Request - 400):

{
  "status": 400,
  "message": "Rating must be between 1 and 5"
}

Response (Forbidden - 403):

{
  "status": 403,
  "message": "You can only provide feedback for your own service requests"
}

---

10. Get Service Requests (Customer View)

Endpoint: GET /service-requests

Request Parameters:

{
  "requestStatus": "Completed",
  "paymentStatus": "Paid",
  "action": null,
  "serviceScheduleType": null,
  "locationPreference": null,
  "fromDate": "2026-01-01T00:00:00Z",
  "toDate": "2026-01-31T23:59:59Z",
  "rowsPerPage": 10,
  "pageNumber": 1
}

Response (Success - 200):

{
  "data": [
    {
      "requestId": "550e8400-e29b-41d4-a716-446655440003",
      "requestNumber": "REQ-2026-001",
      "customerId": "550e8400-e29b-41d4-a716-446655440004",
      "vehicleId": "550e8400-e29b-41d4-a716-446655440005",
      "serviceScheduleType": "OnDemand",
      "locationPreference": "CustomerLocation",
      "requestStatus": "Completed",
      "requestedAt": "2026-01-13T10:30:00Z",
      "scheduledAt": null,
      "latitude": 40.7128,
      "longitude": -74.0060,
      "location": "123 Main St, New York, NY",
      "description": "Full vehicle service",
      "estimatedPrice": 199.98,
      "paymentStatus": "Paid",
      "paymentMethod": "Credit Card",
      "rating": 5,
      "feedback": "Great service!",
      "customer": {
        "userId": "550e8400-e29b-41d4-a716-446655440006",
        "customerId": "550e8400-e29b-41d4-a716-446655440004",
        "customerCode": "CUST-001",
        "email": "customer@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+1234567890",
        "gender": "Male"
      },
      "vehicle": {
        "vin": "WBADT43452G915187",
        "make": "BMW",
        "model": "3 Series",
        "year": 2022,
        "trim": "M Sport",
        "vehicleType": "Passenger Car",
        "bodyType": "Sedan"
      },
      "van": {
        "vanId": "550e8400-e29b-41d4-a716-446655440008",
        "registrationNumber": "VAN-2022-001",
        "vinNumber": "WV2ZZZ3CZ8E123456",
        "make": "Mercedes",
        "model": "Sprinter"
      },
      "technician": {
        "technicianId": "550e8400-e29b-41d4-a716-446655440007",
        "technicianCode": "TECH-001",
        "firstName": "Mike",
        "lastName": "Smith",
        "email": "mike@example.com",
        "phoneNumber": "+1987654321"
      },
      "services": [
        {
          "serviceId": "550e8400-e29b-41d4-a716-446655440001",
          "serviceName": "Oil Change",
          "serviceCode": "OIL-001",
          "serviceDescription": "Premium oil change",
          "servicePrice": 49.99,
          "serviceStatus": "Completed",
          "reasonOfRejection": null
        },
        {
          "serviceId": "550e8400-e29b-41d4-a716-446655440002",
          "serviceName": "Air Filter Replacement",
          "serviceCode": "FILTER-001",
          "serviceDescription": "Air filter replacement",
          "servicePrice": 29.99,
          "serviceStatus": "Completed",
          "reasonOfRejection": null
        }
      ]
    }
  ],
  "totalNumber": 5,
  "hasPreviousPage": false,
  "hasNextPage": true,
  "totalPages": 2,
  "pageNumber": 1,
  "rowsPerPage": 10
}

Response (No Content - 204):

---

11. Get Technician Suggestions

Endpoint: GET /technician-suggestions

Request Parameters:

{
  "searchKeyword": "Mike",
  "status": "Active",
  "hasVanAssigned": true
}

Response (Success - 200):

[
  {
    "technicianId": "550e8400-e29b-41d4-a716-446655440007",
    "technicianCode": "TECH-001",
    "firstName": "Mike",
    "lastName": "Smith",
    "email": "mike@example.com",
    "phoneNumber": "+1987654321"
  },
  {
    "technicianId": "550e8400-e29b-41d4-a716-446655440009",
    "technicianCode": "TECH-002",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "email": "sarah@example.com",
    "phoneNumber": "+1987654322"
  },
  {
    "technicianId": "550e8400-e29b-41d4-a716-446655440011",
    "technicianCode": "TECH-003",
    "firstName": "John",
    "lastName": "Williams",
    "email": "john@example.com",
    "phoneNumber": "+1987654323"
  }
]

Response (No Content - 204):

Response (Server Error - 500):

{
  "status": 500,
  "message": "An error occurred while fetching technician suggestions"
}

---

Development Tasks & Estimates

(Break down the development process into smaller tasks and provide time estimates for each.)

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Define Workflow	X hours	Dependency 1	Any notes here
2	Task 2 Description	X hours	Dependency 2	Any notes here
3	Task 3 Description	X hours	Dependency 3	Any notes here
4	Total	X hours	Dependency 3	Any notes here

---

Testing & Quality Assurance

(Outline the testing strategy and quality assurance measures for the feature.)

• Unit Tests:
  (List the unit tests that will be written for this feature.)

• Integration Tests:
  (Describe how integration testing will be conducted.)

• Acceptance Criteria:
  (Define the criteria that must be met for the feature to be considered complete.)

• Testing Tools:
  (List any tools that will be used for testing.)

---

Deployment Considerations

(Describe any deployment considerations, including environment configurations, feature toggles, or migration steps.)

• Configuration Changes:
  (Detail any configuration changes required for this feature.)

• Rollout Plan:
  (Outline the plan for rolling out the feature, including any phased releases.)

---

Risks & Mitigations

(Identify potential risks and the strategies to mitigate them.)

Risk	Impact	Likelihood	Mitigation Strategy
Risk 1	High	Medium	Strategy for mitigating Risk 1
Risk 2	Medium	High	Strategy for mitigating Risk 2
...	...	...	...

---

Review & Approval

(Include a section for review and approval by stakeholders.)

• Reviewer:
  (Name and role of the person reviewing the document.)

• Approval Date:
  (Date when the feature is approved for development.)

---

Notes
(Add any additional notes or considerations related to the feature development here.)