HaHafeng
11676f2840
Bug fixes: - Fix garbled error messages in chat (TypeWriter rendering issue) - Fix R engine NA crash in descriptive.R (defensive isTRUE/is.na checks) - Fix intent misclassification for statistical significance queries - Fix step 2 results not displayed (accept warning status alongside success) - Fix incomplete R code download (only step 1 included) - Fix multi-task state confusion (clicking old card shows new results) - Add R engine and backend parameter logging for debugging Refactor - Unified Record Architecture: - Replace 12 global singleton fields with AnalysisRecord as single source of truth - Remove isWorkflowMode branching across all components - One Analysis = One Record = N Steps paradigm - selectRecord only sets currentRecordId, all rendering derives from currentRecord - Fix cross-hook-instance issue: executeWorkflow fallback to store currentRecordId Updated files: ssaStore, useWorkflow, useAnalysis, SSAChatPane, SSAWorkspacePane, SSACodeModal, WorkflowTimeline, QueryService, WorkflowExecutorService, descriptive.R Tested: Manual integration test passed - multi-task switching, R code completeness Co-authored-by: Cursor <cursoragent@cursor.com>
271 lines
12 KiB
Markdown
271 lines
12 KiB
Markdown
# SSA智能统计分析模块 - 当前状态与开发指南
|
||
|
||
> **文档版本：** v2.1
|
||
> **创建日期：** 2026-02-18
|
||
> **最后更新：** 2026-02-21
|
||
> **维护者：** 开发团队
|
||
> **当前状态：** 🎉 **QPER 主线闭环 + 集成测试通过 + 统一状态管理重构完成**
|
||
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
|
||
>
|
||
> **最新进展（2026-02-21 晚）：**
|
||
> - ✅ **前后端集成测试** — 7 个 Bug 全部修复（R 引擎防御、意图识别、前端状态）
|
||
> - ✅ **统一状态管理重构** — 消除 isWorkflowMode 双轨逻辑，AnalysisRecord 成为唯一数据源
|
||
> - ✅ **多任务切换** — 点击不同卡片正确显示各自的分析计划和结果
|
||
> - ✅ **R 代码完整性** — 多步骤分析的所有步骤代码均可下载/复制
|
||
|
||
---
|
||
|
||
## 📊 模块概览
|
||
|
||
### 基本信息
|
||
|
||
| 项目 | 信息 |
|
||
|------|------|
|
||
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
|
||
| **模块定位** | AI驱动的"白盒"统计分析系统 |
|
||
| **架构模式** | **QPER — Query → Planner → Execute → Reflection** |
|
||
| **前端状态模型** | **Unified Record Architecture — 一次分析 = 一个 Record = N 个 Steps** |
|
||
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
|
||
| **目标用户** | 临床研究人员、生物统计师 |
|
||
| **开发状态** | 🎉 **QPER 主线闭环 + 集成测试通过，Phase Deploy 待启动** |
|
||
|
||
### 核心目标
|
||
|
||
> 让**不懂统计的医生**完成**专业级的统计分析**。
|
||
>
|
||
> **三大特征**：
|
||
> 1. **白盒**：用户完全理解 AI 做了什么，为什么这样做
|
||
> 2. **严谨**：统计护栏自动检测前提条件，违规时自动降级
|
||
> 3. **可交付**：生成论文级结论 + 可在本地运行的 R 代码，支持审计复现
|
||
|
||
---
|
||
|
||
## 🏗️ QPER 四层架构
|
||
|
||
```
|
||
用户："比较两组血压有没有差别"
|
||
│
|
||
▼
|
||
┌─ Q · Query ─────────────────────────────────────┐
|
||
│ LLM 意图解析 + Zod 动态防幻觉 + 追问卡片 │
|
||
│ 输出：ParsedQuery { goal, y, x, design } │
|
||
└──────────────────────┬──────────────────────────┘
|
||
▼
|
||
┌─ P · Planner ────────────────────────────────────┐
|
||
│ 决策表四维匹配 + 流程模板填充 + EPV 防护 │
|
||
│ 输出：WorkflowPlan + PlannedTrace │
|
||
└──────────────────────┬──────────────────────────┘
|
||
▼
|
||
┌─ E · Execute ────────────────────────────────────┐
|
||
│ R 引擎执行 + SSE 实时进度 + Block-based 输出 │
|
||
│ 输出：StepResult[] + ReportBlock[] │
|
||
└──────────────────────┬──────────────────────────┘
|
||
▼
|
||
┌─ R · Reflection ─────────────────────────────────┐
|
||
│ LLM 论文级结论 + 槽位注入 + Zod 校验 │
|
||
│ 输出：ConclusionReport（6 要素） │
|
||
└──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 降级体系
|
||
|
||
| 层 | 正常路径 | 降级路径 | 触发条件 |
|
||
|----|---------|---------|---------|
|
||
| Q | QueryService（LLM） | 正则匹配 fallback | LLM 超时/不可用 |
|
||
| P | DecisionTable + FlowTemplate | 硬编码 if/else | 决策表无匹配 |
|
||
| E | R 引擎 | 错误分类→友好提示 | R 运行时崩溃 |
|
||
| R | ReflectionService（LLM） | ConclusionGeneratorService（规则拼接） | LLM 失败/Zod 校验失败 |
|
||
|
||
---
|
||
|
||
## 🎨 前端架构：统一状态管理
|
||
|
||
> **2026-02-21 重构完成** — 消除 isWorkflowMode 双轨逻辑
|
||
|
||
### 数据模型
|
||
|
||
```typescript
|
||
AnalysisRecord {
|
||
id: string; // = workflowId or generated
|
||
query: string; // 用户原始问题
|
||
createdAt: string;
|
||
status: 'planning' | 'executing' | 'completed' | 'error';
|
||
plan: WorkflowPlan | null; // 统一用 WorkflowPlan（单步也是 1 步的 Plan）
|
||
steps: WorkflowStepResult[]; // 统一用步骤数组
|
||
progress: number; // 0-100
|
||
conclusionReport: ConclusionReport | null;
|
||
}
|
||
```
|
||
|
||
### Store 结构
|
||
|
||
- `analysisHistory: AnalysisRecord[]` — 所有分析记录
|
||
- `currentRecordId: string | null` — 当前激活的记录
|
||
- 派生：`currentRecord = analysisHistory.find(r => r.id === currentRecordId)`
|
||
- 操作：`addRecord(query, plan)` / `updateRecord(id, patch)` / `selectRecord(id)`
|
||
|
||
### 已删除的全局字段
|
||
|
||
`currentPlan`、`executionResult`、`traceSteps`、`workflowPlan`、`workflowSteps`、`workflowProgress`、`conclusionReport`、`isWorkflowMode` 及所有对应 setter。
|
||
|
||
---
|
||
|
||
## 📋 开发进度
|
||
|
||
| Phase | 任务 | 工时 | 状态 | 完成日期 |
|
||
|-------|------|------|------|---------|
|
||
| Phase 0 | 需求分析与架构设计 | - | ✅ 已完成 | 2026-02-18 |
|
||
| Phase 1 | 骨架搭建（T 检验端到端） | - | ✅ 已完成 | 2026-02-19 |
|
||
| Phase 1.5 | V11 UI 前后端联调 | - | ✅ 已完成 | 2026-02-20 |
|
||
| Phase 2A | 多步骤工作流 + 前端集成 | - | ✅ 已完成 | 2026-02-20 |
|
||
| **Phase E+** | **Block-based 标准化** | **15.5h** | ✅ **已完成** | 2026-02-20 |
|
||
| **Phase Q** | **LLM 意图理解** | **33h** | ✅ **已完成** | 2026-02-21 |
|
||
| **Phase P** | **决策表 + 流程模板** | **23h** | ✅ **已完成** | 2026-02-21 |
|
||
| **Phase R** | **LLM 论文级结论** | **22h** | ✅ **已完成** | 2026-02-21 |
|
||
| **集成测试** | **Bug 修复 + 统一状态管理重构** | **~4h** | ✅ **已完成** | 2026-02-21 |
|
||
| Phase Deploy | 工具补齐 + 部署上线 | 37h | 📋 待开始 | - |
|
||
| Phase Q+ | 人机协同增强 | 20h | 📋 待开始 | - |
|
||
| **QPER 透明化** | **Pipeline 可观测性增强** | TBD | 📋 待开始 | - |
|
||
|
||
### 已完成核心功能
|
||
|
||
| 组件 | 完成项 | 状态 |
|
||
|------|--------|------|
|
||
| **R 服务** | 7 个 R 工具 + Block-based 输出 + 防御性编程（NA 安全） | ✅ |
|
||
| **Q 层** | QueryService + LLM Intent + Zod 防幻觉 + 追问卡片 + 统计学意义关键词增强 | ✅ |
|
||
| **P 层** | ConfigLoader + DecisionTable + FlowTemplate + PlannedTrace + 热更新 API | ✅ |
|
||
| **E 层** | WorkflowExecutor + RClient + SSE 实时进度 + 错误分类映射 + 参数日志 | ✅ |
|
||
| **R 层** | ReflectionService + 槽位注入 + Zod 校验 + 敏感性冲突准则 + 结论缓存 + Word 增强 | ✅ |
|
||
| **前端** | 统一 Record 架构 + 多任务切换 + 已完成标记 + DynamicReport + Word/R 导出 | ✅ |
|
||
| **Python** | DataProfileService（is_id_like 标记）+ CSV 解析 | ✅ |
|
||
| **测试** | QPER 端到端 40/40 + 集成测试 7 Bug 修复 | ✅ |
|
||
|
||
---
|
||
|
||
## 📂 代码目录结构
|
||
|
||
```
|
||
backend/src/modules/ssa/
|
||
├── services/
|
||
│ ├── QueryService.ts # Q 层：LLM 意图解析
|
||
│ ├── DecisionTableService.ts # P 层：四维匹配
|
||
│ ├── FlowTemplateService.ts # P 层：流程模板
|
||
│ ├── WorkflowPlannerService.ts # P 层：核心规划入口
|
||
│ ├── WorkflowExecutorService.ts # E 层：步骤编排 + SSE
|
||
│ ├── RClientService.ts # E 层：R 引擎调用
|
||
│ ├── ReflectionService.ts # R 层：LLM 结论生成
|
||
│ ├── ConclusionGeneratorService.ts # R 层 fallback
|
||
│ ├── DataProfileService.ts # 共享：Python 数据质量
|
||
│ └── DataParserService.ts # 共享：文件解析
|
||
├── config/
|
||
│ ├── ConfigLoader.ts # 通用 JSON 加载 + Zod 校验
|
||
│ ├── tools_registry.json # R 工具注册表
|
||
│ ├── decision_tables.json # 四维匹配规则
|
||
│ └── flow_templates.json # 流程模板
|
||
├── types/
|
||
│ ├── query.types.ts # Q 层接口
|
||
│ └── reflection.types.ts # R 层接口
|
||
├── routes/
|
||
│ ├── workflow.routes.ts # 工作流 API（含结论缓存）
|
||
│ └── config.routes.ts # 热更新 API
|
||
└── ...
|
||
|
||
frontend-v2/src/modules/ssa/
|
||
├── stores/
|
||
│ └── ssaStore.ts # Zustand — Unified Record Architecture
|
||
├── hooks/
|
||
│ ├── useWorkflow.ts # 工作流 Hook（addRecord/updateRecord）
|
||
│ └── useAnalysis.ts # 上传/Legacy 兼容
|
||
├── components/
|
||
│ ├── SSAChatPane.tsx # 对话区（卡片 → selectRecord）
|
||
│ ├── SSAWorkspacePane.tsx # 工作区（基于 currentRecord 渲染）
|
||
│ ├── SSACodeModal.tsx # R 代码模态框（从 record.steps 聚合）
|
||
│ ├── WorkflowTimeline.tsx # 执行计划时间线
|
||
│ └── DynamicReport.tsx # Block-based 结果渲染
|
||
└── types/
|
||
└── index.ts # 前端类型定义
|
||
|
||
r-statistics-service/
|
||
├── plumber.R # API 入口（含参数日志）
|
||
└── tools/
|
||
└── descriptive.R # 描述性统计（NA 安全防御）
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发环境
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 1. 数据库（Docker）
|
||
docker start ai-clinical-postgres
|
||
|
||
# 2. Python 服务
|
||
cd extraction_service && python main.py
|
||
|
||
# 3. R 服务
|
||
cd r-statistics-service && Rscript plumber_api.R
|
||
|
||
# 4. Node.js 后端
|
||
cd backend && npm run dev
|
||
|
||
# 5. 前端
|
||
cd frontend-v2 && npm run dev
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
cd backend
|
||
npx tsx scripts/test-ssa-qper-e2e.ts
|
||
```
|
||
|
||
### Prompt 种子（需数据库运行）
|
||
|
||
```bash
|
||
cd backend
|
||
npx tsx scripts/seed-ssa-intent-prompt.ts
|
||
npx tsx scripts/seed-ssa-reflection-prompt.ts
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| **QPER 开发计划（主线）** | `04-开发计划/10-QPER架构开发计划-智能化主线.md` |
|
||
| **QPER 开发总结** | `06-开发记录/SSA-QPER架构开发总结-2026-02-21.md` |
|
||
| **集成测试 Bug 修复** | `06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md` |
|
||
| **智能化愿景设计** | `00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md` |
|
||
| **PRD** | `00-系统设计/PRD SSA-Pro 严谨型智能统计分析模块.md` |
|
||
| **架构设计 V4** | `00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md` |
|
||
|
||
---
|
||
|
||
## 🎯 下一步
|
||
|
||
### 近期（优先级高）
|
||
|
||
1. **QPER 透明化（Pipeline 可观测性）**
|
||
- Q 层：展示 LLM 解析结果（goal、变量、置信度）和降级原因
|
||
- P 层：展示决策表匹配过程和流程模板填充参数
|
||
- E 层：实时展示步骤输入参数 + R 返回摘要；开发模式显示 R 原始错误
|
||
- R 层：展示槽位注入内容和 Zod 校验状态
|
||
- 开发者面板：持久化 trace_log + LLM prompt/response 可查看
|
||
|
||
2. **Phase Deploy（37h）** — 补齐 ANOVA / Fisher / Wilcoxon / 线性回归 + 复合工具 ST_BASELINE_TABLE + 部署上线
|
||
|
||
### 中期
|
||
|
||
3. **Phase Q+（20h）** — 变量数据字典（AI 先猜用户微调）+ 变量选择确认面板（AI 推荐医生确认）
|
||
4. **前端 UI 细节打磨** — 执行计划格式美化、错误状态视觉增强
|
||
|
||
---
|
||
|
||
**文档版本：** v2.1
|
||
**最后更新：** 2026-02-21
|
||
**当前状态：** 🎉 QPER 主线闭环 + 集成测试通过 + 统一状态管理重构完成
|
||
**下一步：** QPER 透明化 → Phase Deploy 工具补齐 + 部署上线
|