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>
756 lines
37 KiB
Markdown
756 lines
37 KiB
Markdown
# 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 开发策略。**
|