flowchart LR
    A[游戏画面 / 小地图帧] --> B[MapLocator]
    B --> C[PositionProvider<br/>Capture / WaitForFix / ResetTracking]

    subgraph S[Session Layer]
        D[NavigationSession<br/>current_path / current_node_idx<br/>virtual_yaw / current_zone_id<br/>progress tracking / stalled_ms]
    end

    C --> D

    subgraph F[NavigationStateMachine<br/>中央编排核心]
        E1[Bootstrap]
        E2[AlignHeading]
        E3[AdvanceOnRoute]
        E4[WaitZoneTransition]
        E5[WaitRelocation]
        E6[RecoverRejoin]
        E7[ExactTargetRefine]
        E8[Finished / Failed]
    end

    D --> F
    C -. 实时 position / yaw / zone_id .-> F

    subgraph P[Planning & Recovery]
        G[RouteRejoinPlanner<br/>Waypoint / Segment candidate planning]
        H[ZoneTransitionController<br/>ConsumeZoneNodes / WaitForExpectedZone]
        I[LocalDriverLite<br/>Cruise / MicroAvoid / Recover]
    end

    subgraph X[Execution Layer]
        J[MotionController<br/>turn / move / sprint<br/>forward commit / adaptive turn learning]
        K[ActionExecutor<br/>RUN / JUMP / INTERACT / PORTAL / FIGHT]
        L[ActionWrapper<br/>controller backend abstraction]
    end

    F --> G
    F --> H
    F --> I
    F --> J
    F --> K

    G --> D
    H --> D
    I --> F

    J --> L
    K --> L
    L --> M[角色控制输入]
    M --> A

    J -. SyncVirtualYaw / turn feedback .-> D
    H -. ConfirmZone / landing portal .-> D
    G -. ApplyRejoinSlice .-> D

stateDiagram-v2
    direction LR

    [*] --> Bootstrap
    Bootstrap --> AlignHeading : 初始 fix 成功
    Bootstrap --> Failed : 初始定位失败

    AlignHeading --> AdvanceOnRoute : 对齐完成
    AlignHeading --> WaitRelocation : 转向后等待稳定
    AlignHeading --> RecoverRejoin : 对齐失败 / 偏差过大

    AdvanceOnRoute --> WaitZoneTransition : 命中 ZONE / PORTAL
    AdvanceOnRoute --> WaitRelocation : 动作后待重定位
    AdvanceOnRoute --> ExactTargetRefine : 进入终点邻域
    AdvanceOnRoute --> Finished : 路径完成
    AdvanceOnRoute --> RecoverRejoin : 偏航 / 卡滞 / 丢路

    WaitZoneTransition --> AdvanceOnRoute : 切区确认成功
    WaitZoneTransition --> WaitRelocation : 传送落地后等待稳定
    WaitZoneTransition --> RecoverRejoin : 未稳定挂回
    WaitZoneTransition --> Failed : 超时失败

    WaitRelocation --> AlignHeading : 需重新对齐
    WaitRelocation --> AdvanceOnRoute : 可继续推进
    WaitRelocation --> RecoverRejoin : 已脱轨
    WaitRelocation --> Failed : 长时间无 fix

    ExactTargetRefine --> Finished : 精修完成
    ExactTargetRefine --> RecoverRejoin : 精修期间失配

    RecoverRejoin --> AlignHeading : 重挂成功
    RecoverRejoin --> Failed : 无可行候选 / 超出 abort distance

    Finished --> [*]
    Failed --> [*]

sequenceDiagram
    participant Sensor as PositionProvider / MapLocator
    participant Session as NavigationSession
    participant FSM as NavigationStateMachine
    participant Driver as LocalDriverLite
    participant Rejoin as RouteRejoinPlanner
    participant Motion as MotionController
    participant Game as Character

    Sensor->>FSM: 持续提供 position / yaw / zone_id
    FSM->>Session: ObserveProgress(actual_distance, waypoint_idx)
    Session-->>FSM: stalled_ms 上升 / best_actual_distance 不再改善

    FSM->>Driver: Evaluate(yaw_error, distance_delta, moved_distance)
    Driver-->>FSM: blocked=true / request_rejoin=true

    alt 可先局部脱困
        FSM->>Motion: SetAction(ForwardLeft / ForwardRight / JumpForward)
        Motion->>Game: 执行微避障 / 恢复动作
        Sensor->>FSM: 返回新的位置观测
    else 直接进入重挂
        FSM->>Rejoin: Plan(current_pos, heading, path, preferred_index)
        Rejoin-->>FSM: 返回 waypoint / segment 候选
        FSM->>Session: ApplyRejoinSlice(slice_start, pos)
        FSM->>Session: UpdatePhase(AlignHeading)
    end

    FSM->>Motion: 重新朝向当前目标
    Motion->>Game: turn / move / sprint
    Sensor->>FSM: 新定位稳定
    FSM->>Session: 继续推进主路径

flowchart TD
    A[AdvanceOnRoute] --> B{当前节点类型}
    B -->|ZONE / PORTAL| C[进入 WaitZoneTransition]
    B -->|普通位置节点| Z[继续路径推进]

    C --> D[ZoneTransitionController]
    D --> E[ConsumeZoneNodes]
    E --> F[WaitForExpectedZone: expected_zone_id]

    F --> G{已进入目标 zone?}
    G -->|否| H[继续等待 fix / 保持前进 / 落地探测]
    H --> F

    G -->|是| I[NavigationSession.ConfirmZone]
    I --> J{是否为 portal 落地后重定位阶段?}
    J -->|是| K[进入 WaitRelocation]
    J -->|否| L[切回 AdvanceOnRoute]

    K --> M[等待位置稳定 / movement settle]
    M --> N{恢复到有效路径上下文?}
    N -->|是| O[AlignHeading 或 AdvanceOnRoute]
    N -->|否| P[RecoverRejoin]

    P --> Q[RouteRejoinPlanner Plan]
    Q --> R{存在可行候选?}
    R -->|是| S[ApplyRejoinSlice]
    S --> O
    R -->|否| T[Failed]