Add onStateUpdate callback for real-time order state monitoring

src/controller/master-controller.ts

@@ -185,6 +185,28 @@ export interface OrderEventHandler {
      * @param context context information of the order event
      */
     onActionStateChanged?(actionState: ActionState, withError: Error, action: Action, target: Node | Edge, context: OrderContext): void;
+
+    /**
+     * Invoked whenever a new state update is received from the AGV for the current order.
+     * 
+     * @remarks
+     * This callback is triggered each time the AGV sends a state update related to the
+     * current order. It provides real-time feedback on the order's execution, including
+     * the AGV's current position, status, and any changes in the order's progress.
+     * 
+     * The frequency of this callback invocation depends on how often the AGV sends
+     * state updates, which can vary based on the AGV's configuration and the complexity
+     * of the current task.
+     * 
+     * This callback is useful for applications that need to monitor the order's progress
+     * in real-time, update user interfaces, or make dynamic decisions based on the
+     * AGV's current state.
+     * 
+     * @param context The current OrderContext, providing the latest state
+     * information directly from the AGV, including the original order details
+     * and the AGV's current state.
+     */
+    onStateUpdate?(context: OrderContext): void;
 }
 
 /**
@@ -701,6 +723,10 @@ export class MasterController extends MasterControlClient {
             cache.isOrderProcessedHandlerInvoked = true;
             cache.eventHandler.onOrderProcessed(undefined, byCancelation, isActive, { order: cache.order, agvId: cache.agvId, state });
             return;
+        } else {
+            if (cache.eventHandler.onStateUpdate) {
+                cache.eventHandler.onStateUpdate({ order: cache.order, agvId: cache.agvId, state });
+            }
         }
     }