# 设计文档：统一历史记录与上下文管理重构

## 1. 目标
实现一个统一且一致的历史管理系统，达成以下目标：
1. **原子化历史记录**：一个“历史记录”严格对应**一次 Workflow 执行**（由 `request_id` 标识），彻底解决历史列表重复/碎片化问题。
2. **单一数据源**：全局上下文（VGCS/Git）作为所有文件产物（报告、日志、数据）的唯一真实存储源。
3. **轻量化索引**：数据库（`session_data` 或新表）仅存储结构化的“索引”（Snapshot），指向 VGCS 中的 Commit 和文件路径。

## 2. 现状分析
- **碎片化**：目前 `analysis_results` 表存储的是单个 Task 的结果。如果一个工作流包含 N 个分析步骤，历史列表中就会出现 N 条记录。
- **数据冗余**：结果内容（Markdown 等）既作为文件存在 VGCS 中，又作为文本列存在 Postgres 数据库中。
- **历史视图缺失**：缺乏一个能够代表整次执行状态（包含拓扑结构、状态、所有产物引用）的根对象，导致查询历史列表时困难。

## 3. 架构方案

### 3.1. 核心概念：工作流快照 (Workflow Snapshot)
不再将每个 Task 视为独立的历史记录，我们定义 **Workflow Snapshot** 为历史的原子单位。

一个 Snapshot 包含：
- **元数据**：`request_id`（请求ID）, `symbol`（标的）, `market`（市场）, `template_id`（模板ID）, `start_time`（开始时间）, `end_time`（结束时间）, `final_status`（最终状态）。
- **拓扑结构**：DAG 结构（节点与边）。
- **执行状态**：针对每个节点记录：
    - `status`：状态 (Completed, Failed, Skipped)
    - `output_commit`：该节点产生的 VGCS Commit Hash。
    - `artifacts`：产物映射表，Key 为产物名称，Value 为 VGCS 文件路径 (例如 `{"report": "analysis/summary.md", "log": "analysis/execution.log"}`)。

### 3.2. 数据存储变更

#### A. `workflow_history` 表 (或重构后的 `session_data`)
我们将引入一张专用表（或规范化 `session_data` 的使用）来存储 **Workflow Manifest**。

```sql
CREATE TABLE workflow_history (
    request_id UUID PRIMARY KEY,
    symbol VARCHAR(20) NOT NULL,
    market VARCHAR(10) NOT NULL,
    template_id VARCHAR(50),
    status VARCHAR(20) NOT NULL, -- 'Completed', 'Failed'
    start_time TIMESTAMPTZ NOT NULL,
    end_time TIMESTAMPTZ,
    
    -- Snapshot JSON 数据
    snapshot_data JSONB NOT NULL 
    -- {
    --   "dag": { ... },
    --   "tasks": {
    --     "task_id_1": { "status": "Completed", "commit": "abc1234", "paths": { "report": "..." } }
    --   }
    -- }
);
```

*注：为了减少迁移摩擦，我们可以继续使用 `session_data` 表，并指定 `data_type = 'workflow_snapshot'`，但建立专用表更有利于查询和维护。*

#### B. VGCS (Git 上下文) 的使用规范
- **输入**：初始 Commit 包含 `request.json`。
- **过程**：每个 Task (Worker) 检出基础 Commit，执行工作，写入文件（报告、日志），并创建 **New Commit**。
- **合并**：Orchestrator 负责追踪这些 Commit 的 DAG 关系。
- **终态**：Orchestrator 创建最终的“Merge Commit”（可选，或仅引用各叶子节点的 Commit）并在 `workflow_history` 中记录。

### 3.3. 组件职责划分

#### 1. Worker 服务 (Report Gen, Providers)
- **输入**：接收 `base_commit`, `task_id`, `output_path_config`。
- **动作**：
    - 初始化 `WorkerContext` (VGCS)。
    - 将 `report.md` 写入 `output_path`。
    - 将 `_execution.md` (日志) 写入 `log_path`。
    - **Commit**：提交更改，生成 Commit Hash。
- **输出**：返回 `new_commit_hash` 和 `artifact_paths` (Map<Name, Path>) 给 Orchestrator。
- **禁止**：Worker 不再直接向数据库的 `analysis_results` 表写入数据。

#### 2. Workflow Orchestrator (编排器)
- **协调**：从 `TaskCompleted` 事件中收集 `new_commit_hash` 和 `artifact_paths`。
- **状态追踪**：更新内存中的 DAG 状态。
- **完成处理**：
    - 当所有任务结束后，生成 **Workflow Snapshot**。
    - 调用 `persistence-service` 将 Snapshot 保存至 `workflow_history`。
    - 发送 `WorkflowCompleted` 事件。

#### 3. Data Persistence Service (持久化服务)
- **新接口**：`GET /api/v1/history`
    - 返回 `workflow_history` 列表（摘要信息）。
- **新接口**：`GET /api/v1/history/{request_id}`
    - 返回完整的 Snapshot（详情信息）。
- **旧接口处理**：废弃 `GET /api/v1/analysis-results` 或将其重定向为查询 `workflow_history`。

#### 4. Frontend (前端)
- **历史页**：调用 `/api/v1/history`。每个 `request_id` 只展示一行。
- **报告页**：
    - 获取特定的历史详情。
    - 使用 `artifact_paths` + `commit_hash` 通过 VGCS API (或代理)以此获取文件内容。

## 4. 实施计划

1.  **Schema 定义**：定义 `WorkflowSnapshot` 结构体及 SQL 迁移脚本 (`workflow_history`)。
2.  **Orchestrator 改造**：
    - 修改 `handle_task_completed` 以聚合 `artifact_paths`。
    - 实现 `finalize_workflow` 逻辑，用于构建并保存 Snapshot。
3.  **Worker 改造**：
    - 确保 `report-generator` 在 `TaskResult` 中返回结构化的 `artifact_paths`。
    - 移除 `report-generator` 中对 `create_analysis_result` 的数据库调用。
4.  **Persistence Service 改造**：
    - 实现 `workflow_history` 的 CRUD 操作。
5.  **Frontend 改造**：
    - 更新 API 调用以适配新的历史记录接口。

## 5. 核心收益
- **单一事实来源**：文件存 Git，元数据存 DB，杜绝数据不同步。
- **历史记录原子性**：一次运行 = 一条记录。
- **可追溯性**：每个产物都精确关联到一个 Git Commit。

