# 历史报告功能实施前 Dry Run 报告

## 概览
本报告对“历史报告”功能的实施方案进行了全面的“Dry Run”检查。我们检查了后端服务 (`data-persistence-service`, `api-gateway`, `report-generator-service`) 和前端代码 (`schema.gen.ts`, UI 组件)，确认了所有必要的变更点和潜在的遗漏。

## 检查清单与发现 (Dry Run Findings)

### 1. 后端: Report Generator Service (Fix Missing Persistence)
*   **现状**: `run_vgcs_based_generation` 函数在生成报告后，仅提交到了 VGCS (Git)，没有调用 `persistence_client` 写入数据库。
*   **影响**: 数据库中没有记录，导致历史查询接口返回空列表。
*   **修正动作**:
    *   在 `worker.rs` 的 `run_vgcs_based_generation` 函数末尾（生成 commit 后），构建 `NewAnalysisResult` 结构体。
    *   调用 `persistence_client.create_analysis_result`。
    *   注意：`NewAnalysisResult` 需要 `module_id` 和 `template_id`，目前这些信息在 `command` 中是可选的 (`Option`)。在 `message_consumer.rs` 中解析 `WorkflowTaskCommand` 时，我们已经提取了这些信息并放入了 `GenerateReportCommand`。需要确保传递链路完整。

### 2. 后端: Data Persistence Service (Query Update)
*   **现状**:
    *   `AnalysisQuery` 结构体强制要求 `symbol: String`。
    *   DB 查询 `get_analysis_results` 强制 `WHERE symbol = $1`。
*   **修正动作**:
    *   修改 `AnalysisQuery`，将 `symbol` 改为 `Option<String>`。
    *   修改 `get_analysis_results` SQL，使其根据 symbol 是否存在动态构建 `WHERE` 子句（或者使用 `COALESCE` 技巧，但动态构建更清晰）。
    *   在 SQL 中强制加上 `LIMIT 10`（或者通过参数控制，为了简化本次只做最近10条，建议硬编码默认值或加 `limit` 参数）。

### 3. 后端: API Gateway (Endpoint Update)
*   **现状**:
    *   `AnalysisResultQuery` 结构体定义了 `symbol: String`。
    *   `get_analysis_results_by_symbol` 处理器绑定了该 Query。
    *   没有 `GET /api/v1/analysis-results/:id` 接口。
*   **修正动作**:
    *   修改 `AnalysisResultQuery` 为 `symbol: Option<String>`。
    *   更新 `get_analysis_results` 处理器以适应可选参数。
    *   新增 `get_analysis_result_by_id` 处理器，代理请求到 persistence service。
    *   **关键遗漏检查**: 确保 `utoipa` 的宏定义 (`#[utoipa::path(...)]`) 也同步更新，否则生成的 OpenAPI 文档不对，前端 schema 就不会更新。

### 4. 前端: Schema与API客户端
*   **现状**: `schema.gen.ts` 是自动生成的。
*   **动作**:
    *   后端修改完并启动后，运行脚本 `scripts/update_api_spec.sh` (或类似机制) 重新生成 `openapi.json`。
    *   前端运行 `npm run openapi-ts` 更新 `schema.gen.ts`。
    *   **确认**: `get_analysis_results` 的参数应变为可选，且新增 `get_analysis_result_by_id` 方法。

### 5. 前端: UI 组件
*   **Dashboard / Header**:
    *   需要新增 `RecentReportsDropdown` 组件。
    *   逻辑：Mount 时调用 `api.get_analysis_results()` (无参)，获取列表。
    *   渲染：下拉列表，点击项使用 `Link` 跳转。
*   **HistoricalReportPage**:
    *   新增路由 `/history/:id` 在 `App.tsx`。
    *   组件逻辑：获取 `id` 参数 -> 调用 `api.get_analysis_result_by_id({ id })` -> 渲染 Markdown。
    *   **复用**: 可以复用 `TaskDetailView` 中的 Markdown 渲染逻辑（样式一致性）。

## 风险评估与应对
*   **数据不一致**: 如果 Worker 写入 Git 成功但写入 DB 失败怎么办？
    *   *应对*: 记录 Error 日志。本次暂不引入复杂的分布式事务。DB 缺失仅导致历史列表少一条，不影响核心业务（报告已生成且在 Git 中）。
*   **Schema 类型不匹配**: 手动修改后端 struct 后，前端生成的 TS 类型可能报错。
    *   *应对*: 严格按照 `common-contracts` 定义 DTO，确保 `utoipa` 宏准确描述 `Option` 类型。

## 执行结论
计划可行。已识别关键遗漏（Worker 持久化缺失）。

**执行顺序**:
1.  **Fix Worker Persistence** (最关键，确保新数据能进去)
2.  **Update Persistence Service** (支持无 symbol 查询)
3.  **Update API Gateway** (暴露接口)
4.  **Update OpenAPI & Frontend Client**
5.  **Implement Frontend UI**

准备开始执行。

