# Backend Requirements for Frontend Refactor

由于前端正在进行“破坏式”重构，删除了所有包含业务逻辑控制、状态推断、流程编排的代码（如 `useReportEngine`, `ExecutionStepManager`），后端必须接管以下职责，以支持纯被动式（Puppet Mode）的前端。

## 1. 核心原则
前端不再拥有“大脑”，只拥有“眼睛”和“耳朵”。所有状态变更、流程流转、错误判断全由后端指令驱动。

## 2. 接口需求

### 2.1 统一事件流 (Unified Event Stream)
前端将只连接**一个**长连接通道（SSE 或 WebSocket），用于接收整个分析周期的所有信息。

*   **Endpoint**: `/api/v2/workflow/events?request_id={id}` (建议)
*   **职责**: 聚合 NATS (Data Fetching), Internal State (Report Generator), Database (Persistence) 的所有事件。

### 2.2 事件类型定义 (Protocol)
后端需要推送以下类型的事件，且 Payload 必须包含前端渲染所需的所有上下文，前端不再发起二次请求查询详情。

1.  **`WORKFLOW_START`**
    *   标志流程开始。
    *   Payload: `{ symbol, market, template_id, timestamp }`

2.  **`PHASE_CHANGED`**
    *   **关键**: 前端不再判断何时切换界面，完全依赖此事件。
    *   Payload: `{ phase: 'DATA_FETCHING' | 'ANALYZING' | 'COMPLETED' | 'FAILED', previous_phase: '...' }`

3.  **`TASK_PROGRESS` (Data Fetching Phase)**
    *   替代前端轮询 `/api/tasks`。
    *   Payload: `{ task_id, provider, status, progress, message }`
    *   **注意**: 后端需负责聚合多个 Provider 的进度，前端只管展示列表。

4.  **`MODULE_PROGRESS` (Analysis Phase)**
    *   替代旧的 SSE 流。
    *   Payload: `{ module_id, content_delta, status }`

5.  **`WORKFLOW_ERROR`**
    *   **关键**: 包含错误级别（Fatal/Warning）。前端只展示，不判断是否重试。
    *   Payload: `{ code, message, is_fatal, suggestion }`

## 3. 逻辑接管需求

### 3.1 状态机迁移 (State Transitions)
*   **旧逻辑 (已删)**: 前端轮询任务 -> `if (all_tasks_done) start_analysis()`.
*   **新逻辑**: 后端 `Workflow Orchestrator` 监听任务完成事件 -> 自动触发分析 -> 推送 `PHASE_CHANGED: ANALYZING` 给前端。

### 3.2 容错与部分成功 (Partial Success)
*   **旧逻辑 (已删)**: 前端判断 `if (failed_tasks < total) continue`.
*   **新逻辑**: 后端决定数据缺失量是否允许继续分析。如果允许，直接进入分析阶段；如果不允许，推送 `WORKFLOW_ERROR`。

### 3.3 超时控制 (Timeout)
*   **旧逻辑 (已删)**: 前端 `setTimeout(10min)`.
*   **新逻辑**: 后端设置执行超时。如果超时，主动推送 Error 事件关闭连接。前端仅处理网络层面的断开重连。

### 3.4 断点恢复 (Resume)
*   **需求**: 当用户刷新页面重连 SSE 时，后端必须立即推送一条 `SNAPSHOT` 事件，包含当前所有已完成的任务、已生成的报告片段、当前所处的阶段。
*   **目的**: 防止前端因为丢失历史事件而无法渲染完整界面。

## 4. 废弃接口
以下接口的前端调用代码已被删除，后端可酌情保留用于调试，但业务不再依赖：
*   `GET /api/tasks/{id}` (轮询接口)
*   `GET /api/analysis-results/stream` (旧的纯分析流，需升级为统一流)