Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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.

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
HaHafeng
2026-02-19 20:57:00 +08:00
parent 8137e3cde2
commit 49b5c37cb1
86 changed files with 21207 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files

206
docs/03-业务模块/SSA-智能统计分析/04-开发计划/00-MVP开发计划总览.md
View File

@@ -1,10 +1,10 @@
# SSA-Pro MVP 开发计划总览
> **文档版本：** v1.3
> **文档版本：** v1.5
> **创建日期：** 2026-02-18
> **最后更新：** 2026-02-18（纳入 V3.0 终极审查建议）
> **最后更新：** 2026-02-18（纳入专家配置体系 + 决策表匹配 + R代码库）
> **项目代号：** SSA (Smart Statistical Analysis)
> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具
> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具，支持咨询模式
---
@@ -15,9 +15,11 @@
| 类别 | 内容 |
|------|------|
| **统计工具** | 10 个高频工具（T检验、ANOVA、卡方、相关性等） |
| **双模式支持** | 🆕 **智能分析模式**（上传数据→执行）+ **咨询模式**（无数据→SAP文档）|
| **核心流程** | 上传数据 → AI规划 → 用户确认 → R执行 → 结果交付 |
| **交互能力** | 计划确认卡片、执行路径树、结果展示、代码下载 |
| **交互能力** | 计划确认卡片、执行路径树、结果展示、代码下载、🆕 SAP文档导出 |
| **智能能力** | RAG工具检索、Planner规划、Critic结果解读 |
| **配置中台** | 🆕 统计决策表 + R代码库 + 参数映射 + 护栏规则链 + 解读模板 |
| **数据安全** | LLM只看Schema，R服务处理真实数据 |
### 1.2 不包含内容 ❌
@@ -26,8 +28,9 @@
|------|------|---------|
| 50+ 工具量产 | MVP只做10个核心工具 | Phase 3 |
| 跨模块 Skills 化 | 不实现 Global Skill Registry | V2.0 |
| Word 报告导出 | 先实现代码下载 | Phase 3 |
| Word 报告导出 | 先实现代码下载 + SAP 文档 | Phase 3 |
| 大文件 OSS 传输 | MVP 限制 2MB 以内 | Phase 3 |
| 配置管理 UI | MVP 使用 Excel 导入 | V2.0 |
### 1.3 MVP 工具清单（10个）
@@ -46,65 +49,143 @@
---
## 2. 整体架构
## 2. 整体架构（双引擎 + 配置中台）
### 2.1 架构概念
```
┌─────────────────────────────────────────────────────────────────┐
│ 前端 (React 19) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 数据上传 │ │ 计划卡片 │ │ 执行路径 │ │ 结果展示 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ 用户触点 │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 智能分析模式 │ │ 咨询模式 │ │
│ │ (上传数据+执行) │ │ (无数据,生成SAP) │ │
│ └────────┬────────┘ └────────┬────────┘ │
└────────────┼──────────────────────────┼─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Planner (大脑) - Node.js │
│ ┌─────────┐ ┌───────────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Rewriter│→ │🆕 决策表匹配 │→ │ Planner │→ │ Critic │ │
│ └─────────┘ │(Goal,Y,X,Design)│ └─────────┘ └─────────┘ │
│ └───────────────┘ │
│ 📌 只看 Schema，四维匹配精准选工具，支持有数据/无数据 │
└────────────────────────────┬────────────────────────────────────┘
│ HTTP API
┌────────────────────────────┴────────────────────────────────────┐
│ Node.js 后端 (Brain) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ SSA Orchestrator (编排服务) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Rewriter│→ │ RAG检索 │→ │ Planner │→ │ Critic │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ 只看 Schema，不看真实数据 │
└────────────────────────────┬────────────────────────────────────┘
│ HTTP (内网)
┌────────────────────────────┴────────────────────────────────────┐
│ R 统计服务 (Hand) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Plumber API Gateway │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ 护栏检查 │→ │ 核心计算 │→ │ 代码生成 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ 处理真实数据，网络隔离 │
│ (仅智能分析模式)
▼
┌─────────────────────────────────────────────────────────────────┐
│ Executor (四肢) - R Docker │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 护栏检查 │→ │ 核心计算 │→ │ 代码生成 │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ 📌 处理真实数据，网络隔离 │
└─────────────────────────────────────────────────────────────────┘
▲
┌────────────────────────────┴────────────────────────────────────┐
│ 🆕 配置中台 (Config Center) - 专家知识库 │
├─────────────────────────────────────────────────────────────────┤
│ 📊 Planner 配置 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ 决策表: Goal_Type + Y_Type + X_Type + Design → Tool_Code ││
│ └─────────────────────────────────────────────────────────────┘│
│ 🔧 Executor 配置 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ R代码库: 100+ 成熟脚本 │ 参数映射 │ 护栏规则链(Block/Warn/Switch)││
│ │ 输出定义 │ 解读模板 │ 代码交付模板 ││
│ └─────────────────────────────────────────────────────────────┘│
│ 📌 统计专家配置，系统动态加载，统一入口 run_analysis() │
└─────────────────────────────────────────────────────────────────┘
```
### 2.2 双模式流程
| 模式 | 数据要求 | 调用链 | 输出 |
|------|---------|--------|------|
| **智能分析** | ✅ 上传数据 | Planner → Executor | 结果 + R 代码 |
| **统计咨询** | ❌ 无需数据 | Planner only | SAP 文档（Word） |
### 2.3 代码目录结构（概念显性化）
```
backend/src/modules/ssa/
├── planner/ ← Planner 职责
│ ├── DataParserService.ts # 解析数据 Schema
│ ├── DecisionTableService.ts # 🆕 决策表匹配 (Goal,Y,X,Design)
│ ├── ToolRetrievalService.ts # RAG 检索（辅助）
│ ├── PlannerService.ts # 生成分析计划（有数据）
│ └── ConsultService.ts # 无数据咨询（生成 SAP）
│
├── executor/ ← Executor 职责
│ └── RClientService.ts # 调用 R 服务
│
├── config/ ← 配置中台
│ ├── DecisionTableLoader.ts # 🆕 加载统计决策表
│ ├── RCodeLibraryService.ts # 🆕 R 代码库管理
│ ├── ParamMappingService.ts # 🆕 参数映射配置
│ ├── GuardrailConfigService.ts # 🆕 护栏规则链
│ └── ConfigValidatorService.ts # 配置校验
│
├── routes/ # API 路由
├── dto/ # 数据传输对象
└── types/ # 类型定义
```
### 2.4 🆕 专家配置文件结构
```
config/ssa/
├── decision_table.xlsx # 统计决策表（Planner 用）
│ └── Sheet: Scenarios # Goal + Y + X + Design → Tool
├── r_scripts/ # 🆕 100+ 成熟 R 脚本
│ ├── t_test_ind.R
│ ├── wilcoxon.R
│ ├── anova_one.R
│ └── ...
├── tool_config.xlsx # 工具配置
│ ├── Sheet: Metadata # 工具基础信息
│ ├── Sheet: ParamMapping # JSON Key → R 参数名
│ ├── Sheet: Guardrails # 护栏规则链
│ ├── Sheet: OutputDef # 输出字段定义
│ └── Sheet: Interpretation # 结果解读模板
└── code_templates/ # 用户下载的代码模板
├── t_test.R.template
└── ...
```
---
## 3. 里程碑与时间线
### Phase 1：骨架搭建（Week 1-2）
### Phase 1：骨架搭建 + 配置中台（Week 1-2）
**目标：** 跑通 T 检验的 "Hello World"
**目标：** 跑通 T 检验 + 配置中台基础 + 决策表匹配
| 交付物 | 验收标准 |
|--------|---------|
| R Docker 镜像 | 本地可运行，健康检查通过 |
| Plumber API | POST /api/v1/skills/ST_T_TEST_IND 返回 JSON |
| Node.js 转发 | POST /api/v1/ssa/execute 调用 R 成功 |
| 数据库 Schema | tools_library, sessions, messages 表创建 |
| 前端骨架 | 基础页面框架，可上传文件 |
| 数据库 Schema | tools_library, sessions, messages, 🆕**r_code_library** 表创建 |
| 🆕 决策表加载 | 从 Excel 加载 (Goal,Y,X,Design) → Tool 映射 |
| 🆕 R 代码库管理 | 上传 R 脚本到数据库，统一 `run_analysis()` 入口 |
| 🆕 参数映射配置 | JSON Key → R 参数名映射可配置 |
| 🆕 护栏规则链 | Block/Warn/Switch 三种 Action 可配置 |
| 🆕 配置热加载 | Admin API `/config/reload` 触发配置更新 |
| 前端骨架 | 基础页面框架，🆕 **模式切换 Tab**（分析/咨询）|
### Phase 2：智能规划与交互（Week 3-4）
### Phase 2：智能规划与咨询模式（Week 3-4）
**目标：** 用户可与 AI 对话，确认后执行
**目标：** 决策表驱动规划 + 纯咨询模式双上线
| 交付物 | 验收标准 |
|--------|---------|
| RAG 检索 | 输入"两组差异"能返回 T 检验 |
| Planner | 生成正确的参数映射 JSON |
| 🆕 决策表匹配 | 根据 (Goal,Y,X,Design) 精准选工具，RAG 辅助 |
| Planner（有数据） | 决策表 + Schema → 参数映射 JSON |
| 🆕 Planner（无数据） | 决策表 + 用户描述 → SAP 文档 |
| 🆕 SAP 文档导出 | Word/Markdown 格式下载 |
| 🆕 结果解读模板 | 根据配置的解读模板生成论文级结论 |
| 计划确认卡片 | 前端展示，用户可修改参数 |
| 执行路径树 | 显示护栏检查步骤 |
| 执行路径树 | 显示护栏检查步骤（含 Action 类型）|
| 5 个工具 | T检验、配对T、ANOVA、卡方、相关性 |
### Phase 3：完善与联调（Week 5-6）
@@ -116,22 +197,57 @@
| Critic 解读 | 生成严谨的统计结论 |
| 代码下载 | 用户可下载 .R 文件 |
| 10 个工具 | 全部上线并测试通过 |
| 端到端测试 | 10 个典型场景通过 |
| 🆕 配置验证 | Excel 导入时校验格式/必填/唯一性 |
| 端到端测试 | 10 个典型场景通过（含咨询模式）|
| SAE 部署 | R 服务部署成功 |
---
## 4. 核心 API 设计
### 4.1 会话与分析 API
```
POST /api/v1/ssa/sessions # 创建会话
POST /api/v1/ssa/sessions/:id/upload # 上传数据
POST /api/v1/ssa/sessions/:id/plan # 生成计划（不执行）
POST /api/v1/ssa/sessions/:id/upload # 上传数据（智能分析模式）
POST /api/v1/ssa/sessions/:id/plan # 生成计划（有数据）
POST /api/v1/ssa/sessions/:id/execute # 确认执行
GET /api/v1/ssa/sessions/:id/messages # 获取消息历史
GET /api/v1/ssa/sessions/:id/download-code # 下载代码
```
### 4.2 🆕 咨询模式 API
```
POST /api/v1/ssa/consult # 创建咨询会话（无数据）
POST /api/v1/ssa/consult/:id/chat # 咨询对话（多轮）
POST /api/v1/ssa/consult/:id/generate-sap # 生成 SAP 文档
GET /api/v1/ssa/consult/:id/download-sap # 下载 SAP（Word/MD）
```
### 4.3 🆕 配置中台 API
```
# 决策表配置
POST /api/v1/ssa/config/decision-table # 导入决策表 Excel
GET /api/v1/ssa/config/decision-table # 获取决策表
# R 代码库配置
POST /api/v1/ssa/config/r-scripts # 上传 R 脚本
GET /api/v1/ssa/config/r-scripts # 获取脚本列表
PUT /api/v1/ssa/config/r-scripts/:id # 更新脚本
# 工具配置
POST /api/v1/ssa/config/tool-config # 导入工具配置 Excel
GET /api/v1/ssa/config/tools # 获取工具列表
GET /api/v1/ssa/config/tools/:code/params # 获取参数映射
GET /api/v1/ssa/config/tools/:code/guardrails # 获取护栏规则
# 通用
POST /api/v1/ssa/config/reload # 热加载所有配置（Admin）
GET /api/v1/ssa/config/validate # 校验配置文件
```
---
## 5. 依赖与集成
@@ -154,7 +270,9 @@ GET /api/v1/ssa/sessions/:id/download-code # 下载代码
| R Docker 镜像 | 基于 rocker/r-ver:4.3，含 Plumber + renv |
| R 统计服务 | SAE 新应用，**VPC 内网通信** |
| SSA 前端模块 | `frontend-v2/src/modules/ssa/` |
| SSA 后端模块 | `backend/src/modules/ssa/` |
| SSA 后端模块 | `backend/src/modules/ssa/`（按 planner/executor/config 组织）|
| 🆕 配置中台 | Excel 配置文件 + ConfigLoaderService |
| 🆕 SAP 生成器 | ConsultService + Word 导出 |
### 5.3 关键配置要求