# SSA-Pro MVP 开发计划总览

> **文档版本：** v1.5  
> **创建日期：** 2026-02-18  
> **最后更新：** 2026-02-18（纳入专家配置体系 + 决策表匹配 + R代码库）  
> **项目代号：** SSA (Smart Statistical Analysis)  
> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具，支持咨询模式

---

## 1. MVP 范围定义

### 1.1 包含内容 ✅

| 类别 | 内容 |
|------|------|
| **统计工具** | 10 个高频工具（T检验、ANOVA、卡方、相关性等） |
| **双模式支持** | 🆕 **智能分析模式**（上传数据→执行）+ **咨询模式**（无数据→SAP文档）|
| **核心流程** | 上传数据 → AI规划 → 用户确认 → R执行 → 结果交付 |
| **交互能力** | 计划确认卡片、执行路径树、结果展示、代码下载、🆕 SAP文档导出 |
| **智能能力** | RAG工具检索、Planner规划、Critic结果解读 |
| **配置中台** | 🆕 统计决策表 + R代码库 + 参数映射 + 护栏规则链 + 解读模板 |
| **数据安全** | LLM只看Schema，R服务处理真实数据 |

### 1.2 不包含内容 ❌

| 类别 | 说明 | 后续阶段 |
|------|------|---------|
| 50+ 工具量产 | MVP只做10个核心工具 | Phase 3 |
| 跨模块 Skills 化 | 不实现 Global Skill Registry | V2.0 |
| Word 报告导出 | 先实现代码下载 + SAP 文档 | Phase 3 |
| 大文件 OSS 传输 | MVP 限制 2MB 以内 | Phase 3 |
| 配置管理 UI | MVP 使用 Excel 导入 | V2.0 |

### 1.3 MVP 工具清单（10个）

| 序号 | 工具代码 | 名称 | 类别 |
|------|---------|------|------|
| 1 | ST_T_TEST_IND | 独立样本 T 检验 | 假设检验 |
| 2 | ST_T_TEST_PAIRED | 配对样本 T 检验 | 假设检验 |
| 3 | ST_ANOVA_ONE | 单因素方差分析 | 假设检验 |
| 4 | ST_CHI_SQUARE | 卡方检验 | 假设检验 |
| 5 | ST_FISHER | Fisher 精确检验 | 假设检验 |
| 6 | ST_WILCOXON | Wilcoxon 秩和检验 | 非参数检验 |
| 7 | ST_MANN_WHITNEY | Mann-Whitney U 检验 | 非参数检验 |
| 8 | ST_CORRELATION | Pearson/Spearman 相关 | 相关分析 |
| 9 | ST_LINEAR_REG | 简单线性回归 | 回归分析 |
| 10 | ST_DESCRIPTIVE | 描述性统计 | 基础统计 |

---

## 2. 整体架构（双引擎 + 配置中台）

### 2.1 架构概念

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户触点                                   │
│   ┌─────────────────┐        ┌─────────────────┐               │
│   │  智能分析模式    │        │   咨询模式       │               │
│   │ (上传数据+执行)  │        │ (无数据,生成SAP) │               │
│   └────────┬────────┘        └────────┬────────┘               │
└────────────┼──────────────────────────┼─────────────────────────┘
             │                          │
             ▼                          ▼
┌─────────────────────────────────────────────────────────────────┐
│              Planner (大脑) - Node.js                            │
│  ┌─────────┐  ┌───────────────┐  ┌─────────┐  ┌─────────┐     │
│  │ Rewriter│→ │🆕 决策表匹配  │→ │ Planner │→ │ Critic  │     │
│  └─────────┘  │(Goal,Y,X,Design)│  └─────────┘  └─────────┘     │
│               └───────────────┘                                 │
│  📌 只看 Schema，四维匹配精准选工具，支持有数据/无数据            │
└────────────────────────────┬────────────────────────────────────┘
                             │ (仅智能分析模式)
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│              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）

**目标：** 跑通 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, 🆕**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）

**目标：** 决策表驱动规划 + 纯咨询模式双上线

| 交付物 | 验收标准 |
|--------|---------|
| 🆕 决策表匹配 | 根据 (Goal,Y,X,Design) 精准选工具，RAG 辅助 |
| Planner（有数据） | 决策表 + Schema → 参数映射 JSON |
| 🆕 Planner（无数据） | 决策表 + 用户描述 → SAP 文档 |
| 🆕 SAP 文档导出 | Word/Markdown 格式下载 |
| 🆕 结果解读模板 | 根据配置的解读模板生成论文级结论 |
| 计划确认卡片 | 前端展示，用户可修改参数 |
| 执行路径树 | 显示护栏检查步骤（含 Action 类型）|
| 5 个工具 | T检验、配对T、ANOVA、卡方、相关性 |

### Phase 3：完善与联调（Week 5-6）

**目标：** MVP 功能完整，可演示

| 交付物 | 验收标准 |
|--------|---------|
| Critic 解读 | 生成严谨的统计结论 |
| 代码下载 | 用户可下载 .R 文件 |
| 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/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. 依赖与集成

### 5.1 平台能力复用

| 能力 | 使用方式 | 状态 |
|------|---------|------|
| LLM 网关 | `LLMFactory.getAdapter('deepseek-v3')` | ✅ 可用 |
| RAG 引擎 | `VectorSearchService` | ✅ 可用 |
| 流式响应 | `StreamingService` (Critic) | ✅ 可用 |
| Prompt 管理 | `capability_schema.prompt_templates` | ✅ 可用 |
| 认证授权 | `authenticate` 中间件 | ✅ 可用 |
| OSS 存储 | `storage.upload()` (图片/代码) | ✅ 可用 |

### 5.2 新增组件

| 组件 | 说明 |
|------|------|
| R Docker 镜像 | 基于 rocker/r-ver:4.3，含 Plumber + renv |
| R 统计服务 | SAE 新应用，**VPC 内网通信** |
| SSA 前端模块 | `frontend-v2/src/modules/ssa/` |
| SSA 后端模块 | `backend/src/modules/ssa/`（按 planner/executor/config 组织）|
| 🆕 配置中台 | Excel 配置文件 + ConfigLoaderService |
| 🆕 SAP 生成器 | ConsultService + Word 导出 |

### 5.3 关键配置要求

| 配置项 | 要求 | 原因 |
|-------|------|------|
| OSS Endpoint | 使用 VPC 内网地址 `oss-cn-xxx-internal.aliyuncs.com` | R 服务网络隔离需求 |
| SAE 扩容策略 | CPU > 60% 或并发 > 5 时自动扩容 | R 单线程，需水平扩展 |
| R 服务出站策略 | Deny Public Internet, Allow VPC | 防止数据外泄 |

---

## 6. 风险与应对

| 风险 | 概率 | 应对策略 |
|------|------|---------|
| R 工具封装进度慢 | 高 | 先做 5 个核心工具，glue 模板化开发 |
| LLM 参数映射错误 | 中 | R 服务强类型校验 + 前端允许修改 |
| LLM 输出 JSON 格式错误 | 中 | json-repair 库修复 + Zod Schema 强校验 |
| R 服务并发阻塞 | 中 | **SAE 固定 2 实例**（避免冷启动 30s+） |
| 大文件导致内存溢出 | 中 | **混合协议**：< 2MB inline，2-20MB OSS |
| R 临时文件堆积 | 中 | on.exit() 清理 + 定时 CronJob |
| SAE 部署 R 失败 | 低 | 提前测试 Docker 镜像 |
| OSS 网络不通 | 低 | **ENV 注入 Endpoint** + DEV_MODE Mock |
| 大样本护栏超时 | 中 | **N > 5000 抽样检验**，避免 Shapiro-Wilk 超时 |
| 🆕 Node.js xlsx 内存刺客 | 中 | **SAE 内存上限 2GB+** |
| 🆕 R 服务 Segfault 崩溃 | 低 | **Liveness Probe** + 502/504 友好提示 |
| 🆕 本地开发 OSS 不通 | 中 | **DEV_MODE** 读取本地 fixtures |
| 🆕 用户代码缺依赖 | 高 | **模板头部自动安装脚本** |
| 🆕 分类变量隐私泄露 | 中 | **稀有值 < 5 隐藏** |
| 🆕 R 错误信息黑盒 | 中 | **map_r_error 友好映射** |

---

## 7. 验收标准（来自 PRD）

1. **准确性**：非正态数据自动降级为非参数检验
2. **性能**：2MB 数据 T 检验端到端 < 5 秒
3. **复现性**：下载的 R 代码本地可运行
4. **隐私**：审计日志不含真实患者数据

---

## 8. 相关文档索引

| 文档 | 路径 | 说明 |
|------|------|------|
| 任务清单 | `04-开发计划/01-任务清单与进度追踪.md` | 可追踪的 TODO |
| R 服务指南 | `04-开发计划/02-R服务开发指南.md` | R 工程师专用 |
| 后端指南 | `04-开发计划/03-后端开发指南.md` | Node.js 工程师专用 |
| 前端指南 | `04-开发计划/04-前端开发指南.md` | 前端工程师专用 |
| PRD | `00-系统设计/PRD SSA-Pro 严谨型智能统计分析模块.md` | 产品需求 |
| 架构设计 | `00-系统设计/SSA-Pro 严谨型智能统计分析架构设计方案V4.md` | 技术架构 |