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-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）

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

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`	技术架构

17 KiB Raw Blame History Unescape Escape

SSA-Pro MVP 开发计划总览

1. MVP 范围定义

1.1 包含内容 ✅

1.2 不包含内容 ❌

1.3 MVP 工具清单（10个）

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

2.1 架构概念

2.2 双模式流程

2.3 代码目录结构（概念显性化）

2.4 🆕 专家配置文件结构

3. 里程碑与时间线

Phase 1：骨架搭建 + 配置中台（Week 1-2）

Phase 2：智能规划与咨询模式（Week 3-4）

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

4. 核心 API 设计

4.1 会话与分析 API

4.2 🆕 咨询模式 API

4.3 🆕 配置中台 API

5. 依赖与集成

5.1 平台能力复用

5.2 新增组件

5.3 关键配置要求

6. 风险与应对

7. 验收标准（来自 PRD）

8. 相关文档索引

17 KiB

Raw Blame History