Technician Action Revert Flow

Author(s)

• [Amarnath Garai]

Last Updated Date

[2026-07-17]

---

SRS References

---

Version History

Version	Date	Changes	Author
1.0	2026-07-16	Initial draft	Amarnath Garai
1.1	2026-07-17	Added isreverted flag details	Amarnath Garai

---

Feature Overview

Objective:
The goal of this feature is to allow technicians to flexibly undo or revert their actions prior to beginning the actual service. The technician will be able to revert to any previous valid status (e.g., from Reached Location directly back to Assigned, skipping EnRoute if necessary).

Scope:
When an action is reverted, the system must restore the appropriate state in the database, clear related timestamps, log the action in a dedicated history table, synchronize all clients via SignalR, and send notifications to the customer and all admins.

Dependencies:

• Service request database tables and migration flow
• Technician master availability updates
• Service request DAL and service layers
• SignalR real-time sync
• Customer and admin notifications
• Route cache invalidation

---

Requirements

1. The technician must be able to revert to any previous valid status before the service starts.
2. The system must support reverting from Reached Location directly back to Assigned, skipping EnRoute if necessary.
3. The system must restore the appropriate database state when an action is reverted.
4. The system must clear related timestamps when reverting state.
5. The system must log every revert action in a dedicated history table.
6. The system must synchronize all clients via SignalR after a revert.
7. The system must send notifications to the customer and all admins after a revert.

[!WARNING] Mobile App State Machine: Since technicians can now skip statuses backwards (e.g., jumping from Reached directly back to Assigned), the mobile apps (Customer and Technician) must handle non-sequential backward transitions safely when receiving the technician_action_reverted SignalR event.

[!IMPORTANT] Metrics and Analytics: Reverting states clears timestamps (e.g., ReachedAt set to null). Ensure your analytics and SLA queries gracefully handle null values or utilize the new servicerequestreverthistory table to account for reverted actions.

---

Design Specifications

• UI/UX Design:
  The mobile apps (Customer and Technician) must handle non-sequential backward transitions safely when receiving the technician_action_reverted SignalR event.

• Data Models:

  [MODIFY] Table: servicerequests
  Add a new boolean column isreverted with default value false to quickly identify if a request has ever been reverted, avoiding complex history table queries for simple status checks.

  [NEW] Table: servicerequestreverthistory
  Create a new migration and table to keep a robust audit trail of all revert actions.

  • Columns:
    • id (UUID PK)
    • requestid (UUID FK to servicerequests)
    • technicianid (UUID FK to technicianmaster)
    • previousstatus (String)
    • newstatus (String)
    • reason (String)
    • createdat (Timestamp)

  [NEW] VanTrackerService/Models/ServiceRequest/RevertActionRequest.cs
  Add a new DTO RevertActionRequest containing:

  • TargetStatus (Enum: RequestStatus - must be Assigned or EnRoute)
  • Reason (string, required)

  [NEW] VanTrackerService/Models/ServiceRequest/RevertHistoryDto.cs
  Add a DTO to expose revert history to clients:

  • PreviousStatus, NewStatus, Reason, CreatedAt

  [MODIFY] VanTrackerService/Models/ServiceRequest/ServiceRequest.cs

  • Add bool IsReverted { get; set; } to the ServiceRequest entity.
  • Add bool IsReverted and List<RevertHistoryDto> RevertHistory to ServiceRequestDetailedResponse.

• API Interfaces:

  Endpoint	Method	Parameters	Response	Response Status Codes
  /service-request/{requestId:guid}/revert-action	PUT	requestId (required, guid) TargetStatus (required, RequestStatus) Reason (required, string)	String (Message)	Service response status

• API Examples:

  {
    "targetStatus": "Assigned",
    "reason": "Technician selected reached location by mistake"
  }

• Third-Party Integrations:

  • SignalR real-time sync
  • Push notifications
  • Email notifications

• Workflow:

  Data Access Layer (DAL)

  [MODIFY] VanTrackerService/DAL/ServiceRequest/IServiceRequestDal.cs
  Add method signature:

  Task<(int Status, string? Message)> RevertTechnicianActionDal(Guid requestId, Guid technicianId, RequestStatus currentStatus, RequestStatus targetStatus, string reason);

  [MODIFY] VanTrackerService/DAL/ServiceRequest/ServiceRequestDal.cs
  Implement RevertTechnicianActionDal utilizing a transaction scope:

  • Update servicerequests: change status to targetStatus and set isreverted = true.
  • Reset Flags:
    • If targetStatus is Assigned: Set isreached = false, reachedat = null. (Assumed journey not started, but you may optionally clear startedjourneyat if it exists).
    • If targetStatus is EnRoute: Set isreached = false, reachedat = null.
  • Insert History: Add a record into servicerequestreverthistory with the Reason.
  • Update technicianmaster:
    • If targetStatus == Assigned: Change technician availability to Available.
    • If targetStatus == EnRoute: Change technician availability to EnRoute.

  Service Layer

  [MODIFY] VanTrackerService/Services/ServiceRequest/IServiceRequestService.cs
  Add method signature:

  Task<(int Status, string? Message)> RevertTechnicianAction(Guid requestId, Guid userId, RevertActionRequest request);

  [MODIFY] VanTrackerService/Services/ServiceRequest/ServiceRequestService.cs
  Implement RevertTechnicianAction:

  1. Validate that the user is a technician and is assigned to the requestId.
  2. Fetch the current request state. Ensure RequestStatus is NOT InProgress, Completed, or Canceled.
  3. Validate targetStatus. Ensure it's a valid backward step (e.g. from Reached (status EnRoute + isreached) to Assigned, or from EnRoute to Assigned).
  4. Call DAL method RevertTechnicianActionDal to update DB and save reason.
  5. Call _realTimeService.BroadcastActionRevertedAsync (SignalR) to sync client apps with the new status and reason.
  6. Call _notificationManager to send Push Notifications and Emails to the Customer and Admins, passing the reason.
  7. Invalidate route cache using _routeCacheService.InvalidateRouteAsync(requestId).

  Hubs & Real-Time Sync

  [MODIFY] VanTrackerService/Hubs/RealTimeHub.cs & IRealTimeService
  Add BroadcastActionRevertedAsync(Guid requestId, RequestStatus targetStatus, string reason). This pushes a technician_action_reverted event to the Request-{RequestId} group and Admin groups.

  API Layer

  [MODIFY] VanTrackerService/Controllers/ServiceManagementController.cs

  • Add a new endpoint [HttpPut("service-request/{requestId:guid}/revert-action")].
  • Require Right.technician_user scope.
  • Accept the RevertActionRequest (containing TargetStatus and Reason) from the body and pass it to the service layer.

---

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Create isreverted column and servicerequestreverthistory migration/table	TBD	Service request and technician tables	Add quick revert indicator and robust audit trail
2	Add revert request and history DTOs	TBD	RequestStatus enum	Add IsReverted and RevertHistory to ServiceRequestDetailedResponse
3	Add DAL interface and implementation	TBD	Database migration	Use transaction scope to update request, flags, history, and technician availability
4	Add service interface and implementation	TBD	DAL implementation	Validate technician assignment, current request state, target status, notifications, SignalR, and route cache
5	Add SignalR broadcast method	TBD	Real-time service	Push technician_action_reverted event to request and admin groups
6	Add API endpoint	TBD	Service implementation	Require Right.technician_user scope
7	Add automated tests	TBD	Service implementation	Validate blocked and invalid revert cases
8	Manual verification	TBD	API endpoint and client sync	Verify technician flow, data integrity, audit trail, real-time sync, and notifications
9	Total	TBD	All tasks	Final estimate to be added

---

Verification Plan

Automated Tests

• Write unit tests for ServiceRequestService.RevertTechnicianAction to ensure validation blocks reverting a request that has already started (InProgress) and that invalid target statuses are rejected.

Manual Verification

1. Technician Flow: Log in as a technician, accept a job, start journey, and reach location.
2. Revert Execution: Use the new API to revert directly back to "Assigned" with a reason.
3. Data Integrity: Verify the database servicerequests status goes back to Assigned, isreverted becomes true, isreached becomes false, reachedat becomes null, and technician availability goes back to Available.
4. Audit Trail: Verify a new row is in the servicerequestreverthistory table with the reason.
5. Real-time Sync: Ensure the customer app/dashboard receives the SignalR event and updates the UI backwards.
6. Notifications: Verify that both the Customer and Admins receive an email and push notification containing the revert reason.