# 高可靠任务调度协议设计 (High Reliability Task Scheduling Protocol)

**日期**: 2025-11-29  
**状态**: Implemented (Testing Pending)  
**优先级**: High  
**背景**: 当前 Workflow 采用 "Fire-and-Forget" 模式，导致当 Provider 处于降级、网络分区或宕机状态时，Orchestrator 无法感知，造成任务“假死”且无法自动恢复。

## 1. 核心设计理念

将 Orchestrator 从简单的“发令员”升级为“任务监理”，对任务进行全生命周期管理。引入 **握手 (Handshake)**、**心跳 (Heartbeat)** 和 **熔断 (Circuit Breaking)** 机制。

## 2. 协议流程图

### 2.1 正常调度流程 (Happy Path)

```mermaid
sequenceDiagram
    participant O as Orchestrator
    participant P as Provider (Worker)
    
    O->>P: Dispatch Task (Request)
    activate O
    P->>O: Acknowledgement (Accepted)
    deactivate O
    Note over O: Task Status: Running
    
    loop Execution
        P->>P: Processing...
        P->>O: Heartbeat (Progress Update)
        Note over O: Reset Watchdog Timer
    end
    
    P->>O: TaskCompleted (Result)
    Note over O: Task Status: Completed
```

### 2.2 拒绝调度流程 (Provider Degraded)

Provider 在降级模式下不再通过 Sleep 阻塞，而是保持连接并快速拒绝任务。

```mermaid
sequenceDiagram
    participant O as Orchestrator
    participant P as Provider (Degraded)
    
    O->>P: Dispatch Task (Request)
    activate O
    P->>O: Acknowledgement (Rejected: "API Key Missing")
    deactivate O
    
    Note over O: Task Status: Failed/Skipped
    O->>O: Trigger Failure Handling
```

### 2.3 调度超时 (Dispatch Timeout)

Provider 宕机或网络断连。

```mermaid
sequenceDiagram
    participant O as Orchestrator
    participant P as Provider (Dead)
    
    O->>P: Dispatch Task (Request)
    activate O
    Note right of O: Wait 5s...
    O->>O: Timeout Error
    deactivate O
    
    Note over O: Task Status: Failed (Dispatch Error)
```

### 2.4 执行超时/心跳丢失 (Execution Watchdog)

任务开始执行后，Worker 意外死亡。

```mermaid
sequenceDiagram
    participant O as Orchestrator (Monitor Loop)
    participant P as Provider
    
    P->>O: Heartbeat (T=0)
    P->>P: Crash! 💥
    
    loop Every 1s
        O->>O: Check Active Tasks
    end
    
    Note over O: Now > LastHeartbeat + 30s
    O->>O: Mark Task Failed (Zombie)
```

## 3. 实施任务清单 (Implementation Tasks)

### Phase 1: 协议定义 (Common Contracts)
- [x] **Define `TaskAcknowledgement` DTO**:
  - `Accepted`
  - `Rejected { reason: String }`
- [x] **Define `TaskHeartbeat`**:
  - 复用 `WorkflowEvent::TaskStateChanged`，当 `status=Running` 时视为心跳。

### Phase 2: 调度器改造 (Orchestrator)
- [x] **Refactor `dispatch_task`**:
  - 从 `nats.publish` 改为 `nats.request`。
  - 设置 strict timeout (e.g., 5s)。
  - 处理 `Rejected` 响应，立即置为 Failed。
- [x] **Implement `TaskMonitor`**:
  - 新增后台 Tokio Task。
  - 维护 `RunningTasks` 列表，包含 `last_heartbeat_at` 和 `started_at`。
  - 逻辑:
    - `if (now - started_at > max_timeout) -> Fail (Timeout)`
    - `if (now - last_heartbeat_at > heartbeat_timeout) -> Fail (Zombie)`

### Phase 3: 提供者改造 (Provider Services)
以 `tushare-provider` 为首个改造对象，其他 Provider 后续跟进。

- [x] **Remove Blocking Sleep**:
  - 即使在 `Degraded` 状态，也要连接 NATS。
- [x] **Implement Ack Logic**:
  - 收到 Command 后，先检查自身状态。
  - 如果 `Degraded`，回复 `Rejected`。
  - 如果正常，回复 `Accepted` 并开始异步执行。
- [x] **Implement Heartbeat**:
  - 在长耗时操作（如 Fetch）中，定期发送进度/心跳事件。
  - 已在 `WorkflowNodeRunner` 层面统一实现。

### Phase 4: 验证与测试 (Validation)
- [ ] **Unit Tests (Contracts/Orchestrator)**:
  - 验证 Ack 序列化/反序列化。
  - 验证 TaskMonitor 的超时逻辑（Mock 时间/Task）。
- [ ] **Component Test (Mock Provider)**:
  - 创建一个 Mock Provider，模拟：
    - 正常 ACK + 完成。
    - 正常 ACK + 半路 Crash（测试心跳丢失）。
    - 拒绝 ACK (Degraded)。
    - 根本不 ACK (Timeout)。
  - 验证 Orchestrator 在上述情况下的状态流转是否正确。

## 4. 预期效果
1. **快速失败**: 系统不再因为配置错误（如缺 Key）而 hang 住 5 分钟，而是毫秒级报错。
2. **自我修复**: 遇到网络波动导致的丢包，Orchestrator 能感知并（未来）触发重试。
3. **可观测性**: 能够清晰区分 "调度失败"、"拒绝执行" 和 "执行超时" 三种错误模式。
