# 报告生成优化与 UI 状态反馈改进设计文档

**状态**: Draft
**日期**: 2025-11-19
**涉及模块**: Report Generator Service (Backend), Frontend (UI)

## 1. 背景与问题分析

当前系统的报告生成流程存在两个主要痛点，导致用户体验不佳且生成内容质量低下：

1.  **数据注入缺失 (Data Injection Gap)**: 
    *   后端在执行 Prompt 渲染时，`financial_data` 被硬编码为 `"..."`。
    *   大模型（LLM）缺乏上下文输入，导致输出“幻觉”内容（如自我介绍、复读指令）或通用废话。
    *   依赖链条虽然在拓扑排序上是正确的，但由于上游（如“基本面分析”）输出无效内容，下游（如“最终结论”）的输入也随之失效。

2.  **UI 状态反馈缺失 (UI/UX Gap)**: 
    *   前端仅有简单的“有数据/无数据”判断。
    *   点击“重新生成”时，UI 往往显示旧的缓存数据，缺乏“生成中”或“进度更新”的实时反馈。
    *   用户无法区分“旧报告”和“正在生成的新报告”。

## 2. 后端优化设计 (Report Generator Service)

### 2.1 数据注入逻辑修复 (Fixing Financial Data Injection)

我们将把当前的“基本面数据获取”视为一个**内置的基础工具（Native Tool）**。

*   **当前逻辑**: 直接透传数据库 Raw Data。
*   **改进逻辑**: 在 `worker.rs` 中实现一个数据格式化器，将 `Vec<TimeSeriesFinancialDto>` 转换为 LLM 易读的 Markdown 表格或结构化文本。

**实现细节**:
1.  **格式化函数**: 实现 `format_financials_to_markdown(financials: &[TimeSeriesFinancialDto]) -> String`。
    *   按年份/季度降序排列。
    *   提取关键指标（营收、净利润、ROE、毛利率等）。
    *   生成 Markdown Table。
2.  **注入 Context**:
    *   在 `Tera` 模板渲染前，调用上述函数。
    *   替换占位符: `context.insert("financial_data", &formatted_data);`。
3.  **上游依赖注入 (保持不变)**:
    *   继续保留现有的 `generated_results` 注入逻辑，确保上游模块（如 `market_analysis`）的输出能正确传递给下游（如 `final_conclusion`）。

### 2.2 执行状态管理 (Execution Status Management)

为了支持前端的“实时状态”，后端需要能够区分“排队中”、“生成中”和“已完成”。

*   **现状**: 只有生成完成后才写入 `analysis_results` 表。
*   **改进**: 引入任务状态流转。

**方案 A (基于数据库 - 推荐 MVP)**:
利用现有的 `analysis_results` 表或新建 `analysis_tasks` 表。
1.  **任务开始时**: 
    *   Worker 开始处理某个 `module_id` 时，立即写入/更新一条记录。
    *   `status`: `PROCESSING`
    *   `content`: 空或 "Analysis in progress..."
2.  **任务完成时**:
    *   更新记录。
    *   `status`: `COMPLETED`
    *   `content`: 实际生成的 Markdown。
3.  **任务失败时**:
    *   `status`: `FAILED`
    *   `content`: 错误信息。

### 2.3 未来扩展性：工具模块 (Future Tool Module)

*   当前设计中，`financial_data` 是硬编码注入的。
*   **未来规划**: 在 Prompt 模板配置中，增加 `tools` 字段。
    ```json
    "tools": ["financial_aggregator", "news_search", "calculator"]
    ```
*   Worker 在渲染 Prompt 前，先解析 `tools` 配置，并行执行对应的工具函数（如 Python 数据清洗脚本），获取输出后注入 Context。当前修复的 `financial_data` 本质上就是 `financial_aggregator` 工具的默认实现。

## 3. 前端优化设计 (Frontend)

### 3.1 状态感知与交互

**目标**: 让用户清晰感知到“正在生成”。

1.  **重新生成按钮行为**:
    *   点击“重新生成”后，**立即**将当前模块的 UI 状态置为 `GENERATING`。
    *   **视觉反馈**: 
        *   方案一（简单）：清空旧内容，显示 Skeleton（骨架屏）+ 进度条/Spinner。
        *   方案二（平滑）：保留旧内容，但在上方覆盖一层半透明遮罩，并显示“正在更新分析...”。(推荐方案二，避免内容跳动)。

2.  **状态轮询 (Polling)**:
    *   由于后端暂未实现 SSE (Server-Sent Events)，前端需采用轮询机制。
    *   当状态为 `GENERATING` 时，每隔 2-3 秒调用一次 API 检查该 `module_id` 的状态。
    *   当后端返回状态变更为 `COMPLETED` 时，停止轮询，刷新显示内容。

### 3.2 组件结构调整

修改 `AnalysisContent.tsx` 组件：

```typescript
interface AnalysisState {
  status: 'idle' | 'loading' | 'success' | 'error';
  data: string | null; // Markdown content
  isStale: boolean; // 标记当前显示的是否为旧缓存
}
```

*   **Idle**: 初始状态。
*   **Loading**: 点击生成后，显示加载动画。
*   **Success**: 获取到新数据。
*   **IsStale**: 点击重新生成瞬间，将 `isStale` 设为 true。UI 上可以给旧文本加灰色滤镜，直到新数据到来。

## 4. 实施计划 (Action Plan)

### Phase 1: 后端数据修正 (Backend Core)
- [ ] 修改 `services/report-generator-service/src/worker.rs`。
- [ ] 实现 `format_financial_data` 辅助函数。
- [ ] 将格式化后的数据注入 Tera Context。
- [ ] 验证大模型输出不再包含“幻觉”文本。

### Phase 2: 后端状态透出 (Backend API)
- [ ] 确认 `NewAnalysisResult` 或相关 DTO 是否支持状态字段。
- [ ] 在 Worker 开始处理模块时，写入 `PROCESSING` 状态到数据库。
- [ ] 确保 API 查询接口能返回 `status` 字段。

### Phase 3: 前端体验升级 (Frontend UI)
- [ ] 修改 `AnalysisContent.tsx`，增加对 `status` 字段的处理。
- [ ] 实现“重新生成”时的 UI 遮罩或 Loading 状态，不再单纯依赖 `useQuery` 的缓存。
- [ ] 优化 Markdown 渲染区的用户体验。

## 5. 验收标准 (Acceptance Criteria)

1.  **内容质量**: 市场分析、基本面分析报告中包含具体的财务数字（如营收、利润），且引用正确，不再出现“请提供数据”的字样。
2.  **流程闭环**: 点击“重新生成”，UI 显示加载状态 -> 后端处理 -> UI 自动刷新为新内容。
3.  **无闪烁**: 页面不会因为轮询而频繁闪烁，状态切换平滑。

