420 lines
18 KiB
Markdown
420 lines
18 KiB
Markdown
# SSA智能统计分析模块 - 当前状态与开发指南
|
||
|
||
> **文档版本：** v1.6
|
||
> **创建日期：** 2026-02-18
|
||
> **最后更新：** 2026-02-20
|
||
> **维护者：** 开发团队
|
||
> **当前状态：** 🎉 **V11 UI 前后端联调测试通过！MVP Phase 1 核心完成 95%**
|
||
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
|
||
>
|
||
> **🎉 里程碑（2026-02-18）：**
|
||
> - ✅ **PRD 完成**：SSA-Pro 严谨型智能统计分析模块需求定义
|
||
> - ✅ **架构设计 V4 完成**：Brain-Hand 双层架构 + 统计护栏 + HITL 人机协同
|
||
> - ✅ **MVP 开发计划 v1.5 完成**：通过 5 轮评审，纳入完整专家配置体系
|
||
> - ✅ **5 份开发文档完成**：总览、任务清单、R服务指南、后端指南、前端指南
|
||
>
|
||
> **🎉 T 检验端到端测试通过（2026-02-19）：**
|
||
> - ✅ **🎉 完整流程验证**：数据上传 → 计划生成 → 分析执行 → 结果展示 → 代码下载
|
||
> - ✅ **R 服务 Bug 修复**：缺失值自动过滤，解决分组变量 3 组问题
|
||
> - ✅ **类型推断优化**：0/1 数字列正确识别为分类变量
|
||
> - ✅ **错误处理增强**：R 服务错误信息正确传递给前端
|
||
> - ✅ **文件名动态生成**：`{toolName}_{dataName}_{MMDD}_{HHmm}.R`
|
||
> - ✅ **前端模块激活**：智能统计分析入口可用
|
||
> - ✅ **用户会话隔离**：不同用户数据正确隔离
|
||
>
|
||
> **🎉 V11 UI 前后端联调测试通过（2026-02-20）：**
|
||
> - ✅ **🎉 V11 UI 像素级还原**：Gemini 风格对话界面，全屏沉浸式体验
|
||
> - ✅ **多任务支持**：单会话内可执行多个分析任务，独立管理状态
|
||
> - ✅ **单页滚动布局**：分析计划 → 执行日志 → 分析结果，步骤进度条导航
|
||
> - ✅ **Word 报告导出**：完整统计报告，包含数据描述、方法、结果、图表、结论
|
||
> - ✅ **输入框遮挡修复**：Scroll Spacer 方案，解决 Flexbox padding-bottom 问题
|
||
> - ✅ **代码清理完成**：删除旧版 V8/V9 组件，精简代码结构
|
||
> - ✅ **前后端完整联调**：数据上传 → 计划生成 → 执行分析 → 结果展示 → 报告导出
|
||
>
|
||
> **🆕 v1.5 新增特性（专家配置体系）：**
|
||
> - 🆕 **统计决策表**：(Goal, Y, X, Design) 四维匹配精准选工具，替代简单 RAG
|
||
> - 🆕 **R 代码库**：支持上传 100+ 成熟 R 脚本，统一 `run_analysis()` 入口
|
||
> - 🆕 **参数映射配置**：JSON Key → R 参数名可配置
|
||
> - 🆕 **护栏规则链**：支持 Block / Warn / Switch 三种 Action
|
||
> - 🆕 **结果解读模板**："填空题"式的论文级结论生成
|
||
|
||
---
|
||
|
||
## 📊 模块概览
|
||
|
||
### 基本信息
|
||
|
||
| 项目 | 信息 |
|
||
|------|------|
|
||
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
|
||
| **模块定位** | AI驱动的"白盒"统计分析系统 |
|
||
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
|
||
| **独立性** | ⭐⭐⭐⭐ 高（可独立使用，也可与其他模块协同） |
|
||
| **目标用户** | 临床研究人员、生物统计师 |
|
||
| **开发状态** | 🚀 **MVP Phase 1 开发中（Week 1 完成 ~95%）** |
|
||
|
||
### 核心目标
|
||
|
||
> 打造一个 **"白盒"、"严谨"、"可交付"** 的智能统计分析系统。
|
||
>
|
||
> **核心差异化**：
|
||
> 1. **白盒**：用户完全理解 AI 做了什么，为什么这样做
|
||
> 2. **严谨**：统计护栏自动检测前提条件，违规时自动降级
|
||
> 3. **可交付**：生成可在本地运行的 R 代码，支持审计复现
|
||
|
||
### 功能规格
|
||
|
||
#### 核心AI能力（规划中）
|
||
|
||
1. **智能规划（Planner）**
|
||
- 🆕 **决策表匹配**：(Goal, Y, X, Design) 四维精准选工具
|
||
- RAG 工具检索：作为决策表的兜底方案
|
||
- 参数映射：将自然语言映射为统计参数（可配置）
|
||
- 统计分析计划（SAP）生成
|
||
|
||
2. **统计护栏（Guardrails）**
|
||
- 正态性检验（Shapiro-Wilk）
|
||
- 方差齐性检验（Levene）
|
||
- 样本量检验
|
||
- 大样本优化（N > 5000 抽样检验）
|
||
- 🆕 **护栏 Action**：Block（阻止） / Warn（警告） / Switch（切换方法）
|
||
|
||
3. **人机协同（HITL）**
|
||
- Plan Card：用户确认/修改分析计划
|
||
- Execution Trace：实时展示执行路径
|
||
- Result Card：结构化结果 + AI 解读
|
||
|
||
4. **代码交付**
|
||
- 生成可复现的 R 代码
|
||
- 自动注入依赖安装脚本
|
||
- APA 格式化输出（p_value_fmt）
|
||
|
||
5. **🆕 咨询模式**
|
||
- 无数据对话：用户只描述研究设计
|
||
- SAP 文档生成：结构化统计分析计划
|
||
- 多格式导出：Word/Markdown
|
||
|
||
6. **🆕 配置中台（专家知识库）**
|
||
- 🆕 **统计决策表**：Goal + Y + X + Design → Tool 映射
|
||
- 🆕 **R 代码库**：100+ 成熟脚本上传，统一 `run_analysis()` 入口
|
||
- 🆕 **参数映射**：JSON Key → R 参数名 + 校验规则
|
||
- 🆕 **护栏规则链**：Check → Threshold → Action (Block/Warn/Switch)
|
||
- 🆕 **结果解读模板**："填空题"式论文级结论
|
||
- Excel 配置导入 + 热加载 + 配置校验
|
||
|
||
#### MVP 工具清单（10个）
|
||
|
||
| 工具代码 | 工具名称 | 适用场景 |
|
||
|---------|---------|---------|
|
||
| ST_T_TEST_IND | 独立样本T检验 | 两组连续变量比较 |
|
||
| ST_T_TEST_PAIRED | 配对样本T检验 | 配对设计 |
|
||
| ST_WILCOXON | Wilcoxon秩和检验 | T检验的非参数替代 |
|
||
| ST_ANOVA_ONE | 单因素方差分析 | 多组连续变量比较 |
|
||
| ST_CHI_SQUARE | 卡方检验 | 分类变量关联 |
|
||
| ST_FISHER | Fisher精确检验 | 小样本分类变量 |
|
||
| ST_CORRELATION | Pearson/Spearman相关 | 连续变量相关性 |
|
||
| ST_REGRESSION_LINEAR | 线性回归 | 预测建模 |
|
||
| ST_REGRESSION_LOGISTIC | Logistic回归 | 二分类预测 |
|
||
| ST_DESCRIBE | 描述性统计 | 数据概览 |
|
||
|
||
---
|
||
|
||
## 🏗️ 架构设计
|
||
|
||
### Brain-Hand 双层架构 + 配置中台
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 用户界面 (Frontend) │
|
||
│ 🆕 ModeSwitch | DataUploader | PlanCard | ResultCard │
|
||
│ ↓ 智能分析 ↓ 咨询模式 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Planner (Brain/大脑) - Node.js │
|
||
│ ┌─────────────────────────────────────────────────────┐│
|
||
│ │ DataParserService: 数据解析 → Schema 提取 ││
|
||
│ │ ToolRetrievalService: RAG 工具检索 ││
|
||
│ │ PlannerService: LLM 规划（有数据） ││
|
||
│ │ 🆕 ConsultService: 无数据咨询 ││
|
||
│ │ 🆕 SAPGeneratorService: SAP 文档生成 ││
|
||
│ │ CriticService: 结果解读（流式） ││
|
||
│ └─────────────────────────────────────────────────────┘│
|
||
│ 📌 只看 Schema，支持有数据/无数据两种模式 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
↓ (仅智能分析模式)
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Executor (Hand/四肢) - R Docker │
|
||
│ ┌─────────────────────────────────────────────────────┐│
|
||
│ │ data_loader.R: 混合数据协议（inline/OSS） ││
|
||
│ │ guardrails.R: 统计护栏（正态/方差齐性/样本量） ││
|
||
│ │ tools/*.R: 统计工具 Wrapper（glue 模板） ││
|
||
│ │ result_formatter.R: 结果格式化（p_value_fmt） ││
|
||
│ │ error_codes.R: 结构化错误码 ││
|
||
│ └─────────────────────────────────────────────────────┘│
|
||
│ 📌 操作真实数据 + 生成可复现代码 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
▲
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ 🆕 配置中台 (Config Center) │
|
||
│ ┌─────────────────────────────────────────────────────┐│
|
||
│ │ ConfigLoaderService: Excel 配置加载 ││
|
||
│ │ ConfigValidatorService: 配置校验 ││
|
||
│ │ ConfigCacheService: 配置缓存 + 热加载 ││
|
||
│ └─────────────────────────────────────────────────────┘│
|
||
│ 📌 统计专家可配置，系统动态加载 │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 关键技术决策
|
||
|
||
| 决策点 | 方案 | 理由 |
|
||
|--------|------|------|
|
||
| **R 服务部署** | SAE Docker（固定 2 实例） | 避免冷启动延迟 |
|
||
| **数据传输** | 混合协议（<2MB inline, 2-20MB OSS） | 平衡性能与内存 |
|
||
| **代码生成** | glue 模板 | 可维护性好于 paste0 |
|
||
| **LLM 输出** | jsonrepair + Zod | 容错 JSON 解析 |
|
||
| **隐私保护** | Schema 脱敏 + 分类变量稀有值隐藏 | 防止 LLM 泄露数据 |
|
||
|
||
---
|
||
|
||
## 📋 开发进度
|
||
|
||
| Phase | 任务 | 状态 | 完成日期 |
|
||
|-------|------|------|---------|
|
||
| Phase 0 | 需求分析与架构设计 | ✅ 已完成 | 2026-02-18 |
|
||
| Phase 0 | MVP 开发计划 v1.0 → v1.6 | ✅ 已完成 | 2026-02-19 |
|
||
| Phase 1 | 骨架搭建 + 配置中台 | 🎉 **核心完成 85%** | 2026-02-19 |
|
||
| Phase 2 | 智能规划 + 咨询模式 | 📋 待开始 | - |
|
||
| Phase 3 | 完善与联调 | 📋 待开始 | - |
|
||
| **总计** | 106 个任务 | **完成 38 项（36%）** | - |
|
||
|
||
### 🎉 Phase 1 已完成核心功能
|
||
|
||
| 组件 | 完成项 | 状态 |
|
||
|------|--------|------|
|
||
| **R 服务** | T 检验、错误码、护栏、预签名 URL、缺失值处理 | ✅ 100% |
|
||
| **后端** | 路由、RClientService、DataParserService、代码下载 | ✅ 83% |
|
||
| **前端** | 页面框架、数据上传、结果展示、代码下载、模块注册 | ✅ 100% |
|
||
| **配置中台** | 数据库表、热加载 API | 🔄 18% |
|
||
|
||
### 开发计划文档
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| **MVP总览** | `04-开发计划/00-MVP开发计划总览.md` | 范围、架构、里程碑 |
|
||
| **任务清单** | `04-开发计划/01-任务清单与进度追踪.md` | 可追踪的 TODO 列表 |
|
||
| **R服务指南** | `04-开发计划/02-R服务开发指南.md` | R 统计工程师专用 |
|
||
| **后端指南** | `04-开发计划/03-后端开发指南.md` | Node.js 工程师专用 |
|
||
| **前端指南** | `04-开发计划/04-前端开发指南.md` | 前端工程师专用 |
|
||
|
||
### 评审记录
|
||
|
||
| 版本 | 评审报告 | 结论 | 日期 |
|
||
|------|---------|------|------|
|
||
| v1.0 | `06-开发记录/SSA-Pro 方案深度审查与风险评估报告.md` | 需修订 | 2026-02-18 |
|
||
| v1.1 | `06-开发记录/SSA-Pro 方案深度审查与风险评估报告 V2.0.md` | 需修订 | 2026-02-18 |
|
||
| v1.2 | `06-开发记录/SSA-Pro V1.2 终极审查与发令报告V3.0.md` | 🟢 通过 | 2026-02-18 |
|
||
| v1.4 | 🆕 纳入双引擎 + 咨询模式 + 配置中台 | 🟢 通过 | 2026-02-18 |
|
||
|
||
---
|
||
|
||
## 🔧 技术依赖
|
||
|
||
### 复用的平台能力
|
||
|
||
| 能力 | 位置 | 用途 |
|
||
|------|------|------|
|
||
| **LLM网关** | `@/common/llm/LLMFactory` | Planner + Critic |
|
||
| **RAG引擎** | `@/common/rag` | 工具检索 |
|
||
| **存储** | `@/common/storage` | OSS 数据传输 |
|
||
| **日志** | `@/common/logging` | 结构化日志 |
|
||
| **流式响应** | `@/common/streaming` | Critic 流式输出 |
|
||
|
||
### LLM模型
|
||
|
||
| 模型 | 用途 | 说明 |
|
||
|------|------|------|
|
||
| DeepSeek-V3 | Planner + Query Rewriter | 性价比高 |
|
||
| Qwen3-rerank | 工具重排序 | 中文理解好 |
|
||
| GPT-5-Pro | Critic 结果解读 | 深度推理 |
|
||
|
||
### R 依赖
|
||
|
||
| 包 | 版本 | 用途 |
|
||
|-----|------|------|
|
||
| plumber | 1.2.1 | Web API 框架 |
|
||
| jsonlite | 1.8.8 | JSON 处理 |
|
||
| ggplot2 | 3.4.4 | 可视化 |
|
||
| glue | 1.7.0 | 模板代码生成 |
|
||
| car | 3.1-2 | Levene 检验 |
|
||
| httr | 1.4.7 | OSS 下载 |
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
### 需求文档
|
||
|
||
- [PRD SSA-Pro 严谨型智能统计分析模块](./00-系统设计/PRD%20SSA-Pro%20严谨型智能统计分析模块.md)
|
||
|
||
### 设计文档
|
||
|
||
- [SSA-Pro 严谨型智能统计分析架构设计方案V4](./00-系统设计/SSA-Pro%20严谨型智能统计分析架构设计方案V4.md) ⬅️ **核心架构文档**
|
||
- [SSA-Pro (V4.1) 统计技能中心架构规范](./00-系统设计/SSA-Pro%20(V4.1)%20统计技能中心架构规范.md)
|
||
|
||
### 原型文件
|
||
|
||
- [智能统计分析V2.html](./03-UI设计/智能统计分析V2.html) - 可直接浏览器打开
|
||
|
||
### 参考文档
|
||
|
||
- [云原生开发规范](../../04-开发规范/08-云原生开发规范.md)
|
||
- [系统架构分层设计](../../00-系统总体设计/01-系统架构分层设计.md)
|
||
|
||
---
|
||
|
||
## 🎯 快速开始
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
docs/03-业务模块/SSA-智能统计分析/
|
||
├── 00-系统设计/ # PRD + 架构设计
|
||
├── 01-需求分析/ # 用户故事、用例
|
||
├── 02-技术设计/ # 详细技术方案
|
||
├── 03-UI设计/ # 原型图
|
||
├── 04-开发计划/ # MVP 开发文档（5份）
|
||
├── 05-测试用例/ # 测试方案
|
||
└── 06-开发记录/ # 评审报告、开发日志
|
||
```
|
||
|
||
### 开发环境准备
|
||
|
||
1. **R 服务环境**
|
||
```bash
|
||
cd r-statistics-service
|
||
docker build -t ssa-r-service .
|
||
docker run -p 8080:8080 -e DEV_MODE=true ssa-r-service
|
||
```
|
||
|
||
2. **后端开发**
|
||
```bash
|
||
cd backend
|
||
npm run dev
|
||
```
|
||
|
||
3. **前端开发**
|
||
```bash
|
||
cd frontend-v2
|
||
npm run dev
|
||
```
|
||
|
||
### API 接口预览
|
||
|
||
#### 智能分析模式
|
||
|
||
```http
|
||
### 创建会话
|
||
POST http://localhost:3001/api/v1/ssa/sessions
|
||
Content-Type: multipart/form-data
|
||
# file: 数据文件
|
||
|
||
### 生成分析计划
|
||
POST http://localhost:3001/api/v1/ssa/sessions/{sessionId}/plan
|
||
Content-Type: application/json
|
||
{"query": "比较两组GLU是否有显著差异"}
|
||
|
||
### 执行分析
|
||
POST http://localhost:3001/api/v1/ssa/sessions/{sessionId}/execute
|
||
Content-Type: application/json
|
||
{"plan": {...}, "debug": false}
|
||
|
||
### 获取结果
|
||
GET http://localhost:3001/api/v1/ssa/sessions/{sessionId}/result
|
||
```
|
||
|
||
#### 🆕 咨询模式
|
||
|
||
```http
|
||
### 创建咨询会话（无数据）
|
||
POST http://localhost:3001/api/v1/ssa/consult
|
||
|
||
### 咨询对话
|
||
POST http://localhost:3001/api/v1/ssa/consult/{sessionId}/chat
|
||
Content-Type: application/json
|
||
{"message": "我有一个双臂 RCT 研究，想比较主要终点..."}
|
||
|
||
### 生成 SAP 文档
|
||
POST http://localhost:3001/api/v1/ssa/consult/{sessionId}/generate-sap
|
||
|
||
### 下载 SAP
|
||
GET http://localhost:3001/api/v1/ssa/consult/{sessionId}/download-sap?format=word
|
||
```
|
||
|
||
#### 🆕 配置中台
|
||
|
||
```http
|
||
### 导入 Excel 配置
|
||
POST http://localhost:3001/api/v1/ssa/config/import
|
||
Content-Type: multipart/form-data
|
||
# file: config.xlsx
|
||
|
||
### 热加载配置
|
||
POST http://localhost:3001/api/v1/ssa/config/reload
|
||
|
||
### 获取工具列表
|
||
GET http://localhost:3001/api/v1/ssa/config/tools
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 对新AI助手
|
||
|
||
1. ✅ **设计文档已完成**：开发前请先阅读架构设计V4
|
||
2. ✅ **开发计划v1.4已审批**：遵循5份开发文档进行开发
|
||
3. ⚠️ **Planner/Executor 分离**：代码目录按 planner/executor 组织
|
||
4. ⚠️ **Brain-Hand 隔离**：Node.js 只看 Schema，R 操作真实数据
|
||
5. ⚠️ **支持无数据模式**：咨询模式下 Planner 可独立工作
|
||
6. ⚠️ **配置外置**：工具定义从 Excel 加载，不硬编码
|
||
7. ⚠️ **混合数据协议**：< 2MB inline，2-20MB OSS
|
||
8. ⚠️ **代码模板同步**：修改 Wrapper 逻辑时必须同步更新 templates/
|
||
|
||
### 风险与应对
|
||
|
||
| 风险 | 概率 | 应对策略 |
|
||
|------|------|---------|
|
||
| R 工具封装进度慢 | 高 | 先做 5 个核心工具，glue 模板化开发 |
|
||
| LLM 输出 JSON 格式错误 | 中 | jsonrepair + Zod 强校验 |
|
||
| R 服务并发阻塞 | 中 | SAE 固定 2 实例 |
|
||
| Node.js xlsx 内存刺客 | 中 | SAE 内存上限 2GB+ |
|
||
| R 服务 Segfault 崩溃 | 低 | Liveness Probe + 502/504 友好提示 |
|
||
| 本地开发 OSS 不通 | 中 | DEV_MODE 读取本地 fixtures |
|
||
| 用户代码缺依赖 | 高 | 模板头部自动安装脚本 |
|
||
|
||
---
|
||
|
||
## 🚀 未来规划
|
||
|
||
### MVP 阶段（当前）
|
||
|
||
- [x] Phase 1：骨架搭建（T检验端到端跑通）✅ 2026-02-19
|
||
- [ ] Phase 2：智能与交互（RAG + HITL + 10工具）
|
||
- [ ] Phase 3：打磨与调试（性能优化 + Bug修复）
|
||
|
||
### V2.0 阶段（规划中）
|
||
|
||
- [ ] 更多统计方法（Meta分析、生存分析、倾向性评分）
|
||
- [ ] 自定义工具上传
|
||
- [ ] 批量分析
|
||
- [ ] 报告导出（Word/PDF）
|
||
|
||
---
|
||
|
||
**文档版本：** v1.5
|
||
**最后更新：** 2026-02-19
|
||
**当前状态：** 🎉 T 检验端到端测试通过，Phase 1 核心完成 85%
|
||
**下一步：** Phase 2 智能规划 + 更多统计方法（或完善配置中台）
|