fix(ssa): Fix 7 integration bugs and refactor frontend unified state management

Bug fixes: - Fix garbled error messages in chat (TypeWriter rendering issue) - Fix R engine NA crash in descriptive.R (defensive isTRUE/is.na checks) - Fix intent misclassification for statistical significance queries - Fix step 2 results not displayed (accept warning status alongside success) - Fix incomplete R code download (only step 1 included) - Fix multi-task state confusion (clicking old card shows new results) - Add R engine and backend parameter logging for debugging Refactor - Unified Record Architecture: - Replace 12 global singleton fields with AnalysisRecord as single source of truth - Remove isWorkflowMode branching across all components - One Analysis = One Record = N Steps paradigm - selectRecord only sets currentRecordId, all rendering derives from currentRecord - Fix cross-hook-instance issue: executeWorkflow fallback to store currentRecordId Updated files: ssaStore, useWorkflow, useAnalysis, SSAChatPane, SSAWorkspacePane, SSACodeModal, WorkflowTimeline, QueryService, WorkflowExecutorService, descriptive.R Tested: Manual integration test passed - multi-task switching, R code completeness Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-21 22:58:59 +08:00
parent 371e1c069c
commit 11676f2840
17 changed files with 1573 additions and 1829 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
+++ b/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
@@ -1,19 +1,17 @@
 # SSA智能统计分析模块 - 当前状态与开发指南

-> **文档版本：** v2.0  
+> **文档版本：** v2.1  
 > **创建日期：** 2026-02-18  
 > **最后更新：** 2026-02-21  
 > **维护者：** 开发团队  
-> **当前状态：** 🎉 **QPER 智能化主线闭环完成！Q→P→E→R 端到端 40/40 通过**  
+> **当前状态：** 🎉 **QPER 主线闭环 + 集成测试通过 + 统一状态管理重构完成**  
 > **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
 > 
-> **🎉 重大里程碑（2026-02-21）：**
-> - ✅ **QPER 四层架构主线闭环** — Phase E+ / Q / P / R 全部完成，93.5h 计划工时
-> - ✅ **端到端测试 40/40 通过** — 两条完整链路（差异比较 + 相关分析）全部跑通
-> - ✅ **LLM 智能意图理解** — 自然语言→四维信息提取，Confidence=0.95
-> - ✅ **配置化决策表驱动** — JSON 驱动方法选择，热更新 API，方法学团队可配置
-> - ✅ **LLM 论文级结论生成** — 6 要素结论 + 槽位注入反幻觉 + Zod 强校验 + 敏感性冲突准则
-> - ✅ **四层降级体系** — 每层 LLM 失败时自动 fallback，系统不中断
+> **最新进展（2026-02-21 晚）：**
+> - ✅ **前后端集成测试** — 7 个 Bug 全部修复（R 引擎防御、意图识别、前端状态）
+> - ✅ **统一状态管理重构** — 消除 isWorkflowMode 双轨逻辑，AnalysisRecord 成为唯一数据源
+> - ✅ **多任务切换** — 点击不同卡片正确显示各自的分析计划和结果
+> - ✅ **R 代码完整性** — 多步骤分析的所有步骤代码均可下载/复制

 ---

@@ -26,9 +24,10 @@
 | **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
 | **模块定位** | AI驱动的"白盒"统计分析系统 |
 | **架构模式** | **QPER — Query → Planner → Execute → Reflection** |
+| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
 | **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
 | **目标用户** | 临床研究人员、生物统计师 |
-| **开发状态** | 🎉 **QPER 主线闭环完成，Phase Deploy 待启动** |
+| **开发状态** | 🎉 **QPER 主线闭环 + 集成测试通过，Phase Deploy 待启动** |

 ### 核心目标

@@ -79,6 +78,38 @@

 ---

+## 🎨 前端架构：统一状态管理
+
+> **2026-02-21 重构完成** — 消除 isWorkflowMode 双轨逻辑
+
+### 数据模型
+
+```typescript
+AnalysisRecord {
+  id: string;                    // = workflowId or generated
+  query: string;                 // 用户原始问题
+  createdAt: string;
+  status: 'planning' | 'executing' | 'completed' | 'error';
+  plan: WorkflowPlan | null;     // 统一用 WorkflowPlan（单步也是 1 步的 Plan）
+  steps: WorkflowStepResult[];   // 统一用步骤数组
+  progress: number;              // 0-100
+  conclusionReport: ConclusionReport | null;
+}
+```
+
+### Store 结构
+
+- `analysisHistory: AnalysisRecord[]` — 所有分析记录
+- `currentRecordId: string | null` — 当前激活的记录
+- 派生：`currentRecord = analysisHistory.find(r => r.id === currentRecordId)`
+- 操作：`addRecord(query, plan)` / `updateRecord(id, patch)` / `selectRecord(id)`
+
+### 已删除的全局字段
+
+`currentPlan`、`executionResult`、`traceSteps`、`workflowPlan`、`workflowSteps`、`workflowProgress`、`conclusionReport`、`isWorkflowMode` 及所有对应 setter。
+
+---
+
 ## 📋 开发进度

 | Phase | 任务 | 工时 | 状态 | 完成日期 |
@@ -91,21 +122,23 @@
 | **Phase Q** | **LLM 意图理解** | **33h** | ✅ **已完成** | 2026-02-21 |
 | **Phase P** | **决策表 + 流程模板** | **23h** | ✅ **已完成** | 2026-02-21 |
 | **Phase R** | **LLM 论文级结论** | **22h** | ✅ **已完成** | 2026-02-21 |
+| **集成测试** | **Bug 修复 + 统一状态管理重构** | **~4h** | ✅ **已完成** | 2026-02-21 |
 | Phase Deploy | 工具补齐 + 部署上线 | 37h | 📋 待开始 | - |
 | Phase Q+ | 人机协同增强 | 20h | 📋 待开始 | - |
+| **QPER 透明化** | **Pipeline 可观测性增强** | TBD | 📋 待开始 | - |

 ### 已完成核心功能

 | 组件 | 完成项 | 状态 |
 |------|--------|------|
-| **R 服务** | 7 个 R 工具（T 检验、描述统计、卡方、Logistic、相关分析等）+ Block-based 输出 | ✅ |
-| **Q 层** | QueryService + LLM Intent + Zod 动态防幻觉 + 追问卡片 + DataProfile 增强 | ✅ |
+| **R 服务** | 7 个 R 工具 + Block-based 输出 + 防御性编程（NA 安全） | ✅ |
+| **Q 层** | QueryService + LLM Intent + Zod 防幻觉 + 追问卡片 + 统计学意义关键词增强 | ✅ |
 | **P 层** | ConfigLoader + DecisionTable + FlowTemplate + PlannedTrace + 热更新 API | ✅ |
-| **E 层** | WorkflowExecutor + RClient + SSE 实时进度 + 错误分类映射 | ✅ |
+| **E 层** | WorkflowExecutor + RClient + SSE 实时进度 + 错误分类映射 + 参数日志 | ✅ |
 | **R 层** | ReflectionService + 槽位注入 + Zod 校验 + 敏感性冲突准则 + 结论缓存 + Word 增强 | ✅ |
-| **前端** | V11 UI + DynamicReport + ClarificationCard + ConclusionReport（渐入动画）+ Word/R 代码导出 | ✅ |
+| **前端** | 统一 Record 架构 + 多任务切换 + 已完成标记 + DynamicReport + Word/R 导出 | ✅ |
 | **Python** | DataProfileService（is_id_like 标记）+ CSV 解析 | ✅ |
-| **测试** | QPER 端到端测试 40/40 通过 | ✅ |
+| **测试** | QPER 端到端 40/40 + 集成测试 7 Bug 修复 | ✅ |

 ---

@@ -137,11 +170,25 @@ backend/src/modules/ssa/
 │   └── config.routes.ts            # 热更新 API
 └── ...

-backend/scripts/
-├── seed-ssa-intent-prompt.ts       # Q 层 Prompt 种子
-├── seed-ssa-reflection-prompt.ts   # R 层 Prompt 种子
-├── test-ssa-qper-e2e.ts            # QPER 端到端测试
-└── ...
+frontend-v2/src/modules/ssa/
+├── stores/
+│   └── ssaStore.ts                 # Zustand — Unified Record Architecture
+├── hooks/
+│   ├── useWorkflow.ts              # 工作流 Hook（addRecord/updateRecord）
+│   └── useAnalysis.ts              # 上传/Legacy 兼容
+├── components/
+│   ├── SSAChatPane.tsx             # 对话区（卡片 → selectRecord）
+│   ├── SSAWorkspacePane.tsx        # 工作区（基于 currentRecord 渲染）
+│   ├── SSACodeModal.tsx            # R 代码模态框（从 record.steps 聚合）
+│   ├── WorkflowTimeline.tsx        # 执行计划时间线
+│   └── DynamicReport.tsx           # Block-based 结果渲染
+└── types/
+    └── index.ts                    # 前端类型定义
+
+r-statistics-service/
+├── plumber.R                       # API 入口（含参数日志）
+└── tools/
+    └── descriptive.R               # 描述性统计（NA 安全防御）
 ```

 ---
@@ -190,6 +237,7 @@ npx tsx scripts/seed-ssa-reflection-prompt.ts
 |------|------|
 | **QPER 开发计划（主线）** | `04-开发计划/10-QPER架构开发计划-智能化主线.md` |
 | **QPER 开发总结** | `06-开发记录/SSA-QPER架构开发总结-2026-02-21.md` |
+| **集成测试 Bug 修复** | `06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md` |
 | **智能化愿景设计** | `00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md` |
 | **PRD** | `00-系统设计/PRD SSA-Pro 严谨型智能统计分析模块.md` |
 | **架构设计 V4** | `00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md` |
@@ -198,13 +246,25 @@ npx tsx scripts/seed-ssa-reflection-prompt.ts

 ## 🎯 下一步

-1. **Phase Deploy（37h）** — 补齐 ANOVA / Fisher / Wilcoxon / 线性回归 + 复合工具 ST_BASELINE_TABLE + 部署上线
-2. **Phase Q+（20h）** — 变量数据字典（AI 先猜用户微调）+ 变量选择确认面板（AI 推荐医生确认）
-3. **前端集成测试** — 用户手动测试 QPER 全链路的真实交互体验
+### 近期（优先级高）
+
+1. **QPER 透明化（Pipeline 可观测性）**
+   - Q 层：展示 LLM 解析结果（goal、变量、置信度）和降级原因
+   - P 层：展示决策表匹配过程和流程模板填充参数
+   - E 层：实时展示步骤输入参数 + R 返回摘要；开发模式显示 R 原始错误
+   - R 层：展示槽位注入内容和 Zod 校验状态
+   - 开发者面板：持久化 trace_log + LLM prompt/response 可查看
+
+2. **Phase Deploy（37h）** — 补齐 ANOVA / Fisher / Wilcoxon / 线性回归 + 复合工具 ST_BASELINE_TABLE + 部署上线
+
+### 中期
+
+3. **Phase Q+（20h）** — 变量数据字典（AI 先猜用户微调）+ 变量选择确认面板（AI 推荐医生确认）
+4. **前端 UI 细节打磨** — 执行计划格式美化、错误状态视觉增强

 ---

-**文档版本：** v2.0  
+**文档版本：** v2.1  
 **最后更新：** 2026-02-21  
-**当前状态：** 🎉 QPER 主线闭环完成，端到端 40/40 通过  
-**下一步：** Phase Deploy 工具补齐 + 部署上线
+**当前状态：** 🎉 QPER 主线闭环 + 集成测试通过 + 统一状态管理重构完成  
+**下一步：** QPER 透明化 → Phase Deploy 工具补齐 + 部署上线