# 设计方案 4: Workflow Orchestrator (调度器) [详细设计版]

## 1. 定位与目标

Orchestrator 负责 DAG 调度、RPC 分发和冲突合并。它使用 Rust 实现。

**核心原则：**
*   **Git as Source of Truth**: 所有的任务产出（数据、报告）均存储在 VGCS (Git) 中。
*   **数据库轻量化**: 数据库仅用于存储系统配置、TimeSeries 缓存以及 Request ID 与 Git Commit Hash 的映射。Workflow 执行过程中不依赖数据库进行状态流转。
*   **Context 隔离**: 每次 Workflow 启动均为全新的 Context（或基于特定 Snapshot），无全局共享 Context。

## 2. 调度逻辑规范

### 2.1 RPC Subject 命名
基于 NATS。
*   **Command Topic**: `workflow.cmd.{routing_key}`
    *   e.g., `workflow.cmd.provider.tushare`
    *   e.g., `workflow.cmd.analysis.report`
*   **Event Topic**: `workflow.evt.task_completed` (统一监听)

### 2.2 Command Payload Schema

```json
{
  "request_id": "uuid-v4",
  "task_id": "fetch_tushare",
  "routing_key": "provider.tushare",
  "config": {
    "market": "CN",
    "years": 5
    // Provider Specific Config
  },
  "context": {
    "base_commit": "a1b2c3d4...", // Empty for initial task
    "mount_path": "/Raw Data/Tushare" 
    // 指示 Worker 建议把结果挂在哪里
  },
  "storage": {
    "root_path": "/mnt/workflow_data"
  }
}
```

### 2.3 Event Payload Schema

```json
{
  "request_id": "uuid-v4",
  "task_id": "fetch_tushare",
  "status": "Completed",
  "result": {
    "new_commit": "e5f6g7h8...",
    "error": null
  }
}
```

## 3. 合并策略 (Merge Strategy) 实现

### 3.1 串行合并 (Fast-Forward)
DAG: A -> B
1.  A returns `C1`.
2.  Orchestrator dispatch B with `base_commit = C1`.

### 3.2 并行合并 (Three-Way Merge)
DAG: A -> B, A -> C. (B, C parallel)
1.  Dispatch B with `base_commit = C1`.
2.  Dispatch C with `base_commit = C1`.
3.  B returns `C2`. C returns `C3`.
4.  **Merge Action**:
    *   Wait for BOTH B and C to complete.
    *   Call `VGCS.merge_trees(base=C1, ours=C2, theirs=C3)`.
    *   Result: `TreeHash T4`.
    *   Create Commit `C4` (Parents: C2, C3).
5.  Dispatch D (dependent on B, C) with `base_commit = C4`.

### 3.3 冲突处理
如果 `VGCS.merge_trees` 返回 Error (Conflict):
1.  Orchestrator 捕获错误。
2.  标记 Workflow 状态为 `Conflict`.
3.  (Future) 触发 `ConflictResolver` Agent，传入 C1, C2, C3。Agent 生成 C4。

## 4. 状态机重构
废弃旧的 `WorkflowStateMachine` 中关于 TaskType 的判断。
引入 `CommitTracker`:
```rust
struct CommitTracker {
    // 记录每个任务产出的 Commit
    task_commits: HashMap<TaskId, String>,
    // 记录当前主分支的 Commit (Latest Merged)
    head_commit: String,
}
```

## 5. 执行计划
1.  **Contract**: 定义 Rust Structs for RPC Payloads.
2.  **NATS**: 实现 Publisher/Subscriber。
3.  **Engine**: 实现 Merge Loop。

## 6. 数据持久化与缓存策略 (Persistence & Caching)

### 6.1 数据库角色 (Database Role)
数据库不再作为业务数据的“主存储”，其角色转变为：
1.  **Configuration**: 存储系统运行所需的配置信息。
2.  **Cache (Hot Data)**: 缓存 Data Provider 抓取的原始数据 (Time-series)，避免重复调用外部 API。
3.  **Index**: 存储 `request_id` -> `final_commit_hash` 的映射，作为系统快照的索引。

### 6.2 Provider 行为模式
Provider 在接收到 Workflow Command 时：
1.  **Check Cache**: 检查本地 DB/Cache 是否有有效数据。
2.  **Fetch (If miss)**: 如果缓存未命中，调用外部 API 获取数据并更新缓存。
3.  **Inject to Context**: 将数据写入当前的 VGCS Context (via `WorkerRuntime`)，生成新的 Commit。
    *   *注意*: Provider 不直接将此次 Workflow 的结果“存”回数据库的业务表，数据库仅作 Cache 用。

### 6.3 Orchestrator 行为
Orchestrator 仅负责追踪 Commit Hash 的演变。
Workflow 结束时，Orchestrator 将最终的 `Head Commit Hash` 关联到 `Request ID` 并持久化（即“Snapshot 落盘”）。
