# 设计方案 0: 系统总览与开发指南 (Overview & Setup)

## 1. 项目背景 (Context)

本项目是一个 **金融基本面分析系统 (Fundamental Analysis System)**。
目标是通过自动化的工作流，从多个数据源（Tushare, YFinance）抓取数据，经过处理，最终生成一份包含估值、风险分析的综合报告。

本次重构旨在解决原系统调度逻辑僵化、上下文管理混乱、大文件支持差的问题。我们将构建一个基于 **Git 内核** 的分布式上下文管理系统。

## 2. 系统架构 (Architecture)

系统由四个核心模块组成：

1.  **VGCS (Virtual Git Context System)**: 底层存储。基于 Git + Blob Store 的版本化文件系统。
2.  **DocOS (Document Object System)**: 逻辑层。提供“文档树”的裂变、聚合操作，屏蔽底层文件细节。
3.  **Worker Runtime**: 适配层。提供 SDK 给业务 Worker（Python/Rust），使其能读写上下文。
4.  **Orchestrator**: 调度层。负责任务分发、依赖管理和并行结果合并。

```mermaid
graph TD
    subgraph "Storage Layer (Shared Volume)"
        Repo[Git Bare Repo]
        Blob[Blob Store]
    end

    subgraph "Library Layer (Rust Crate)"
        VGCS[VGCS Lib] --> Repo & Blob
        DocOS[DocOS Lib] --> VGCS
    end

    subgraph "Execution Layer"
        Orch[Orchestrator Service] --> DocOS
        Worker[Python/Rust Worker] --> Runtime[Worker Runtime SDK]
        Runtime --> DocOS
    end

    Orch -- NATS (RPC) --> Worker
```

## 3. 技术栈规范 (Tech Stack)

### 3.1 Rust (VGCS, DocOS, Orchestrator)
*   **Version**: Stable (1.75+)
*   **Key Crates**:
    *   `git2` (0.18): libgit2 bindings. **注意**: 默认开启 `vendored-openssl` feature 以确保静态链接。
    *   `serde`, `serde_json`: 序列化。
    *   `thiserror`, `anyhow`: 错误处理。
    *   `async-nats` (0.33): 消息队列。
    *   `tokio` (1.0+): 异步运行时。
    *   `sha2`, `hex`: 哈希计算。

### 3.2 Python (Worker Runtime)
*   **Version**: 3.10+
*   **Package Manager**: Poetry
*   **Key Libs**:
    *   `nats-py`: NATS Client.
    *   `pydantic`: 数据验证。
    *   (可选) `libgit2-python`: 如果需要高性能 Git 操作，否则通过 FFI 调用 Rust Lib 或 Shell Out。

## 4. 开发环境搭建 (Dev Setup)

### 4.1 目录准备
在本地开发机上，我们需要模拟共享存储。
```bash
mkdir -p /tmp/workflow_dev/repos
mkdir -p /tmp/workflow_dev/blobs
export WORKFLOW_DATA_PATH=/tmp/workflow_dev
```

### 4.2 Docker 环境
为了确保一致性，所有服务应在 Docker Compose 中运行，挂载同一个 Volume。
```yaml
volumes:
  workflow_data:

services:
  orchestrator:
    image: rust-builder
    volumes:
      - workflow_data:/mnt/workflow_data
    environment:
      - WORKFLOW_DATA_PATH=/mnt/workflow_data
```

## 5. 模块集成方式
*   **VGCS & DocOS**: 将实现为一个独立的 Rust Workspace Member (`crates/workflow-context`)。
*   **Orchestrator**: 引用该 Crate。
*   **Worker (Rust)**: 引用该 Crate。
*   **Worker (Python)**: 通过 `PyO3` 绑定该 Crate，或者（MVP阶段）重写部分逻辑/Shell调用。**建议 MVP 阶段 Python SDK 仅封装 git binary 调用以简化构建**。

## 6. 新人上手路径
1.  阅读 `design_1_vgcs.md`，理解如何在不 clone 的情况下读写 git object。
2.  阅读 `design_2_doc_os.md`，理解“文件变目录”的逻辑。
3.  实现 Rust Crate `workflow-context` (包含 VGCS + DocOS)。
4.  编写单元测试，验证 File -> Blob 的分流逻辑。
5.  集成到 Orchestrator。

