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 工具补齐 + 部署上线
--- a/docs/03-业务模块/SSA-智能统计分析/06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md
+++ b/docs/03-业务模块/SSA-智能统计分析/06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md
@@ -0,0 +1,153 @@
+# SSA 前后端集成测试 Bug 修复与统一状态管理重构
+
+> **日期：** 2026-02-21  
+> **阶段：** QPER 闭环后首次集成测试 + 架构重构  
+> **核心成果：** 修复 7 个集成 Bug + 完成统一状态管理重构（消除双轨逻辑）
+
+---
+
+## 一、Bug 修复清单
+
+### Bug 1: 前端错误消息乱码（`分分析行执行执失行败失…undefined重`）
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 执行失败时，对话区错误消息显示为乱码字符 |
+| **根因** | 错误消息被 TypeWriter 组件逐字渲染导致字符交错；errText 提取有竞态导致 undefined |
+| **修复** | `useWorkflow.ts` — 确保 errText 始终为 String()，错误消息添加 `artifactType: 'execution'` 跳过 TypeWriter |
+| **文件** | `frontend-v2/src/modules/ssa/hooks/useWorkflow.ts` |
+
+### Bug 2: R 引擎 `missing value where TRUE/FALSE needed` 错误
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 描述性统计执行时 R 崩溃，返回 500 错误 |
+| **根因** | `descriptive.R` 中多处 if 条件（group_var 判断、var_types 比较、分组子集）接收到 NA 而非 TRUE/FALSE |
+| **修复** | 全面防御性编程：`isTRUE()`、`is.na()` 检查、robust group_var 归一化、sapply 类型推断 tryCatch、可复现代码生成 tryCatch |
+| **文件** | `r-statistics-service/tools/descriptive.R` |
+
+### Bug 3: 分析意图识别错误（"统计学意义" → 描述性统计）
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 用户问"Yqol和bmi是否有统计学意义"，系统使用描述性统计而非 T 检验/相关分析 |
+| **根因** | Q 层 LLM Prompt 和 Regex fallback 缺少"统计学意义""显著""检验""p值"等关键词到 correlation goal 的映射 |
+| **修复** | `QueryService.ts` fallbackToRegex 增加统计学意义关键词；`seed-ssa-intent-prompt.ts` 新增 Few-Shot 示例 |
+| **文件** | `backend/src/modules/ssa/services/QueryService.ts`, `backend/scripts/seed-ssa-intent-prompt.ts` |
+
+### Bug 4: 步骤 2（Logistic 回归）结果不显示
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | R 返回 status="warning"（ggplot2 废弃警告），前端仅过滤 status="success"，导致步骤 2 结果丢失 |
+| **根因** | 前端 SSAWorkspacePane、SSACodeModal 只识别 `success`，不识别 `warning` |
+| **修复** | 引入 `stepHasResult` 辅助函数：`(s.status === 'success' \|\| s.status === 'warning') && s.result`，替换所有 6 处过滤 |
+| **文件** | `frontend-v2/src/modules/ssa/components/SSAWorkspacePane.tsx`, `SSACodeModal.tsx` |
+
+### Bug 5: R 代码下载不完整（仅步骤 1）
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 多步骤分析完成后，下载的 R 代码只包含步骤 1（描述统计），缺少步骤 2（回归） |
+| **根因** | 与 Bug 4 同源 — SSACodeModal 过滤条件只匹配 `success` |
+| **修复** | 随 Bug 4 一并修复 |
+
+### Bug 6: 多任务状态混淆（点击旧卡片显示新任务结果）
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | 完成两次分析后，点击第 1 次的卡片显示的是第 2 次的结果 |
+| **根因** | workflowPlan/workflowSteps/conclusionReport 等是全局单例，切换记录时未正确同步 |
+| **修复** | 通过统一状态管理重构彻底解决（见下文第二节） |
+
+### Bug 7: 后端/R 引擎调试日志不足
+
+| 项目 | 内容 |
+|------|------|
+| **现象** | R 执行失败时无法定位具体哪些变量传入导致错误 |
+| **修复** | `WorkflowExecutorService.ts` 增加 R 调用前参数日志；`plumber.R` 增加参数接收日志和错误日志 |
+| **文件** | `backend/src/modules/ssa/services/WorkflowExecutorService.ts`, `r-statistics-service/plumber.R` |
+
+---
+
+## 二、统一状态管理重构
+
+### 问题描述
+
+前端存在"双轨逻辑"：
+- **Legacy 路径**：`currentPlan` / `executionResult` / `traceSteps`（全局单例）
+- **Workflow 路径**：`workflowPlan` / `workflowSteps` / `workflowProgress` / `conclusionReport`（也是全局单例）
+- `isWorkflowMode` 分支在多个组件中分叉
+
+多任务场景下，全局单例被最新任务覆盖，导致切换卡片时显示错误数据。
+
+### 重构方案
+
+**核心思想：一次分析 = 一个 Record = N 个 Steps**
+
+```
+AnalysisRecord {
+  id, query, createdAt,
+  status: 'planning' | 'executing' | 'completed' | 'error',
+  plan: WorkflowPlan | null,
+  steps: WorkflowStepResult[],
+  progress: number,
+  conclusionReport: ConclusionReport | null,
+}
+```
+
+### 改动文件
+
+| 文件 | 改动要点 |
+|------|---------|
+| `ssaStore.ts` | 删除 12 个全局单例字段及 setter；新增 `addRecord`/`updateRecord`/`selectRecord`；`selectRecord` 只设 currentRecordId，不复制数据 |
+| `useWorkflow.ts` | SSE 事件处理只调用 `updateRecord(rid, patch)`；删除对 `setWorkflowSteps` 等全局 setter 的调用 |
+| `useAnalysis.ts` | `generatePlan` 改为调用 `addRecord` 创建 1-step Record |
+| `SSAChatPane.tsx` | SAP/Result 卡片统一行为：`selectRecord(recordId)` + 打开工作区；已完成记录显示绿色"已完成"徽章 |
+| `SSAWorkspacePane.tsx` | 所有渲染基于 `currentRecord`；删除 `isWorkflowMode` 分支；phase 直接使用 `record.status` |
+| `SSACodeModal.tsx` | 从 `currentRecord.steps` 聚合代码；删除 Legacy fallback |
+| `ssa-workspace.css` | 新增 `.sap-card-badge` 样式 |
+
+### 额外修复
+
+- **executeWorkflow 跨 hook 实例问题**：`SSAChatPane` 和 `SSAWorkspacePane` 各自有独立的 `useWorkflow()` 实例，`generateWorkflowPlan` 在 ChatPane 实例中设置了 `currentRecordIdRef`，但 `executeWorkflow` 在 WorkspacePane 实例中执行时 ref 为 null。修复：fallback 到 store 的 `currentRecordId`。
+
+---
+
+## 三、未完成工作与后续计划
+
+### QPER 透明化与可观测性
+
+目前 QPER 四层的执行细节对用户不够透明，出错时用户难以了解具体原因，开发调试也依赖日志查看：
+
+1. **Q 层透明化**
+   - 展示 LLM 意图解析的 ParsedQuery 结果（goal、变量、设计类型、置信度）
+   - 低置信度时展示降级原因（"LLM 超时，使用关键词匹配"）
+
+2. **P 层透明化**
+   - 展示决策表匹配过程（匹配了哪条规则、得分）
+   - 展示流程模板填充参数
+
+3. **E 层透明化**
+   - 实时展示每个步骤的输入参数和 R 返回结果摘要
+   - 错误时展示 R 原始错误信息（开发模式）
+
+4. **R 层透明化**
+   - 展示 LLM 结论生成的槽位注入内容
+   - Zod 校验失败时展示具体字段错误
+
+5. **开发调试增强**
+   - 持久化 trace_log 到数据库
+   - 前端"开发者面板"查看完整 QPER pipeline 日志
+   - LLM 调用的 prompt/response 可查看
+
+### 其他待完成项
+
+- Phase Deploy：补齐 ANOVA / Fisher / Wilcoxon / 线性回归等 R 工具
+- Phase Q+：变量数据字典 + 变量选择确认面板
+- 前端 UI 细节打磨：执行计划格式美化、错误状态视觉增强
+
+---
+
+**测试状态：** 手动集成测试通过（多任务切换、卡片状态、R 代码完整性）  
+**影响范围：** 纯前端重构 + R 脚本防御性修复 + 后端日志增强，后端 API 不变