HaHafeng
428a22adf2
Phase 2A: WorkflowPlannerService, WorkflowExecutorService, Python data quality, 6 bug fixes, DescriptiveResultView, multi-step R code/Word export, MVP UI reuse. V11 UI: Gemini-style, multi-task, single-page scroll, Word export. Architecture: Block-based rendering consensus (4 block types). New R tools: chi_square, correlation, descriptive, logistic_binary, mann_whitney, t_test_paired. Docs: dev summary, block-based plan, status updates, task list v2.0. Co-authored-by: Cursor <cursoragent@cursor.com>
188 lines
8.0 KiB
Markdown
188 lines
8.0 KiB
Markdown
# 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. **更多统计工具前端验证**
|
||
- 卡方检验、相关分析、回归分析的多步骤联合执行测试
|
||
|
||
---
|
||
|
||
**文档结束**
|