AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md

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 双轨逻辑

数据模型

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 安全防御）

---

🔧 开发环境

启动服务

# 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

运行测试

cd backend
npx tsx scripts/test-ssa-qper-e2e.ts

Prompt 种子（需数据库运行）

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 工具补齐 + 部署上线