# 分析模板集成设计文档

## 1. 概述
系统正在从单一、固定的分析配置架构向多模板架构迁移。目前，后端已支持 `AnalysisTemplateSets` 并能执行特定的模板。然而，前端在渲染报告标签页（Tabs）和触发分析时，仍然依赖于过时的 `AnalysisModulesConfig`（单一配置集）。

本文档概述了将“分析模板”完全集成到用户工作流中所需的变更，具体包括：
1.  **触发分析**：在启动新的分析任务时选择特定的模板。
2.  **报告展示**：根据分析所使用的模板，动态渲染标签页和内容。

## 2. 当前状态 vs. 目标状态

| 功能特性 | 当前状态 | 目标状态 |
| :--- | :--- | :--- |
| **配置管理** | `useAnalysisConfig` (过时，单一模块列表) | `useAnalysisTemplateSets` (多套具名模板) |
| **触发分析** | `trigger(symbol, market)` (无模板选择) | `trigger(symbol, market, templateId)` |
| **报告标签页** | 硬编码遍历过时的 `analysis_modules` keys | 根据报告使用的**特定模板**动态生成标签页 |
| **模块名称** | 从全局默认配置获取 | 从所使用的特定模板配置中获取 |

## 3. 详细设计

### 3.1. 后端变更

#### 3.1.1. API Gateway (`api-gateway`)
*   **Endpoint**: `POST /api/data-requests`
*   **变更**: 更新请求 DTO (Data Transfer Object) 以接收可选参数 `template_id: String`。
*   **逻辑**: 将此 `template_id` 通过 `GenerateReportCommand` 向下传递给 `report-generator-service`。

#### 3.1.2. 数据持久化 / 报告数据
*   **需求**: 前端需要知道生成某份报告时具体使用了*哪个*模板，以便正确渲染标签页（包括标题和顺序）。
*   **变更**: 确保 `GET /api/financials/...` 或 `GET /api/reports/...` 的响应数据中，在 metadata 中包含 `template_id`。
*   **实现**: 前端 `route.ts` 聚合层通过查询 `analysis-results` 获取最新的 `template_id` 并注入到 `meta` 中。

### 3.2. 前端变更

#### 3.2.1. API Hooks (`useApi.ts`)
*   **`useDataRequest`**: 更新 `trigger` 函数签名：
    ```typescript
    trigger(symbol: string, market: string, templateId?: string)
    ```
*   **`useAnalysisTemplateSets`**: 确保此 hook 可用（目前代码中已存在）。

#### 3.2.2. 触发 UI (报告页侧边栏 / 查询页)
*   **组件**: 在“触发分析”按钮旁增加一个 `TemplateSelector` (选择框/下拉菜单)。
*   **数据源**: `useAnalysisTemplateSets`。
*   **默认值**: 自动选中第一个可用的模板，或者标记为 "default" 的模板。

#### 3.2.3. 报告页面 (`frontend/src/app/report/[symbol]/page.tsx`)
这是最复杂的变更部分。我们需要重构标签页（Tabs）的生成逻辑。

1.  **移除旧逻辑**:
    *   移除对 `useAnalysisConfig` (全局默认配置) 的依赖。
    *   弃用/移除 `runAnalysesSequentially` (旧的前端编排流程)。

2.  **识别模板**:
    *   从获取到的财务/报告数据中读取 `template_id` (例如 `financials.meta.template_id` 或类似位置)。
    *   **Strict Mode**: 如果缺失 `template_id`，则视为严重数据错误，前端直接报错停止渲染，**绝不进行默认值回退或自动推断**。

3.  **动态标签页**:
    *   使用 `useAnalysisTemplateSets` 获取 `templateSets`。
    *   从 `templateSets[currentTemplateId].modules` 中推导出 `activeModules` 列表。
    *   遍历 `activeModules` 来生成 `TabsTrigger` 和 `TabsContent`。
    *   **显示名称**: 使用 `moduleConfig.name`。
    *   **排序**: 严格遵循模板中定义的顺序（或依赖顺序）。

### 3.3. 数据流

1.  **用户**选择 "标准分析模板 V2" (Standard Analysis V2) 并点击 "运行"。
2.  **前端**调用 `POST /api/data-requests`，载荷为 `{ ..., template_id: "standard_v2" }`。
3.  **后端**使用 "standard_v2" 中定义的模块生成报告。
4.  **前端**轮询任务进度。
5.  **前端**获取完成的数据。数据包含元数据 `meta: { template_id: "standard_v2" }`。
6.  **前端**查询 "standard_v2" 的配置详情。
7.  **前端**渲染标签页：如 "公司简介"、"财务健康"（均来自 V2 配置）。

## 4. 实施步骤

1.  **后端更新**:
    *   验证 `api-gateway` 是否正确传递 `template_id`。
    *   验证报告 API 是否在 metadata 中返回 `template_id`。

2.  **前端 - 触发**:
    *   更新 `useDataRequest` hook。
    *   在 `ReportPage` 中添加 `TemplateSelector` 组件。

3.  **前端 - 展示**:
    *   重构 `ReportPage` 以使用 `templateSets`。
    *   根据报告中的 `template_id` 动态计算 `analysisTypes`。

## 5. 待办事项列表 (To-Do List)

### Phase 1: 后端与接口 (Backend & API)
- [x] **1.1 更新请求 DTO (api-gateway)**
    - 目标: `api-gateway` 的 `DataRequest` 结构体
    - 动作: 增加 `template_id` 字段 (Option<String>)
    - 验证: `curl` 请求带 `template_id` 能被解析
- [x] **1.2 传递 Command (api-gateway -> report-service)**
    - 目标: `GenerateReportCommand` 消息
    - 动作: 确保 `template_id` 被正确透传到消息队列或服务调用中
- [x] **1.3 验证报告元数据 (data-persistence)**
    - 目标: `GET /api/financials/...` 接口
    - 动作: 检查返回的 JSON 中 `meta` 字段是否包含 `template_id`
    - 备注: 已通过 frontend `route.ts` 聚合实现

### Phase 2: 前端逻辑 (Frontend Logic)
- [x] **2.1 更新 API Hook**
    - 文件: `frontend/src/hooks/useApi.ts`
    - 动作: 修改 `useDataRequest` 的 `trigger` 方法签名，支持 `templateId` 参数
- [x] **2.2 移除旧版依赖**
    - 文件: `frontend/src/app/report/[symbol]/page.tsx`
    - 动作: 移除 `useAnalysisConfig` 及相关旧版逻辑 (`runAnalysesSequentially`)

### Phase 3: 前端界面 (Frontend UI)
- [x] **3.1 实现模板选择器**
    - 文件: `frontend/src/app/report/[symbol]/page.tsx` (侧边栏)
    - 动作: 添加 `<Select>` 组件，数据源为 `useAnalysisTemplateSets`
    - 逻辑: 默认选中第一个模板，点击"触发分析"时传递选中的 ID
- [x] **3.2 动态渲染标签页**
    - 文件: `frontend/src/app/report/[symbol]/page.tsx` (主区域)
    - 动作:
        1. 从 `financials.meta.template_id` 获取当前报告的模板 ID
        2. 若 ID 缺失直接抛出错误 (Strict Mode)
        3. 根据 ID 从 `templateSets` 获取模块列表
        4. 遍历模块列表渲染 `<TabsTrigger>` 和 `<TabsContent>`
        5. 内容从 `useAnalysisResults` hook 获取

### Phase 4: 验证与清理 (Verification)
- [ ] **4.1 端到端测试**
    - 动作: 创建新模板 -> 选择该模板触发分析 -> 验证报告页只显示该模板定义的模块
- [x] **4.2 代码清理**
    - 动作: 删除未使用的旧版配置 Hook 和类型定义
