# SSA智能统计分析模块 - 当前状态与开发指南

> **文档版本：** v3.0  
> **创建日期：** 2026-02-18  
> **最后更新：** 2026-02-22  
> **维护者：** 开发团队  
> **当前状态：** 🎉 **QPER 主线闭环 + 智能对话与工具体系架构设计完成**  
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
> 
> **最新进展（2026-02-22）：**
> - ✅ **智能对话与工具体系架构设计完成** — 四层七工具 + 对话层 LLM + 意图路由器
> - ✅ **开发计划 v1.2 定稿** — 6 Phase / 134h / 22 天（含 8 条架构约束 + Postgres-Only 缓存规范）
> - ✅ **3 份系统设计文档** — 意图识别架构、工具体系规划方案、四层七工具实现机制详解
> - ✅ **6 条架构审查建议已裁定** — 3 预警（Function Calling 冲突、System Prompt 膨胀、流式输出）+ 3 盲区（Postgres-Only 缓存、上下文守卫、Zod 动态校验）
> 
> **此前进展（2026-02-21）：**
> - ✅ **前后端集成测试** — 7 个 Bug 全部修复（R 引擎防御、意图识别、前端状态）
> - ✅ **统一状态管理重构** — 消除 isWorkflowMode 双轨逻辑，AnalysisRecord 成为唯一数据源
> - ✅ **多任务切换** — 点击不同卡片正确显示各自的分析计划和结果
> - ✅ **R 代码完整性** — 多步骤分析的所有步骤代码均可下载/复制

---

## 📊 模块概览

### 基本信息

| 项目 | 信息 |
|------|------|
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
| **模块定位** | AI驱动的"白盒"统计分析系统 → 升级为"数据感知的统计顾问" |
| **架构模式** | **QPER（执行层）** + **四层七工具 + 对话层 LLM（智能对话层）** |
| **前端状态模型** | **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 |
| **架构设计** | **智能对话与工具体系架构设计** | **~8h** | ✅ **已完成** | 2026-02-22 |
| Phase Deploy | 工具补齐 + 部署上线 | 37h | 📋 待开始 | - |
| **Phase I** | **Session 黑板 + READ 层** | **30h** | 📋 待开始（吸收 Phase Q+） | - |
| **Phase II** | **对话层 LLM + 意图路由器 + 统一对话入口** | **35h** | 📋 待开始 | - |
| **Phase III** | **method_consult + ask_user 标准化** | **20h** | 📋 待开始 | - |
| **Phase IV** | **THINK + ACT 工具封装** | **21h** | 📋 待开始 | - |
| **Phase V** | **反思编排 + 高级特性** | **18h** | 📋 待开始 | - |
| **Phase VI** | **集成测试 + 可观测性** | **10h** | 📋 待开始 | - |

### 已完成核心功能

| 组件 | 完成项 | 状态 |
|------|--------|------|
| **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` |
| **🆕 智能对话与工具体系开发计划** | `04-开发计划/11-智能对话与工具体系开发计划.md` |
| **🆕 意图识别与对话架构设计** | `00-系统设计/SSA-Pro 意图识别与对话架构设计.md` |
| **🆕 工具体系规划方案（融合方案）** | `00-系统设计/SSA-Pro 工具体系规划方案（团队讨论稿）.md` |
| **🆕 四层七工具实现机制详解** | `00-系统设计/SSA-Pro 四层七工具实现机制详解.md` |
| **QPER 开发总结** | `06-开发记录/SSA-QPER架构开发总结-2026-02-21.md` |
| **集成测试 Bug 修复** | `06-开发记录/2026-02-21-集成测试Bug修复与统一状态管理重构.md` |
| **智能化愿景设计** | `00-系统设计/SSA-Pro 理想状态与智能化愿景设计.md` |
| **PRD** | `00-系统设计/PRA SSA-Pro 严谨型智能统计分析模块.md` |
| **架构设计 V4** | `00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md` |

---

## 🎯 下一步

### 近期（优先级高）

1. **Phase Deploy（37h / 5.5 天）** — 补齐 R 工具 7→11 + 生产环境部署上线

2. **Phase I — Session 黑板 + READ 层（30h / 5 天）** — 已吸收 Phase Q+
   - SessionBlackboardService（CacheFactory / Postgres-Only 架构）
   - `get_data_overview` + `get_variable_detail` 工具
   - DataContext 前端展示 + 变量字典面板
   - PICO 推断 + 用户确认流程

3. **Phase II — 对话层 LLM + 意图路由器 + 统一对话入口（35h / 5.5 天）**
   - ConversationService 核心（六段式 System Prompt 动态组装）
   - IntentRouterService（规则 + LLM 混合路由 + 上下文守卫）
   - 统一对话 API `/api/ssa/chat`
   - chat/explore 意图处理

### 中期

4. **Phase III（20h）** — method_consult + ask_user 标准化
5. **Phase IV（21h）** — THINK + ACT 工具封装 + analyze 完整链路
6. **Phase V（18h）** — 反思编排 + discuss + feedback

### 后期

7. **Phase VI（10h）** — 集成测试 + 可观测性（含 QPER 透明化）

**详细计划：** `04-开发计划/11-智能对话与工具体系开发计划.md`（v1.2，含 8 条架构约束 C1-C8）

---

## 🏗️ 智能对话架构概览（四层七工具 + 对话层 LLM）

> **设计目标：** 从"统计分析执行器"升级为"数据感知的统计顾问"

```
用户消息
  │
  ▼
┌─ Intent Router ──────────────────────────────────────┐
│ 规则引擎优先 + LLM 兜底 + 上下文守卫（§16.5）       │
│ → chat / explore / consult / analyze / discuss / feedback │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ Conversation Layer LLM ─────────────────────────────┐
│ 六段式 System Prompt + DataContext 注入 + 流式输出    │
│ Token 预算 ≤4000（§16.2）+ 禁止 Function Calling（§16.1）│
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ 四层七工具 ─────────────────────────────────────────┐
│ READ:  get_data_overview | get_variable_detail | method_consult │
│ INTERACT: ask_user                                    │
│ THINK: analysis_plan                                  │
│ ACT:   run_step | write_report                        │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌─ QPER 执行层（已有） ────────────────────────────────┐
│ Q → P → E → R（四层降级体系，不动）                    │
└──────────────────────────────────────────────────────┘
```

**关键架构约束（详见开发计划 §16-§17）：**

| # | 约束 |
|---|------|
| C1 | 对话层 LLM 禁止 Function Calling tools 参数 |
| C4 | Session 黑板使用 CacheFactory（Postgres-Only，无 Redis） |
| C5 | 数据依赖意图必须有上下文守卫 |
| C6 | LLM 枚举输出必须 Zod 动态校验 |

---

**文档版本：** v3.0  
**最后更新：** 2026-02-22  
**当前状态：** 🎉 QPER 主线闭环 + 智能对话与工具体系架构设计完成  
**下一步：** Phase Deploy（工具补齐）→ Phase I（Session 黑板 + READ 层）