Files

HaHafeng 428a22adf2 feat(ssa): Complete Phase 2A frontend integration - multi-step workflow end-to-end

Phase 2A: WorkflowPlannerService, WorkflowExecutorService, Python data quality, 6 bug fixes, DescriptiveResultView, multi-step R code/Word export, MVP UI reuse. V11 UI: Gemini-style, multi-task, single-page scroll, Word export. Architecture: Block-based rendering consensus (4 block types). New R tools: chi_square, correlation, descriptive, logistic_binary, mann_whitney, t_test_paired. Docs: dev summary, block-based plan, status updates, task list v2.0.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-02-20 23:09:27 +08:00

19 KiB

Raw Blame History

SSA-Pro MVP 开发计划总览

文档版本： v1.7
创建日期： 2026-02-18
最后更新： 2026-02-20（纳入 Prompt 体系 + 多工具流程规划 + 数据质量核查报告）
项目代号： SSA (Smart Statistical Analysis)
MVP 目标： 打通完整闭环，上线 10 个核心统计工具，支持多工具流程规划 + 数据质量核查

0. 🆕 智能化演进愿景（战略定位）

详细文档参考： 04-开发计划/06-智能化演进共识与MVP执行计划.md

0.1 产品终极目标

SSA-Pro 的终极目标是 Level 3：颠覆性的智能分析助手

让不懂统计的医生，能够完成专业级的统计分析。

0.2 三阶段演进路线

Phase 1/2: 爬行期 (MVP) ← 当前阶段
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：打透 Tool Calling，建立用户信任
机制：100个工具作为固定API，LLM 做智能调度
AI角色：高级调度员 / 全科主任医师

Phase 2.5: 行走期
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：引入受限的代码智能
机制：数据清洗允许 LLM 生成代码，核心统计仍用固定工具

Phase 3: 奔跑期 (终极愿景)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
目标：自愈型靶向代码修改
机制：运行报错时，LLM 根据错误日志靶向修改工具代码
关键：不是自由生成代码，而是基于现有工具的靶向修复

0.3 MVP 阶段的"为未来铺路"任务

伏笔任务	Phase 3 用途	MVP 阶段行动
Prompt 动态注入体系	支持专家配置热更新	🆕 骨架（AI工程师）+ 血肉（统计专家）分离
多工具流程规划	复杂场景的自动化	🆕 LLM 生成 2-7 步串联执行流程
数据质量核查报告	智能诊断异常数据	🆕 自动生成"数据体检报告"（评分 + 建议）
Prompt 世界观	LLM 理解自己可以修改代码	Prompt 中强调"代码库"概念
向量库代码片段	便于 LLM 理解工具代码	`tools_library` 存入核心代码片段
结构化错误日志	用于错误反馈自愈	建立 JSON 格式的错误捕获管道
黄金数据集积累	学习"什么错误如何修复"	完整记录每次调用（含报错）

0.4 关键共识

⚠️ Phase 3 的"代码智能"不是让 LLM 自由发挥写代码

而是：LLM 串联工具 → 执行 → 如果报错 → 错误日志反馈给 LLM → 靶向修改代码/参数 → 重新执行

1. MVP 范围定义

1.1 包含内容 ✅

类别	内容
统计工具	10 个高频工具（T检验、ANOVA、卡方、相关性等）
双模式支持	🆕 智能分析模式（上传数据→执行）+ 咨询模式（无数据→SAP文档）
🆕 多工具流程规划	LLM 规划 2-7 步串联流程（数据检查 → 前提检验 → 核心分析 → 效应量 → 结论）
🆕 数据质量核查报告	自动生成"数据体检报告"（缺失值/异常值/分布/平衡性），含质量评分和建议
核心流程	上传数据 → 数据质量核查 → AI规划 → 用户确认 → 多步串联执行 → 结果交付
交互能力	计划确认卡片、执行路径树、结果展示、代码下载、🆕 SAP文档导出
智能能力	🆕 Prompt 动态注入 + 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`	技术架构

19 KiB Raw Blame History Unescape Escape

SSA-Pro MVP 开发计划总览

0. 🆕 智能化演进愿景（战略定位）

0.1 产品终极目标

0.2 三阶段演进路线

0.3 MVP 阶段的"为未来铺路"任务

0.4 关键共识

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. 相关文档索引

19 KiB

Raw Blame History