查看“使用手册 - 寻路启发器功能”的源代码

= 使用手册 - 寻路启发器功能 =

== 1. 寻路启发器作用 ==
在实际现场业务中，我们往往需要对"哪种车可以走哪条路"进行限定，或者自定义寻路的规则。寻路启发器允许我们定义这些自定义规则，以优化路径搜索过程，提高效率并满足特定的业务需求。

== 2. 寻路启发器工作原理 ==
寻路启发器在路径搜索过程中起着关键作用。它们被用于：

# 预选（PreSelect）：在考虑一个新的路径节点之前进行初步筛选。
# 定价（Price）：为路径分配成本或优先级。
# 路径验证（PerRoute）：验证整个路径是否有效。
# 后选（PostSelect）：在其他启发式方法之后进行最终筛选。

系统会在搜索过程中的不同阶段调用这些启发器，以指导搜索算法做出更智能的决策。

== 3. 如何定义一个启发器 ==
要定义一个启发器，请按照以下步骤操作：

# 创建一个继承自 <code>HeuristicsContainer</code> 的类。
# 在类中定义一个或多个方法，并使用 <code>[HeuristicDef]</code> 属性标记它们。
# 根据需要实现启发式逻辑。

=== 基本示例 ===
<syntaxhighlight lang="csharp">
public class BYDBcHeuristics : HeuristicsContainer
{
    [HeuristicDef]
    public bool BYDCarShouldGo(SegmentPlan.SearchStat stat)
    {
        if (plan.usingCar.fields.ContainsKey("A"))
        {
            if (stat.previousTrack.fields.ContainsKey("noAllowA")) return false;
            return true;
        }
        if (plan.usingCar.fields.ContainsKey("BC"))
        {
            if (stat.previousTrack.fields.ContainsKey("noAllowBC")) return false;
            return true;
        }
        return true;
    }
}
</syntaxhighlight>

这个示例展示了一个简单的启发器，它根据车辆和轨道的特定字段来决定是否允许车辆通过某条路径。

== 4. 启发器类型 ==
启发器可以有不同的类型，通过 <code>HeuristicDef</code> 属性的 <code>role</code> 参数指定：

<syntaxhighlight lang="csharp">
[HeuristicDef(role = HeuristicDef.HType.PreSelect)]
[HeuristicDef(role = HeuristicDef.HType.Price)]
[HeuristicDef(role = HeuristicDef.HType.PerRoute)]
[HeuristicDef(role = HeuristicDef.HType.PostSelect)]
</syntaxhighlight>

* <code>PreSelect</code>：在考虑新节点之前调用
* <code>Price</code>：用于计算路径成本
* <code>PerRoute</code>：验证整个路径
* <code>PostSelect</code>：在其他启发式方法之后进行最终筛选

== 5. 访问上下文信息 ==
在启发器方法中，你可以访问 <code>SegmentPlan.SearchStat</code> 对象，它包含了当前搜索状态的信息：

* <code>stat.CurrentSite</code>：当前站点
* <code>stat.previous</code>：前一个搜索状态
* <code>stat.previousTrack</code>：前一个轨道
* <code>stat.sequence</code>：已访问的站点序列
* <code>plan.usingCar</code>：当前使用的车辆

== 6. 高级用法 ==

=== 6.1 车辆特定启发器 ===
你可以创建只适用于特定类型车辆的启发器：

<syntaxhighlight lang="csharp">
[HeuristicDef(carTypes = new[] { typeof(ElectricCar) })]
public bool ElectricCarHeuristic(SegmentPlan.SearchStat stat)
{
    // 只对电动车应用的逻辑
}
</syntaxhighlight>

=== 6.2 定价启发器 ===
定价启发器用于调整路径的成本或优先级：

<syntaxhighlight lang="csharp">
[HeuristicDef(role = HeuristicDef.HType.Price)]
public void AdjustPrice(SegmentPlan.SearchStat stat)
{
    // 根据某些条件调整价格
    if (SomeCondition)
    {
        stat.price += 10;
    }
}
</syntaxhighlight>

=== 6.3 初始化逻辑 ===
如果你的启发器需要一些初始化逻辑，可以重写 <code>initHeuristics</code> 方法：

<syntaxhighlight lang="csharp">
public override void initHeuristics()
{
    // 执行一些初始化逻辑
}
</syntaxhighlight>

== 7. 最佳实践 ==
# 保持启发器简单和高效，因为它们会被频繁调用。
# 利用不同类型的启发器（PreSelect、Price、PerRoute、PostSelect）来优化搜索过程的不同阶段。
# 使用车辆特定的启发器来处理不同类型车辆的特殊需求。
# 充分利用 <code>SegmentPlan.SearchStat</code> 对象提供的上下文信息。
# 在复杂的启发器中考虑性能优化，例如缓存计算结果。

通过正确使用启发器，你可以极大地提高路径规划的效率和准确性，同时满足复杂的业务需求。