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
parent f9ed0c2528
commit 8137e3cde2
19 changed files with 5756 additions and 98 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/04-开发计划/00-MVP开发计划总览.md
+++ b/docs/03-业务模块/SSA-智能统计分析/04-开发计划/00-MVP开发计划总览.md
@@ -0,0 +1,209 @@
+# SSA-Pro MVP 开发计划总览
+
+> **文档版本：** v1.3  
+> **创建日期：** 2026-02-18  
+> **最后更新：** 2026-02-18（纳入 V3.0 终极审查建议）  
+> **项目代号：** SSA (Smart Statistical Analysis)  
+> **MVP 目标：** 打通完整闭环，上线 10 个核心统计工具
+
+---
+
+## 1. MVP 范围定义
+
+### 1.1 包含内容 ✅
+
+| 类别 | 内容 |
+|------|------|
+| **统计工具** | 10 个高频工具（T检验、ANOVA、卡方、相关性等） |
+| **核心流程** | 上传数据 → AI规划 → 用户确认 → R执行 → 结果交付 |
+| **交互能力** | 计划确认卡片、执行路径树、结果展示、代码下载 |
+| **智能能力** | RAG工具检索、Planner规划、Critic结果解读 |
+| **数据安全** | LLM只看Schema，R服务处理真实数据 |
+
+### 1.2 不包含内容 ❌
+
+| 类别 | 说明 | 后续阶段 |
+|------|------|---------|
+| 50+ 工具量产 | MVP只做10个核心工具 | Phase 3 |
+| 跨模块 Skills 化 | 不实现 Global Skill Registry | V2.0 |
+| Word 报告导出 | 先实现代码下载 | Phase 3 |
+| 大文件 OSS 传输 | MVP 限制 2MB 以内 | Phase 3 |
+
+### 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. 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      前端 (React 19)                             │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
+│  │ 数据上传 │  │ 计划卡片 │  │ 执行路径 │  │ 结果展示 │            │
+│  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │
+└────────────────────────────┬────────────────────────────────────┘
+                             │ HTTP API
+┌────────────────────────────┴────────────────────────────────────┐
+│                   Node.js 后端 (Brain)                           │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │  SSA Orchestrator (编排服务)                               │  │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐     │  │
+│  │  │ Rewriter│→ │ RAG检索 │→ │ Planner │→ │ Critic  │     │  │
+│  │  └─────────┘  └─────────┘  └─────────┘  └─────────┘     │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│           只看 Schema，不看真实数据                               │
+└────────────────────────────┬────────────────────────────────────┘
+                             │ HTTP (内网)
+┌────────────────────────────┴────────────────────────────────────┐
+│                    R 统计服务 (Hand)                             │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │  Plumber API Gateway                                       │  │
+│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐                   │  │
+│  │  │ 护栏检查 │→ │ 核心计算 │→ │ 代码生成 │                   │  │
+│  │  └─────────┘  └─────────┘  └─────────┘                   │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│           处理真实数据，网络隔离                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 3. 里程碑与时间线
+
+### Phase 1：骨架搭建（Week 1-2）
+
+**目标：** 跑通 T 检验的 "Hello World"
+
+| 交付物 | 验收标准 |
+|--------|---------|
+| 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 表创建 |
+| 前端骨架 | 基础页面框架，可上传文件 |
+
+### Phase 2：智能规划与交互（Week 3-4）
+
+**目标：** 用户可与 AI 对话，确认后执行
+
+| 交付物 | 验收标准 |
+|--------|---------|
+| RAG 检索 | 输入"两组差异"能返回 T 检验 |
+| Planner | 生成正确的参数映射 JSON |
+| 计划确认卡片 | 前端展示，用户可修改参数 |
+| 执行路径树 | 显示护栏检查步骤 |
+| 5 个工具 | T检验、配对T、ANOVA、卡方、相关性 |
+
+### Phase 3：完善与联调（Week 5-6）
+
+**目标：** MVP 功能完整，可演示
+
+| 交付物 | 验收标准 |
+|--------|---------|
+| Critic 解读 | 生成严谨的统计结论 |
+| 代码下载 | 用户可下载 .R 文件 |
+| 10 个工具 | 全部上线并测试通过 |
+| 端到端测试 | 10 个典型场景通过 |
+| SAE 部署 | R 服务部署成功 |
+
+---
+
+## 4. 核心 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  # 下载代码
+```
+
+---
+
+## 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/` |
+
+### 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` | 技术架构 |