zengzy / hhrcs_service · Files

using System;
using System.Collections.Concurrent;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using System.Threading.Channels;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using Rcs.Application.Services;
using Rcs.Application.Services.PathFind;
using Rcs.Application.Services.PathFind.Models;
using Rcs.Application.Services.PathFind.Realtime;
using Rcs.Domain.Entities;
using Rcs.Domain.Enums;
using Rcs.Domain.Settings;
using StackExchange.Redis;

namespace Rcs.Infrastructure.PathFinding.Realtime;

/// <summary>
/// 全局导航实时协调器，基于状态事件和冲突事件在发送前给出路径调整决策。
/// </summary>
public sealed class GlobalNavigationCoordinator : BackgroundService, IGlobalNavigationCoordinator
{
    /// <summary>
    /// 路口队列相关 Redis Key 前缀。
    /// </summary>
    private const string QueueKeyPrefix = "rcs:route:queue";

    /// <summary>
    /// 正常发送模式编码。
    /// </summary>
    private const string ModeNormal = RouteModeCodes.Normal;

    /// <summary>
    /// 等待模式编码。
    /// </summary>
    private const string ModeHold = RouteModeCodes.HoldingAtWaitNode;

    /// <summary>
    /// 排队模式编码。
    /// </summary>
    private const string ModeQueue = RouteModeCodes.QueueingForJunction;

    /// <summary>
    /// 占用路口模式编码。
    /// </summary>
    private const string ModeOccupying = RouteModeCodes.OccupyingJunction;

    /// <summary>
    /// 绕行模式编码。
    /// </summary>
    private const string ModeDetouring = RouteModeCodes.Detouring;

    /// <summary>
    /// 重规划待执行模式编码。
    /// </summary>
    private const string ModeReplanPending = RouteModeCodes.ReplanPending;

    /// <summary>
    /// 阻塞保护模式编码。
    /// </summary>
    private const string ModeBlocked = RouteModeCodes.Blocked;

    /// <summary>
    /// 继续发送策略编码。
    /// </summary>
    private const string StrategyContinue = "Continue";

    /// <summary>
    /// 头段裁剪对齐策略编码。
    /// </summary>
    private const string StrategyTrim = "TrimProgressAlign";

    /// <summary>
    /// 就近等待策略编码。
    /// </summary>
    private const string StrategyWait = "WaitNearest";

    /// <summary>
    /// 路口排队占位策略编码。
    /// </summary>
    private const string StrategyQueue = "JunctionOccupy";

    /// <summary>
    /// 局部绕行策略编码。
    /// </summary>
    private const string StrategyDetour = "LocalDetour";

    /// <summary>
    /// 侧向让行策略编码。
    /// </summary>
    private const string StrategyLateral = "LateralYield";

    /// <summary>
    /// 泊车让行策略编码。
    /// </summary>
    private const string StrategyParking = "ParkingYield";

    /// <summary>
    /// 退让策略编码。
    /// </summary>
    private const string StrategyRetreat = "Retreat";

    /// <summary>
    /// 尾段重规划策略编码。
    /// </summary>
    private const string StrategyReplan = "ReplanTail";

    /// <summary>
    /// 阻塞保护策略编码。
    /// </summary>
    private const string StrategyBlocked = "Blocked";

    /// <summary>
    /// 运行日志。
    /// </summary>
    private readonly ILogger<GlobalNavigationCoordinator> _logger;

    /// <summary>
    /// 路口与资源占用控制服务。
    /// </summary>
    private readonly IUnifiedTrafficControlService _trafficControl;

    /// <summary>
    /// 路径服务。
    /// </summary>
    private readonly IAgvPathService _agvPathService;

    /// <summary>
    /// 避让策略选择器。
    /// </summary>
    private readonly IAvoidanceStrategySelector _strategySelector;

    /// <summary>
    /// Redis 连接。
    /// </summary>
    private readonly IConnectionMultiplexer _redis;

    /// <summary>
    /// 配置变更订阅句柄。
    /// </summary>
    private readonly IDisposable? _settingsChangeSubscription;

    /// <summary>
    /// 协调器配置快照。
    /// </summary>
    private GlobalCoordinatorSettings _coordinatorSettings = new();

    /// <summary>
    /// 机器人状态事件通道。
    /// </summary>
    private readonly Channel<RobotStateNavigationEvent> _stateEvents;

    /// <summary>
    /// 机器人运行态快照。
    /// </summary>
    private readonly ConcurrentDictionary<Guid, RobotNavSnapshot> _robotSnapshots = new();

    /// <summary>
    /// 锁冲突快照。
    /// </summary>
    private readonly ConcurrentDictionary<Guid, LockConflictSnapshot> _lockConflictSnapshots = new();

    /// <summary>
    /// 策略命中次数统计。
    /// </summary>
    private readonly ConcurrentDictionary<string, long> _decisionStrategyCounts = new(StringComparer.Ordinal);

    /// <summary>
    /// 继续决策计数。
    /// </summary>
    private long _decisionContinueCount;

    /// <summary>
    /// 等待决策计数。
    /// </summary>
    private long _decisionHoldCount;

    /// <summary>
    /// 补丁决策计数。
    /// </summary>
    private long _decisionPatchCount;

    /// <summary>
    /// 最近一次指标日志时间。
    /// </summary>
    private DateTime _lastDecisionMetricsLogUtc = DateTime.Now;

    /// <summary>
    /// 指标日志间隔。
    /// </summary>
    private TimeSpan _decisionMetricsLogInterval = TimeSpan.FromSeconds(60);

    public GlobalNavigationCoordinator(
        ILogger<GlobalNavigationCoordinator> logger,
        IUnifiedTrafficControlService trafficControl,
        IAgvPathService agvPathService,
        IAvoidanceStrategySelector strategySelector,
        IConnectionMultiplexer redis,
        IOptionsMonitor<AppSettings> settings)
    {
        _logger = logger;
        _trafficControl = trafficControl;
        _agvPathService = agvPathService;
        _strategySelector = strategySelector;
        _redis = redis;
        ApplyCoordinatorSettings(settings.CurrentValue);
        _settingsChangeSubscription = settings.OnChange(ApplyCoordinatorSettings);
        _stateEvents = Channel.CreateUnbounded<RobotStateNavigationEvent>(new UnboundedChannelOptions
        {
            SingleReader = true,
            SingleWriter = false
        });
    }

    /// <summary>
    /// 将机器人实时状态写入内部通道，采用事件解耦原则降低发送链路与决策链路耦合度。
    /// </summary>
    public Task PublishStateEventAsync(RobotStateNavigationEvent evt, CancellationToken ct = default)
    {
        if (!_stateEvents.Writer.TryWrite(evt))
        {
            _logger.LogDebug("[全局导航] 丢弃状态事件: RobotId={RobotId}", evt.RobotId);
        }

        return Task.CompletedTask;
    }

    /// <summary>
    /// 接收并聚合锁冲突事件，通过时间连续性累计冲突强度，为策略升级提供事实依据。
    /// </summary>
    public Task PublishLockConflictEventAsync(LockConflictNavigationEvent evt, CancellationToken ct = default)
    {
        if (evt.RobotId == Guid.Empty)
        {
            return Task.CompletedTask;
        }

        var occurredAtUtc = evt.OccurredAtUtc == default ? DateTime.Now : evt.OccurredAtUtc;
        _lockConflictSnapshots.AddOrUpdate(
            evt.RobotId,
            _ => new LockConflictSnapshot
            {
                MapCode = evt.MapCode,
                LastNodeCode = evt.NodeCode,
                LastEdgeCode = evt.EdgeCode,
                LastFailureReason = evt.FailureReason,
                LastOccurredAtUtc = occurredAtUtc,
                ReverseConflictStreak = evt.HasReverseConflict ? 1 : 0,
                TotalConflictStreak = 1
            },
            (_, old) =>
            {
                var contiguous = occurredAtUtc - old.LastOccurredAtUtc <= TimeSpan.FromSeconds(10);
                return new LockConflictSnapshot
                {
                    MapCode = string.IsNullOrWhiteSpace(evt.MapCode) ? old.MapCode : evt.MapCode,
                    LastNodeCode = evt.NodeCode,
                    LastEdgeCode = evt.EdgeCode,
                    LastFailureReason = evt.FailureReason,
                    LastOccurredAtUtc = occurredAtUtc,
                    ReverseConflictStreak = evt.HasReverseConflict
                        ? (contiguous ? old.ReverseConflictStreak + 1 : 1)
                        : 0,
                    TotalConflictStreak = contiguous ? old.TotalConflictStreak + 1 : 1
                };
            });

        return Task.CompletedTask;
    }

    /// <summary>
    /// 应用热更新配置并刷新阈值参数，保证策略可在线调参与即时生效。
    /// </summary>
    private void ApplyCoordinatorSettings(AppSettings appSettings)
    {
        var next = appSettings.GlobalNavigation?.Coordinator ?? new GlobalCoordinatorSettings();
        _coordinatorSettings = next;
        _decisionMetricsLogInterval = TimeSpan.FromSeconds(Math.Max(10, next.DecisionMetricsIntervalSeconds));

        _logger.LogInformation(
            "[全局导航] 配置已更新: 恢复稳定阈值={ResumeStable}, 短等待秒数={HoldShort}, 排队等待秒数={HoldQueue}, 排队过期秒数={QueueStale}, 升级-等待阈值={EscalateWait}, 升级-绕行阈值={EscalateDetour}, 升级-侧向避让阈值={EscalateLateral}, 升级-泊车避让阈值={EscalateParking}, 升级-后退阈值={EscalateRetreat}, 升级-重规划阈值={EscalateReplan}, 升级-阻塞阈值={EscalateBlocked}, 阻塞等待秒数={BlockedHold}, 启用侧向避让={EnableLateral}, 启用泊车避让={EnableParking}, 启用后退={EnableRetreat}",
            next.ResumeStablePassThreshold,
            next.HoldSecondsShort,
            next.HoldSecondsQueue,
            next.QueueStaleSeconds,
            next.ConflictEscalateNearestWaitThreshold,
            next.ConflictEscalateDetourThreshold,
            next.ConflictEscalateLateralYieldThreshold,
            next.ConflictEscalateParkingThreshold,
            next.ConflictEscalateRetreatThreshold,
            next.ConflictEscalateReplanThreshold,
            next.ConflictEscalateBlockedThreshold,
            next.BlockedHoldSeconds,
            next.EnableLateralYield,
            next.EnableParkingYield,
            next.EnableRetreat);
    }

    /// <summary>
    /// 发送前主决策入口，基于状态机与冲突探测结果在继续、等待、补丁与重规划间做选择。
    /// </summary>
    public async Task<RouteAdjustmentDecision> TryAdjustBeforeSendAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        string? lastNodeCode,
        bool isDriving,
        CancellationToken ct = default)
    {
        if (cache.CurrentJunctionIndex >= cache.JunctionSegments.Count)
        {
            return Continue("all segments sent");
        }

        var (lastNode, driving) = ResolveRuntime(robotId, lastNodeCode, isDriving);
        var first = GetFirstUnsentSegment(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex);
        if (first == null)
        {
            return Continue("unsent empty");
        }

        if (!string.Equals(cache.RouteMode, ModeQueue, StringComparison.Ordinal) &&
            !string.Equals(cache.RouteMode, ModeOccupying, StringComparison.Ordinal) &&
            !string.IsNullOrWhiteSpace(cache.HoldNodeCode))
        {
            await ReleaseQueueTicketAsync(robotId, cache.MapCode, cache.HoldNodeCode);
        }

        if (string.Equals(cache.RouteMode, ModeHold, StringComparison.Ordinal))
        {
            return await HandleHoldAsync(robotId, cache, first, lastNode, driving, ct);
        }

        if (string.Equals(cache.RouteMode, ModeQueue, StringComparison.Ordinal))
        {
            return await HandleQueueAsync(robotId, cache, first, lastNode, driving, ct);
        }

        if (string.Equals(cache.RouteMode, ModeOccupying, StringComparison.Ordinal))
        {
            return await HandleOccupyingAsync(robotId, cache, first, lastNode, driving, ct);
        }

        if (string.Equals(cache.RouteMode, ModeReplanPending, StringComparison.Ordinal))
        {
            return await HandleReplanPendingAsync(robotId, cache, first, lastNode, driving, ct);
        }

        if (string.Equals(cache.RouteMode, ModeBlocked, StringComparison.Ordinal))
        {
            return await HandleBlockedAsync(robotId, cache, first, lastNode, driving, ct);
        }

        var trim = TryBuildTrimHeadPatch(cache, lastNode);
        if (trim != null)
        {
            cache.LastDecisionCode = StrategyTrim;
            return Patch(trim, "trim stale head");
        }

        var conflict = await ProbeConflictAsync(robotId, cache.MapCode, first);
        if (!conflict.HasConflict)
        {
            cache.RouteMode = ModeNormal;
            cache.StablePassCount = Math.Max(cache.StablePassCount + 1, 1);
            cache.ConsecutiveConflictFailCount = 0;
            cache.BlockedReason = null;
            _lockConflictSnapshots.TryRemove(robotId, out _);
            return Continue("normal");
        }

        if (conflict.HasReverseConflict)
        {
            var (queuePos, queueSize) = await EnsureQueueTicketAsync(robotId, cache.MapCode, first.FromNodeCode, ct);
            if (queuePos <= 0)
            {
                return Hold(
                    cache,
                    StrategyQueue,
                    Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                    first.FromNodeCode,
                    $"occupy granted and waiting release (1/{queueSize})",
                    ModeOccupying);
            }

            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                first.FromNodeCode,
                $"reverse conflict queueing ({queuePos + 1}/{queueSize})");
        }

        return Hold(cache, StrategyWait, Math.Max(1, _coordinatorSettings.HoldSecondsShort), first.FromNodeCode, "occupied, wait nearest");
    }

    /// <summary>
    /// 处理等待态流程，依据等待窗口、节点一致性与冲突连续性决定续等或升级。
    /// </summary>
    private async Task<RouteAdjustmentDecision> HandleHoldAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        string? lastNode,
        bool driving,
        CancellationToken ct)
    {
        var waitNode = cache.HoldNodeCode ?? first.FromNodeCode;
        var atWaitNode = string.Equals(waitNode, lastNode, StringComparison.OrdinalIgnoreCase);
        if (!atWaitNode || driving)
        {
            return Hold(cache, StrategyWait, Math.Max(1, _coordinatorSettings.HoldSecondsShort), waitNode, "waiting robot stop at wait node");
        }

        var conflict = await ProbeConflictAsync(robotId, cache.MapCode, first);
        if (!conflict.HasConflict)
        {
            cache.StablePassCount = Math.Max(cache.StablePassCount, 0) + 1;
            cache.ConsecutiveConflictFailCount = 0;
            cache.BlockedReason = null;
            if (cache.StablePassCount < Math.Max(1, _coordinatorSettings.ResumeStablePassThreshold))
            {
                return Hold(cache, StrategyWait, 1, waitNode, "precheck pass not stable");
            }

            var trim = TryBuildTrimHeadPatch(cache, lastNode);
            return trim != null ? Patch(trim, "resume and trim") : Continue("resume from wait");
        }

        cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
        var failStreak = Math.Abs(Math.Min(cache.StablePassCount, 0));

        if (cache.IsWaitingForNetAction)
        {
            return Hold(
                cache,
                StrategyWait,
                Math.Max(1, _coordinatorSettings.HoldSecondsShort),
                waitNode,
                "net action pending, tail mutation disabled");
        }

        cache.ConsecutiveConflictFailCount = Math.Max(0, cache.ConsecutiveConflictFailCount) + 1;
        var hasRecentReverseLockConflict = HasRecentReverseConflictSignal(robotId, cache.MapCode);
        var selectionContext = new AvoidanceSelectionContext
        {
            FailStreak = failStreak,
            HasReverseConflict = conflict.HasReverseConflict || hasRecentReverseLockConflict,
            EscalateWaitThreshold = _coordinatorSettings.ConflictEscalateNearestWaitThreshold,
            EscalateDetourThreshold = _coordinatorSettings.ConflictEscalateDetourThreshold,
            EscalateLateralYieldThreshold = _coordinatorSettings.ConflictEscalateLateralYieldThreshold,
            EscalateParkingThreshold = _coordinatorSettings.ConflictEscalateParkingThreshold,
            EscalateRetreatThreshold = _coordinatorSettings.ConflictEscalateRetreatThreshold,
            EscalateReplanThreshold = _coordinatorSettings.ConflictEscalateReplanThreshold,
            EnableLateralYield = _coordinatorSettings.EnableLateralYield,
            EnableParkingYield = _coordinatorSettings.EnableParkingYield,
            EnableRetreat = _coordinatorSettings.EnableRetreat
        };

        var candidates = _strategySelector.SelectHoldCandidates(selectionContext);
        if (candidates.Count > 0)
        {
            _logger.LogDebug(
                "[全局导航] 等待升级候选策略: RobotId={RobotId}, FailStreak={FailStreak}, ReverseConflict={ReverseConflict}, Candidates={Candidates}",
                robotId,
                failStreak,
                conflict.HasReverseConflict || hasRecentReverseLockConflict,
                string.Join(",", candidates));
        }

        foreach (var strategy in candidates)
        {
            var decision = await TryBuildEscalationDecisionAsync(
                robotId, cache, first, conflict, lastNode, strategy);
            if (decision != null)
            {
                cache.ConsecutiveConflictFailCount = 0;
                return decision;
            }
        }

        if (cache.ConsecutiveConflictFailCount >= Math.Max(1, _coordinatorSettings.ConflictEscalateBlockedThreshold))
        {
            cache.RouteMode = ModeBlocked;
            cache.BlockedReason = "conflict escalated to blocked protection mode";
            cache.LastDecisionCode = StrategyBlocked;
            var blockedHold = Math.Max(1, _coordinatorSettings.BlockedHoldSeconds);
            return Hold(
                cache,
                StrategyBlocked,
                blockedHold,
                waitNode,
                $"blocked by persistent conflict ({cache.ConsecutiveConflictFailCount})",
                ModeBlocked);
        }

        if (conflict.HasReverseConflict)
        {
            var (queuePos, queueSize) = await EnsureQueueTicketAsync(robotId, cache.MapCode, waitNode, ct);
            if (queuePos <= 0)
            {
                return Hold(
                    cache,
                    StrategyQueue,
                    Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                    waitNode,
                    $"occupy granted from hold mode (1/{queueSize})",
                    ModeOccupying);
            }

            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"reverse conflict queueing ({queuePos + 1}/{queueSize})");
        }

        return Hold(cache, StrategyWait, Math.Max(1, _coordinatorSettings.HoldSecondsShort), waitNode, "holding for conflict clear");
    }

    /// <summary>
    /// 处理排队态流程，结合队列位置与占用状态决定继续排队或转入占位执行。
    /// </summary>
    private async Task<RouteAdjustmentDecision> HandleQueueAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        string? lastNode,
        bool driving,
        CancellationToken ct)
    {
        var waitNode = cache.HoldNodeCode ?? first.FromNodeCode;
        var (queuePos, queueSize) = await EnsureQueueTicketAsync(robotId, cache.MapCode, waitNode, ct);

        if (!string.Equals(waitNode, lastNode, StringComparison.OrdinalIgnoreCase) || driving)
        {
            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"queueing and waiting position ({queuePos + 1}/{queueSize})");
        }

        if (queuePos > 0)
        {
            cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"queue turn pending ({queuePos + 1}/{queueSize})");
        }

        return await HandleOccupyingAsync(
            robotId,
            cache,
            first,
            lastNode,
            driving,
            ct,
            queuePos,
            queueSize);
    }

    /// <summary>
    /// 处理占位态流程，在已占位前提下等待冲突消退并评估恢复发送时机。
    /// </summary>
    private async Task<RouteAdjustmentDecision> HandleOccupyingAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        string? lastNode,
        bool driving,
        CancellationToken ct,
        int? knownQueuePos = null,
        int? knownQueueSize = null)
    {
        var waitNode = cache.HoldNodeCode ?? first.FromNodeCode;
        var queuePos = knownQueuePos ?? 0;
        var queueSize = knownQueueSize ?? 1;
        if (!knownQueuePos.HasValue || !knownQueueSize.HasValue)
        {
            (queuePos, queueSize) = await EnsureQueueTicketAsync(robotId, cache.MapCode, waitNode, ct);
        }

        if (queuePos > 0)
        {
            cache.RouteMode = ModeQueue;
            cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"occupy turn lost ({queuePos + 1}/{queueSize}), back to queue");
        }

        if (!string.Equals(waitNode, lastNode, StringComparison.OrdinalIgnoreCase) || driving)
        {
            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"occupying junction and waiting robot settle (1/{queueSize})",
                ModeOccupying);
        }

        var conflict = await ProbeConflictAsync(robotId, cache.MapCode, first);
        if (conflict.HasConflict)
        {
            cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
            cache.ConsecutiveConflictFailCount = Math.Max(0, cache.ConsecutiveConflictFailCount) + 1;

            if (cache.ConsecutiveConflictFailCount >= Math.Max(1, _coordinatorSettings.ConflictEscalateBlockedThreshold))
            {
                cache.RouteMode = ModeBlocked;
                cache.BlockedReason = "occupying mode conflict escalated to blocked protection mode";
                cache.LastDecisionCode = StrategyBlocked;
                return Hold(
                    cache,
                    StrategyBlocked,
                    Math.Max(1, _coordinatorSettings.BlockedHoldSeconds),
                    waitNode,
                    $"blocked in occupying mode ({cache.ConsecutiveConflictFailCount})",
                    ModeBlocked);
            }

            return Hold(
                cache,
                StrategyQueue,
                Math.Max(1, _coordinatorSettings.HoldSecondsQueue),
                waitNode,
                $"occupying and waiting junction release (1/{queueSize})",
                ModeOccupying);
        }

        cache.StablePassCount = Math.Max(cache.StablePassCount, 0) + 1;
        cache.ConsecutiveConflictFailCount = 0;
        cache.BlockedReason = null;
        if (cache.StablePassCount < Math.Max(1, _coordinatorSettings.ResumeStablePassThreshold))
        {
            return Hold(
                cache,
                StrategyQueue,
                1,
                waitNode,
                $"occupying precheck pass not stable (1/{queueSize})",
                ModeOccupying);
        }

        await ReleaseQueueTicketAsync(robotId, cache.MapCode, waitNode);
        var trim = TryBuildTrimHeadPatch(cache, lastNode);
        return trim != null ? Patch(trim, "occupying released trim") : Continue("occupying released");
    }

    /// <summary>
    /// 处理阻塞保护态流程，通过受控等待与降频重试抑制冲突抖动扩散。
    /// </summary>
    private async Task<RouteAdjustmentDecision> HandleBlockedAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        string? lastNode,
        bool driving,
        CancellationToken ct)
    {
        var waitNode = cache.HoldNodeCode ?? first.FromNodeCode;
        var atWaitNode = string.Equals(waitNode, lastNode, StringComparison.OrdinalIgnoreCase);
        if (!atWaitNode || driving)
        {
            return Hold(
                cache,
                StrategyBlocked,
                Math.Max(1, _coordinatorSettings.BlockedHoldSeconds),
                waitNode,
                "blocked mode waiting for robot stop",
                ModeBlocked);
        }

        var conflict = await ProbeConflictAsync(robotId, cache.MapCode, first);
        if (conflict.HasConflict)
        {
            cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
            cache.ConsecutiveConflictFailCount = Math.Max(0, cache.ConsecutiveConflictFailCount) + 1;
            return Hold(
                cache,
                StrategyBlocked,
                Math.Max(1, _coordinatorSettings.BlockedHoldSeconds),
                waitNode,
                "blocked mode conflict not cleared",
                ModeBlocked);
        }

        cache.StablePassCount = Math.Max(cache.StablePassCount, 0) + 1;
        if (cache.StablePassCount < Math.Max(1, _coordinatorSettings.ResumeStablePassThreshold))
        {
            return Hold(cache, StrategyBlocked, 1, waitNode, "blocked precheck pass not stable", ModeBlocked);
        }

        cache.RouteMode = ModeNormal;
        cache.ConsecutiveConflictFailCount = 0;
        cache.BlockedReason = null;
        var trim = TryBuildTrimHeadPatch(cache, lastNode);
        return trim != null ? Patch(trim, "blocked recovered and trim") : Continue("blocked recovered");
    }

    /// <summary>
    /// 处理重规划待执行态，校验补丁可用性并在可发送与继续等待间切换。
    /// </summary>
    private async Task<RouteAdjustmentDecision> HandleReplanPendingAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        string? lastNode,
        bool driving,
        CancellationToken ct)
    {
        ct.ThrowIfCancellationRequested();
        var waitNode = cache.HoldNodeCode ?? first.FromNodeCode;
        var atWaitNode = string.Equals(waitNode, lastNode, StringComparison.OrdinalIgnoreCase);
        if (!atWaitNode || driving)
        {
            return Hold(
                cache,
                StrategyReplan,
                Math.Max(1, _coordinatorSettings.HoldSecondsShort),
                waitNode,
                "replan pending mode waiting for robot stop",
                ModeReplanPending);
        }

        if (cache.IsWaitingForNetAction)
        {
            return Hold(
                cache,
                StrategyReplan,
                Math.Max(1, _coordinatorSettings.HoldSecondsShort),
                waitNode,
                "replan pending but net action in progress",
                ModeReplanPending);
        }

        var conflict = await ProbeConflictAsync(robotId, cache.MapCode, first);
        var patch = await TryBuildReplanTailPatchAsync(cache, first, conflict, lastNode);
        if (patch != null)
        {
            cache.LastDecisionCode = StrategyReplan;
            return Replan(patch, "replan pending patch");
        }

        cache.StablePassCount = Math.Min(cache.StablePassCount, 0) - 1;
        cache.ConsecutiveConflictFailCount = Math.Max(0, cache.ConsecutiveConflictFailCount) + 1;
        if (cache.ConsecutiveConflictFailCount >= Math.Max(1, _coordinatorSettings.ConflictEscalateBlockedThreshold))
        {
            cache.RouteMode = ModeBlocked;
            cache.BlockedReason = "replan pending failed and escalated to blocked mode";
            cache.LastDecisionCode = StrategyBlocked;
            return Hold(
                cache,
                StrategyBlocked,
                Math.Max(1, _coordinatorSettings.BlockedHoldSeconds),
                waitNode,
                "replan pending failed, blocked",
                ModeBlocked);
        }

        return Hold(
            cache,
            StrategyReplan,
            Math.Max(1, _coordinatorSettings.HoldSecondsShort),
            waitNode,
            "replan pending no feasible patch, keep waiting",
            ModeReplanPending);
    }

    /// <summary>
    /// 按候选策略顺序尝试构建升级决策，遵循由低成本到高成本的逐级退让原则。
    /// </summary>
    private async Task<RouteAdjustmentDecision?> TryBuildEscalationDecisionAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode,
        string strategyCode)
    {
        switch (strategyCode)
        {
            case AvoidanceStrategyCodes.WaitNearest:
            {
                var patch = await TryBuildNearestWaitPatchAsync(robotId, cache, first, conflict);
                if (patch == null) return null;
                cache.RouteMode = ModeDetouring;
                cache.LastDecisionCode = StrategyWait;
                return Patch(patch, "nearest wait patch");
            }
            case AvoidanceStrategyCodes.LocalDetour:
            {
                var patch = await TryBuildLocalDetourPatchAsync(cache, first, conflict, lastNode);
                if (patch == null) return null;
                cache.RouteMode = ModeDetouring;
                cache.LastDecisionCode = StrategyDetour;
                return Patch(patch, "local detour patch");
            }
            case AvoidanceStrategyCodes.LateralYield:
            {
                var patch = await TryBuildLateralYieldPatchAsync(robotId, cache, first, conflict, lastNode);
                if (patch == null) return null;
                cache.RouteMode = ModeDetouring;
                cache.LastDecisionCode = StrategyLateral;
                return Patch(patch, "lateral yield patch");
            }
            case AvoidanceStrategyCodes.ParkingYield:
            {
                var patch = await TryBuildParkingYieldPatchAsync(robotId, cache, first, conflict, lastNode);
                if (patch == null) return null;
                cache.RouteMode = ModeDetouring;
                cache.LastDecisionCode = StrategyParking;
                return Patch(patch, "parking yield patch");
            }
            case AvoidanceStrategyCodes.Retreat:
            {
                var patch = await TryBuildRetreatPatchAsync(cache, first, conflict, lastNode);
                if (patch == null) return null;
                cache.RouteMode = ModeDetouring;
                cache.LastDecisionCode = StrategyRetreat;
                return Patch(patch, "retreat patch");
            }
            case AvoidanceStrategyCodes.ReplanTail:
            {
                var patch = await TryBuildReplanTailPatchAsync(cache, first, conflict, lastNode);
                if (patch == null) return null;
                cache.RouteMode = ModeReplanPending;
                cache.HoldNodeCode ??= first.FromNodeCode;
                cache.LastDecisionCode = StrategyReplan;
                return Replan(patch, "full tail replan patch");
            }
            default:
                return null;
        }
    }

    /// <summary>
    /// 探测首段节点/边占用与逆向冲突，形成后续决策所需的冲突画像。
    /// </summary>
    private async Task<ConflictProbe> ProbeConflictAsync(Guid robotId, string mapCode, PathSegmentWithCode first)
    {
        var nodeOccupied = !string.IsNullOrWhiteSpace(first.ToNodeCode) &&
                           await _trafficControl.IsNodeOccupiedByOtherAsync(mapCode, first.ToNodeCode, robotId);

        var edgeOccupied = false;
        var reverseConflict = false;
        if (!string.IsNullOrWhiteSpace(first.EdgeCode))
        {
            var holder = await _trafficControl.GetEdgeLockHolderAsync(mapCode, first.EdgeCode);
            edgeOccupied = holder.HasValue && holder.Value != robotId;
            reverseConflict = await _trafficControl.HasReverseConflictAsync(
                mapCode, first.EdgeCode, first.FromNodeCode, first.ToNodeCode, robotId);
        }

        return new ConflictProbe
        {
            HasConflict = nodeOccupied || edgeOccupied || reverseConflict,
            HasReverseConflict = reverseConflict,
            BlockingNodeCode = nodeOccupied ? first.ToNodeCode : null,
            BlockingEdgeCode = edgeOccupied || reverseConflict ? first.EdgeCode : null
        };
    }

    /// <summary>
    /// 构建就近等待补丁，以最小改动原则优先保持原有主路径。
    /// </summary>
    private async Task<TailPatch?> TryBuildNearestWaitPatchAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null)
        {
            return null;
        }

        var startNodeCode = first.FromNodeCode;
        var waitingNodes = graph.GetWaitingAreaNodes()
            .Select(id => graph.Nodes.TryGetValue(id, out var node) ? node : null)
            .Where(node => node != null)
            .Select(node => node!)
            .ToList();

        if (waitingNodes.Count == 0)
        {
            return null;
        }

        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var rejoinNodes = GetUnsentNodeCandidates(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex)
            .Skip(1)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Take(8)
            .ToList();

        foreach (var waitNode in waitingNodes)
        {
            if (await _trafficControl.IsNodeOccupiedByOtherAsync(cache.MapCode, waitNode.NodeCode, robotId))
            {
                continue;
            }

            var p1 = FindNodeCodePath(graph, startNodeCode, waitNode.NodeCode, forbiddenNodes, forbiddenEdges, 24);
            if (p1.Count == 0) continue;

            foreach (var rejoin in rejoinNodes)
            {
                var p2 = FindNodeCodePath(graph, waitNode.NodeCode, rejoin, forbiddenNodes, forbiddenEdges, 28);
                if (p2.Count == 0) continue;
                if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, rejoin, out var j, out var r, out var s))
                {
                    continue;
                }

                var merged = p1.Select(CloneSegment).Concat(p2.Select(CloneSegment)).ToList();
                RemoveDuplicateBoundary(merged);
                if (merged.Count == 0) continue;

                var suffix = BuildTailFromPosition(cache, j, r, s);
                var newTail = BuildTailWithPrefix(merged, suffix);
                if (newTail.Count == 0) continue;

                return new TailPatch
                {
                    ExpectedPlanVersion = cache.PlanVersion,
                    FromJunctionIndex = cache.CurrentJunctionIndex,
                    FromResourceIndex = cache.CurrentResourceIndex,
                    StrategyCode = StrategyWait,
                    Reason = $"nearest wait node {waitNode.NodeCode}",
                    WaitNodeCode = waitNode.NodeCode,
                    RejoinNodeCode = rejoin,
                    NewTail = newTail
                };
            }
        }

        return null;
    }

    /// <summary>
    /// 构建侧向让行补丁，通过短距离偏移临时释放关键冲突点。
    /// </summary>
    private async Task<TailPatch?> TryBuildLateralYieldPatchAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null)
        {
            return null;
        }

        var startNodeCode = string.IsNullOrWhiteSpace(lastNode) ? first.FromNodeCode : lastNode;
        var startNode = graph.Nodes.Values.FirstOrDefault(n =>
            string.Equals(n.NodeCode, startNodeCode, StringComparison.OrdinalIgnoreCase));
        if (startNode == null)
        {
            return null;
        }

        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var lateralCandidates = graph.Nodes.Values
            .Where(n => !string.Equals(n.NodeCode, startNodeCode, StringComparison.OrdinalIgnoreCase))
            .Where(n =>
                n.NodeCode.Contains("yield", StringComparison.OrdinalIgnoreCase) ||
                n.NodeCode.Contains("side", StringComparison.OrdinalIgnoreCase) ||
                n.NodeCode.Contains("lane", StringComparison.OrdinalIgnoreCase) ||
                n.NodeCode.Contains("bay", StringComparison.OrdinalIgnoreCase))
            .OrderBy(n => DistanceSquared(startNode, n))
            .Take(12)
            .ToList();

        if (lateralCandidates.Count == 0)
        {
            return null;
        }

        var rejoinNodes = GetUnsentNodeCandidates(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex)
            .Skip(2)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Take(8)
            .ToList();

        foreach (var lateralNode in lateralCandidates)
        {
            if (await _trafficControl.IsNodeOccupiedByOtherAsync(cache.MapCode, lateralNode.NodeCode, robotId))
            {
                continue;
            }

            var toLateral = FindNodeCodePath(graph, startNodeCode, lateralNode.NodeCode, forbiddenNodes, forbiddenEdges, 24);
            if (toLateral.Count == 0)
            {
                continue;
            }

            foreach (var rejoin in rejoinNodes)
            {
                var toRejoin = FindNodeCodePath(graph, lateralNode.NodeCode, rejoin, forbiddenNodes, forbiddenEdges, 32);
                if (toRejoin.Count == 0)
                {
                    continue;
                }

                if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, rejoin, out var j, out var r, out var s))
                {
                    continue;
                }

                var merged = toLateral.Select(CloneSegment).Concat(toRejoin.Select(CloneSegment)).ToList();
                RemoveDuplicateBoundary(merged);
                if (merged.Count == 0)
                {
                    continue;
                }

                var suffix = BuildTailFromPosition(cache, j, r, s);
                var newTail = BuildTailWithPrefix(merged, suffix);
                if (newTail.Count == 0)
                {
                    continue;
                }

                return new TailPatch
                {
                    ExpectedPlanVersion = cache.PlanVersion,
                    FromJunctionIndex = cache.CurrentJunctionIndex,
                    FromResourceIndex = cache.CurrentResourceIndex,
                    StrategyCode = StrategyLateral,
                    Reason = $"lateral yield via {lateralNode.NodeCode}",
                    WaitNodeCode = lateralNode.NodeCode,
                    RejoinNodeCode = rejoin,
                    NewTail = newTail
                };
            }
        }

        return null;
    }

    /// <summary>
    /// 构建局部绕行补丁，在限定范围内绕过冲突区域并尽快回归主线。
    /// </summary>
    private async Task<TailPatch?> TryBuildLocalDetourPatchAsync(
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null)
        {
            return null;
        }

        var startNodeCode = string.IsNullOrWhiteSpace(lastNode) ? first.FromNodeCode : lastNode;
        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var rejoinNodes = GetUnsentNodeCandidates(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex)
            .Skip(2)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Take(8)
            .ToList();

        foreach (var rejoin in rejoinNodes)
        {
            var detour = FindNodeCodePath(graph, startNodeCode, rejoin, forbiddenNodes, forbiddenEdges, 32);
            if (detour.Count == 0) continue;
            if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, rejoin, out var j, out var r, out var s))
            {
                continue;
            }

            var suffix = BuildTailFromPosition(cache, j, r, s);
            var newTail = BuildTailWithPrefix(detour, suffix);
            if (newTail.Count == 0) continue;

            return new TailPatch
            {
                ExpectedPlanVersion = cache.PlanVersion,
                FromJunctionIndex = cache.CurrentJunctionIndex,
                FromResourceIndex = cache.CurrentResourceIndex,
                StrategyCode = StrategyDetour,
                Reason = $"local detour to {rejoin}",
                RejoinNodeCode = rejoin,
                NewTail = newTail
            };
        }

        return null;
    }

    /// <summary>
    /// 构建泊车让行补丁，将机器人导入可停靠节点以降低主通道占用。
    /// </summary>
    private async Task<TailPatch?> TryBuildParkingYieldPatchAsync(
        Guid robotId,
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null)
        {
            return null;
        }

        var startNodeCode = string.IsNullOrWhiteSpace(lastNode) ? first.FromNodeCode : lastNode;
        var startNode = graph.Nodes.Values.FirstOrDefault(n =>
            string.Equals(n.NodeCode, startNodeCode, StringComparison.OrdinalIgnoreCase));
        if (startNode == null)
        {
            return null;
        }

        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var parkingCandidates = graph.Nodes.Values
            .Where(n => !string.Equals(n.NodeCode, startNodeCode, StringComparison.OrdinalIgnoreCase))
            .Where(n =>
                n.NodeCode.Contains("parking", StringComparison.OrdinalIgnoreCase) ||
                n.NodeCode.Contains("wait", StringComparison.OrdinalIgnoreCase))
            .OrderBy(n => DistanceSquared(startNode, n))
            .Take(10)
            .ToList();

        if (parkingCandidates.Count == 0)
        {
            return null;
        }

        var rejoinNodes = GetUnsentNodeCandidates(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex)
            .Skip(2)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Take(8)
            .ToList();

        foreach (var parkingNode in parkingCandidates)
        {
            if (await _trafficControl.IsNodeOccupiedByOtherAsync(cache.MapCode, parkingNode.NodeCode, robotId))
            {
                continue;
            }

            var toParking = FindNodeCodePath(graph, startNodeCode, parkingNode.NodeCode, forbiddenNodes, forbiddenEdges, 28);
            if (toParking.Count == 0)
            {
                continue;
            }

            foreach (var rejoin in rejoinNodes)
            {
                var toRejoin = FindNodeCodePath(graph, parkingNode.NodeCode, rejoin, forbiddenNodes, forbiddenEdges, 36);
                if (toRejoin.Count == 0)
                {
                    continue;
                }

                if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, rejoin, out var j, out var r, out var s))
                {
                    continue;
                }

                var merged = toParking.Select(CloneSegment).Concat(toRejoin.Select(CloneSegment)).ToList();
                RemoveDuplicateBoundary(merged);
                if (merged.Count == 0)
                {
                    continue;
                }

                var suffix = BuildTailFromPosition(cache, j, r, s);
                var newTail = BuildTailWithPrefix(merged, suffix);
                if (newTail.Count == 0)
                {
                    continue;
                }

                return new TailPatch
                {
                    ExpectedPlanVersion = cache.PlanVersion,
                    FromJunctionIndex = cache.CurrentJunctionIndex,
                    FromResourceIndex = cache.CurrentResourceIndex,
                    StrategyCode = StrategyParking,
                    Reason = $"parking yield via {parkingNode.NodeCode}",
                    WaitNodeCode = parkingNode.NodeCode,
                    RejoinNodeCode = rejoin,
                    NewTail = newTail
                };
            }
        }

        return null;
    }

    /// <summary>
    /// 构建退让补丁，通过反向回撤扩展会车空间并降低对向死锁概率。
    /// </summary>
    private async Task<TailPatch?> TryBuildRetreatPatchAsync(
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null)
        {
            return null;
        }

        var startNodeCode = string.IsNullOrWhiteSpace(lastNode) ? first.FromNodeCode : lastNode;
        var startNode = graph.Nodes.Values.FirstOrDefault(n =>
            string.Equals(n.NodeCode, startNodeCode, StringComparison.OrdinalIgnoreCase));
        if (startNode == null)
        {
            return null;
        }

        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var retreatCandidates = startNode.InEdges
            .Select(e => graph.Nodes.TryGetValue(e.FromNodeId, out var node) ? node : null)
            .Where(node => node != null)
            .Select(node => node!)
            .OrderBy(n => n.OutEdges.Count >= 3 ? 1 : 0)
            .ThenBy(n => DistanceSquared(startNode, n))
            .Take(8)
            .ToList();

        if (retreatCandidates.Count == 0)
        {
            return null;
        }

        var rejoinNodes = GetUnsentNodeCandidates(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex)
            .Skip(2)
            .Distinct(StringComparer.OrdinalIgnoreCase)
            .Take(8)
            .ToList();

        foreach (var retreatNode in retreatCandidates)
        {
            var toRetreat = FindNodeCodePath(graph, startNodeCode, retreatNode.NodeCode, forbiddenNodes, forbiddenEdges, 20);
            if (toRetreat.Count == 0)
            {
                continue;
            }

            foreach (var rejoin in rejoinNodes)
            {
                var toRejoin = FindNodeCodePath(graph, retreatNode.NodeCode, rejoin, forbiddenNodes, forbiddenEdges, 40);
                if (toRejoin.Count == 0)
                {
                    continue;
                }

                if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, rejoin, out var j, out var r, out var s))
                {
                    continue;
                }

                var merged = toRetreat.Select(CloneSegment).Concat(toRejoin.Select(CloneSegment)).ToList();
                RemoveDuplicateBoundary(merged);
                if (merged.Count == 0)
                {
                    continue;
                }

                var suffix = BuildTailFromPosition(cache, j, r, s);
                var newTail = BuildTailWithPrefix(merged, suffix);
                if (newTail.Count == 0)
                {
                    continue;
                }

                return new TailPatch
                {
                    ExpectedPlanVersion = cache.PlanVersion,
                    FromJunctionIndex = cache.CurrentJunctionIndex,
                    FromResourceIndex = cache.CurrentResourceIndex,
                    StrategyCode = StrategyRetreat,
                    Reason = $"retreat via {retreatNode.NodeCode}",
                    WaitNodeCode = retreatNode.NodeCode,
                    RejoinNodeCode = rejoin,
                    NewTail = newTail
                };
            }
        }

        return null;
    }

    /// <summary>
    /// 构建尾段重规划补丁，在局部策略无效时执行更全局的替代路径搜索。
    /// </summary>
    private async Task<TailPatch?> TryBuildReplanTailPatchAsync(
        VdaSegmentedPathCache cache,
        PathSegmentWithCode first,
        ConflictProbe conflict,
        string? lastNode)
    {
        var graph = await _agvPathService.GetOrBuildGraphAsync(cache.MapId);
        if (graph == null || string.IsNullOrWhiteSpace(cache.OriginalGoalNodeCode))
        {
            return null;
        }

        var startNodeCode = string.IsNullOrWhiteSpace(lastNode) ? first.FromNodeCode : lastNode;
        var goalNodeCode = cache.OriginalGoalNodeCode!;

        var forbiddenNodes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        var forbiddenEdges = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingNodeCode)) forbiddenNodes.Add(conflict.BlockingNodeCode);
        if (!string.IsNullOrWhiteSpace(conflict.BlockingEdgeCode)) forbiddenEdges.Add(conflict.BlockingEdgeCode);

        var replanned = FindNodeCodePath(graph, startNodeCode, goalNodeCode, forbiddenNodes, forbiddenEdges, 120);
        if (replanned.Count == 0)
        {
            // 如果严格禁用过滤后无可选路径，则尝试放宽条件进行全局重规划。
            replanned = FindNodeCodePath(
                graph,
                startNodeCode,
                goalNodeCode,
                new HashSet<string>(StringComparer.OrdinalIgnoreCase),
                new HashSet<string>(StringComparer.OrdinalIgnoreCase),
                120);
        }

        if (replanned.Count == 0)
        {
            return null;
        }

        var newTail = BuildTailWithPrefix(replanned, new List<List<List<PathSegmentWithCode>>>());
        if (newTail.Count == 0)
        {
            return null;
        }

        return new TailPatch
        {
            ExpectedPlanVersion = cache.PlanVersion,
            FromJunctionIndex = cache.CurrentJunctionIndex,
            FromResourceIndex = cache.CurrentResourceIndex,
            StrategyCode = StrategyReplan,
            Reason = $"full tail replan to goal {goalNodeCode}",
            RejoinNodeCode = goalNodeCode,
            NewTail = newTail
        };
    }

    /// <summary>
    /// 计算两个节点平面距离的平方值，用于候选点按近似距离排序。
    /// </summary>
    private static double DistanceSquared(PathNode from, PathNode to)
    {
        var dx = from.X - to.X;
        var dy = from.Y - to.Y;
        return dx * dx + dy * dy;
    }

    /// <summary>
    /// 在禁用节点/边约束下执行图搜索，求解满足约束的节点编码路径。
    /// </summary>
    private static List<PathSegmentWithCode> FindNodeCodePath(
        PathGraph graph,
        string fromNodeCode,
        string toNodeCode,
        HashSet<string> forbiddenNodes,
        HashSet<string> forbiddenEdges,
        int maxHops)
    {
        if (string.Equals(fromNodeCode, toNodeCode, StringComparison.OrdinalIgnoreCase)) return new List<PathSegmentWithCode>();
        var start = graph.Nodes.Values.FirstOrDefault(n => string.Equals(n.NodeCode, fromNodeCode, StringComparison.OrdinalIgnoreCase));
        var target = graph.Nodes.Values.FirstOrDefault(n => string.Equals(n.NodeCode, toNodeCode, StringComparison.OrdinalIgnoreCase));
        if (start == null || target == null) return new List<PathSegmentWithCode>();

        var q = new Queue<Guid>();
        var prev = new Dictionary<Guid, PathEdge>();
        var depth = new Dictionary<Guid, int>();
        var visited = new HashSet<Guid> { start.NodeId };
        q.Enqueue(start.NodeId);
        depth[start.NodeId] = 0;

        while (q.Count > 0)
        {
            var currentId = q.Dequeue();
            if (!graph.Nodes.TryGetValue(currentId, out var current)) continue;
            if (depth[currentId] >= maxHops) continue;

            foreach (var edge in current.OutEdges)
            {
                if (forbiddenEdges.Contains(edge.EdgeCode)) continue;
                if (!graph.Nodes.TryGetValue(edge.ToNodeId, out var next)) continue;
                if (!string.Equals(next.NodeCode, toNodeCode, StringComparison.OrdinalIgnoreCase) && forbiddenNodes.Contains(next.NodeCode)) continue;
                if (!visited.Add(next.NodeId)) continue;

                prev[next.NodeId] = edge;
                depth[next.NodeId] = depth[currentId] + 1;
                if (next.NodeId == target.NodeId)
                {
                    return RebuildPath(prev, start.NodeId, target.NodeId);
                }

                q.Enqueue(next.NodeId);
            }
        }

        return new List<PathSegmentWithCode>();
    }

    /// <summary>
    /// 根据前驱关系逆向回溯并重建连续路径段，确保结果可用于补丁下发。
    /// </summary>
    private static List<PathSegmentWithCode> RebuildPath(Dictionary<Guid, PathEdge> prev, Guid startId, Guid endId)
    {
        var edges = new List<PathEdge>();
        var cursor = endId;
        while (cursor != startId)
        {
            if (!prev.TryGetValue(cursor, out var edge))
            {
                return new List<PathSegmentWithCode>();
            }

            edges.Add(edge);
            cursor = edge.FromNodeId;
        }

        edges.Reverse();
        return edges.Select(edge => new PathSegmentWithCode
        {
            EdgeId = edge.EdgeId,
            FromNodeId = edge.FromNodeId,
            ToNodeId = edge.ToNodeId,
            Length = edge.Length,
            MaxSpeed = edge.MaxSpeed,
            RequiredAngle = 0,
            Angle = 0,
            StartTheta = 0,
            EndTheta = edge.DirectionRad,
            EdgeCode = edge.EdgeCode,
            FromNodeCode = edge.FromNodeCode,
            ToNodeCode = edge.ToNodeCode,
            StartNodeActions = new List<StepAction>(),
            EndNodeActions = new List<StepAction>(),
            StartNodeNetActionTypes = new Dictionary<Guid, ActionType>(),
            EndNodeNetActionTypes = new Dictionary<Guid, ActionType>()
        }).ToList();
    }

    /// <summary>
    /// 移除拼接边界重复段，保证补丁路径拓扑连续且无冗余跳变。
    /// </summary>
    private static void RemoveDuplicateBoundary(List<PathSegmentWithCode> segments)
    {
        for (var i = segments.Count - 1; i > 0; i--)
        {
            var a = segments[i - 1];
            var b = segments[i];
            if (string.Equals(a.EdgeCode, b.EdgeCode, StringComparison.OrdinalIgnoreCase) &&
                string.Equals(a.FromNodeCode, b.FromNodeCode, StringComparison.OrdinalIgnoreCase) &&
                string.Equals(a.ToNodeCode, b.ToNodeCode, StringComparison.OrdinalIgnoreCase))
            {
                segments.RemoveAt(i);
            }
        }
    }

    /// <summary>
    /// 合并保留前缀与新尾段，确保已发送区域不被覆盖且未发送区域可替换。
    /// </summary>
    private static List<List<List<PathSegmentWithCode>>> BuildTailWithPrefix(
        List<PathSegmentWithCode> prefix,
        List<List<List<PathSegmentWithCode>>> suffix)
    {
        var tail = new List<List<List<PathSegmentWithCode>>>();
        if (prefix.Count > 0)
        {
            tail.Add(new List<List<PathSegmentWithCode>> { prefix.Select(CloneSegment).ToList() });
        }

        tail.AddRange(suffix.Select(j => j.Select(r => r.Select(CloneSegment).ToList()).ToList()));
        return tail;
    }

    /// <summary>
    /// 提取未发送区域节点候选集，为等待点与让行点筛选提供输入。
    /// </summary>
    private static List<string> GetUnsentNodeCandidates(VdaSegmentedPathCache cache, int fromJunction, int fromResource)
    {
        var nodes = new List<string>();
        var firstAdded = false;
        for (var j = fromJunction; j < cache.JunctionSegments.Count; j++)
        {
            var resources = cache.JunctionSegments[j].ResourceSegments;
            var rStart = j == fromJunction ? fromResource : 0;
            for (var r = rStart; r < resources.Count; r++)
            {
                var segs = resources[r].Segments;
                if (segs.Count == 0) continue;
                if (!firstAdded)
                {
                    nodes.Add(segs[0].FromNodeCode);
                    firstAdded = true;
                }

                nodes.AddRange(segs.Select(s => s.ToNodeCode));
            }
        }

        return nodes.Where(code => !string.IsNullOrWhiteSpace(code)).ToList()!;
    }

    /// <summary>
    /// 基于 Redis 有序集合确保队列票据原子存在并返回序位，支撑公平排队。
    /// </summary>
    private async Task<(int Position, int Size)> EnsureQueueTicketAsync(
        Guid robotId,
        string mapCode,
        string queueNodeCode,
        CancellationToken ct)
    {
        if (string.IsNullOrWhiteSpace(mapCode) || string.IsNullOrWhiteSpace(queueNodeCode))
        {
            return (0, 1);
        }

        ct.ThrowIfCancellationRequested();
        var db = _redis.GetDatabase();
        var orderKey = BuildQueueOrderKey(mapCode, queueNodeCode);
        var aliveKey = BuildQueueAliveKey(mapCode, queueNodeCode);
        var member = BuildQueueMember(robotId);
        var nowMs = DateTimeOffset.Now.ToUnixTimeMilliseconds();
        var staleSeconds = Math.Max(10, _coordinatorSettings.QueueStaleSeconds);
        var staleBeforeMs = nowMs - staleSeconds * 1000L;

        var staleMembers = await db.SortedSetRangeByScoreAsync(aliveKey, double.NegativeInfinity, staleBeforeMs);
        if (staleMembers.Length > 0)
        {
            await db.SortedSetRemoveAsync(aliveKey, staleMembers);
            await db.SortedSetRemoveAsync(orderKey, staleMembers);
        }

        await db.SortedSetAddAsync(orderKey, member, nowMs, when: When.NotExists);
        await db.SortedSetAddAsync(aliveKey, member, nowMs, when: When.Always);

        var ttl = TimeSpan.FromSeconds(staleSeconds * 2);
        await db.KeyExpireAsync(orderKey, ttl);
        await db.KeyExpireAsync(aliveKey, ttl);

        var rank = await db.SortedSetRankAsync(orderKey, member, Order.Ascending);
        var count = await db.SortedSetLengthAsync(orderKey);
        return ((int)(rank ?? 0), (int)Math.Max(1, count));
    }

    /// <summary>
    /// 释放完成或失效的队列票据，避免僵尸成员影响后续排队公平性。
    /// </summary>
    private async Task ReleaseQueueTicketAsync(Guid robotId, string mapCode, string? queueNodeCode)
    {
        if (string.IsNullOrWhiteSpace(mapCode) || string.IsNullOrWhiteSpace(queueNodeCode))
        {
            return;
        }

        var db = _redis.GetDatabase();
        var member = BuildQueueMember(robotId);
        await db.SortedSetRemoveAsync(BuildQueueOrderKey(mapCode, queueNodeCode), member);
        await db.SortedSetRemoveAsync(BuildQueueAliveKey(mapCode, queueNodeCode), member);
    }

    /// <summary>
    /// 构建队列顺序 Key，按地图与节点维度进行隔离。
    /// </summary>
    private static string BuildQueueOrderKey(string mapCode, string queueNodeCode)
        => $"{QueueKeyPrefix}:{mapCode}:{queueNodeCode}:order";

    /// <summary>
    /// 构建队列存活 Key，用于成员活性续期与过期清理。
    /// </summary>
    private static string BuildQueueAliveKey(string mapCode, string queueNodeCode)
        => $"{QueueKeyPrefix}:{mapCode}:{queueNodeCode}:alive";

    /// <summary>
    /// 将机器人标识规范化为队列成员字符串，保证跨进程一致识别。
    /// </summary>
    private static string BuildQueueMember(Guid robotId) => robotId.ToString("N");

    /// <summary>
    /// 融合快照状态与调用参数，优先采用更新鲜数据以降低决策误判。
    /// </summary>
    private (string? LastNodeCode, bool IsDriving) ResolveRuntime(Guid robotId, string? lastNodeCode, bool isDriving)
    {
        var effectiveLastNode = lastNodeCode;
        var effectiveDriving = isDriving;
        if ((string.IsNullOrWhiteSpace(effectiveLastNode) || !isDriving) &&
            _robotSnapshots.TryGetValue(robotId, out var snapshot))
        {
            if (string.IsNullOrWhiteSpace(effectiveLastNode)) effectiveLastNode = snapshot.LastNodeCode;
            if (!isDriving) effectiveDriving = snapshot.IsDriving;
        }

        return (effectiveLastNode, effectiveDriving);
    }

    /// <summary>
    /// 判断近期逆向冲突是否成立，用于触发更保守的升级策略。
    /// </summary>
    private bool HasRecentReverseConflictSignal(Guid robotId, string mapCode)
    {
        if (!_lockConflictSnapshots.TryGetValue(robotId, out var snapshot))
        {
            return false;
        }

        if (!string.IsNullOrWhiteSpace(snapshot.MapCode) &&
            !string.IsNullOrWhiteSpace(mapCode) &&
            !string.Equals(snapshot.MapCode, mapCode, StringComparison.OrdinalIgnoreCase))
        {
            return false;
        }

        var age = DateTime.Now - snapshot.LastOccurredAtUtc;
        if (age > TimeSpan.FromSeconds(20))
        {
            _lockConflictSnapshots.TryRemove(robotId, out _);
            return false;
        }

        return snapshot.ReverseConflictStreak > 0;
    }

    /// <summary>
    /// 构造继续发送决策，表示当前无需路径调整。
    /// </summary>
    private RouteAdjustmentDecision Continue(string message) =>
        TrackDecision(new RouteAdjustmentDecision
        {
            Action = RouteAdjustmentAction.Continue,
            StrategyCode = StrategyContinue,
            Message = message
        });

    /// <summary>
    /// 构造补丁决策，在不重发已发送段前提下替换未发送尾段。
    /// </summary>
    private RouteAdjustmentDecision Patch(TailPatch patch, string message) =>
        TrackDecision(new RouteAdjustmentDecision
        {
            Action = RouteAdjustmentAction.PatchTail,
            StrategyCode = patch.StrategyCode,
            Patch = patch,
            Message = message
        });

    /// <summary>
    /// 构造重规划决策，适用于局部避让无法消解冲突的场景。
    /// </summary>
    private RouteAdjustmentDecision Replan(TailPatch patch, string message) =>
        TrackDecision(new RouteAdjustmentDecision
        {
            Action = RouteAdjustmentAction.ReplanTail,
            StrategyCode = patch.StrategyCode,
            Patch = patch,
            Message = message
        });

    /// <summary>
    /// 构造等待决策并写入等待窗口，利用时间缓冲抑制高频冲突重试。
    /// </summary>
    private RouteAdjustmentDecision Hold(
        VdaSegmentedPathCache cache,
        string strategyCode,
        int holdSeconds,
        string holdNodeCode,
        string message,
        string? routeModeOverride = null)
    {
        var holdUntil = DateTime.Now.AddSeconds(Math.Max(1, holdSeconds));
        cache.RouteMode = routeModeOverride ??
                          (string.Equals(strategyCode, StrategyQueue, StringComparison.Ordinal) ? ModeQueue : ModeHold);
        cache.HoldNodeCode = holdNodeCode;
        cache.HoldUntilUtc = holdUntil;
        cache.LastDecisionCode = strategyCode;

        return TrackDecision(new RouteAdjustmentDecision
        {
            Action = RouteAdjustmentAction.Hold,
            StrategyCode = strategyCode,
            SuggestedHoldUntilUtc = holdUntil,
            Message = message
        });
    }

    /// <summary>
    /// 记录决策计数与策略命中分布，为运行观测和参数优化提供指标。
    /// </summary>
    private RouteAdjustmentDecision TrackDecision(RouteAdjustmentDecision decision)
    {
        switch (decision.Action)
        {
            case RouteAdjustmentAction.Hold:
                System.Threading.Interlocked.Increment(ref _decisionHoldCount);
                break;
            case RouteAdjustmentAction.PatchTail:
            case RouteAdjustmentAction.ReplanTail:
                System.Threading.Interlocked.Increment(ref _decisionPatchCount);
                break;
            default:
                System.Threading.Interlocked.Increment(ref _decisionContinueCount);
                break;
        }

        var strategy = string.IsNullOrWhiteSpace(decision.StrategyCode) ? "Unknown" : decision.StrategyCode;
        _decisionStrategyCounts.AddOrUpdate(strategy, 1, (_, oldValue) => oldValue + 1);
        MaybeLogDecisionMetrics();
        return decision;
    }

    /// <summary>
    /// 按时间窗口输出决策统计，便于发现策略偏斜与异常波动。
    /// </summary>
    private void MaybeLogDecisionMetrics()
    {
        var now = DateTime.Now;
        if (now - _lastDecisionMetricsLogUtc < _decisionMetricsLogInterval)
        {
            return;
        }

        _lastDecisionMetricsLogUtc = now;
        var topStrategies = string.Join(",",
            _decisionStrategyCounts
                .OrderByDescending(item => item.Value)
                .Take(5)
                .Select(item => $"{item.Key}:{item.Value}"));

        _logger.LogInformation(
            "[全局导航] 决策指标: Continue={Continue}, Hold={Hold}, Patch={Patch}, TopStrategies={TopStrategies}",
            System.Threading.Interlocked.Read(ref _decisionContinueCount),
            System.Threading.Interlocked.Read(ref _decisionHoldCount),
            System.Threading.Interlocked.Read(ref _decisionPatchCount),
            string.IsNullOrWhiteSpace(topStrategies) ? "-" : topStrategies);
    }

    /// <summary>
    /// 按机器人实际进度裁剪过时头段，避免重复下发历史路径。
    /// </summary>
    private static TailPatch? TryBuildTrimHeadPatch(VdaSegmentedPathCache cache, string? lastNodeCode)
    {
        if (string.IsNullOrWhiteSpace(lastNodeCode)) return null;
        if (cache.CurrentJunctionIndex >= cache.JunctionSegments.Count) return null;

        var first = GetFirstUnsentSegment(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex);
        if (first == null || string.Equals(first.FromNodeCode, lastNodeCode, StringComparison.OrdinalIgnoreCase)) return null;

        if (!TryFindStartPosition(cache, cache.CurrentJunctionIndex, cache.CurrentResourceIndex, lastNodeCode, out var j, out var r, out var s))
        {
            return null;
        }

        if (j == cache.CurrentJunctionIndex && r == cache.CurrentResourceIndex && s == 0) return null;
        var tail = BuildTailFromPosition(cache, j, r, s);
        if (tail.Count == 0) return null;

        return new TailPatch
        {
            ExpectedPlanVersion = cache.PlanVersion,
            FromJunctionIndex = cache.CurrentJunctionIndex,
            FromResourceIndex = cache.CurrentResourceIndex,
            StrategyCode = StrategyTrim,
            Reason = $"align unsent tail from {lastNodeCode}",
            RejoinNodeCode = lastNodeCode,
            NewTail = tail
        };
    }

    /// <summary>
    /// 定位未发送区域首段，作为冲突探测与策略计算的基准输入。
    /// </summary>
    private static PathSegmentWithCode? GetFirstUnsentSegment(VdaSegmentedPathCache cache, int fromJunction, int fromResource)
    {
        for (var j = fromJunction; j < cache.JunctionSegments.Count; j++)
        {
            var resources = cache.JunctionSegments[j].ResourceSegments;
            var rStart = j == fromJunction ? fromResource : 0;
            for (var r = rStart; r < resources.Count; r++)
            {
                var seg = resources[r].Segments.FirstOrDefault();
                if (seg != null) return seg;
            }
        }

        return null;
    }

    /// <summary>
    /// 在缓存路径中定位节点对应发送起点，为裁剪与回归计算提供锚点。
    /// </summary>
    private static bool TryFindStartPosition(
        VdaSegmentedPathCache cache,
        int fromJunction,
        int fromResource,
        string nodeCode,
        out int startJunction,
        out int startResource,
        out int startSegment)
    {
        startJunction = -1;
        startResource = -1;
        startSegment = -1;

        for (var j = fromJunction; j < cache.JunctionSegments.Count; j++)
        {
            var resources = cache.JunctionSegments[j].ResourceSegments;
            var rStart = j == fromJunction ? fromResource : 0;
            for (var r = rStart; r < resources.Count; r++)
            {
                var segs = resources[r].Segments;
                for (var s = 0; s < segs.Count; s++)
                {
                    if (string.Equals(segs[s].FromNodeCode, nodeCode, StringComparison.OrdinalIgnoreCase))
                    {
                        startJunction = j;
                        startResource = r;
                        startSegment = s;
                        return true;
                    }

                    if (!string.Equals(segs[s].ToNodeCode, nodeCode, StringComparison.OrdinalIgnoreCase)) continue;
                    if (s + 1 < segs.Count)
                    {
                        startJunction = j;
                        startResource = r;
                        startSegment = s + 1;
                        return true;
                    }

                    if (TryFindNextNonEmptyResource(cache, j, r + 1, out startJunction, out startResource))
                    {
                        startSegment = 0;
                        return true;
                    }
                }
            }
        }

        return false;
    }

    /// <summary>
    /// 从指定位置向后查找首个非空资源段，保证补丁起点有效。
    /// </summary>
    private static bool TryFindNextNonEmptyResource(VdaSegmentedPathCache cache, int junctionIndex, int fromResource, out int nextJunction, out int nextResource)
    {
        nextJunction = -1;
        nextResource = -1;
        for (var j = junctionIndex; j < cache.JunctionSegments.Count; j++)
        {
            var resources = cache.JunctionSegments[j].ResourceSegments;
            var rStart = j == junctionIndex ? fromResource : 0;
            for (var r = rStart; r < resources.Count; r++)
            {
                if (resources[r].Segments.Count == 0) continue;
                nextJunction = j;
                nextResource = r;
                return true;
            }
        }

        return false;
    }

    /// <summary>
    /// 从指定坐标重建尾段三层结构，保持与缓存组织形式一致。
    /// </summary>
    private static List<List<List<PathSegmentWithCode>>> BuildTailFromPosition(VdaSegmentedPathCache cache, int startJunction, int startResource, int startSegment)
    {
        var newTail = new List<List<List<PathSegmentWithCode>>>();
        for (var j = startJunction; j < cache.JunctionSegments.Count; j++)
        {
            var patchJ = new List<List<PathSegmentWithCode>>();
            var rStart = j == startJunction ? startResource : 0;
            for (var r = rStart; r < cache.JunctionSegments[j].ResourceSegments.Count; r++)
            {
                var src = cache.JunctionSegments[j].ResourceSegments[r].Segments;
                if (src.Count == 0) continue;
                var sStart = j == startJunction && r == startResource ? startSegment : 0;
                if (sStart >= src.Count) continue;
                patchJ.Add(src.Skip(sStart).Select(CloneSegment).ToList());
            }

            if (patchJ.Count > 0) newTail.Add(patchJ);
        }

        return newTail;
    }

    /// <summary>
    /// 深拷贝原子路径段及动作集合，避免引用共享导致状态污染。
    /// </summary>
    private static PathSegmentWithCode CloneSegment(PathSegmentWithCode segment) =>
        new()
        {
            EdgeId = segment.EdgeId,
            FromNodeId = segment.FromNodeId,
            ToNodeId = segment.ToNodeId,
            Angle = segment.Angle,
            Length = segment.Length,
            MaxSpeed = segment.MaxSpeed,
            RequiredAngle = segment.RequiredAngle,
            StartTheta = segment.StartTheta,
            EndTheta = segment.EndTheta,
            EdgeCode = segment.EdgeCode,
            FromNodeCode = segment.FromNodeCode,
            ToNodeCode = segment.ToNodeCode,
            ForkAngleOffset = segment.ForkAngleOffset,
            StartNodeActions = new List<StepAction>(segment.StartNodeActions),
            StartNodeNetActionTypes = new Dictionary<Guid, ActionType>(segment.StartNodeNetActionTypes),
            EndNodeActions = new List<StepAction>(segment.EndNodeActions),
            EndNodeNetActionTypes = new Dictionary<Guid, ActionType>(segment.EndNodeNetActionTypes)
        };

    /// <summary>
    /// 后台消费状态事件并更新运行快照，利用单读通道保证处理时序一致。
    /// </summary>
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await foreach (var evt in _stateEvents.Reader.ReadAllAsync(stoppingToken))
        {
            _robotSnapshots[evt.RobotId] = new RobotNavSnapshot
            {
                LastNodeCode = evt.LastNodeCode,
                IsDriving = evt.IsDriving,
                UpdatedAtUtc = evt.OccurredAtUtc
            };
        }
    }

    /// <summary>
    /// 释放订阅等资源，避免热更新后重复回调与资源泄漏。
    /// </summary>
    public override void Dispose()
    {
        _settingsChangeSubscription?.Dispose();
        base.Dispose();
    }

    private sealed class ConflictProbe
    {
        /// <summary>
        /// 是否存在冲突。
        /// </summary>
        public bool HasConflict { get; set; }

        /// <summary>
        /// 是否存在逆向冲突。
        /// </summary>
        public bool HasReverseConflict { get; set; }

        /// <summary>
        /// 阻塞节点编码。
        /// </summary>
        public string? BlockingNodeCode { get; set; }

        /// <summary>
        /// 阻塞边编码。
        /// </summary>
        public string? BlockingEdgeCode { get; set; }
    }

    private sealed class RobotNavSnapshot
    {
        /// <summary>
        /// 最后节点编码。
        /// </summary>
        public string? LastNodeCode { get; set; }

        /// <summary>
        /// 是否行驶中。
        /// </summary>
        public bool IsDriving { get; set; }

        /// <summary>
        /// 快照更新时间（UTC）。
        /// </summary>
        public DateTime UpdatedAtUtc { get; set; }
    }

    private sealed class LockConflictSnapshot
    {
        /// <summary>
        /// 地图编码。
        /// </summary>
        public string? MapCode { get; set; }

        /// <summary>
        /// 最近冲突节点编码。
        /// </summary>
        public string? LastNodeCode { get; set; }

        /// <summary>
        /// 最近冲突边编码。
        /// </summary>
        public string? LastEdgeCode { get; set; }

        /// <summary>
        /// 最近失败原因。
        /// </summary>
        public string? LastFailureReason { get; set; }

        /// <summary>
        /// 最近冲突发生时间（UTC）。
        /// </summary>
        public DateTime LastOccurredAtUtc { get; set; }

        /// <summary>
        /// 连续逆向冲突次数。
        /// </summary>
        public int ReverseConflictStreak { get; set; }

        /// <summary>
        /// 连续总冲突次数。
        /// </summary>
        public int TotalConflictStreak { get; set; }
    }
}