Files

HaHafeng 371e1c069c 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>

2026-02-21 18:15:53 +08:00

6.4 KiB

Raw Blame History

SSA-Pro 前端 UI 改进计划 (V8版) 深度审查与风险排雷报告

审查对象： 05-前端UI改进开发计划-V8双屏版.md

审查时间： 2026-02-19

审查结论： 🟢 A- (方向精准，复用策略极佳，但缺乏复杂状态联动与降级方案细节)

1. 总体评价与亮点 (Highlights)

这份开发计划有 3 个非常出色的地方，必须予以肯定：

跨模块资产复用意识极强：果断决定将 AIA 模块的 ResizableSplitPane 下沉到 shared/components，这能省去至少 2 天的拖拽和边界计算开发时间。
组件职责拆分清晰：ArtifactPane 作为容器，内部按状态分发 SAPViewer、ExecutionViewer、ResultViewer，这是非常标准的策略模式（Strategy Pattern），易于后期扩展（比如新增 MLViewer）。
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 进行如下补充：

Phase 1 基建期：增加对 ResizableSplitPane 小屏幕降级 (Drawer) 的设计。
Phase 2 左侧期：明确 DataMountZone 的纯前端解析表头逻辑。
Phase 3 右侧期：补充左右屏状态联动的联调计划，特别是流式响应过程中的触发时机。

结论： 计划非常优秀，只要把这几个“状态联动”的坑提前填平，这个 V8 版本的智能工作台将成为整个平台最惊艳的功能模块。准予在补充细节后启动开发！🚀

6.4 KiB Raw Blame History Unescape Escape