Files

HaHafeng 49b5c37cb1 feat(ssa): Complete T-test end-to-end testing with 9 bug fixes - Phase 1 core 85% complete. R service: missing value auto-filter. Backend: error handling, variable matching, dynamic filename. Frontend: module activation, session isolation, error propagation. Full flow verified.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-19 20:57:00 +08:00

17 KiB

Raw Blame History

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

文档版本： v1.5
创建日期： 2026-02-18
最后更新： 2026-02-19
维护者： 开发团队
当前状态： 🎉 T 检验端到端测试通过！MVP Phase 1 核心完成 85%
文档目的： 快速了解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

✅ 前端模块激活：智能统计分析入口可用

✅ 用户会话隔离：不同用户数据正确隔离

🆕 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 完成 ~80%）

核心目标

打造一个 "白盒"、"严谨"、"可交付" 的智能统计分析系统。

核心差异化：

白盒：用户完全理解 AI 做了什么，为什么这样做

严谨：统计护栏自动检测前提条件，违规时自动降级

可交付：生成可在本地运行的 R 代码，支持审计复现

功能规格

核心AI能力（规划中）

智能规划（Planner）
- 🆕 决策表匹配：(Goal, Y, X, Design) 四维精准选工具
- RAG 工具检索：作为决策表的兜底方案
- 参数映射：将自然语言映射为统计参数（可配置）
- 统计分析计划（SAP）生成
统计护栏（Guardrails）
- 正态性检验（Shapiro-Wilk）
- 方差齐性检验（Levene）
- 样本量检验
- 大样本优化（N > 5000 抽样检验）
- 🆕 护栏 Action：Block（阻止） / Warn（警告） / Switch（切换方法）
人机协同（HITL）
- Plan Card：用户确认/修改分析计划
- Execution Trace：实时展示执行路径
- Result Card：结构化结果 + AI 解读
代码交付
- 生成可复现的 R 代码
- 自动注入依赖安装脚本
- APA 格式化输出（p_value_fmt）
🆕 咨询模式
- 无数据对话：用户只描述研究设计
- SAP 文档生成：结构化统计分析计划
- 多格式导出：Word/Markdown
🆕 配置中台（专家知识库）
- 🆕 统计决策表：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 严谨型智能统计分析模块

设计文档

SSA-Pro 严谨型智能统计分析架构设计方案V4 ⬅️ 核心架构文档
SSA-Pro (V4.1) 统计技能中心架构规范

原型文件

智能统计分析V2.html - 可直接浏览器打开

参考文档

🎯 快速开始

目录结构

docs/03-业务模块/SSA-智能统计分析/
├── 00-系统设计/           # PRD + 架构设计
├── 01-需求分析/           # 用户故事、用例
├── 02-技术设计/           # 详细技术方案
├── 03-UI设计/             # 原型图
├── 04-开发计划/           # MVP 开发文档（5份）
├── 05-测试用例/           # 测试方案
└── 06-开发记录/           # 评审报告、开发日志

开发环境准备

R 服务环境

cd r-statistics-service
docker build -t ssa-r-service .
docker run -p 8080:8080 -e DEV_MODE=true ssa-r-service

后端开发
```
cd backend
npm run dev
```
前端开发
```
cd frontend-v2
npm run dev
```

API 接口预览

智能分析模式

### 创建会话
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

🆕 咨询模式

### 创建咨询会话（无数据）
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

🆕 配置中台

### 导入 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助手

✅ 设计文档已完成：开发前请先阅读架构设计V4
✅ 开发计划v1.4已审批：遵循5份开发文档进行开发
⚠️ Planner/Executor 分离：代码目录按 planner/executor 组织
⚠️ Brain-Hand 隔离：Node.js 只看 Schema，R 操作真实数据
⚠️ 支持无数据模式：咨询模式下 Planner 可独立工作
⚠️ 配置外置：工具定义从 Excel 加载，不硬编码
⚠️ 混合数据协议：< 2MB inline，2-20MB OSS
⚠️ 代码模板同步：修改 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 阶段（当前）

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 智能规划 + 更多统计方法（或完善配置中台）

17 KiB Raw Blame History Unescape Escape

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

📊 模块概览

基本信息

核心目标

功能规格

核心AI能力（规划中）

MVP 工具清单（10个）

🏗️ 架构设计

Brain-Hand 双层架构 + 配置中台

关键技术决策

📋 开发进度

🎉 Phase 1 已完成核心功能

开发计划文档

评审记录

🔧 技术依赖

复用的平台能力

LLM模型

R 依赖

📚 相关文档

需求文档

设计文档

原型文件

参考文档

🎯 快速开始

目录结构

开发环境准备

API 接口预览

智能分析模式

🆕 咨询模式

🆕 配置中台

⚠️ 注意事项

对新AI助手

风险与应对

🚀 未来规划

MVP 阶段（当前）

V2.0 阶段（规划中）

17 KiB

Raw Blame History