feat(ssa): Complete QPER architecture - Query, Planner, Execute, Reflection layers
Implement the full QPER intelligent analysis pipeline: - Phase E+: Block-based standardization for all 7 R tools, DynamicReport renderer, Word export enhancement - Phase Q: LLM intent parsing with dynamic Zod validation against real column names, ClarificationCard component, DataProfile is_id_like tagging - Phase P: ConfigLoader with Zod schema validation and hot-reload API, DecisionTableService (4-dimension matching), FlowTemplateService with EPV protection, PlannedTrace audit output - Phase R: ReflectionService with statistical slot injection, sensitivity analysis conflict rules, ConclusionReport with section reveal animation, conclusion caching API, graceful R error classification End-to-end test: 40/40 passed across two complete analysis scenarios. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -0,0 +1,244 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user