zengzy / hhrcs_service · Files

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Rcs.Application.Services.PathFind.Models;

namespace Rcs.Application.Services.PathFind.Realtime;

/// <summary>
/// 全局导航协调器返回的路径调整动作。
/// </summary>
public enum RouteAdjustmentAction
{
    /// <summary>
    /// 继续按当前路径发送。
    /// </summary>
    Continue = 0,

    /// <summary>
    /// 暂停发送并进入等待窗口。
    /// </summary>
    Hold = 1,

    /// <summary>
    /// 对未发送尾段应用补丁路径。
    /// </summary>
    PatchTail = 2,

    /// <summary>
    /// 触发尾段重规划并替换。
    /// </summary>
    ReplanTail = 3
}

/// <summary>
/// 全局导航决策共享的策略编码。
/// </summary>
public static class AvoidanceStrategyCodes
{
    /// <summary>
    /// 无需调整，直接继续。
    /// </summary>
    public const string Continue = "Continue";

    /// <summary>
    /// 就近等待。
    /// </summary>
    public const string WaitNearest = "WaitNearest";

    /// <summary>
    /// 路口占位排队。
    /// </summary>
    public const string JunctionOccupy = "JunctionOccupy";

    /// <summary>
    /// 局部绕行。
    /// </summary>
    public const string LocalDetour = "LocalDetour";

    /// <summary>
    /// 侧向让行。
    /// </summary>
    public const string LateralYield = "LateralYield";

    /// <summary>
    /// 泊车让行。
    /// </summary>
    public const string ParkingYield = "ParkingYield";

    /// <summary>
    /// 退让回撤。
    /// </summary>
    public const string Retreat = "Retreat";

    /// <summary>
    /// 尾段重规划。
    /// </summary>
    public const string ReplanTail = "ReplanTail";

    /// <summary>
    /// 请求空闲机器人让行。
    /// @author zzy
    /// </summary>
    public const string RequestIdleYield = "RequestIdleYield";
}

/// <summary>
/// 全局导航状态机共享的路线模式编码。
/// </summary>
public static class RouteModeCodes
{
    /// <summary>
    /// 正常发送模式。
    /// </summary>
    public const string Normal = "Normal";

    /// <summary>
    /// 在等待节点保持等待。
    /// </summary>
    public const string HoldingAtWaitNode = "HoldingAtWaitNode";

    /// <summary>
    /// 路口排队等待。
    /// </summary>
    public const string QueueingForJunction = "QueueingForJunction";

    /// <summary>
    /// 占用路口等待放行。
    /// </summary>
    public const string OccupyingJunction = "OccupyingJunction";

    /// <summary>
    /// 绕行执行中。
    /// </summary>
    public const string Detouring = "Detouring";

    /// <summary>
    /// 回归主路径中。
    /// </summary>
    public const string Rejoining = "Rejoining";

    /// <summary>
    /// 等待重规划结果。
    /// </summary>
    public const string ReplanPending = "ReplanPending";

    /// <summary>
    /// 阻塞保护态。
    /// </summary>
    public const string Blocked = "Blocked";
}

/// <summary>
/// 机器人处于等待升级阶段时，策略选择器使用的输入参数。
/// </summary>
public sealed class AvoidanceSelectionContext
{
    /// <summary>
    /// 连续冲突失败次数。
    /// </summary>
    public int FailStreak { get; set; }

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

    /// <summary>
    /// 触发等待策略的阈值。
    /// </summary>
    public int EscalateWaitThreshold { get; set; }

    /// <summary>
    /// 触发绕行策略的阈值。
    /// </summary>
    public int EscalateDetourThreshold { get; set; }

    /// <summary>
    /// 触发侧向让行策略的阈值。
    /// </summary>
    public int EscalateLateralYieldThreshold { get; set; }

    /// <summary>
    /// 触发泊车让行策略的阈值。
    /// </summary>
    public int EscalateParkingThreshold { get; set; }

    /// <summary>
    /// 触发退让策略的阈值。
    /// </summary>
    public int EscalateRetreatThreshold { get; set; }

    /// <summary>
    /// 触发重规划策略的阈值。
    /// </summary>
    public int EscalateReplanThreshold { get; set; }

    /// <summary>
    /// 是否启用侧向让行。
    /// </summary>
    public bool EnableLateralYield { get; set; }

    /// <summary>
    /// 是否启用泊车让行。
    /// </summary>
    public bool EnableParkingYield { get; set; }

    /// <summary>
    /// 是否启用退让。
    /// </summary>
    public bool EnableRetreat { get; set; }
}

/// <summary>
/// 根据运行时上下文选择候选避让策略。
/// </summary>
public interface IAvoidanceStrategySelector
{
    /// <summary>
    /// 按当前上下文选择候选策略编码列表。
    /// </summary>
    IReadOnlyList<string> SelectHoldCandidates(AvoidanceSelectionContext context);
}

/// <summary>
/// 用于替换未发送路径的尾段补丁载荷。
/// </summary>
public sealed class TailPatch
{
    /// <summary>
    /// 补丁唯一标识。
    /// </summary>
    public Guid PatchId { get; set; } = Guid.NewGuid();

    /// <summary>
    /// 应用补丁所期望的路径版本号。
    /// </summary>
    public long ExpectedPlanVersion { get; set; }

    /// <summary>
    /// 补丁起始路口索引。
    /// </summary>
    public int FromJunctionIndex { get; set; }

    /// <summary>
    /// 补丁起始资源段索引。
    /// </summary>
    public int FromResourceIndex { get; set; }

    /// <summary>
    /// 触发补丁的策略编码。
    /// </summary>
    public string StrategyCode { get; set; } = string.Empty;

    /// <summary>
    /// 补丁原因说明。
    /// </summary>
    public string Reason { get; set; } = string.Empty;

    /// <summary>
    /// 建议等待节点编码。
    /// </summary>
    public string? WaitNodeCode { get; set; }

    /// <summary>
    /// 期望回归节点编码。
    /// </summary>
    public string? RejoinNodeCode { get; set; }

    /// <summary>
    /// 新尾段路径（三层结构：路口段/资源段/原子段）。
    /// </summary>
    public List<List<List<PathSegmentWithCode>>> NewTail { get; set; } = new();
}

/// <summary>
/// 全局导航协调器生成的决策结果。
/// </summary>
public sealed class RouteAdjustmentDecision
{
    /// <summary>
    /// 调整动作类型。
    /// </summary>
    public RouteAdjustmentAction Action { get; set; } = RouteAdjustmentAction.Continue;

    /// <summary>
    /// 决策说明消息。
    /// </summary>
    public string Message { get; set; } = string.Empty;

    /// <summary>
    /// 决策对应策略编码。
    /// </summary>
    public string StrategyCode { get; set; } = "Continue";

    /// <summary>
    /// 建议等待截止时间（UTC）。
    /// </summary>
    public DateTime? SuggestedHoldUntilUtc { get; set; }

    /// <summary>
    /// 待应用的尾段补丁（可空）。
    /// </summary>
    public TailPatch? Patch { get; set; }
}

/// <summary>
/// 全局导航协调器消费的实时状态事件。
/// </summary>
public sealed class RobotStateNavigationEvent
{
    /// <summary>
    /// 机器人ID。
    /// </summary>
    public Guid RobotId { get; set; }

    /// <summary>
    /// 机器人制造商编码。
    /// </summary>
    public string RobotManufacturer { get; set; } = string.Empty;

    /// <summary>
    /// 机器人序列号。
    /// </summary>
    public string RobotSerialNumber { get; set; } = string.Empty;

    /// <summary>
    /// 最后经过节点编码。
    /// </summary>
    public string? LastNodeCode { get; set; }

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

    /// <summary>
    /// 事件发生时间（UTC）。
    /// </summary>
    public DateTime OccurredAtUtc { get; set; } = DateTime.Now;
}

/// <summary>
/// 协调器消费的锁冲突事件（加锁失败/逆向冲突）。
/// </summary>
public sealed class LockConflictNavigationEvent
{
    /// <summary>
    /// 机器人ID。
    /// </summary>
    public Guid RobotId { get; set; }

    /// <summary>
    /// 地图编码。
    /// </summary>
    public string MapCode { get; set; } = string.Empty;

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

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

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

    /// <summary>
    /// 冲突失败原因。
    /// </summary>
    public string? FailureReason { get; set; }

    /// <summary>
    /// 事件发生时间（UTC）。
    /// </summary>
    public DateTime OccurredAtUtc { get; set; } = DateTime.Now;
}

/// <summary>
/// 即将下发的下一段锁定范围快照。
/// </summary>
public sealed class NextSegmentLockScope
{
    /// <summary>
    /// 当前路口段索引。
    /// </summary>
    public int JunctionIndex { get; set; }

    /// <summary>
    /// 当前资源段索引。
    /// </summary>
    public int ResourceIndex { get; set; }

    /// <summary>
    /// 当前准备下发的资源段原始路径。
    /// </summary>
    public List<PathSegmentWithCode> DispatchSegments { get; set; } = new();

    /// <summary>
    /// 当前阶段真实参与冲突检测/加锁的候选路径集合。
    /// </summary>
    public List<PathSegmentWithCode> LockCandidates { get; set; } = new();

    /// <summary>
    /// 当前阶段应建立的严格绑定锁计划。
    /// </summary>
    public List<VdaLockBindingPlan> BindingPlans { get; set; } = new();

    /// <summary>
    /// 推荐等待节点编码。
    /// </summary>
    public string? HoldNodeCode { get; set; }

    /// <summary>
    /// 是否为一级段首个资源段，对应整段锁定语义。
    /// </summary>
    public bool LocksWholeJunctionScope { get; set; }

}

/// <summary>
/// 下一段锁定范围内识别出的阻塞资源类型。
/// </summary>
public enum BlockingResourceType
{
    /// <summary>
    /// 节点被占用。
    /// </summary>
    NodeOccupied = 0,

    /// <summary>
    /// 逆向边冲突。
    /// </summary>
    ReverseEdgeOccupied = 1,

    /// <summary>
    /// 同向边占用。
    /// </summary>
    SameDirectionEdgeOccupied = 2
}

/// <summary>
/// 下一段锁定范围中的阻塞资源描述。
/// </summary>
public sealed class BlockingResourceDescriptor
{
    /// <summary>
    /// 阻塞资源类型。
    /// </summary>
    public BlockingResourceType ResourceType { get; set; }

    /// <summary>
    /// 资源在当前锁定范围中的顺序索引。
    /// </summary>
    public int PathIndex { get; set; }

    /// <summary>
    /// 阻塞锚点节点编码。
    /// 节点冲突时为该节点；边冲突时优先为边起点，缺失时回退为边终点。
    /// </summary>
    public string? BlockingNodeCode { get; set; }

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

    /// <summary>
    /// 边起点节点编码。
    /// </summary>
    public string? FromNodeCode { get; set; }

    /// <summary>
    /// 边终点节点编码。
    /// </summary>
    public string? ToNodeCode { get; set; }

    /// <summary>
    /// 占用资源的机器人ID。
    /// </summary>
    public Guid OccupyingRobotId { get; set; }

    /// <summary>
    /// 是否为同向边占用。
    /// </summary>
    public bool IsSameDirectionEdge { get; set; }
}

/// <summary>
/// 状态事件驱动的全局导航协调器。
/// </summary>
public interface IGlobalNavigationCoordinator
{
    /// <summary>
    /// 发布机器人实时状态事件。
    /// </summary>
    Task PublishStateEventAsync(RobotStateNavigationEvent evt, CancellationToken ct = default);

    /// <summary>
    /// 发布锁冲突事件（加锁检查失败或逆向冲突）。
    /// </summary>
    Task PublishLockConflictEventAsync(LockConflictNavigationEvent evt, CancellationToken ct = default);

    /// <summary>
    /// 应用发送前路径调整决策。
    /// </summary>
    Task<RouteAdjustmentDecision> TryAdjustBeforeSendAsync(
        Domain.Entities.Robot robot,
        VdaSegmentedPathCache cache,
        NextSegmentLockScope? nextScope,
        string? lastNodeCode,
        bool isDriving,
        CancellationToken ct = default);

    /// <summary>
    /// 在整段锁失败后，再次尝试触发空闲机器人让行。
    /// </summary>
    Task<RouteAdjustmentDecision?> TryAdjustAfterLockFailureAsync(
        Domain.Entities.Robot robot,
        VdaSegmentedPathCache cache,
        NextSegmentLockScope? nextScope,
        string? lastNodeCode,
        bool isDriving,
        CancellationToken ct = default);
}

/// <summary>
/// 将尾段补丁应用到 VDA 分段缓存。
/// </summary>
public interface ITailPatchApplier
{
    /// <summary>
    /// 将尾段补丁应用到缓存，失败时返回失败原因。
    /// </summary>
    bool TryApplyPatch(VdaSegmentedPathCache cache, TailPatch patch, out string failureReason);
}

/// <summary>
/// 等待/排队恢复触发请求。
/// </summary>
public sealed class HoldResumeRequest
{
    /// <summary>
    /// 机器人ID。
    /// </summary>
    public Guid RobotId { get; set; }

    /// <summary>
    /// 机器人制造商编码。
    /// </summary>
    public string RobotManufacturer { get; set; } = string.Empty;

    /// <summary>
    /// 机器人序列号。
    /// </summary>
    public string RobotSerialNumber { get; set; } = string.Empty;

    /// <summary>
    /// 任务ID。
    /// </summary>
    public Guid TaskId { get; set; }

    /// <summary>
    /// 子任务ID。
    /// </summary>
    public Guid SubTaskId { get; set; }

    /// <summary>
    /// 路径缓存Key。
    /// </summary>
    public string PathCacheKey { get; set; } = string.Empty;

    /// <summary>
    /// 恢复时要求匹配的路径版本号。
    /// </summary>
    public long ExpectedPlanVersion { get; set; }

    /// <summary>
    /// 期望保持的等待节点编码。
    /// </summary>
    public string? HoldNodeCode { get; set; }

    /// <summary>
    /// 计划恢复调度时间（UTC）。
    /// </summary>
    public DateTime ResumeAtUtc { get; set; } = DateTime.Now;
}

/// <summary>
/// 为等待/排队状态调度延迟恢复尝试。
/// </summary>
public interface IGlobalNavigationResumeScheduler
{
    /// <summary>
    /// 提交一次延迟恢复调度请求。
    /// </summary>
    Task ScheduleResumeAsync(HoldResumeRequest request, CancellationToken ct = default);
}

/// <summary>
/// 空闲机器人让行请求。
/// @author zzy
/// </summary>
public sealed class IdleRobotYieldRequest
{
    /// <summary>
    /// 请求让行的机器人ID（有任务的机器人）。
    /// </summary>
    public Guid RequestingRobotId { get; set; }

    /// <summary>
    /// 被请求让行的空闲机器人ID。
    /// </summary>
    public Guid IdleRobotId { get; set; }

    /// <summary>
    /// 地图编码。
    /// </summary>
    public string MapCode { get; set; } = string.Empty;

    /// <summary>
    /// 地图ID。
    /// </summary>
    public Guid MapId { get; set; }

    /// <summary>
    /// 阻塞资源对应的锚点节点编码。
    /// 节点冲突时为该节点；边冲突时优先取边起点，缺失时回退边终点。
    /// </summary>
    public string BlockingNodeCode { get; set; } = string.Empty;

    /// <summary>
    /// 阻塞边编码（边冲突时提供）。
    /// </summary>
    public string? BlockingEdgeCode { get; set; }

    /// <summary>
    /// 让行目标节点编码（可选，为空时自动查找）。
    /// </summary>
    public string? TargetNodeCode { get; set; }

    /// <summary>
    /// 请求时间（UTC）。
    /// </summary>
    public DateTime RequestedAtUtc { get; set; } = DateTime.Now;
}

/// <summary>
/// 空闲机器人让行结果。
/// @author zzy
/// </summary>
public sealed class IdleYieldResult
{
    /// <summary>
    /// 是否成功。
    /// </summary>
    public bool Success { get; set; }

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

    /// <summary>
    /// 下发的订单ID。
    /// </summary>
    public string? OrderId { get; set; }

    /// <summary>
    /// 让行目标节点编码。
    /// </summary>
    public string? TargetNodeCode { get; set; }
}