103 lines
6.4 KiB
Markdown
103 lines
6.4 KiB
Markdown
# **SSA-Pro 前端 UI 改进计划 (V8版) 深度审查与风险排雷报告**
|
||
|
||
**审查对象：** 05-前端UI改进开发计划-V8双屏版.md
|
||
|
||
**审查时间：** 2026-02-19
|
||
|
||
**审查结论：** 🟢 **A- (方向精准，复用策略极佳，但缺乏复杂状态联动与降级方案细节)**
|
||
|
||
## **1\. 总体评价与亮点 (Highlights)**
|
||
|
||
这份开发计划有 3 个非常出色的地方，必须予以肯定：
|
||
|
||
1. **跨模块资产复用意识极强**：果断决定将 AIA 模块的 ResizableSplitPane 下沉到 shared/components，这能省去至少 2 天的拖拽和边界计算开发时间。
|
||
2. **组件职责拆分清晰**：ArtifactPane 作为容器，内部按状态分发 SAPViewer、ExecutionViewer、ResultViewer，这是非常标准的策略模式（Strategy Pattern），易于后期扩展（比如新增 MLViewer）。
|
||
3. **Zustand 状态管理切入点准确**：意识到了左右双屏需要全局状态管理来解耦。
|
||
|
||
## **2\. 技术盲区与改进建议 (Critical Blind Spots)**
|
||
|
||
结合 SSA-Pro 的实际业务需求（如流式响应、护栏动画、历史记录），当前计划在以下 5 个维度存在缺失，需要**立即补充到架构设计中**：
|
||
|
||
### **🚨 盲区一：左侧流式输出与右侧面板的“精准握手” (Stream-to-Artifact Sync)**
|
||
|
||
* **问题描述**：计划中未说明左侧聊天框 (ChatPane) 在接收大模型**流式响应 (Streaming)** 时，如何触发右侧面板 (ArtifactPane) 的切换。
|
||
* **业务场景**：AI 正在打字输出：“我为您生成了分析方案...”，此时右侧应该**立刻**切换到 SAPViewer，而不是等 AI 把整段话说完才切换。
|
||
* **技术挑战**：如果复用 AIA 的 AIStreamChat，它是如何解析带有结构化意图（如生成卡片指令）的 Markdown 流的？
|
||
* **改进建议**：
|
||
* 采用 **"特定标记解析"** 或 **"Tool Calling"** 机制。
|
||
* 必须在前端实现一个 Stream Interceptor（流拦截器）。当流中出现类似 \<Artifact type="sap"\> 的占位符时，立刻触发 ssaStore.setActivePane('sap')。
|
||
|
||
### **🚨 盲区二：历史记录回溯的“状态水合” (History Hydration)**
|
||
|
||
* **问题描述**：双屏模式下，如果用户点击了侧边栏的“历史记录（比如昨天的 T 检验）”，右侧面板该显示什么？
|
||
* **业务场景**：用户点击历史记录，不仅左侧要加载聊天记录，右侧还要**瞬间恢复**到当时最终的 ResultViewer 状态和图表数据。
|
||
* **改进建议**：
|
||
* ssaStore 中的状态必须是**可序列化和反序列化的**。
|
||
* 后端返回的历史会话接口 GET /sessions/:id 中，除了 messages 数组，必须包含 current\_artifact\_state。
|
||
* 在前端计划中增加任务：**"实现历史会话切换时的 Artifact 状态恢复逻辑"**。
|
||
|
||
### **🚨 盲区三：响应式降级策略完全缺失 (Responsive Downgrade)**
|
||
|
||
* **问题描述**：V8 计划只考虑了宽屏 PC。但如果用户在 13 寸小笔记本（屏幕宽度 \< 1200px）或平板上打开，双屏会极其拥挤，三线表会挤变形。
|
||
* **技术挑战**：如何让双屏设计在小屏幕下依然可用？
|
||
* **改进建议**：
|
||
* 引入 CSS 媒体查询 (@media) 或 Tailwind 的 lg: 断点。
|
||
* **降级方案**：当屏幕宽度小于 1024px 时，隐藏右侧 ArtifactPane，将其转化为一个 **全屏抽屉 (Drawer)** 或 **浮动模态框 (Modal)**。左侧气泡中增加一个明显的按钮：“点击查看结果面板”。
|
||
|
||
### **🚨 盲区四：ExecutionViewer 的动态数据流机制**
|
||
|
||
* **问题描述**：计划中提到了 ExecutionViewer（执行日志视图），但没有说明它的数据是怎么来的。
|
||
* **业务场景**：点击“执行”后，R 服务可能要跑 3-5 秒。这期间，护栏检查（正态性、方差）的状态是逐条出来的。
|
||
* **改进建议**：
|
||
* 明确采用 **轮询 (Polling)** 还是 **服务器推送 (SSE)**。
|
||
* 如果 MVP 阶段后端是同步阻塞返回（没有 SSE），前端 ExecutionViewer 必须实现一套 **“伪进度/骨架屏动画” (Simulated Progress)** 机制来安抚用户等待情绪，直到真实数据返回后再一次性渲染。
|
||
|
||
### **🚨 盲区五：前端数据 Schema 解析前置 (Client-side Schema Extraction)**
|
||
|
||
* **问题描述**：计划中提到了 DataMountZone，但未说明数据是如何解析的。
|
||
* **业务场景**：为了保护隐私，SSA-Pro 架构要求**真实数据不传给大模型，只传列名 (Schema)**。
|
||
* **改进建议**：
|
||
* 前端在 DataMountZone 组件中，必须集成轻量级的解析库（如 papaparse 处理 CSV，或使用 FileReader 提取前两行）。
|
||
* 在文件上传前，**前端先提取表头**，拼接到用户的 Prompt 中发送给 Planner。
|
||
|
||
## **3\. 架构师建议的 Store 结构补充**
|
||
|
||
为了支撑上述复杂的交互，建议在开发计划的 ssaStore.ts 部分，补充以下具体的 State 结构定义：
|
||
|
||
// 推荐的 ssaStore.ts 核心结构
|
||
interface SsaState {
|
||
// 1\. 全局模式与上下文
|
||
sessionId: string | null;
|
||
mode: 'consult' | 'analysis';
|
||
|
||
// 2\. 数据挂载状态
|
||
mountedData: {
|
||
fileName: string;
|
||
fileSize: number;
|
||
schema: string\[\]; // 表头数组 (关键)
|
||
ossKey?: string; // 上传后的引用
|
||
} | null;
|
||
|
||
// 3\. 右侧工作区状态 (The Artifacts)
|
||
activeArtifact: 'empty' | 'sap' | 'execution' | 'result';
|
||
artifactData: {
|
||
sap?: SapPlan; // AI 生成的计划
|
||
execution?: TraceLog\[\]; // 执行过程日志
|
||
result?: AnalysisResult; // 最终图表和三线表
|
||
};
|
||
|
||
// 4\. Actions
|
||
setMountedData: (data: any) \=\> void;
|
||
setActiveArtifact: (type: 'empty' | 'sap' | 'execution' | 'result', data?: any) \=\> void;
|
||
hydrateFromHistory: (sessionData: Session) \=\> void; // 解决盲区二
|
||
}
|
||
|
||
## **4\. 行动指南 (Next Steps)**
|
||
|
||
请前端负责人（Tech Lead）基于此报告，对原 05-前端UI改进开发计划-V8双屏版.md 进行如下补充：
|
||
|
||
1. **Phase 1 基建期**：增加对 ResizableSplitPane 小屏幕降级 (Drawer) 的设计。
|
||
2. **Phase 2 左侧期**：明确 DataMountZone 的纯前端解析表头逻辑。
|
||
3. **Phase 3 右侧期**：补充左右屏状态联动的联调计划，特别是流式响应过程中的触发时机。
|
||
|
||
**结论：** 计划非常优秀，只要把这几个“状态联动”的坑提前填平，这个 V8 版本的智能工作台将成为整个平台最惊艳的功能模块。准予在补充细节后启动开发！🚀 |