AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md

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 不变