AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/06-开发记录/2026-02-20-Phase2A-前端集成与多步骤工作流开发总结.md

SSA-Pro 2026-02-20 开发总结：Phase 2A 前端集成与多步骤工作流

版本： v1.0
日期： 2026-02-20
编写： AI 开发助手
状态： ✅ Phase 2A 前端集成完成 + Block-based 架构方案达成共识

---

1. 开发目标

本日核心目标是 Phase 2A 智能核心前端集成，将后端多步骤工作流（Workflow）功能端到端打通到前端 UI，并解决集成过程中发现的所有 Bug。

---

2. 完成工作清单

2.1 Python 数据质量服务集成

任务	状态	说明
CSV 直传 Python 端点	✅ 完成	新增 /api/ssa/data-profile-csv 端点，Python 直接解析 CSV
端口配置修复	✅ 修复	默认端口从 8081 修正为 8000
环境变量补充	✅ 完成	backend/.env 新增 EXTRACTION_SERVICE_URL
文件格式智能检测	✅ 完成	DataProfileService 自动检测 JSON/CSV 调用不同端点

2.2 多步骤工作流前端集成

任务	状态	说明
意图识别增强	✅ 完成	WorkflowPlannerService 正则提取变量名 + 变量类型判断
统计工具智能选择	✅ 完成	根据变量类型（分类/连续）正确选择统计方法
SSE 实时进度	✅ 完成	前后端 SSE 消息格式对齐，支持 connected/step_start/step_complete
工作流执行触发	✅ 修复	SSE 连接时自动触发 executeWorkflow，解决"卡在调用R引擎"问题

2.3 前端 UI 修复与优化

任务	状态	说明
SAP 按钮误显示	✅ 修复	移除数据上传后自动显示分析计划的逻辑
数据质量报告位置	✅ 修复	移至 messages.map 循环前，紧跟数据上传
分析计划 undefined	✅ 修复	前后端 WorkflowPlan 接口对齐
复用 MVP 设计	✅ 完成	多步骤模式复用 MVP 单步骤的 UI 组件风格
CSS 布局混乱	✅ 修复	移除 position: absolute，修复 padding 双重叠加
滚动不可用	✅ 修复	移除 .terminal-box 的 max-width 限制

2.4 多步骤结果展示

任务	状态	说明
执行日志	✅ 完成	MVP 风格 terminal-box + TraceLogItem，显示 [步骤 N] 工具名 → 状态
统计结果渲染	✅ 完成	各步骤独立显示统计量、P值、效应量、置信区间
分组统计表	✅ 完成	group_stats 渲染为 sci-table
回归系数表	✅ 完成	coefficients 渲染为专用表格
描述性统计	✅ 完成	专用 DescriptiveResultView 组件，处理 variables+by_group
图表显示	✅ 完成	plots base64 图片渲染

2.5 导出功能

任务	状态	说明
R 代码导出	✅ 完成	多步骤模式聚合所有步骤的 reproducible_code
Word 报告导出	✅ 完成	exportWorkflowReport 完整报告：摘要+各步骤详情+描述性统计
描述性统计导出修复	✅ 修复	正确解析 variables 对象中数值/分类变量并生成表格

2.6 架构讨论与规划

任务	状态	说明
Block-based 协议评估	✅ 完成	评估并认可 SSA-Pro 动态结果渲染与通信协议规范.md
开发计划编写	✅ 完成	08-Block-based动态结果渲染开发计划.md

---

3. 关键 Bug 修复详情

Bug #1：CSV 文件解析失败

现象：后端报错 "Unexpected token 's', "sex,smoke,"... is not valid JSON"
根因：DataProfileService 从 OSS 下载 CSV 文件后，尝试 JSON.parse() 解析
修复：新增文件类型检测逻辑，CSV 文件直接以字符串形式发送到 Python 新端点 /api/ssa/data-profile-csv

Bug #2：统计方法选择错误

现象：分析 sex 与 Yqol（分类变量 0/1）的关系，推荐 T 检验而非卡方/Logistic
根因：WorkflowPlannerService 未提取具体变量名，也未检查变量类型
修复：重写 parseUserIntent 和 generateSteps，基于正则提取变量名 + DataProfile 变量类型判断

Bug #3：SSE 执行卡死

现象：前端显示"正在调用云端 R 引擎"但无进展，后端日志显示执行正常
根因：SSE stream 路由仅注册监听器，未触发 executeWorkflow
修复：/:workflowId/stream 路由在客户端连接时异步触发工作流执行

Bug #4：结果数据丢失

现象：执行日志正常但结果区域为空，导出按钮不显示
根因：WorkflowExecutorService 只展开 response.data.results，丢失 plots、reproducible_code 等字段
修复：将 plots、result_table、reproducible_code、trace_log、warnings 全部注入 step.result

Bug #5：描述性统计显示异常

现象：描述性统计只显示几个数字，不是表格
根因：R 服务返回 { summary, variables: { "varName": {...} } } 嵌套结构，前端未正确解析
修复：创建 DescriptiveResultView 专用组件，正确遍历 variables 对象生成数值/分类变量表格

Bug #6：Word 报告缺少描述性统计

现象：导出 Word 报告无描述性统计内容
根因：exportWorkflowReport 未处理描述性统计的 variables 对象结构
修复：添加 classifyExportVar 辅助函数，遍历 variables 生成 docx 表格行

---

4. 修改文件清单

后端 (backend)

文件	修改类型	说明
services/DataProfileService.ts	增强	CSV 直传 Python、文件类型检测
services/WorkflowPlannerService.ts	重写	意图解析、变量类型判断、工具选择
services/WorkflowExecutorService.ts	修复	result 字段完整传递
routes/workflow.routes.ts	修复	SSE 触发执行
.env	新增	EXTRACTION_SERVICE_URL

Python 服务 (extraction_service)

文件	修改类型	说明
main.py	新增	/api/ssa/data-profile-csv 端点

前端 (frontend-v2)

文件	修改类型	说明
components/SSAChatPane.tsx	修复	SAP 显示逻辑、DataProfile 位置、工作流调用
components/SSAWorkspacePane.tsx	重构	复用 MVP 设计、DescriptiveResultView、多步骤渲染
components/SSACodeModal.tsx	增强	多步骤 R 代码聚合
hooks/useWorkflow.ts	修复	SSE 消息兼容处理
hooks/useAnalysis.ts	增强	exportWorkflowReport + 描述性统计导出
types/index.ts	扩展	SSE 消息类型定义
styles/ssa-workspace.css	修复	布局、滚动、间距

---

5. 架构决策

达成共识：Block-based 动态结果渲染

经过讨论，团队就以下架构方向达成共识：

1. 采用 Block-based 协议：R 工具输出标准化的 report_blocks 数组
2. 4 种 Block 类型：markdown、table、image、key_value
3. Node.js 零维护：直接透传 report_blocks，不做字段映射
4. 前端单一组件：DynamicReport.tsx 动态渲染所有工具的结果
5. 渐进式迁移：新旧协议并存，逐步替换

详见 04-开发计划/08-Block-based动态结果渲染开发计划.md

---

6. 当前状态总结

维度	状态
Phase 2A 后端	✅ 100%（多步骤工作流、意图识别、SSE 进度）
Phase 2A 前端	✅ 100%（UI 集成、结果展示、导出功能）
数据质量服务	✅ Python 服务正常调用
端到端流程	✅ 上传 → 质量报告 → 多步骤规划 → 执行 → 结果 → 导出
Block-based 重构	📋 计划已制定，待开始

---

7. 下一步计划

1. Block-based 动态渲染实施（~2.5 天）

   • Phase 1：前端 DynamicReport.tsx + R 辅助函数库
   • Phase 2：7 个 R 工具逐一改造
   • Phase 3：清理旧的自定义渲染代码

2. 更多统计工具前端验证

   • 卡方检验、相关分析、回归分析的多步骤联合执行测试

---

文档结束