Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ssa): Complete Phase 2A frontend integration - multi-step workflow end-to-end

Browse Source 
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>
This commit is contained in:
HaHafeng
2026-02-20 23:09:27 +08:00
parent 23b422f758
commit 428a22adf2
62 changed files with 15416 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/03-业务模块/SSA-智能统计分析/04-开发计划/00-MVP开发计划总览.md
View File

@@ -1,10 +1,61 @@
# SSA-Pro MVP 开发计划总览
> **文档版本：** v1.5
> **文档版本：** v1.7
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18（纳入专家配置体系 + 决策表匹配 + R代码库）
> **最后更新：** 2026-02-20（纳入 Prompt 体系 + 多工具流程规划 + 数据质量核查报告）
> **项目代号：** SSA (Smart Statistical Analysis)
> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具，支持咨询模式
> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具，支持多工具流程规划 + 数据质量核查
---
## 0. 🆕 智能化演进愿景（战略定位）
> **详细文档参考：** `04-开发计划/06-智能化演进共识与MVP执行计划.md`
### 0.1 产品终极目标
> **SSA-Pro 的终极目标是 Level 3：颠覆性的智能分析助手**
>
> 让不懂统计的医生，能够完成专业级的统计分析。
### 0.2 三阶段演进路线
```
Phase 1/2: 爬行期 (MVP) ← 当前阶段
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：打透 Tool Calling，建立用户信任
机制：100个工具作为固定API，LLM 做智能调度
AI角色：高级调度员 / 全科主任医师
Phase 2.5: 行走期
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：引入受限的代码智能
机制：数据清洗允许 LLM 生成代码，核心统计仍用固定工具
Phase 3: 奔跑期 (终极愿景)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：自愈型靶向代码修改
机制：运行报错时，LLM 根据错误日志靶向修改工具代码
关键：不是自由生成代码，而是基于现有工具的靶向修复
```
### 0.3 MVP 阶段的"为未来铺路"任务
| 伏笔任务 | Phase 3 用途 | MVP 阶段行动 |
|---------|-------------|-------------|
| **Prompt 动态注入体系** | 支持专家配置热更新 | 🆕 骨架（AI工程师）+ 血肉（统计专家）分离 |
| **多工具流程规划** | 复杂场景的自动化 | 🆕 LLM 生成 2-7 步串联执行流程 |
| **数据质量核查报告** | 智能诊断异常数据 | 🆕 自动生成"数据体检报告"（评分 + 建议）|
| **Prompt 世界观** | LLM 理解自己可以修改代码 | Prompt 中强调"代码库"概念 |
| **向量库代码片段** | 便于 LLM 理解工具代码 | `tools_library` 存入核心代码片段 |
| **结构化错误日志** | 用于错误反馈自愈 | 建立 JSON 格式的错误捕获管道 |
| **黄金数据集积累** | 学习"什么错误如何修复" | 完整记录每次调用（含报错） |
### 0.4 关键共识
> ⚠️ **Phase 3 的"代码智能"不是让 LLM 自由发挥写代码**
>
> 而是：LLM 串联工具 → 执行 → 如果报错 → 错误日志反馈给 LLM → 靶向修改代码/参数 → 重新执行
---
@@ -16,9 +67,11 @@
|------|------|
| **统计工具** | 10 个高频工具（T检验、ANOVA、卡方、相关性等） |
| **双模式支持** | 🆕 **智能分析模式**（上传数据→执行）+ **咨询模式**（无数据→SAP文档）|
| **核心流程** | 上传数据 → AI规划 → 用户确认 → R执行 → 结果交付 |
| **🆕 多工具流程规划** | LLM 规划 2-7 步串联流程（数据检查 → 前提检验 → 核心分析 → 效应量 → 结论）|
| **🆕 数据质量核查报告** | 自动生成"数据体检报告"（缺失值/异常值/分布/平衡性），含质量评分和建议 |
| **核心流程** | 上传数据 → **数据质量核查** → AI规划 → 用户确认 → **多步串联执行** → 结果交付 |
| **交互能力** | 计划确认卡片、执行路径树、结果展示、代码下载、🆕 SAP文档导出 |
| **智能能力** | RAG工具检索、Planner规划、Critic结果解读 |
| **智能能力** | 🆕 **Prompt 动态注入** + RAG工具检索 + Planner规划 + Critic结果解读 |
| **配置中台** | 🆕 统计决策表 + R代码库 + 参数映射 + 护栏规则链 + 解读模板 |
| **数据安全** | LLM只看Schema，R服务处理真实数据 |

100
docs/03-业务模块/SSA-智能统计分析/04-开发计划/01-任务清单与进度追踪.md
View File

@@ -1,11 +1,13 @@
# SSA-Pro MVP 任务清单与进度追踪
> **文档版本：** v1.7
> **文档版本：** v2.0
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-20（V11 UI 前后端联调通过）
> **最后更新：** 2026-02-20（Phase 2A 前端集成完成 + Block-based 架构共识）
> **更新频率：** 每日站会后更新
>
> **当前进度：** Phase 1 核心完成 ~95%，配置中台待开发
> **当前进度：** Phase 2A 完成，下一步 Phase 2B Block-based 动态渲染重构
>
> **📌 核心文档：** `07-Phase2A-智能化核心开发计划.md` | `08-Block-based动态结果渲染开发计划.md`
---
@@ -111,7 +113,54 @@
## Phase 2：智能规划与咨询模式（Week 3-4）
**里程碑目标：** 决策表驱动规划 + 咨询模式上线
**里程碑目标：** 多工具流程规划 + 数据质量核查 + 咨询模式上线
### 🆕 核心智能化任务（优先级最高）
| 状态 | 任务 | 预估 | 备注 |
|------|------|------|------|
| ✅ | 🆕 **Prompt 体系整合到后端开发指南** | 2h | **动态注入模式** |
| ✅ | 🆕 **多工具流程规划设计** | 3h | **WorkflowPlannerService 设计** |
| ✅ | 🆕 **数据质量核查报告设计** | 3h | **DataQualityService 设计** |
| ✅ | 🆕 **实现 WorkflowPlannerService** | 4h | **意图识别 + 变量类型判断 + 工具智能选择** |
| ✅ | 🆕 **实现 WorkflowExecutorService** | 4h | **串联执行 + SSE 实时进度 + 结果完整传递** |
| ✅ | 🆕 **实现 DataQualityService（Python）** | 3h | **CSV 直传 Python 解析，双端点支持** |
| ⬜ | 🆕 **实现 ST_QUALITY_REPORT R 脚本** | 4h | **缺失值/异常值/分布/平衡性** |
| ✅ | 🆕 **实现前端数据质量核查报告卡片** | 3h | **DataProfileCard 组件** |
| ✅ | 🆕 **实现前端多步骤流程展示** | 3h | **SSE 实时更新 + MVP 风格复用** |
### 🆕 Phase 2A 前端集成任务（2026-02-20 完成）
| 状态 | 任务 | 预估 | 备注 |
|------|------|------|------|
| ✅ | 🆕 **SSAChatPane 工作流调用集成** | 2h | **handleSend → generateWorkflowPlan** |
| ✅ | 🆕 **SSE 消息格式前后端对齐** | 2h | **camelCase/snake_case 兼容** |
| ✅ | 🆕 **多步骤执行日志 UI** | 2h | **MVP terminal-box + TraceLogItem 复用** |
| ✅ | 🆕 **多步骤结果展示 UI** | 3h | **统计量/分组表/回归系数/图表** |
| ✅ | 🆕 **DescriptiveResultView 组件** | 3h | **处理 variables+by_group 嵌套结构** |
| ✅ | 🆕 **多步骤 R 代码聚合导出** | 1h | **SSACodeModal 工作流模式** |
| ✅ | 🆕 **多步骤 Word 报告导出** | 3h | **exportWorkflowReport + 描述性统计** |
| ✅ | 🆕 **CSS 布局修复** | 2h | **position/padding/max-width 系统性修复** |
| ✅ | 🆕 **6 个前端 Bug 修复** | 3h | **SAP 误显示/SSE 卡死/结果丢失等** |
### 🆕 Phase 2B Block-based 动态渲染任务（待开始）
| 状态 | 任务 | 预估 | 备注 |
|------|------|------|------|
| ⬜ | 🆕 **创建 DynamicReport.tsx 组件** | 2h | **4 个 Block 渲染子组件** |
| ⬜ | 🆕 **创建 exportBlocksToWord.ts** | 2h | **Block 数组 → Word 文档** |
| ⬜ | 🆕 **后端透传 report_blocks** | 0.5h | **WorkflowExecutorService** |
| ⬜ | 🆕 **R 辅助函数库 block_helpers.R** | 1h | **make_table_block() 等** |
| ⬜ | 🆕 **SSAWorkspacePane 集成** | 1h | **优先读 report_blocks，fallback 旧逻辑** |
| ⬜ | 🆕 **descriptive.R 改造** | 1.5h | **输出 report_blocks** |
| ⬜ | 🆕 **t_test_ind.R 改造** | 1h | **输出 report_blocks** |
| ⬜ | 🆕 **logistic_binary.R 改造** | 1.5h | **输出 report_blocks** |
| ⬜ | 🆕 **chi_square.R 改造** | 1h | **输出 report_blocks** |
| ⬜ | 🆕 **correlation.R 改造** | 1h | **输出 report_blocks** |
| ⬜ | 🆕 **t_test_paired.R 改造** | 1h | **输出 report_blocks** |
| ⬜ | 🆕 **mann_whitney.R 改造** | 1h | **输出 report_blocks** |
| ⬜ | 🆕 **清理旧自定义渲染代码** | 2h | **删除 isDescriptive 等分支** |
| ⬜ | 🆕 **清理旧导出逻辑** | 1.5h | **删除 classifyExportVar 等** |
### R 服务任务
@@ -219,10 +268,15 @@
| Phase | 任务总数 | 已完成 | 进度 |
|-------|---------|--------|------|
| Phase 1 | 49 | 47 | 96% |
| Phase 2 | 30 | 0 | 0% |
| Phase 2 核心智能化 | 9 | 8 | 89% |
| Phase 2A 前端集成 | 9 | 9 | 100% |
| Phase 2B Block-based | 14 | 0 | 0% |
| Phase 2 其他（R/后端/前端） | 30 | 0 | 0% |
| Phase 3 | 22 | 0 | 0% |
| **总计** | **101** | **47** | **47%** |
| **总计** | **133** | **64** | **48%** |
> **v2.0 更新**：Phase 2A 前端集成完成 + Block-based 架构共识达成（2026-02-20）
> **v1.8 更新**：纳入 Prompt 体系 + 多工具流程规划 + 数据质量核查报告设计（2026-02-20）
> **v1.7 更新**：V11 UI 前后端联调通过，Phase 1 核心完成 96%（2026-02-20）
> **v1.6 更新**：Phase 1 核心流程完成，T 检验端到端测试通过（2026-02-19）
@@ -240,29 +294,33 @@
### 2026-02-20
**完成项：**
**上午 - V11 UI 联调：**
- ✅ **V11 UI 像素级还原**：Gemini 风格全屏沉浸式体验
- ✅ **多任务支持**：单会话可执行多个分析任务，独立管理状态
- ✅ **单页滚动布局**：分析计划 → 执行日志 → 分析结果，步骤进度条导航
- ✅ **Word 报告导出**：使用 docx 库生成完整统计报告
- ✅ **输入框遮挡修复**：Scroll Spacer 方案解决 Flexbox padding-bottom 问题
- ✅ **输入框遮挡修复**：Scroll Spacer 方案
- ✅ **代码清理**：删除 7 个旧版 V8/V9 组件
- ✅ **前后端联调测试**：端到端流程验证通过
- ✅ **文档更新**：开发记录、模块状态、任务清单
**下午 - Phase 2A 前端集成（核心）：**
- ✅ **Python 数据质量服务集成**：CSV 直传 Python 解析，修复端口/环境变量
- ✅ **WorkflowPlannerService 实现**：正则变量提取 + 变量类型判断 + 智能工具选择
- ✅ **WorkflowExecutorService 修复**：result 字段完整传递（plots/code/trace_log）
- ✅ **SSE 前后端对齐**：stream 路由触发执行 + 消息格式兼容
- ✅ **多步骤 UI 复用 MVP 设计**：terminal-box 日志 + 统计量/表格/图表结果
- ✅ **DescriptiveResultView 组件**：variables+by_group 嵌套结构解析
- ✅ **多步骤导出功能**：R 代码聚合 + Word 报告（含描述性统计）
- ✅ **6 个 Bug 修复**：SAP 误显示、布局混乱、SSE 卡死、结果丢失、描述性统计、Word 导出
- ✅ **Block-based 架构共识**：评估并认可动态结果渲染协议规范
- ✅ **Block-based 开发计划**：`08-Block-based动态结果渲染开发计划.md`
**关键技术方案：**
- Scroll Spacer：物理占位元素解决 Flexbox 滚动问题
- AnalysisRecord：多任务状态管理架构
- docx 库：Word 文档生成（支持表格、图片嵌入）
- Block-based Protocol：4 种 Block 类型（markdown/table/image/key_value）
- 渐进式迁移：report_blocks 优先，fallback 旧逻辑
- SSE 触发模式：客户端连接时异步触发 executeWorkflow
**待解决：**
- 配置中台功能待开发（DecisionTableLoader, RCodeLibraryService 等）
- json-repair 和 zod 依赖待安装
- DataParserService 隐私保护待实现
**下一步建议：**
- 方向 A：完成 Phase 1 配置中台（推荐，使 MVP 功能完整）
- 方向 B：进入 Phase 2 扩展更多统计方法
**下一步：**
- Phase 2B：Block-based 动态渲染重构（~2.5 天）
---

48
docs/03-业务模块/SSA-智能统计分析/04-开发计划/02-R服务开发指南.md
View File

@@ -1,8 +1,8 @@
# SSA-Pro R 服务开发指南
> **文档版本：** v1.5
> **文档版本：** v1.6
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18（纳入专家配置体系 + 统一入口函数）
> **最后更新：** 2026-02-20（纳入智能化演进共识 + 错误捕获管道设计）
> **目标读者：** R 统计工程师
---
@@ -237,6 +237,50 @@ function(req, tool_code) {
## 4. 错误码定义
### 🆕 4.0 错误捕获管道设计（为 Phase 3 靶向修改铺路）
> **重要**：结构化的错误捕获是 Phase 3 "靶向代码修改"能力的基础。
>
> 详细背景参考：`04-开发计划/06-智能化演进共识与MVP执行计划.md`
**Phase 3 的工作流程：**
```
工具执行报错 → 错误捕获管道 → 结构化 JSON → 反馈给 LLM → LLM 靶向修改代码
```
**错误 JSON 结构要求（便于 LLM 理解）：**
```json
{
"status": "error",
"error_code": "E002",
"error_type": "business",
"message": "列 'blood_pressure' 类型应为 numeric，实际为 character",
"user_hint": "该列包含非数值数据，请检查数据格式",
"context": {
"tool_code": "ST_T_TEST_IND",
"problematic_column": "blood_pressure",
"expected_type": "numeric",
"actual_type": "character",
"sample_values": ["120", "130", "未知", "125"],
"line_number": 45
}
}
```
**关键字段说明：**
| 字段 | MVP 用途 | Phase 3 用途 |
|------|---------|-------------|
| `error_code` | 日志分类 | LLM 识别错误类型 |
| `error_type` | 区分业务/系统错误 | LLM 判断是否可自愈 |
| `message` | 开发调试 | LLM 理解错误原因 |
| `user_hint` | 前端展示 | 保留 |
| `context` | 🆕 可选 | LLM 靶向修改的关键信息 |
> **MVP 阶段行动**：错误响应中尽量包含 `context` 信息，为 Phase 3 积累"黄金数据集"。
---
```r
# utils/error_codes.R
# 📌 结构化错误码，便于 LLM 自愈

554
docs/03-业务模块/SSA-智能统计分析/04-开发计划/03-后端开发指南.md
View File

@@ -1,8 +1,8 @@
# SSA-Pro 后端开发指南
> **文档版本：** v1.5
> **文档版本：** v1.7
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18（纳入专家配置体系 + 决策表匹配 + R代码库）
> **最后更新：** 2026-02-20（纳入 Prompt 体系 + 多工具流程规划 + 数据质量核查报告）
> **目标读者：** Node.js 后端工程师
---
@@ -61,6 +61,517 @@ backend/src/modules/ssa/
---
## 1.2 🆕 Prompt 体系与专家配置边界
> **核心理念：骨架与血肉的分离**
>
> 详细设计参考：`06-开发记录/SSA-Pro Prompt体系与专家配置边界梳理.md`
### 1.2.1 动态 Prompt 注入模式
```
┌─────────────────────────────────────────────────────────────────┐
│ Prompt 动态注入架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AI 工程师维护 统计专家维护 │
│ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Prompt 模板 │ │ 配置中台 (Excel) │ │
│ │ (骨架) │ │ - 决策表 │ │
│ │ │ │ - 使用规则 │ │
│ │ {{占位符}} │ ◀─────── │ - 解读模板 │ │
│ │ │ 注入 │ - 禁用词列表 │ │
│ └─────────────┘ └─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 完整 Prompt = 骨架 + 血肉 → 发送给 LLM ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```
### 1.2.2 三个核心 Prompt
| 环节 | Prompt 名称 | 作用 | 专家注入内容 |
|------|------------|------|-------------|
| **意图重写** | `SSA_QUERY_REWRITER` | 将医生口语翻译为统计术语 | 同义词字典 |
| **智能规划** | `SSA_PLANNER` | 选择工具 + 生成参数映射 | 工具定义 + 使用规则 |
| **结果解读** | `SSA_CRITIC` | 生成论文级结论 | 解读模板 + 禁用词 |
### 1.2.3 职责边界表
| 资产类型 | 谁来写？ | 存在哪里？ | 被谁执行？ |
|---------|---------|-----------|-----------|
| System Prompt 模板 (骨架) | AI 工程师 | `prompt_templates` 表 | 传给 LLM |
| 工具适用条件/数据要求 | 统计专家 | 配置中台 Excel | 注入 Prompt → LLM |
| 统计护栏规则 | 统计专家 | 配置中台 Excel | **传给 R 服务，由 R 强执行** |
| R 代码模板 | 统计专家 | 配置中台 Excel | 传给 R 服务 |
| 论文结论解释规范 | 统计专家 | 配置中台 Excel | 注入 Critic Prompt → LLM |
> ⚠️ **关键原则**：统计护栏规则（如正态性检验 P<0.05 降级）**绝对不要**放到 Prompt 里让 LLM 判断。这些规则必须由 R 代码强逻辑执行。
---
## 1.3 🆕 多工具流程规划设计
> **愿景目标**："不是执行方法，而是规划流程"
>
> **MVP 目标**：LLM 能够规划 2-7 个工具的串联执行流程
### 1.3.1 流程规划架构
```
用户："比较两组患者的血压差异"
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 多工具流程规划 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: 意图解析 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 目的：差异比较 | 变量：连续 | 分组：二分类 | 设计：独立 ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ Step 2: 流程规划（LLM 输出） │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ { ││
│ │ "workflow": [ ││
│ │ { "step": 1, "tool": "ST_DATA_CHECK", "name": "数据校验" },││
│ │ { "step": 2, "tool": "ST_QUALITY_REPORT", "name": "质量核查" },││
│ │ { "step": 3, "tool": "ST_NORMALITY_TEST", "name": "正态性检验" },││
│ │ { "step": 4, "tool": "ST_LEVENE_TEST", "name": "方差齐性" },││
│ │ { "step": 5, "tool": "ST_T_TEST_IND", "name": "T检验" },││
│ │ { "step": 6, "tool": "ST_EFFECT_SIZE", "name": "效应量" },││
│ │ { "step": 7, "tool": "ST_CONCLUSION", "name": "结论生成" }││
│ │ ], ││
│ │ "reasoning": "两组独立样本比较，需先检验前提条件..." ││
│ │ } ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ Step 3: 串联执行 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 工具1 → 工具2 → 工具3 → ... → 工具N ││
│ │ ↓ ↓ ↓ ↓ ││
│ │ 结果1 → 结果2 → 结果3 → ... → 最终报告 ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 1.3.2 WorkflowPlannerService 设计
```typescript
// planner/WorkflowPlannerService.ts
interface WorkflowStep {
step: number;
toolCode: string;
toolName: string;
params?: Record<string, any>;
dependsOn?: number[]; // 依赖的前置步骤
}
interface WorkflowPlan {
workflow: WorkflowStep[];
reasoning: string;
estimatedTime: number; // 预估耗时(秒)
}
export class WorkflowPlannerService {
/**
* 生成多工具执行流程
*/
async generateWorkflow(
sessionId: string,
userQuery: string,
dataSchema: object
): Promise<WorkflowPlan> {
// 1. 获取候选工具
const tools = await this.toolRetrieval.retrieveTools(userQuery, dataSchema, 10);
// 2. 构造 Prompt（包含流程规划指令）
const prompt = this.buildWorkflowPrompt(userQuery, dataSchema, tools);
// 3. 调用 LLM 生成流程
const llm = LLMFactory.getAdapter('deepseek-v3');
const response = await llm.chat([
{ role: 'system', content: prompt },
{ role: 'user', content: userQuery }
]);
// 4. 解析 + 校验
return this.parseWorkflowPlan(response, tools);
}
/**
* 构造流程规划 Prompt
*/
private buildWorkflowPrompt(query: string, schema: object, tools: any[]): string {
return `
你是一位顶尖的临床数据科学家。你拥有一个包含 ${tools.length} 个专家级统计工具的代码库。
用户数据结构：
${JSON.stringify(schema, null, 2)}
可用工具库：
${tools.map(t => `- ${t.toolCode}: ${t.name} - ${t.description}`).join('\n')}
请根据用户需求，规划一个完整的统计分析流程。流程应包含：
1. 数据质量核查（必须）
2. 前提条件检验（如适用）
3. 核心统计分析
4. 效应量计算（如适用）
5. 结论生成
输出 JSON 格式：
{
"workflow": [
{ "step": 1, "toolCode": "工具代码", "toolName": "工具名称" },
...
],
"reasoning": "规划理由"
}
只输出 JSON，不要其他内容。
`.trim();
}
}
```
### 1.3.3 WorkflowExecutorService 设计
```typescript
// executor/WorkflowExecutorService.ts
interface StepResult {
step: number;
toolCode: string;
status: 'success' | 'warning' | 'error';
result?: any;
error?: string;
executionMs: number;
}
export class WorkflowExecutorService {
/**
* 串联执行多个工具
*/
async executeWorkflow(
sessionId: string,
workflow: WorkflowStep[],
onStepComplete?: (stepResult: StepResult) => void // 实时回调
): Promise<StepResult[]> {
const results: StepResult[] = [];
let previousResult: any = null;
for (const step of workflow) {
const startTime = Date.now();
try {
// 构造本步骤的输入（可能依赖前置步骤的输出）
const input = this.buildStepInput(step, previousResult, sessionId);
// 调用 R 服务执行
const result = await this.rClient.execute(sessionId, {
tool_code: step.toolCode,
params: input
});
const stepResult: StepResult = {
step: step.step,
toolCode: step.toolCode,
status: result.status === 'success' ? 'success' : 'warning',
result: result,
executionMs: Date.now() - startTime
};
results.push(stepResult);
previousResult = result;
// 实时通知前端
onStepComplete?.(stepResult);
} catch (error: any) {
const stepResult: StepResult = {
step: step.step,
toolCode: step.toolCode,
status: 'error',
error: error.message,
executionMs: Date.now() - startTime
};
results.push(stepResult);
onStepComplete?.(stepResult);
// 决定是否继续执行后续步骤
if (this.isCriticalError(error)) {
break; // 关键错误，中断流程
}
// 非关键错误，继续执行
}
}
return results;
}
}
```
---
## 1.4 🆕 数据质量核查报告设计
> **愿景目标**：自动生成"数据体检报告"，主动告诉用户数据有什么问题
>
> **MVP 目标**：在执行分析前，先生成数据质量核查报告
### 1.4.1 核查报告结构
```typescript
// types/DataQualityReport.ts
interface DataQualityReport {
// 基础统计
summary: {
totalRows: number;
totalColumns: number;
numericColumns: number;
categoricalColumns: number;
};
// 缺失值分析
missingAnalysis: {
totalMissing: number;
missingRate: number; // 总体缺失率
columns: Array<{
name: string;
missingCount: number;
missingRate: number;
suggestion: string; // 处理建议
}>;
};
// 异常值检测
outlierAnalysis: {
columns: Array<{
name: string;
outlierCount: number;
outlierValues: any[];
method: 'IQR' | 'ZScore';
suggestion: string;
}>;
};
// 分布检验（数值变量）
distributionAnalysis: {
columns: Array<{
name: string;
shapiroP: number;
isNormal: boolean;
skewness: number;
kurtosis: number;
suggestion: string;
}>;
};
// 分组平衡性（如有分组变量）
groupBalance?: {
groupColumn: string;
groups: Array<{
name: string;
count: number;
percentage: number;
}>;
isBalanced: boolean;
suggestion: string;
};
// 整体评估
overallAssessment: {
qualityScore: number; // 0-100
level: 'good' | 'acceptable' | 'poor';
warnings: string[];
recommendations: string[];
};
}
```
### 1.4.2 DataQualityService 设计
```typescript
// planner/DataQualityService.ts
export class DataQualityService {
/**
* 生成数据质量核查报告
* 这是 R 服务调用，不是 LLM
*/
async generateReport(sessionId: string): Promise<DataQualityReport> {
// 调用 R 服务的数据质量核查工具
const result = await this.rClient.execute(sessionId, {
tool_code: 'ST_QUALITY_REPORT',
params: {
check_missing: true,
check_outliers: true,
check_distribution: true,
check_balance: true
}
});
return this.transformToReport(result);
}
/**
* 生成用户友好的摘要（可选用 LLM 增强）
*/
async generateSummary(report: DataQualityReport): Promise<string> {
const llm = LLMFactory.getAdapter('deepseek-v3');
const prompt = `
你是一位数据分析专家。请根据以下数据质量核查结果，生成一段简洁的中文摘要（3-5句话），
告诉用户数据的整体质量如何，主要问题是什么，是否可以继续分析。
核查结果：
${JSON.stringify(report, null, 2)}
请直接输出摘要文本。
`;
return await llm.chat([{ role: 'user', content: prompt }]);
}
}
```
### 1.4.3 R 服务端实现（ST_QUALITY_REPORT）
```r
# tools/quality_report.R
#' @tool_code ST_QUALITY_REPORT
#' @name 数据质量核查报告
#' @description 生成全面的数据质量评估报告
run_analysis <- function(input) {
# 加载数据
df <- load_data(input)
report <- list()
# 1. 基础统计
report$summary <- list(
totalRows = nrow(df),
totalColumns = ncol(df),
numericColumns = sum(sapply(df, is.numeric)),
categoricalColumns = sum(sapply(df, is.character) | sapply(df, is.factor))
)
# 2. 缺失值分析
report$missingAnalysis <- analyze_missing(df)
# 3. 异常值检测（IQR 方法）
report$outlierAnalysis <- analyze_outliers(df)
# 4. 分布检验
report$distributionAnalysis <- analyze_distribution(df)
# 5. 分组平衡性
if (!is.null(input$group_var)) {
report$groupBalance <- analyze_balance(df, input$group_var)
}
# 6. 整体评估
report$overallAssessment <- calculate_quality_score(report)
return(list(
status = "success",
report = report
))
}
# 计算整体质量评分
calculate_quality_score <- function(report) {
score <- 100
warnings <- c()
recommendations <- c()
# 缺失值扣分
if (report$missingAnalysis$missingRate > 0.1) {
score <- score - 20
warnings <- c(warnings, "缺失值比例超过10%")
recommendations <- c(recommendations, "建议处理缺失值后再进行分析")
} else if (report$missingAnalysis$missingRate > 0.05) {
score <- score - 10
warnings <- c(warnings, "存在一定比例的缺失值")
}
# 异常值扣分
outlier_cols <- sum(sapply(report$outlierAnalysis$columns, function(x) x$outlierCount > 0))
if (outlier_cols > 0) {
score <- score - 5 * outlier_cols
warnings <- c(warnings, paste0(outlier_cols, "个变量存在异常值"))
}
# 非正态扣分（提示，不强制扣分）
non_normal <- sum(!sapply(report$distributionAnalysis$columns, function(x) x$isNormal))
if (non_normal > 0) {
recommendations <- c(recommendations,
paste0(non_normal, "个变量不满足正态分布，系统将自动选择非参数方法"))
}
# 确定等级
level <- if (score >= 80) "good" else if (score >= 60) "acceptable" else "poor"
return(list(
qualityScore = max(0, score),
level = level,
warnings = warnings,
recommendations = recommendations
))
}
```
### 1.4.4 前端展示（核查报告卡片）
```
┌─────────────────────────────────────────────────────────────────┐
│ 📊 数据质量核查报告 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 📈 数据概况 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 总样本量：200 行 × 15 列 ││
│ │ 数值变量：8 个 | 分类变量：7 个 ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ⚠️ 发现的问题 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ • 缺失值：血压字段有 12 例缺失 (6%) ││
│ │ • 异常值：2 例血压 > 300 mmHg（疑似记录错误） ││
│ │ • 正态性：治疗组血压不满足正态分布 ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ 💡 系统建议 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 1. 建议处理 2 例异常值后再分析 ││
│ │ 2. 由于正态性不满足，系统将自动选择非参数方法 ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ 🎯 整体评估：良好 (82/100) │
│ │
│ [继续分析] [下载报告] │
└─────────────────────────────────────────────────────────────────┘
```
---
## 2. 数据库 Schema（Prisma）
```prisma
@@ -683,6 +1194,45 @@ export class ToolRetrievalService {
### 4.3 PlannerService（AI 规划 + JSON 容错）
#### 🆕 Prompt 世界观设计（智能化演进关键）
> **重要**：Prompt 的"世界观"设计直接影响 LLM 的推理质量和未来演进能力。
>
> 详细背景参考：`04-开发计划/06-智能化演进共识与MVP执行计划.md`
**错误的世界观（接线员思维）：**
```
你是一个工具选择器，从以下列表中选择合适的工具...
```
**正确的世界观（数据科学家思维）：**
```
你是一位顶尖的临床数据科学家，拥有以下能力：
1. 深刻理解医学研究的统计学需求
2. 精通各类统计方法的适用场景和前提条件
3. 能够诊断数据特征并选择最优分析路径
你现在拥有一个包含 100+ 专家级统计算法的代码库。
每个算法都经过统计学专家的严格验证，确保结果的权威性。
请理解医生的研究意图，诊断数据特征，从代码库中选择最合适的工具组合，
并制定完整的分析计划。你的目标是帮助医生产出可以直接用于 SCI 论文的统计结果。
```
**为什么这很重要？**
| 维度 | 接线员思维 | 数据科学家思维 |
|------|-----------|---------------|
| LLM 自我认知 | 被动的工具选择器 | 主动的分析规划师 |
| 推理深度 | 简单匹配 | 深度分析数据特征 |
| 输出质量 | 可能选错工具 | 更准确的工具选择 |
| Phase 3 演进 | 难以扩展到代码修改 | 自然过渡到代码理解和修改 |
> **MVP 阶段行动**：更新 `SSA_PLANNER` Prompt 模板，使用"数据科学家"世界观。
---
```typescript
// services/PlannerService.ts
import { LLMFactory } from '@/common/llm/adapters/LLMFactory';

47
docs/03-业务模块/SSA-智能统计分析/04-开发计划/04-前端开发指南.md
View File

@@ -1,10 +1,10 @@
# SSA-Pro 前端开发指南
> **文档版本：** v1.5
> **文档版本：** v1.6
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18（纳入专家配置体系 + 护栏 Action 展示）
> **最后更新：** 2026-02-20（纳入智能化演进共识 + 分步展示设计）
> **目标读者：** 前端工程师
> **原型参考：** `03-UI设计/智能统计分析V2.html`
> **原型参考：** `03-UI设计/V11.html`（V11 像素级还原）
---
@@ -62,6 +62,47 @@ frontend-v2/src/modules/ssa/
| **无数据友好** | 咨询模式不要求上传数据 |
| **SAP 导出** | 咨询完成后可下载 Word/Markdown |
### 1.2 🆕 智能化演进设计（为 Phase 3 铺路）
> **重要**：前端 UI 设计需要为未来的"靶向代码修改"能力预留扩展点。
>
> 详细背景参考：`04-开发计划/06-智能化演进共识与MVP执行计划.md`
**Phase 3 的工作流程（前端视角）：**
```
用户提问 → 系统规划多个步骤 → 依次执行
↓
步骤 N 执行报错
↓
前端展示错误信息 + "正在自动修复..."
↓
LLM 靶向修改代码 → 重新执行
↓
成功 → 继续下一步
```
**MVP 阶段需要预埋的 UI 能力：**
| 能力 | MVP 用途 | Phase 3 用途 |
|------|---------|-------------|
| **分步展示** | 显示工具执行链 | 显示每步的执行/修复状态 |
| **步骤状态** | 成功/失败/进行中 | 增加"修复中"状态 |
| **错误详情** | 展示用户友好错误 | 展示"正在分析错误原因..." |
| **实时日志** | 执行轨迹 | 显示 LLM 修复过程 |
**SAP 卡片的步骤展示（已在 V11 实现）：**
```
系统将按以下步骤为您完成分析：
✅ 步骤 1：数据校验 (ST_DATA_CHECK)
✅ 步骤 2：缺失值检测 (ST_MISSING_REPORT)
🔄 步骤 3：正态性检验 (ST_NORMALITY_TEST) ← 执行中
⏳ 步骤 4：独立样本T检验 (ST_T_TEST_IND)
⏳ 步骤 5：结论生成 (ST_CONCLUSION)
```
> **MVP 阶段行动**：确保 `ExecutionTrace` 组件支持多步骤展示和状态切换。
---
## 2. 原型图核心元素解析

426
docs/03-业务模块/SSA-智能统计分析/04-开发计划/06-智能化演进共识与MVP执行计划.md Normal file
View File

@@ -0,0 +1,426 @@
# SSA-Pro 智能化演进共识与 MVP 执行计划
**文档版本：** v1.1
**创建日期：** 2026-02-20
**最后更新：** 2026-02-20（澄清 Phase 3 靶向修改概念）
**文档性质：** 团队共识文档 & 执行计划
**参与讨论：** 产品团队、架构团队、开发团队
---
## 一、背景与讨论历程
### 1.1 讨论起因
在 SSA-Pro 智能统计分析模块的开发过程中，团队就"智能化"的实现路径产生了深入讨论：
- **愿景设计**：《SSA-Pro 理想状态与智能化愿景设计》提出了"代码智能"范式
- **架构审查**：开发团队对愿景进行了多轮审查，提出了安全性和工程可行性的关切
- **最终共识**：经过充分讨论，团队在愿景与落地之间找到了平衡点
### 1.2 关键讨论文档
| 文档 | 核心观点 |
|------|---------|
| 《SSA-Pro 理想状态与智能化愿景设计》 | 代码智能范式，LLM 动态修改代码 |
| 《架构审查反馈与智能化路径讨论》 | 区分工具调用 vs 代码智能，明确产品定位 |
| 《终极架构共识与智能化演进备忘录》 | 提出"受限代码生成"桥梁方案 |
| 《智能化演进路径评估报告》 | Tool Calling vs Agentic Code Gen 对比 |
| 《智能化演进阶梯》 | Phase 2 是 Phase 3 的基础 |
---
## 二、最终共识
### 2.1 产品定位共识
> **SSA-Pro 的终极目标是 Level 3：颠覆性的智能分析助手**
>
> 让不懂统计的医生，能够完成专业级的统计分析。
### 2.2 技术路径共识
| 共识点 | 说明 |
|--------|------|
| **代码智能是正确的终点** | 100个R脚本作为基础组件，LLM 编排调用，报错时靶向修改 |
| **Tool Calling 是必经的起点** | MVP 阶段必须先把工具调用做到极致 |
| **分阶段实现是务实选择** | 爬行 → 行走 → 奔跑 |
| **医疗领域零容错** | P值必须100%正确，安全红线不可逾越 |
### 2.3 关键澄清：Phase 3 的"靶向修改"
> ⚠️ **重要澄清：Phase 3 不是让 LLM 自由发挥写代码，而是"靶向修改"**
**错误理解 ❌**
| 误解 | 说明 |
|------|------|
| 100个R文件是"学习资料" | LLM 从中学习后自由生成代码 |
| LLM 自由发挥写代码 | 从零开始生成统计代码 |
| 漫无目的地改代码 | 没有明确目标的代码修改 |
**正确理解 ✅**
| 正解 | 说明 |
|------|------|
| 100个R文件是"基础组件" | 经过专家验证的固定工具 |
| LLM 主要工作是"编排" | 串联多个工具形成分析流程 |
| 只在报错时"靶向修改" | 根据错误信息针对性调整代码/参数 |
| 修改范围有限 | 修复错误，而非重写工具 |
**Phase 3 执行流程图：**
```
用户提问
│
▼
LLM 串联 N 个工具（基于 100 个固定工具）
│
▼
依次执行每个工具
│
├── 成功 → 继续执行下一个工具 → 全部完成 → 输出结果
│
└── 报错 → 捕获【错误日志 + 用户数据片段】
│
▼
反馈给 LLM 分析错误原因
│
▼
LLM 针对性修改该工具的代码/参数
（不是重写，是修复）
│
▼
重新执行该工具 → 成功则继续
```
**本质区别：**
| 维度 | 自由生成（错误理解） | 靶向修改（正确理解） |
|------|---------------------|---------------------|
| **触发条件** | 每次都生成新代码 | 只在报错时修改 |
| **修改范围** | 整个代码 | 出错的部分 |
| **代码来源** | LLM 凭空生成 | 基于现有工具代码 |
| **目标** | 生成新功能 | 修复运行错误 |
### 2.4 关键认知修正
| 原有观点 | 修正后观点 |
|---------|-----------|
| MVP 就应该做代码智能 | MVP 必须先把 Tool Calling 打透 |
| 100个R代码让 LLM 自由修改 | 核心统计代码必须锁死，只有数据清洗可放开 |
| 宏工具方案与目标不兼容 | 宏工具是通往代码智能的必经之路 |
### 2.5 安全红线
| 风险 | 说明 | 应对措施 |
|------|------|---------|
| **RCE 漏洞** | 动态执行 LLM 生成的代码存在远程代码执行风险 | Phase 3 前必须有 MicroVM 级别隔离 |
| **统计学幻觉** | LLM 可能生成"看似正确实则谬误"的统计代码 | 核心统计代码必须使用专家验证的固定脚本 |
| **不可复现** | 动态生成的代码每次可能不同 | MVP 阶段使用固定工具保证 100% 可复现 |
---
## 三、三阶段演进路线图
```
┌─────────────────────────────────────────────────────────────────────────┐
│ SSA-Pro 智能化演进路线图 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1/2: 爬行期 (MVP) ───────────────────────────────────────────── │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 目标：打透 Tool Calling，建立用户信任 │ │
│ │ 机制：100个工具作为固定API，LLM 做智能调度 │ │
│ │ AI角色：高级调度员 / 全科主任医师 │ │
│ │ 交付：V11 UI + 工具编排 + 论文级输出 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Phase 2.5: 行走期 ─────────────────────────────────────────────────── │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 目标：引入受限的代码智能 │ │
│ │ 机制： │ │
│ │ - 数据清洗：允许 LLM 生成 dplyr 代码（白名单 AST 检查） │ │
│ │ - 核心统计：仍然强制使用固定工具 │ │
│ │ AI角色：数据清洗实习生 + 统计调度员 │ │
│ │ 交付：自愈型数据处理 + 错误反馈机制 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Phase 3: 奔跑期 (终极愿景) ────────────────────────────────────────── │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 目标：自愈型靶向代码修改 │ │
│ │ 前提：MicroVM 沙箱、AST 安全检查、充分的黄金数据集 │ │
│ │ 机制： │ │
│ │ - LLM 串联多个工具执行 │ │
│ │ - 运行成功 → 直接返回结果 │ │
│ │ - 运行报错 → 错误日志+数据反馈给 LLM → 靶向修改代码/参数 │ │
│ │ - 重新执行 → 直到成功 │ │
│ │ AI角色：全能数据科学家 / AI 统计学家 │ │
│ │ 关键：不是自由生成代码，而是基于现有工具的靶向修复 │ │
│ │ 交付：颠覆性的智能分析体验 │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
---
## 四、MVP 阶段执行计划
### 4.1 核心目标
> **把 Tool Calling 做到极致，让 LLM 成为最聪明的"全科主任医师"**
- 准确理解医生意图
- 精准选择工具组合
- 正确编排执行顺序
- 输出论文级结果
### 4.2 具体任务清单
#### 任务 1：Planner Prompt 重构 🔴 最高优先级
**目标：** 改变 LLM 的"世界观"，从"接线员"升级为"数据科学家"
**当前 Prompt（接线员思维）：**
```
你是一个工具选择器，从以下列表中选择合适的工具...
```
**目标 Prompt（数据科学家思维）：**
```
你是一位顶尖的临床数据科学家，拥有以下能力：
1. 深刻理解医学研究的统计学需求
2. 精通各类统计方法的适用场景和前提条件
3. 能够诊断数据特征并选择最优分析路径
你现在拥有一个包含 100+ 专家级统计算法的代码库。
每个算法都经过统计学专家的严格验证，确保结果的权威性。
请理解医生的研究意图，诊断数据特征，从代码库中选择最合适的工具组合，
并制定完整的分析计划。你的目标是帮助医生产出可以直接用于 SCI 论文的统计结果。
```
**工时估计：** 0.5 天
---
#### 任务 2：向量库增强（为 Phase 3 埋伏笔）
**目标：** 在 `tools_library.xlsx` 中增加字段，为未来的代码智能铺路
| 新增字段 | 用途 | 示例 |
|---------|------|------|
| `core_code_snippet` | R脚本的核心代码片段 | `t.test(x, y, paired = FALSE)` |
| `typical_error_patterns` | 常见报错及处理方式 | `"non-numeric argument" -> 检查数据类型` |
| `data_requirements` | 数据格式要求 | `需要两列数值型数据` |
| `statistical_assumptions` | 统计前提条件 | `正态分布、方差齐性` |
**工时估计：** 1 天
---
#### 任务 3：执行沙箱强化
**目标：** 建立健壮的错误捕获和日志系统
| 子任务 | 说明 |
|--------|------|
| 错误捕获管道 | R stderr → 结构化 JSON → 可被 LLM 理解 |
| 超时机制 | 单次执行超过 30s 自动终止 |
| 资源限制 | CPU/内存使用上限 |
| 日志记录 | 完整记录每次调用，积累黄金数据集 |
**工时估计：** 2 天
---
#### 任务 4：工具编排能力
**目标：** 实现多工具串联执行
```
用户："帮我做一个完整的组间比较分析"
LLM 生成的执行计划：
─────────────────────────────────────
步骤 1: ST_DATA_CHECK → 数据校验
步骤 2: ST_MISSING_REPORT → 缺失值检测
步骤 3: ST_NORMALITY_TEST → 正态性检验
步骤 4: ST_LEVENE_TEST → 方差齐性检验
步骤 5: ST_T_TEST_IND → 独立样本T检验（或根据前提选择非参数）
步骤 6: ST_EFFECT_SIZE → 效应量计算
步骤 7: ST_CONCLUSION → 结论生成
```
**工时估计：** 3 天
---
#### 任务 5：前端 SAP 卡片增强
**目标：** 展示完整的工具调用链，增加用户信任
```
┌─────────────────────────────────────────────────────────────┐
│ 📋 统计分析计划 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 研究目的：比较两组患者的疗效差异 │
│ 数据特征：连续变量，两组比较，样本量 n=120 │
│ │
│ 系统将按以下步骤为您完成分析： │
│ │
│ ✅ 步骤 1：数据校验 (ST_DATA_CHECK) │
│ ✅ 步骤 2：缺失值检测 (ST_MISSING_REPORT) │
│ ✅ 步骤 3：正态性检验 (ST_NORMALITY_TEST) │
│ ✅ 步骤 4：方差齐性检验 (ST_LEVENE_TEST) │
│ ✅ 步骤 5：独立样本T检验 (ST_T_TEST_IND) │
│ ✅ 步骤 6：效应量计算 (ST_EFFECT_SIZE) │
│ ✅ 步骤 7：结论生成 (ST_CONCLUSION) │
│ │
│ 预计耗时：约 30 秒 │
│ │
│ [确认执行] [修改计划] │
└─────────────────────────────────────────────────────────────┘
```
**工时估计：** 1 天
---
#### 任务 6：Critic Agent 论文级输出
**目标：** 升级结论生成，符合医学期刊规范
**输出模板：**
```
## 统计方法
采用独立样本 t 检验比较两组患者的 [指标名称] 差异。
统计分析使用 R 4.3.0 完成，P < 0.05 认为差异有统计学意义。
## 结果
[实验组/对照组] 的 [指标名称] 为 [均值 ± 标准差]，
两组间差异 [有/无] 统计学意义 (t = [值], P = [值])。
## 效应量
Cohen's d = [值]，表明效应量为 [小/中/大]。
```
**工时估计：** 1 天
---
### 4.3 任务优先级排序
| 优先级 | 任务 | 工时 | 依赖 |
|--------|------|------|------|
| 🔴 P0 | Planner Prompt 重构 | 0.5 天 | 无 |
| 🔴 P0 | 执行沙箱强化 | 2 天 | 无 |
| 🟡 P1 | 工具编排能力 | 3 天 | 沙箱强化 |
| 🟡 P1 | 向量库增强 | 1 天 | 无 |
| 🟢 P2 | 前端 SAP 卡片增强 | 1 天 | 工具编排 |
| 🟢 P2 | Critic Agent 论文级输出 | 1 天 | 无 |
**总工时估计：** 8.5 天
---
## 五、为 Phase 3 埋下的伏笔
虽然 MVP 阶段使用 Tool Calling 范式，但我们要为未来的"靶向修改"能力做好准备：
| 伏笔 | Phase 3 用途 | MVP 阶段行动 |
|------|-------------|-------------|
| **Prompt 世界观** | LLM 理解自己可以修改代码 | 在 Prompt 中强调代码库概念 |
| **向量库代码片段** | LLM 理解工具代码，便于靶向修改 | 存入核心代码片段 |
| **黄金数据集** | 学习"什么错误如何修复" | 完整记录每次调用（含报错） |
| **错误捕获管道** | 将错误信息结构化反馈给 LLM | 建立结构化错误日志 |
| **前端分步展示** | 展示修复过程，支持人机协同 | UI 已支持步骤级展示 |
### 5.1 错误捕获管道的重要性
Phase 3 的核心能力是"遇错自愈"，这依赖于高质量的错误反馈：
```
工具执行报错
│
▼
错误捕获管道（MVP 阶段建设）
│
├── 捕获 R stderr 原始错误
│
├── 解析为结构化 JSON
│ {
│ "error_type": "non-numeric argument",
│ "line_number": 45,
│ "problematic_column": "blood_pressure",
│ "sample_data": ["120", "130", "未知", "125"]
│ }
│
└── 反馈给 LLM 进行靶向修复
```
这个管道在 MVP 阶段就要建设完成，为 Phase 3 打好基础。
---
## 六、成功标准
### MVP 阶段验收标准
| 指标 | 目标 |
|------|------|
| 工具选择准确率 | ≥ 95% |
| 参数填充正确率 | ≥ 98% |
| 执行成功率 | ≥ 90%（标准数据集） |
| 结果可复现性 | 100% |
| 用户满意度 | ≥ 4.0 / 5.0 |
### Phase 2.5 进入条件
| 条件 | 说明 |
|------|------|
| MVP 稳定运行 3 个月 | 验证基础架构稳定性 |
| 积累 1000+ 成功调用记录 | 黄金数据集基础 |
| 错误捕获管道完善 | 支持结构化错误反馈 |
| AST 白名单检查机制就绪 | 数据清洗代码安全保障 |
---
## 七、总结
### 一句话总结
> **代码智能是正确的终点，但 Tool Calling 是必经的起点。**
>
> **先把 100 个工具的调度做到极致，积累黄金数据集，Phase 3 自然水到渠成。**
### 团队共识
1. **愿景一致**：代码智能是终极目标
2. **路径清晰**：爬行 → 行走 → 奔跑
3. **红线明确**：医疗领域零容错，P值必须100%正确
4. **执行务实**：MVP 聚焦 Tool Calling，为未来埋伏笔
5. **概念清晰**：Phase 3 是"靶向修改"，不是"自由生成"
### 关键澄清
> **100 个 R 文件的定位：基础组件，不是学习资料**
>
> - LLM 的主要工作是"编排"这些工具
> - 只有在运行报错时，才进行"靶向修改"
> - 修改的目标是修复错误，而非重写工具
### 行动号召
> **全军出击，拿下 MVP！** 🚀
---
*文档结束*
*本文档为团队共识文档，所有成员应遵循此计划执行。*

755
docs/03-业务模块/SSA-智能统计分析/04-开发计划/07-Phase2A-智能化核心开发计划.md Normal file
View File

@@ -0,0 +1,755 @@
# SSA-Pro Phase 2A：智能化核心开发计划
> **文档版本：** v1.1
> **创建日期：** 2026-02-20
> **最后更新：** 2026-02-20（纳入架构审查反馈：暗礁预警 + Python/R 分工 + 执行时机）
> **目标：** 以终为始，完成智能统计分析的核心能力
> **里程碑：** 5 大核心组件跑通 + 7 个统计工具上线
---
## 1. 战略定位：为什么 Phase 2A 是 MVP 的核心？
```
┌─────────────────────────────────────────────────────────────────┐
│ SSA-Pro 开发阶段定位 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1 ✅ 已完成 │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 骨架搭建：前后端架构 + T检验端到端 + V11 UI │
│ 验证目标：证明"能跑通" │
│ │
│ Phase 2A ⭐ 当前阶段（本计划） │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 智能化核心：5大组件 + 7个工具 + 多工具流程规划 │
│ 验证目标：证明"真正智能" │
│ │
│ Phase 2B+ 后续阶段 │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 扩展完善：更多工具 + 咨询模式 + 配置中台 │
│ 性质：复制粘贴 + 修修补补 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**核心观点：Phase 2A 完成后，智能化能力就完成了 85%+。后续工作主要是"量"的扩展，而非"质"的突破。**
---
## 2. 以终为始：5 大核心组件
```
┌─────────────────────────────────────────────────────────────────┐
│ 理想的智能统计分析系统 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 1. 意图理解器 (Intent Parser) ✅ 已有 │ │
│ │ - Query Rewriter：医学术语 → 统计术语 │ │
│ │ - Planner：Goal/Y/X/Design 四维提取 │ │
│ │ - 不确定时追问澄清 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 2. 数据诊断器 (Data Diagnostician) 🆕 Phase 2A │ │
│ │ │ │
│ │ ⏱️ 时机 A：用户上传数据时 → Python (Tool C) │ │
│ │ - 数据概况（行数、列数、类型推断） │ │
│ │ - 缺失值分析（每列缺失数、缺失率） │ │
│ │ - 异常值检测（IQR 方法） │ │
│ │ - 基础描述统计（均值、中位数、标准差） │ │
│ │ → 输出：DataProfile JSON（喂给 LLM 生成 SAP） │ │
│ │ │ │
│ │ ⏱️ 时机 B：执行核心计算前 → R Service (JIT 护栏) │ │
│ │ - 正态性检验（Shapiro-Wilk，针对特定 Y 变量） │ │
│ │ - 方差齐性检验（Levene，针对特定分组） │ │
│ │ → 输出：StatisticalChecks JSON（决定方法选择） │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 3. 路径规划器 (Pathway Planner) 🆕 Phase 2A │ │
│ │ - LLM 理解用户意图 + 数据特征 │ │
│ │ - 规划 2-7 步分析流程 │ │
│ │ - 选择合适的统计工具组合 │ │
│ │ → 输出：多步骤执行计划 (workflow_steps[]) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 4. 流程执行器 (Workflow Executor) 🆕 Phase 2A │ │
│ │ - 串联执行多个工具 │ │
│ │ - 结果在步骤间传递 │ │
│ │ - 护栏检查与自动降级 │ │
│ │ - 实时进度反馈（SSE 推送） │ │
│ │ → 输出：step_results[] │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 5. 结论生成器 (Conclusion Generator) ✅ 已有 │ │
│ │ - Critic Agent：多步骤结果整合 │ │
│ │ - 论文级结论模板 │ │
│ │ - 方法学说明 + 局限性声明 │ │
│ │ → 输出：综合分析报告 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 2.1 组件状态汇总
| 组件 | 状态 | Phase 2A 任务 |
|------|------|--------------|
| 1. 意图理解器 | ✅ 已有 | 优化 Prompt，增强追问能力 |
| 2. 数据诊断器 | 🆕 待做 | **核心开发项** |
| 3. 路径规划器 | 🆕 待做 | **核心开发项** |
| 4. 流程执行器 | 🆕 待做 | **核心开发项** |
| 5. 结论生成器 | ✅ 已有 | 增强多步骤结果整合能力 |
---
## 3. 工具清单：7 个统计方法
### 3.1 工具总览
| 序号 | 工具代码 | 名称 | 类别 | 状态 | 典型场景 |
|------|---------|------|------|------|---------|
| 1 | ST_T_TEST_IND | 独立样本 T 检验 | 参数检验 | ✅ 已完成 | 两组连续变量比较 |
| 2 | ST_MANN_WHITNEY | Mann-Whitney U 检验 | 非参数检验 | 🆕 待做 | 两组非正态/等级变量比较 |
| 3 | ST_CHI_SQUARE | 卡方检验 | 分类变量 | 🆕 待做 | 两个分类变量关联 |
| 4 | ST_LOGISTIC_BINARY | 二元 Logistic 回归 | 多因素分析 | 🆕 待做 | 二分类结局的危险因素 |
| 5 | ST_T_TEST_PAIRED | 配对 T 检验 | 参数检验 | 🆕 待做 | 前后对比/配对设计 |
| 6 | ST_CORRELATION | Pearson/Spearman 相关 | 相关分析 | 🆕 待做 | 两个连续变量相关性 |
| 7 | ST_DESCRIPTIVE | 描述性统计 | 基础统计 | 🆕 待做 | 数据概况/基线表 |
### 3.2 工具选择逻辑（供 LLM 规划参考）
```
┌─────────────────────────────────────────────────────────────────┐
│ 工具选择决策树 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 研究目的是什么？ │
│ ├─ 描述数据 → ST_DESCRIPTIVE │
│ ├─ 比较两组 │
│ │ ├─ Y 是连续变量 │
│ │ │ ├─ 独立样本 │
│ │ │ │ ├─ 正态分布 → ST_T_TEST_IND │
│ │ │ │ └─ 非正态 → ST_MANN_WHITNEY │
│ │ │ └─ 配对样本 → ST_T_TEST_PAIRED │
│ │ └─ Y 是分类变量 → ST_CHI_SQUARE │
│ ├─ 分析相关性 │
│ │ ├─ 正态分布 → ST_CORRELATION (Pearson) │
│ │ └─ 非正态 → ST_CORRELATION (Spearman) │
│ └─ 多因素分析 │
│ └─ Y 是二分类 → ST_LOGISTIC_BINARY │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 3.3 各工具详细定义
#### 3.3.1 ST_MANN_WHITNEY（Mann-Whitney U 检验）
| 属性 | 值 |
|------|---|
| **适用场景** | 两组独立样本比较，Y 为连续/等级变量，不满足正态性假设 |
| **输入参数** | `group_var`（分组变量）, `value_var`（数值变量） |
| **输出** | U 统计量、Z 值、P 值、效应量 r、中位数对比 |
| **护栏** | 每组样本量 ≥ 5；分组变量必须是二分类 |
| **降级来源** | T 检验正态性不满足时自动降级 |
#### 3.3.2 ST_CHI_SQUARE（卡方检验）
| 属性 | 值 |
|------|---|
| **适用场景** | 两个分类变量的关联分析 |
| **输入参数** | `var1`（分类变量1）, `var2`（分类变量2） |
| **输出** | χ² 统计量、自由度、P 值、Cramér's V |
| **护栏** | 期望频数 < 5 的格子不超过 20%；否则提示使用 Fisher |
| **自动降级** | 2×2 表且有格子 < 5 → Fisher 精确检验 |
#### 3.3.3 ST_LOGISTIC_BINARY（二元 Logistic 回归）
| 属性 | 值 |
|------|---|
| **适用场景** | 二分类结局变量的多因素分析 |
| **输入参数** | `outcome_var`（结局变量）, `predictors`（预测变量列表）, `confounders`（混杂因素，可选） |
| **输出** | OR、95% CI、P 值（每个变量）、模型拟合度（AIC、Hosmer-Lemeshow） |
| **护栏** | 事件数 / 自变量数 ≥ 10（EPV 规则）；共线性检测（VIF < 5） |
| **高级** | 支持单因素 → 多因素两步分析 |
#### 3.3.4 ST_T_TEST_PAIRED（配对 T 检验）
| 属性 | 值 |
|------|---|
| **适用场景** | 配对设计，同一对象前后对比 |
| **输入参数** | `before_var`（前测变量）, `after_var`（后测变量） |
| **输出** | 差值均值、t 统计量、P 值、Cohen's d、95% CI |
| **护栏** | 差值满足正态性；样本量 ≥ 10 |
| **降级** | 差值非正态 → Wilcoxon 符号秩检验 |
#### 3.3.5 ST_CORRELATION（相关分析）
| 属性 | 值 |
|------|---|
| **适用场景** | 两个连续变量的相关性分析 |
| **输入参数** | `var_x`, `var_y`, `method`（pearson/spearman/auto） |
| **输出** | 相关系数 r、P 值、散点图 |
| **护栏** | 样本量 ≥ 10；检测异常值影响 |
| **自动选择** | 两变量均正态 → Pearson；否则 → Spearman |
#### 3.3.6 ST_DESCRIPTIVE（描述性统计）
| 属性 | 值 |
|------|---|
| **适用场景** | 数据概况、基线特征表 |
| **输入参数** | `variables`（变量列表）, `group_var`（可选，分组） |
| **输出** | 连续变量：均值±SD、中位数(IQR)；分类变量：n(%) |
| **特殊** | 自动识别变量类型；支持分组对比 |
---
## 4. 数据流架构（含执行时机）
### 4.1 完整数据流
```
┌─────────────────────────────────────────────────────────────────┐
│ 完整数据流（含执行时机） │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 用户上传数据 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ ⏱️ 时机 A: Python (Tool C) │ │
│ │ → DataProfile JSON │ │
│ │ - 列类型、缺失率、异常值 │ │
│ │ - 唯一值、基础描述统计 │ │
│ └──────────────────┬──────────────────┘ │
│ │ 喂给 LLM │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 意图理解器 + 路径规划器 (LLM) │ │
│ │ → SAP: Group=Gender, Value=GLU │ │
│ │ → Workflow: [描述统计, T检验] │ │
│ └──────────────────┬──────────────────┘ │
│ │ 用户确认执行 │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ ⏱️ 时机 B: R Service (JIT 护栏) │ │
│ │ → 针对 GLU 做正态性检验 │ │
│ │ → 针对 Gender 分组做方差齐性检验 │ │
│ │ → StatisticalChecks JSON │ │
│ └──────────────────┬──────────────────┘ │
│ │ 根据结果决策 │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ 正态 + 方差齐 → T 检验 │ │
│ │ 非正态 → Mann-Whitney │ │
│ │ 方差不齐 → Welch T 检验 │ │
│ └──────────────────┬──────────────────┘ │
│ ▼ │
│ 执行核心统计 → 生成结果 → 结论生成器 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 4.2 执行时机说明
| 时机 | 触发条件 | 执行层 | 目的 |
|------|---------|--------|------|
| **时机 A** | 用户上传数据 | Python (Tool C) | 让 LLM 知道"数据长什么样" |
| **时机 B** | 用户确认执行前 | R Service | JIT 护栏：检验统计假设是否满足 |
> ⚠️ **关键原则**：上传时不知道 Y 是什么，不能对全表做正态性检验。只有 LLM 确定了 Group=X, Value=Y 后，才能在执行前做 JIT 护栏检验。
### 4.3 Python (Tool C) DataProfile 接口
```typescript
// 新增接口：POST /api/dc/profile
interface DataProfileRequest {
sessionId: string; // Tool C 会话 ID
}
interface DataProfileResponse {
columns: Array<{
name: string;
type: 'numeric' | 'categorical' | 'datetime' | 'text';
missingCount: number;
missingRate: number;
uniqueCount: number;
// 数值列
mean?: number;
median?: number;
std?: number;
min?: number;
max?: number;
outlierCount?: number;
// 分类列
topValues?: Array<{ value: string; count: number }>;
}>;
summary: {
totalRows: number;
totalColumns: number;
numericColumns: number;
categoricalColumns: number;
overallMissingRate: number;
};
}
```
### 4.4 R Service JIT 护栏接口
```typescript
// 在执行核心工具前调用
interface JITGuardrailRequest {
sessionId: string;
toolCode: string; // e.g., "ST_T_TEST_IND"
params: {
groupVar: string; // e.g., "Gender"
valueVar: string; // e.g., "GLU"
};
}
interface JITGuardrailResponse {
checks: Array<{
checkName: string; // e.g., "正态性检验"
passed: boolean;
pValue: number;
recommendation: string;
}>;
suggestedTool: string; // 如果检验不通过，建议的替代工具
canProceed: boolean;
}
```
---
## 5. 开发任务清单
### 5.0 前置任务：数据库 Schema 更新
> **重要**：遵循 `docs/04-开发规范/09-数据库开发规范.md`，使用 Prisma Migrate
#### 新增表设计（方案 2：清晰结构）
```prisma
/// SSA 多步骤流程
model SsaWorkflow {
id String @id @default(uuid())
sessionId String @map("session_id")
messageId String? @map("message_id") /// 关联的计划消息
status String @default("pending") /// pending | running | completed | partial | error
totalSteps Int @map("total_steps")
completedSteps Int @default(0) @map("completed_steps")
workflowPlan Json @map("workflow_plan") /// 原始计划 JSON
createdAt DateTime @default(now()) @map("created_at")
completedAt DateTime? @map("completed_at")
session SsaSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
steps SsaWorkflowStep[]
@@index([sessionId], map: "idx_ssa_workflow_session")
@@map("ssa_workflows")
@@schema("ssa_schema")
}
/// SSA 流程步骤
model SsaWorkflowStep {
id String @id @default(uuid())
workflowId String @map("workflow_id")
stepOrder Int @map("step_order")
toolCode String @map("tool_code")
toolName String @map("tool_name")
status String @default("pending") /// pending | running | success | warning | error | skipped
inputParams Json? @map("input_params")
guardrailChecks Json? @map("guardrail_checks") /// JIT 护栏检验结果
outputResult Json? @map("output_result")
errorInfo Json? @map("error_info")
executionMs Int? @map("execution_ms")
startedAt DateTime? @map("started_at")
completedAt DateTime? @map("completed_at")
workflow SsaWorkflow @relation(fields: [workflowId], references: [id], onDelete: Cascade)
@@index([workflowId], map: "idx_ssa_workflow_step_workflow")
@@map("ssa_workflow_steps")
@@schema("ssa_schema")
}
```
#### SsaSession 扩展字段
```prisma
model SsaSession {
// ... 现有字段 ...
// 🆕 新增字段
dataProfile Json? @map("data_profile") /// Python 生成的 DataProfile
// 🆕 新增关系
workflows SsaWorkflow[]
}
```
#### 迁移任务
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 🆕 备份开发数据库 | 0.5h | P0 | - |
| 🆕 修改 schema.prisma（新增表 + 字段） | 1h | P0 | 备份 |
| 🆕 执行 `prisma migrate dev --name add_ssa_workflow_tables` | 0.5h | P0 | Schema |
| 🆕 检查生成的迁移 SQL | 0.5h | P0 | 迁移 |
| 🆕 本地测试 | 1h | P0 | SQL |
| 🆕 更新 Prisma Client 类型 | 0.5h | P0 | 测试 |
**预估总工时：4h（约 0.5 天）**
---
### 5.1 阶段一：R 工具扩展（6 个新工具）
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 实现 ST_MANN_WHITNEY（Mann-Whitney U 检验） | 4h | P0 | - |
| 实现 ST_CHI_SQUARE（卡方检验） | 4h | P0 | - |
| 实现 ST_LOGISTIC_BINARY（二元 Logistic 回归） | 6h | P0 | - |
| 实现 ST_T_TEST_PAIRED（配对 T 检验） | 3h | P1 | - |
| 实现 ST_CORRELATION（相关分析） | 3h | P1 | - |
| 实现 ST_DESCRIPTIVE（描述性统计） | 4h | P1 | - |
| 统一 run_analysis() 入口 + 护栏函数 | 4h | P0 | 以上全部 |
**预估总工时：28h（约 4 天）**
### 5.2 阶段二：数据诊断器（Python + R 分工）
#### 5.2.1 时机 A：Python DataProfile（上传时）
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 🆕 扩展 Tool C Python：新增 `/api/dc/profile` 端点 | 4h | P0 | - |
| 🆕 实现 DataProfileService 后端服务（调用 Tool C） | 3h | P0 | Python 端点 |
| 🆕 实现前端 DataProfile 展示卡片 | 3h | P0 | 后端服务 |
| 🆕 集成到 SSA 上传数据流程 | 2h | P0 | 前端卡片 |
#### 5.2.2 时机 B：R JIT 护栏（执行前）
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 🆕 实现 R 正态性检验函数（Shapiro-Wilk） | 2h | P0 | - |
| 🆕 实现 R 方差齐性检验函数（Levene） | 2h | P0 | - |
| 🆕 集成 JIT 护栏到 WorkflowExecutorService | 2h | P0 | R 函数 |
| 🆕 实现自动方法降级逻辑 | 2h | P0 | JIT 护栏 |
**预估总工时：20h（约 2.5 天）**
### 5.3 阶段三：路径规划器（多工具流程规划）
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 设计 WorkflowPlan 数据结构 | 2h | P0 | - |
| 实现 WorkflowPlannerService（LLM 规划） | 6h | P0 | 数据结构 |
| 设计规划 Prompt（工具选择逻辑） | 4h | P0 | 7个工具定义 |
| 实现后端 /plan 接口返回多步骤计划 | 3h | P0 | Planner |
| 实现前端多步骤计划展示卡片 | 4h | P0 | 后端接口 |
**预估总工时：19h（约 2.5 天）**
### 5.4 阶段四：流程执行器（串联执行）
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 实现 WorkflowExecutorService | 6h | P0 | 所有 R 工具 |
| 实现步骤间结果传递逻辑 | 3h | P0 | Executor |
| 实现 SSE 实时进度推送 | 3h | P0 | Executor |
| 实现后端 /execute 接口支持多步骤 | 3h | P0 | SSE |
| 实现前端多步骤进度展示 | 4h | P0 | 后端接口 |
| 实现执行中断/重试机制 | 2h | P1 | 基础执行 |
**预估总工时：21h（约 3 天）**
### 5.5 阶段五：结论生成器增强
| 任务 | 预估 | 优先级 | 依赖 |
|------|------|--------|------|
| 增强 Critic Prompt（多步骤结果整合） | 3h | P0 | - |
| 实现多步骤结果汇总逻辑 | 2h | P0 | Executor |
| 增强报告模板（方法学 + 局限性） | 2h | P1 | - |
**预估总工时：7h（约 1 天）**
---
## 6. 开发计划时间表
```
Week 1：R 工具扩展
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-2: ST_MANN_WHITNEY + ST_CHI_SQUARE
Day 3-4: ST_LOGISTIC_BINARY（复杂度最高）
Day 5: ST_T_TEST_PAIRED + ST_CORRELATION + ST_DESCRIPTIVE
Week 2：核心组件开发
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-2: 数据诊断器（ST_QUALITY_REPORT + DataQualityService）
Day 3-4: 路径规划器（WorkflowPlannerService + Prompt）
Day 5: 流程执行器（WorkflowExecutorService）
Week 3：联调与打磨
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Day 1-2: 前端多步骤 UI + SSE 实时进度
Day 3: 结论生成器增强
Day 4-5: 端到端联调测试 + Bug 修复
```
**总预估：3 周（15 个工作日）**
---
## 7. 验收标准
### 7.1 功能验收
| 验收项 | 标准 |
|--------|------|
| 工具覆盖 | 7 个工具全部可用 |
| 数据诊断 | 上传数据后自动生成质量核查报告 |
| 流程规划 | LLM 能根据用户问题规划 2-7 步流程 |
| 串联执行 | 多步骤顺序执行，实时显示进度 |
| 结果整合 | 生成包含所有步骤结果的综合报告 |
### 7.2 场景验收（必须通过）
| 场景 | 预期流程 |
|------|---------|
| "比较两组血压" | 描述统计 → T检验 → （非正态时）Mann-Whitney |
| "分析吸烟与肺癌的关系" | 描述统计 → 卡方检验 |
| "哪些因素影响糖尿病" | 描述统计 → 单因素Logistic → 多因素Logistic |
| "治疗前后血压变化" | 描述统计 → 配对T检验 |
| "年龄与血压相关吗" | 描述统计 → 相关分析 |
### 7.3 性能验收
| 指标 | 标准 |
|------|------|
| 数据诊断耗时 | < 5 秒（200行数据） |
| 流程规划耗时 | < 3 秒（LLM 响应） |
| 单步骤执行耗时 | < 10 秒 |
| 完整流程耗时 | < 60 秒（5 步骤） |
---
## 8. 风险与应对
| 风险 | 影响 | 应对策略 |
|------|------|---------|
| LLM 规划不准确 | 工具选择错误 | 增加护栏校验 + 人工确认 |
| R 工具开发延期 | 阻塞后续开发 | 可并行开发，先做简单工具 |
| 多步骤执行失败 | 流程中断 | 实现重试机制 + 部分结果保存 |
| 结果传递复杂 | 步骤间数据格式不匹配 | 定义统一的 StepResult 结构 |
---
## 9. 🚨 工程规范（架构审查暗礁预警）
> **来源：** 架构审查报告，避免开发过程中踩坑
### 9.1 暗礁 1：R 脚本输出裁剪（防止 LLM Token 超载）
**问题**：R 脚本返回的 JSON 可能包含原始全量数据（如残差数组、原始数据点），导致 LLM Token 超载、响应极慢甚至报错。
**强制规范**：
```r
# ❌ 错误示例：返回原始数据
result <- list(
p_value = 0.032,
residuals = residuals(model), # 可能有几百个值！
raw_data = df # 原始数据！
)
# ✅ 正确示例：只返回精简结果
result <- list(
p_value = 0.032,
t_statistic = 2.15,
df = 48,
ci_lower = 0.5,
ci_upper = 2.3,
effect_size = 0.62,
# 图表只返回精简坐标点（最多 100 个点）
plot_data = head(plot_points, 100)
)
```
**检查清单**：
- [ ] 禁止返回 `residuals`、`fitted.values` 等长数组
- [ ] 禁止返回原始数据 `df` 或 `raw_data`
- [ ] 图表坐标点限制在 100 个以内
- [ ] JSON 输出大小不超过 50KB
---
### 9.2 暗礁 3：容错管道（支持部分成功）
**问题**：多步骤执行时，一步失败导致整个流程崩溃，用户丢失已成功的结果。
**强制规范**：
```typescript
// WorkflowExecutorService 必须实现容错管道
interface StepResult {
step: number;
toolCode: string;
status: 'success' | 'warning' | 'error';
result?: any;
error?: {
code: string;
message: string;
userHint: string;
};
executionMs: number;
}
// ✅ 正确实现：每步结果独立保存
async executeWorkflow(workflow: WorkflowStep[]): Promise<StepResult[]> {
const results: StepResult[] = [];
for (const step of workflow) {
try {
const result = await this.executeStep(step);
results.push({ ...step, status: 'success', result });
} catch (error) {
// ⚠️ 关键：失败不中断，记录错误继续
results.push({
...step,
status: 'error',
error: this.formatError(error)
});
// 只有关键错误才中断
if (this.isCriticalError(error)) break;
}
}
return results; // 返回部分成功的结果
}
```
**前端展示**：
```
✅ 描述性统计 (执行成功, 点击查看)
✅ 正态性检验 (执行成功, 点击查看)
❌ T检验 (执行失败: 方差为0, 点击查看原因)
⏸️ Mann-Whitney (已跳过)
```
---
### 9.3 SSE 消息格式规范
**强制格式**：
```typescript
interface SSEMessage {
type: 'step_start' | 'step_progress' | 'step_complete' | 'step_error' | 'workflow_complete';
step: number;
toolCode: string;
toolName: string;
status: 'running' | 'success' | 'error' | 'skipped';
message: string;
progress?: number; // 0-100，可选
result?: any; // 步骤完成时的结果
error?: {
code: string;
message: string;
userHint: string;
};
timestamp: string;
}
```
**示例消息序列**：
```json
{"type":"step_start","step":1,"toolCode":"ST_DESCRIPTIVE","toolName":"描述性统计","status":"running","message":"正在生成描述性统计...","timestamp":"2026-02-20T10:00:00Z"}
{"type":"step_complete","step":1,"toolCode":"ST_DESCRIPTIVE","toolName":"描述性统计","status":"success","message":"描述性统计完成","result":{...},"timestamp":"2026-02-20T10:00:02Z"}
{"type":"step_start","step":2,"toolCode":"ST_T_TEST_IND","toolName":"独立样本T检验","status":"running","message":"正在执行正态性检验（JIT护栏）...","timestamp":"2026-02-20T10:00:02Z"}
{"type":"step_progress","step":2,"toolCode":"ST_T_TEST_IND","toolName":"独立样本T检验","status":"running","message":"正态性检验通过，执行T检验...","progress":50,"timestamp":"2026-02-20T10:00:03Z"}
{"type":"step_complete","step":2,"toolCode":"ST_T_TEST_IND","toolName":"独立样本T检验","status":"success","message":"T检验完成","result":{...},"timestamp":"2026-02-20T10:00:05Z"}
{"type":"workflow_complete","status":"success","message":"分析流程执行完成，共2个步骤","timestamp":"2026-02-20T10:00:05Z"}
```
**前端渲染效果**：
```
┌─────────────────────────────────────────────────────────────────┐
│ 执行日志 │
├─────────────────────────────────────────────────────────────────┤
│ [10:00:00] ▶ 正在生成描述性统计... │
│ [10:00:02] ✅ 描述性统计完成 │
│ [10:00:02] ▶ 正在执行正态性检验（JIT护栏）... │
│ [10:00:03] ▶ 正态性检验通过，执行T检验... │
│ [10:00:05] ✅ T检验完成 │
│ [10:00:05] 🎉 分析流程执行完成，共2个步骤 │
└─────────────────────────────────────────────────────────────────┘
```
---
## 10. Phase 2A 完成后的系统能力
```
┌─────────────────────────────────────────────────────────────────┐
│ Phase 2A 完成后的 SSA-Pro │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ✅ 用户能做什么： │
│ ────────────────────────────────────────────────────────────── │
│ • 上传数据，自动获得数据质量报告 │
│ • 用自然语言描述分析需求 │
│ • 系统自动规划多步骤分析流程 │
│ • 一键执行，实时看到每步进度 │
│ • 获得包含完整方法学说明的论文级报告 │
│ │
│ ✅ 系统具备的智能： │
│ ────────────────────────────────────────────────────────────── │
│ • 理解医学术语，翻译为统计需求 │
│ • 根据数据特征自动调整方法（正态→非参数） │
│ • 规划完整分析路径，而非单一方法 │
│ • 整合多步骤结果，生成综合结论 │
│ │
│ ✅ 后续扩展方向： │
│ ────────────────────────────────────────────────────────────── │
│ • 增加更多统计方法（复制工具模板即可） │
│ • 增加咨询模式（无数据也能获得 SAP） │
│ • 增加配置中台（量产工具管理） │
│ • Phase 3 靶向代码修改（架构已预埋） │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 11. 总结
**Phase 2A 是 SSA-Pro MVP 的真正内核。**
完成 Phase 2A 后：
- 5 大核心组件全部跑通
- 7 个统计方法可用
- 多工具流程规划能力上线
- 数据质量核查报告上线
- **智能化能力完成 85%+**
后续工作（Phase 2B+）主要是：
- 扩展更多统计方法（复制粘贴）
- 增加咨询模式（锦上添花）
- 配置中台（量产效率）
**这才是以终为始的 MVP 开发策略。**

153
docs/03-业务模块/SSA-智能统计分析/04-开发计划/08-Block-based动态结果渲染开发计划.md Normal file
View File

@@ -0,0 +1,153 @@
# Block-based 动态结果渲染开发计划
> **版本：** v1.0
> **创建日期：** 2026-02-20
> **状态：** 📋 待开始
> **优先级：** P0（架构级改进，影响所有后续工具开发）
> **关联文档：** `06-开发记录/SSA-Pro 动态结果渲染与通信协议规范.md`
---
## 1. 背景与动机
### 当前痛点
目前每个 R 工具返回独特的数据结构，导致：
- **R 端**：每个工具自定义 `results` 字段（T检验有 `group_stats`，Logistic有 `coefficients`，描述性统计有 `variables`）
- **Node.js 后端**：用 `...response.data.results` 硬展开，手动拼装 `plots`、`result_table` 等字段
- **前端**：为每种工具写 `if (isDescriptive)` / `if (r?.coefficients)` 等分支渲染逻辑
- **导出报告**：Word 导出同样需要为每种工具写独立的构建逻辑
**核心矛盾**：R 工具数量增长（当前 7 个，目标 100+），但前端/后端的维护成本线性增长。
### 目标
采用 Block-based 协议，实现：
- R 端输出标准化的 `report_blocks` 数组
- Node.js 零维护透传
- 前端一个 `DynamicReport` 组件渲染所有工具的结果
- Word 导出一个 `exportBlocksToWord` 函数处理所有工具
---
## 2. 技术方案
### 2.1 四种 Block 类型
| Block 类型 | 用途 | 典型场景 |
|-----------|------|---------|
| `markdown` | 文本解读、警告、结论 | AI 统计解读、护栏警告、方法说明 |
| `table` | 三线表、矩阵 | 分组统计表、回归系数表、列联表、描述性统计表 |
| `image` | 可视化图表 | 箱线图、森林图、直方图、马赛克图 |
| `key_value` | 核心统计量高亮 | P值、统计量、效应量、AIC |
### 2.2 协议结构
```json
{
"status": "success",
"trace_log": ["..."],
"reproducible_code": "library(ggplot2)...",
"report_blocks": [
{
"type": "key_value",
"title": "核心指标",
"items": [
{"label": "统计方法", "value": "Independent T-Test"},
{"label": "t 值", "value": "2.45"},
{"label": "P 值", "value": "0.015", "status": "significant"}
]
},
{
"type": "table",
"title": "Table 1. 分组统计",
"data": {
"headers": ["Group", "N", "Mean ± SD"],
"rows": [["Drug", "60", "14.5 ± 3.2"], ["Placebo", "60", "8.2 ± 2.8"]]
}
},
{
"type": "image",
"title": "Figure 1. 分布对比",
"format": "base64",
"src": "iVBORw0KGgo...",
"caption": "箱线图展示两组分布"
},
{
"type": "markdown",
"content": "**AI 解读：** 两组差异具有统计学意义 (P = 0.015)..."
}
]
}
```
---
## 3. 实施计划
### Phase 1：基础设施（1 天）
| 任务 | 层级 | 说明 | 预估 |
|------|------|------|------|
| 1.1 创建 `DynamicReport.tsx` 组件 | 前端 | 4 个 Block 渲染子组件 | 2h |
| 1.2 创建 `exportBlocksToWord.ts` | 前端 | Block 数组 → Word 文档 | 2h |
| 1.3 后端透传 `report_blocks` | 后端 | WorkflowExecutorService 透传 | 0.5h |
| 1.4 R 端辅助函数库 `block_helpers.R` | R | `make_table_block()`, `make_image_block()` 等 | 1h |
| 1.5 SSAWorkspacePane 集成 | 前端 | 优先读 `report_blocks`，fallback 旧逻辑 | 1h |
### Phase 2：R 工具改造（2 天）
| 任务 | R 工具 | 当前 Block 输出内容 | 预估 |
|------|--------|-------------------|------|
| 2.1 | `descriptive.R` | summary key_value + 数值变量 table + 分类变量 table + 直方图/柱状图 image | 1.5h |
| 2.2 | `t_test_ind.R` | 核心指标 key_value + 分组统计 table + AI 解读 markdown + 箱线图 image | 1h |
| 2.3 | `logistic_binary.R` | 模型拟合 key_value + 回归系数 table + 森林图 image + AI 解读 markdown | 1.5h |
| 2.4 | `chi_square.R` | 核心指标 key_value + 列联表 table + 马赛克图 image | 1h |
| 2.5 | `correlation.R` | 核心指标 key_value + 散点图 image + AI 解读 markdown | 1h |
| 2.6 | `t_test_paired.R` | 核心指标 key_value + 配对差值 table + image | 1h |
| 2.7 | `mann_whitney.R` | 核心指标 key_value + 分组统计 table + image | 1h |
### Phase 3：清理旧代码（0.5 天）
| 任务 | 说明 | 预估 |
|------|------|------|
| 3.1 移除 SSAWorkspacePane 中的自定义渲染逻辑 | 删除 `isDescriptive`、`r?.coefficients` 等分支 | 1h |
| 3.2 移除 useAnalysis.ts 中的自定义导出逻辑 | 删除 `isDescStep`、`classifyExportVar` 等 | 1h |
| 3.3 移除后端 result 字段展开逻辑 | 删除 `...response.data.results` 拼装 | 0.5h |
| 3.4 更新文档 | 更新开发指南、R 服务开发规范 | 0.5h |
---
## 4. 向后兼容策略
采用 **渐进式迁移**，不一刀切：
1. R 工具同时返回 `results`（旧）和 `report_blocks`（新）
2. 前端优先读 `report_blocks`，如果不存在则 fallback 到旧的自定义渲染
3. 全部 7 个工具迁移完成后，再删除旧渲染代码
---
## 5. 预期收益
| 指标 | 改造前 | 改造后 |
|------|--------|--------|
| 新增 1 个 R 工具的前端开发量 | 50-100 行自定义渲染 + 50 行导出逻辑 | 0 行 |
| 新增 1 个 R 工具的后端开发量 | 10-20 行字段映射 | 0 行 |
| 前端结果渲染组件数 | N 个（每种工具一个分支） | 1 个 DynamicReport |
| Word 导出维护成本 | 每种工具单独处理 | 1 个通用函数 |
---
## 6. 总工时估算
| Phase | 工时 |
|-------|------|
| Phase 1：基础设施 | 6.5h |
| Phase 2：R 工具改造 | 8h |
| Phase 3：清理旧代码 | 3h |
| **合计** | **~17.5h（约 2.5 天）** |
---
**下一步：** 待用户确认后开始 Phase 1 实施。