# SSA-Pro 前端 UI 改进计划 - 审查回应

> **回应日期：** 2026-02-20  
> **回应人：** SSA 开发团队  
> **审查文档：** SSA-Pro 前端 UI 改进计划审查报告.md  
> **原计划文档：** 05-前端UI改进开发计划-V8双屏版.md

---

## 📋 总体评价

感谢审查团队的细致审核，总体评价 **A-** 及三个亮点（组件复用、职责拆分、Zustand 状态管理）的肯定，我们深感认可。

以下是对 5 个盲区的逐条回应：

---

## 盲区一：流式输出与右侧面板的"精准握手"

### 审查意见
> AI 正在打字输出时，右侧应该立刻切换到 SAPViewer，建议采用"特定标记解析"或"Tool Calling"机制。

### 回应：✅ 认可，补充到计划

**我们的方案**：采用 **Artifact 标记解析** 机制

```typescript
// AI 输出流中嵌入结构化标记
"我已为您生成分析方案：<Artifact type='sap' id='plan-001' />"

// useAIStream Hook 中增加解析逻辑
const handleChunk = (chunk: string) => {
  const artifactMatch = chunk.match(/<Artifact type='(\w+)' id='([^']+)' \/>/);
  if (artifactMatch) {
    const [_, type, id] = artifactMatch;
    ssaStore.setActivePane(type as 'sap' | 'execution' | 'result');
    ssaStore.loadArtifact(type, id);
  }
};
```

**已有能力支撑**：
- `useAIStream` Hook 已支持流式解析（见 `shared/components/Chat/hooks/useAIStream.ts`）
- 后端 `StreamingService` 已支持 OpenAI Compatible 格式

**计划更新**：在 Day 2 任务中新增"流式标记解析器"开发（预计 2h）

---

## 盲区二：历史记录回溯的"状态水合"

### 审查意见
> 用户点击历史记录时，右侧要瞬间恢复到当时最终的 ResultViewer 状态。

### 回应：✅ 部分认可，MVP 简化处理

**MVP 方案**：

| 步骤 | 处理方式 |
|------|---------|
| 1. 用户点击历史 | 左侧加载聊天记录 |
| 2. 右侧初始状态 | 显示 `empty`（空状态） |
| 3. 自动恢复 | 根据 session 数据判断最终状态，自动切换 |

**Store 扩展**：

```typescript
// ssaStore.ts 新增
hydrateFromHistory: (session: SSASession) => {
  // 根据 session 状态恢复右侧面板
  if (session.executionResult) {
    set({ activePane: 'result', currentArtifact: { type: 'result', data: session.executionResult } });
  } else if (session.currentPlan) {
    set({ activePane: 'sap', currentArtifact: { type: 'sap', data: session.currentPlan } });
  } else {
    set({ activePane: 'empty', currentArtifact: null });
  }
}
```

**后端配合**：现有 `GET /api/v1/ssa/sessions/:id` 已返回完整 session 数据（含 plan、result），无需修改。

**计划更新**：在 Store 设计章节补充 `hydrateFromHistory` action。

---

## 盲区三：响应式降级策略

### 审查意见
> 小屏幕（<1024px）双屏会拥挤，建议降级为抽屉或模态框。

### 回应：✅ 认可，但延后至 Phase 2

**理由**：
1. V8 原型图明确定位 **PC 端宽屏**（1280px+）
2. 目标用户为医院研究人员，主要使用 PC 办公
3. MVP 聚焦核心体验，响应式作为增强功能

**Phase 2 降级方案**（预留设计）：

```css
/* 小屏幕降级：右侧变为全屏 Drawer */
@media (max-width: 1024px) {
  .ssa-workspace {
    /* 隐藏右侧面板 */
    .artifact-pane { display: none; }
    
    /* 左侧全宽 */
    .chat-pane { width: 100%; }
  }
  
  /* 结果以 Drawer 形式弹出 */
  .artifact-drawer {
    position: fixed;
    right: 0;
    width: 90vw;
    height: 100vh;
  }
}
```

**计划更新**：在"风险与应对"章节注明响应式降级作为 Phase 2 任务。

---

## 盲区四：ExecutionViewer 的动态数据流机制

### 审查意见
> 未说明 ExecutionViewer 数据是轮询还是 SSE，建议明确技术方案。

### 回应：⚠️ 审查者对现有能力不了解

**现有能力**：

| 能力 | 位置 | 状态 |
|------|------|------|
| **useAIStream Hook** | `shared/components/Chat/hooks/useAIStream.ts` | ✅ 已实现 |
| **StreamingService** | `backend/src/common/streaming/` | ✅ 已实现 |
| **traceSteps 状态管理** | `ssaStore.ts` 第 32-35 行 | ✅ 已实现 |

```typescript
// 现有 ssaStore.ts
setTraceSteps: (steps: TraceStep[]) => void;
updateTraceStep: (index: number, step: Partial<TraceStep>) => void;
```

**SSA 执行日志的技术路径**：

| 方案 | 说明 | MVP 采用 |
|------|------|---------|
| **方案 A** | 对话流内嵌执行状态（复用 useAIStream） | ✅ 推荐 |
| **方案 B** | 独立 SSE 端点 | Phase 2 |
| **方案 C** | 同步返回 + 伪进度 | 备选 |

**推荐方案 A 示例**：

```
// AI 对话流中输出执行状态
data: {"choices":[{"delta":{"content":"🔍 正在检验正态性..."}}]}
data: {"choices":[{"delta":{"content":"✅ Shapiro-Wilk p=0.32，符合正态分布"}}]}
data: {"choices":[{"delta":{"content":"📊 正在执行独立样本 T 检验..."}}]}
data: {"choices":[{"delta":{"content":"<Artifact type='result' id='xxx' />"}}]}
```

**无需额外开发**：直接复用 `AIStreamChat` 组件，后端调整输出格式即可。

**计划更新**：在技术方案章节补充"执行日志数据流"说明。

---

## 盲区五：前端数据 Schema 解析前置

### 审查意见
> 建议前端用 papaparse 提取表头，拼接到 Prompt 发送给 Planner。

### 回应：❌ 不采纳，违背隐私架构

**SSA 隐私保护架构**（核心设计原则）：

```
真实数据绝不传给 LLM，只传脱敏后的 Schema
```

**正确的数据流**：

```
┌─────────┐     完整文件      ┌─────────┐    脱敏 Schema    ┌─────────┐
│  前端   │ ───────────────→ │  后端   │ ───────────────→ │  LLM    │
└─────────┘                   └─────────┘                   └─────────┘
                               ↑
                         DataParserService
                         ├── 隐藏稀有值 (<5)
                         ├── 模糊 Min/Max (N<10)
                         └── 脱敏处理
```

**如果前端解析 Schema 会发生什么**：

| 风险 | 说明 |
|------|------|
| 绕过隐私保护 | 原始 Schema 可能包含敏感分类值 |
| 脱敏逻辑分散 | 后端已有 `DataParserService`，前端重复实现 |
| 架构不一致 | 违背"后端统一控制"原则 |

**现有后端实现**：

```typescript
// backend/src/modules/ssa/services/DataParserService.ts
// 已实现：
// - 表头解析
// - 稀有值隐藏（<5）
// - Min/Max 模糊（N<10）
// - 脱敏 Schema 返回
```

**结论**：保持现有设计，不在前端解析 Schema。

---

## 📝 计划更新汇总

| 盲区 | 处理方式 | 计划更新内容 |
|------|---------|-------------|
| **盲区一** | ✅ 采纳 | Day 2 新增"流式标记解析器"任务 |
| **盲区二** | ✅ 部分采纳 | Store 设计章节补充 `hydrateFromHistory` |
| **盲区三** | ⏸️ 延后 | 风险章节注明 Phase 2 处理 |
| **盲区四** | 📝 澄清 | 技术方案章节补充执行日志数据流说明 |
| **盲区五** | ❌ 不采纳 | 无需修改，保持后端 Schema 解析 |

---

## 🎯 最终结论

1. **计划总体方向正确**，审查团队的 A- 评分符合实际
2. **盲区一、二、三** 的建议有价值，已纳入计划或延后处理
3. **盲区四** 审查者对现有 SSE 能力不了解，已澄清技术路径
4. **盲区五** 建议违背隐私架构设计，不予采纳

**准予启动开发！** 🚀

---

**回应人：** SSA 开发团队  
**日期：** 2026-02-20