Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8137e3cde2f6e115de0e922334ff1d196dc9d502
AIclinicalresearch/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
HaHafeng 8137e3cde2 feat(ssa): Complete SSA-Pro MVP development plan v1.3 
Summary:

- Add PRD and architecture design V4 (Brain-Hand model)

- Complete 5 development guide documents

- Pass 3 rounds of team review (v1.0 -> v1.3)

- Add module status guide document

- Update system status document

Key Features:

- Brain-Hand architecture: Node.js + R Docker

- Statistical guardrails with auto degradation

- HITL workflow: PlanCard -> ExecutionTrace -> ResultCard

- Mixed data protocol: inline vs OSS

- Reproducible R code delivery

MVP Scope: 10 statistical tools

Status: Design 100%, ready for development
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-18 21:58:37 +08:00

320 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SSA智能统计分析模块 - 当前状态与开发指南
> **文档版本：** v1.0
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18
> **维护者：** 开发团队
> **当前状态：** 📋 **MVP 开发计划 v1.3 完成，准予启动开发**
> **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
>
> **🎉 里程碑（2026-02-18）：**
> - ✅ **PRD 完成**：SSA-Pro 严谨型智能统计分析模块需求定义
> - ✅ **架构设计 V4 完成**：Brain-Hand 双层架构 + 统计护栏 + HITL 人机协同
> - ✅ **MVP 开发计划 v1.3 完成**：通过 3 轮团队评审，准予启动开发
> - ✅ **5 份开发文档完成**：总览、任务清单、R服务指南、后端指南、前端指南
---
## 📊 模块概览
### 基本信息
| 项目 | 信息 |
|------|------|
| **模块名称** | SSA - 智能统计分析 (Smart Statistical Analysis) |
| **模块定位** | AI驱动的"白盒"统计分析系统 |
| **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
| **独立性** | ⭐⭐⭐⭐ 高（可独立使用，也可与其他模块协同） |
| **目标用户** | 临床研究人员、生物统计师 |
| **开发状态** | 📋 **MVP 开发计划完成，准备启动开发** |
### 核心目标
> 打造一个 **"白盒"、"严谨"、"可交付"** 的智能统计分析系统。
>
> **核心差异化**：
> 1. **白盒**：用户完全理解 AI 做了什么，为什么这样做
> 2. **严谨**：统计护栏自动检测前提条件，违规时自动降级
> 3. **可交付**：生成可在本地运行的 R 代码，支持审计复现
### 功能规格
#### 核心AI能力（规划中）
1. **智能规划（Planner）**
- RAG 工具检索：根据用户意图召回最适合的统计方法
- 参数映射：将自然语言映射为统计参数
- 统计分析计划（SAP）生成
2. **统计护栏（Guardrails）**
- 正态性检验（Shapiro-Wilk）
- 方差齐性检验（Levene）
- 样本量检验
- 大样本优化（N > 5000 抽样检验）
3. **人机协同（HITL）**
- Plan Card：用户确认/修改分析计划
- Execution Trace：实时展示执行路径
- Result Card：结构化结果 + AI 解读
4. **代码交付**
- 生成可复现的 R 代码
- 自动注入依赖安装脚本
- APA 格式化输出（p_value_fmt）
#### 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) │
│ DataUploader | PlanCard | ExecutionTrace | ResultCard │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Brain Layer (Node.js) │
│ ┌─────────────────────────────────────────────────────┐│
│ │ DataParserService: 数据解析 → Schema 提取 ││
│ │ ToolRetrievalService: RAG 工具检索 ││
│ │ PlannerService: LLM 规划 + 参数映射 ││
│ │ RClientService: R 服务调用（混合数据协议） ││
│ │ CriticService: 结果解读（流式） ││
│ └─────────────────────────────────────────────────────┘│
│ 📌 只看 Schema（无真实数据） │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ Hand Layer (R Docker) │
│ ┌─────────────────────────────────────────────────────┐│
│ │ data_loader.R: 混合数据协议（inline/OSS） ││
│ │ guardrails.R: 统计护栏（正态/方差齐性/样本量） ││
│ │ tools/*.R: 统计工具 Wrapper（glue 模板） ││
│ │ result_formatter.R: 结果格式化（p_value_fmt） ││
│ │ error_codes.R: 结构化错误码 ││
│ └─────────────────────────────────────────────────────┘│
│ 📌 操作真实数据 + 生成可复现代码 │
└─────────────────────────────────────────────────────────┘
```
### 关键技术决策
| 决策点 | 方案 | 理由 |
|--------|------|------|
| **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.3 | ✅ 已完成 | 2026-02-18 |
| Phase 1 | 骨架搭建（T检验端到端） | 📋 待开始 | - |
| Phase 2 | 智能与交互（RAG + HITL） | 📋 待开始 | - |
| Phase 3 | 打磨与调试 | 📋 待开始 | - |
| **总计** | - | **设计 100%，开发 0%** | - |
### 开发计划文档
| 文档 | 路径 | 说明 |
|------|------|------|
| **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 |
---
## 🔧 技术依赖
### 复用的平台能力
| 能力 | 位置 | 用途 |
|------|------|------|
| **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
```
---
## ⚠️ 注意事项
### 对新AI助手
1. ✅ **设计文档已完成**：开发前请先阅读架构设计V4
2. ✅ **开发计划v1.3已审批**：遵循5份开发文档进行开发
3. ⚠️ **Brain-Hand 隔离**：Node.js 只看 Schema，R 操作真实数据
4. ⚠️ **混合数据协议**：< 2MB inline，2-20MB OSS
5. ⚠️ **代码模板同步**：修改 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检验端到端跑通）
- [ ] Phase 2：智能与交互（RAG + HITL + 10工具）
- [ ] Phase 3：打磨与调试（性能优化 + Bug修复）
### V2.0 阶段（规划中）
- [ ] 更多统计方法（Meta分析、生存分析、倾向性评分）
- [ ] 自定义工具上传
- [ ] 批量分析
- [ ] 报告导出（Word/PDF）
---
**文档版本：** v1.0
**最后更新：** 2026-02-18
**当前状态：** 📋 MVP 开发计划 v1.3 完成，准予启动开发
**下一步：** Phase 1 骨架搭建
Reference in New Issue View Git Blame Copy Permalink