# 前端架构重构计划：状态管理与工作流控制权移交

## 1. 背景与现状
当前的 `fundamental-analysis` 前端项目源自一个 POC (Proof of Concept) 原型。在快速迭代过程中，遗留了大量“为了跑通流程而写”的临时逻辑。核心问题在于**前端承担了过多的业务控制逻辑**，导致前后端状态不一致、错误处理困难、用户体验割裂。

### 核心痛点
1.  **“自嗨式”状态流转**：前端自行判断何时从“数据获取”切换到“分析报告”阶段（基于轮询结果推断），而非响应后端的明确指令。
2.  **脆弱的 Polling + SSE 混合模式**：前端先轮询 HTTP 接口查询进度，再断开连接 SSE 流。这两者之间存在状态断层，且严重依赖 HTTP 接口的实时性（而这个接口又是后端实时聚合下游得来的，极易超时）。
3.  **缺乏统一的状态源 (Source of Truth)**：前端维护了一套复杂的 `ReportState`，后端也有一套状态，两者通过不稳定的网络请求同步，经常出现“前端显示完成，后端还在跑”或“后端报错，前端还在转圈”的情况。

## 2. 重构目标
**原则：前端归前端（UI展示），后端归后端（业务逻辑与流转控制）。**

1.  **控制权移交**：所有涉及业务流程流转（Phase Transition）的逻辑，必须由后端通过事件或状态字段明确驱动。前端只负责渲染当前状态。
2.  **单一数据流 (Single Stream)**：废除“HTTP Polling -> SSE”的混合模式，建立统一的 WebSocket 或 SSE 通道。从发请求那一刻起，所有状态变更（包括数据获取进度、分析进度、报错）全由服务端推送。
3.  **简化状态机**：前端 `useReportEngine` 钩子应简化为单纯的“状态订阅者”，不再包含复杂的判断逻辑（如 `if (tasks.every(t => t.success)) switchPhase()`）。

## 3. 实施方案 (Tasks)

### Phase 1: 后端基础设施准备 (Backend Readiness)
- [ ] **统一事件流接口**：在 `api-gateway` 实现一个统一的 SSE/WebSocket 端点（如 `/v2/workflow/events`）。
    - 该端点应聚合：`DataFetchProgress` (NATS), `WorkflowStart` (NATS), `ModuleProgress` (ReportGenerator), `WorkflowComplete`。
- [ ] **Gateway 状态缓存**：`api-gateway` 需要维护一个轻量级的 Request 状态缓存（Redis 或 内存），不再实时透传查询请求给下游 Provider，而是直接返回缓存的最新状态。
- [ ] **定义统一状态协议**：制定前后端通用的状态枚举（`PENDING`, `DATA_FETCHING`, `ANALYZING`, `COMPLETED`, `FAILED`）。

### Phase 2: 前端逻辑剥离 (Frontend Refactoring)
- [ ] **废除 useReportEngine 里的推断逻辑**：删除所有 `useEffect` 里关于状态切换的 `if/else` 判断代码。
- [ ] **实现 Event-Driven Hook**：重写 `useReportEngine`，使其核心逻辑变为：连接流 -> 收到事件 -> 更新 State。
    - 收到 `STATUS_CHANGED: DATA_FETCHING` -> 显示数据加载 UI。
    - 收到 `STATUS_CHANGED: ANALYZING` -> 自动切换到分析 UI（无需前端判断数据是否齐备）。
    - 收到 `ERROR` -> 显示错误 UI。
- [ ] **清理旧代码**：移除对 `/api/tasks` 轮询的依赖代码。

### Phase 3: 验证与兜底
- [ ] **断线重连机制**：实现 SSE/WS 的自动重连，并能从后端获取“当前快照”来恢复状态，防止刷新页面丢失进度。
- [ ] **超时兜底**：仅保留最基本的网络超时提示（如“服务器连接中断”），不再处理业务逻辑超时。

## 4. 复杂度评估与建议
- **复杂度**：中等偏高 (Medium-High)。涉及前后端协议变更和核心 Hook 重写。
- **风险**：高。这是系统的心脏部位，重构期间可能会导致整个分析流程暂时不可用。
- **建议**：**单独开一个线程（Branch/Session）进行**。不要在当前修复 Bug 的线程中混合进行。这需要系统性的设计和逐步替换，无法通过简单的 Patch 完成。

---
*Created: 2025-11-20*

