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
parent 8137e3cde2
commit 49b5c37cb1
86 changed files with 21207 additions and 252 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
+++ b/docs/03-业务模块/SSA-智能统计分析/00-模块当前状态与开发指南.md
@@ -1,17 +1,33 @@
 # SSA智能统计分析模块 - 当前状态与开发指南

-> **文档版本：** v1.0  
+> **文档版本：** v1.5  
 > **创建日期：** 2026-02-18  
-> **最后更新：** 2026-02-18  
+> **最后更新：** 2026-02-19  
 > **维护者：** 开发团队  
-> **当前状态：** 📋 **MVP 开发计划 v1.3 完成，准予启动开发**  
+> **当前状态：** 🎉 **T 检验端到端测试通过！MVP Phase 1 核心完成 85%**  
 > **文档目的：** 快速了解SSA模块状态，为新AI助手提供上下文
 > 
 > **🎉 里程碑（2026-02-18）：**
 > - ✅ **PRD 完成**：SSA-Pro 严谨型智能统计分析模块需求定义
 > - ✅ **架构设计 V4 完成**：Brain-Hand 双层架构 + 统计护栏 + HITL 人机协同
-> - ✅ **MVP 开发计划 v1.3 完成**：通过 3 轮团队评审，准予启动开发
+> - ✅ **MVP 开发计划 v1.5 完成**：通过 5 轮评审，纳入完整专家配置体系
 > - ✅ **5 份开发文档完成**：总览、任务清单、R服务指南、后端指南、前端指南
+>
+> **🎉 T 检验端到端测试通过（2026-02-19）：**
+> - ✅ **🎉 完整流程验证**：数据上传 → 计划生成 → 分析执行 → 结果展示 → 代码下载
+> - ✅ **R 服务 Bug 修复**：缺失值自动过滤，解决分组变量 3 组问题
+> - ✅ **类型推断优化**：0/1 数字列正确识别为分类变量
+> - ✅ **错误处理增强**：R 服务错误信息正确传递给前端
+> - ✅ **文件名动态生成**：`{toolName}_{dataName}_{MMDD}_{HHmm}.R`
+> - ✅ **前端模块激活**：智能统计分析入口可用
+> - ✅ **用户会话隔离**：不同用户数据正确隔离
+> 
+> **🆕 v1.5 新增特性（专家配置体系）：**
+> - 🆕 **统计决策表**：(Goal, Y, X, Design) 四维匹配精准选工具，替代简单 RAG
+> - 🆕 **R 代码库**：支持上传 100+ 成熟 R 脚本，统一 `run_analysis()` 入口
+> - 🆕 **参数映射配置**：JSON Key → R 参数名可配置
+> - 🆕 **护栏规则链**：支持 Block / Warn / Switch 三种 Action
+> - 🆕 **结果解读模板**："填空题"式的论文级结论生成

 ---

@@ -26,7 +42,7 @@
 | **商业价值** | ⭐⭐⭐⭐⭐ 极高 |
 | **独立性** | ⭐⭐⭐⭐ 高（可独立使用，也可与其他模块协同） |
 | **目标用户** | 临床研究人员、生物统计师 |
-| **开发状态** | 📋 **MVP 开发计划完成，准备启动开发** |
+| **开发状态** | 🚀 **MVP Phase 1 开发中（Week 1 完成 ~80%）** |

 ### 核心目标

@@ -42,8 +58,9 @@
 #### 核心AI能力（规划中）

 1. **智能规划（Planner）**
-   - RAG 工具检索：根据用户意图召回最适合的统计方法
-   - 参数映射：将自然语言映射为统计参数
+   - 🆕 **决策表匹配**：(Goal, Y, X, Design) 四维精准选工具
+   - RAG 工具检索：作为决策表的兜底方案
+   - 参数映射：将自然语言映射为统计参数（可配置）
   - 统计分析计划（SAP）生成

 2. **统计护栏（Guardrails）**
@@ -51,6 +68,7 @@
   - 方差齐性检验（Levene）
   - 样本量检验
   - 大样本优化（N > 5000 抽样检验）
+   - 🆕 **护栏 Action**：Block（阻止） / Warn（警告） / Switch（切换方法）

 3. **人机协同（HITL）**
   - Plan Card：用户确认/修改分析计划
@@ -62,6 +80,19 @@
   - 自动注入依赖安装脚本
   - APA 格式化输出（p_value_fmt）

+5. **🆕 咨询模式**
+   - 无数据对话：用户只描述研究设计
+   - SAP 文档生成：结构化统计分析计划
+   - 多格式导出：Word/Markdown
+
+6. **🆕 配置中台（专家知识库）**
+   - 🆕 **统计决策表**：Goal + Y + X + Design → Tool 映射
+   - 🆕 **R 代码库**：100+ 成熟脚本上传，统一 `run_analysis()` 入口
+   - 🆕 **参数映射**：JSON Key → R 参数名 + 校验规则
+   - 🆕 **护栏规则链**：Check → Threshold → Action (Block/Warn/Switch)
+   - 🆕 **结果解读模板**："填空题"式论文级结论
+   - Excel 配置导入 + 热加载 + 配置校验
+
 #### MVP 工具清单（10个）

 | 工具代码 | 工具名称 | 适用场景 |
@@ -81,28 +112,30 @@

 ## 🏗️ 架构设计

-### Brain-Hand 双层架构
+### Brain-Hand 双层架构 + 配置中台

 ```
 ┌─────────────────────────────────────────────────────────┐
 │                  用户界面 (Frontend)                     │
-│  DataUploader | PlanCard | ExecutionTrace | ResultCard  │
+│  🆕 ModeSwitch | DataUploader | PlanCard | ResultCard  │
+│                   ↓ 智能分析    ↓ 咨询模式              │
 └─────────────────────────────────────────────────────────┘
                          ↓
 ┌─────────────────────────────────────────────────────────┐
-│              Brain Layer (Node.js)                       │
+│     Planner (Brain/大脑) - Node.js                      │
 │  ┌─────────────────────────────────────────────────────┐│
 │  │ DataParserService: 数据解析 → Schema 提取           ││
 │  │ ToolRetrievalService: RAG 工具检索                  ││
-│  │ PlannerService: LLM 规划 + 参数映射                 ││
-│  │ RClientService: R 服务调用（混合数据协议）          ││
+│  │ PlannerService: LLM 规划（有数据）                  ││
+│  │ 🆕 ConsultService: 无数据咨询                       ││
+│  │ 🆕 SAPGeneratorService: SAP 文档生成                ││
 │  │ CriticService: 结果解读（流式）                     ││
 │  └─────────────────────────────────────────────────────┘│
-│  📌 只看 Schema（无真实数据）                           │
+│  📌 只看 Schema，支持有数据/无数据两种模式              │
 └─────────────────────────────────────────────────────────┘
-                          ↓
+                          ↓ (仅智能分析模式)
 ┌─────────────────────────────────────────────────────────┐
-│              Hand Layer (R Docker)                       │
+│     Executor (Hand/四肢) - R Docker                      │
 │  ┌─────────────────────────────────────────────────────┐│
 │  │ data_loader.R: 混合数据协议（inline/OSS）          ││
 │  │ guardrails.R: 统计护栏（正态/方差齐性/样本量）     ││
@@ -111,6 +144,16 @@
 │  │ error_codes.R: 结构化错误码                        ││
 │  └─────────────────────────────────────────────────────┘│
 │  📌 操作真实数据 + 生成可复现代码                       │
+└─────────────────────────────────────────────────────────┘
+                          ▲
+┌─────────────────────────────────────────────────────────┐
+│     🆕 配置中台 (Config Center)                         │
+│  ┌─────────────────────────────────────────────────────┐│
+│  │ ConfigLoaderService: Excel 配置加载                ││
+│  │ ConfigValidatorService: 配置校验                   ││
+│  │ ConfigCacheService: 配置缓存 + 热加载              ││
+│  └─────────────────────────────────────────────────────┘│
+│  📌 统计专家可配置，系统动态加载                        │
 └─────────────────────────────────────────────────────────┘
 ```

@@ -128,14 +171,23 @@

 ## 📋 开发进度

-| Phase | 任务 | 状态 | 计划日期 |
+| Phase | 任务 | 状态 | 完成日期 |
 |-------|------|------|---------|
 | Phase 0 | 需求分析与架构设计 | ✅ 已完成 | 2026-02-18 |
-| Phase 0 | MVP 开发计划 v1.0 → v1.3 | ✅ 已完成 | 2026-02-18 |
-| Phase 1 | 骨架搭建（T检验端到端） | 📋 待开始 | - |
-| Phase 2 | 智能与交互（RAG + HITL） | 📋 待开始 | - |
-| Phase 3 | 打磨与调试 | 📋 待开始 | - |
-| **总计** | - | **设计 100%，开发 0%** | - |
+| Phase 0 | MVP 开发计划 v1.0 → v1.6 | ✅ 已完成 | 2026-02-19 |
+| Phase 1 | 骨架搭建 + 配置中台 | 🎉 **核心完成 85%** | 2026-02-19 |
+| Phase 2 | 智能规划 + 咨询模式 | 📋 待开始 | - |
+| Phase 3 | 完善与联调 | 📋 待开始 | - |
+| **总计** | 106 个任务 | **完成 38 项（36%）** | - |
+
+### 🎉 Phase 1 已完成核心功能
+
+| 组件 | 完成项 | 状态 |
+|------|--------|------|
+| **R 服务** | T 检验、错误码、护栏、预签名 URL、缺失值处理 | ✅ 100% |
+| **后端** | 路由、RClientService、DataParserService、代码下载 | ✅ 83% |
+| **前端** | 页面框架、数据上传、结果展示、代码下载、模块注册 | ✅ 100% |
+| **配置中台** | 数据库表、热加载 API | 🔄 18% |

 ### 开发计划文档

@@ -154,6 +206,7 @@
 | v1.0 | `06-开发记录/SSA-Pro 方案深度审查与风险评估报告.md` | 需修订 | 2026-02-18 |
 | v1.1 | `06-开发记录/SSA-Pro 方案深度审查与风险评估报告 V2.0.md` | 需修订 | 2026-02-18 |
 | v1.2 | `06-开发记录/SSA-Pro V1.2 终极审查与发令报告V3.0.md` | 🟢 通过 | 2026-02-18 |
+| v1.4 | 🆕 纳入双引擎 + 咨询模式 + 配置中台 | 🟢 通过 | 2026-02-18 |

 ---

@@ -250,6 +303,8 @@ docs/03-业务模块/SSA-智能统计分析/

 ### API 接口预览

+#### 智能分析模式
+
 ```http
 ### 创建会话
 POST http://localhost:3001/api/v1/ssa/sessions
@@ -270,6 +325,39 @@ Content-Type: application/json
 GET http://localhost:3001/api/v1/ssa/sessions/{sessionId}/result
 ```

+#### 🆕 咨询模式
+
+```http
+### 创建咨询会话（无数据）
+POST http://localhost:3001/api/v1/ssa/consult
+
+### 咨询对话
+POST http://localhost:3001/api/v1/ssa/consult/{sessionId}/chat
+Content-Type: application/json
+{"message": "我有一个双臂 RCT 研究，想比较主要终点..."}
+
+### 生成 SAP 文档
+POST http://localhost:3001/api/v1/ssa/consult/{sessionId}/generate-sap
+
+### 下载 SAP
+GET http://localhost:3001/api/v1/ssa/consult/{sessionId}/download-sap?format=word
+```
+
+#### 🆕 配置中台
+
+```http
+### 导入 Excel 配置
+POST http://localhost:3001/api/v1/ssa/config/import
+Content-Type: multipart/form-data
+# file: config.xlsx
+
+### 热加载配置
+POST http://localhost:3001/api/v1/ssa/config/reload
+
+### 获取工具列表
+GET http://localhost:3001/api/v1/ssa/config/tools
+```
+
 ---

 ## ⚠️ 注意事项
@@ -277,10 +365,13 @@ GET http://localhost:3001/api/v1/ssa/sessions/{sessionId}/result
 ### 对新AI助手

 1. ✅ **设计文档已完成**：开发前请先阅读架构设计V4
-2. ✅ **开发计划v1.3已审批**：遵循5份开发文档进行开发
-3. ⚠️ **Brain-Hand 隔离**：Node.js 只看 Schema，R 操作真实数据
-4. ⚠️ **混合数据协议**：< 2MB inline，2-20MB OSS
-5. ⚠️ **代码模板同步**：修改 Wrapper 逻辑时必须同步更新 templates/
+2. ✅ **开发计划v1.4已审批**：遵循5份开发文档进行开发
+3. ⚠️ **Planner/Executor 分离**：代码目录按 planner/executor 组织
+4. ⚠️ **Brain-Hand 隔离**：Node.js 只看 Schema，R 操作真实数据
+5. ⚠️ **支持无数据模式**：咨询模式下 Planner 可独立工作
+6. ⚠️ **配置外置**：工具定义从 Excel 加载，不硬编码
+7. ⚠️ **混合数据协议**：< 2MB inline，2-20MB OSS
+8. ⚠️ **代码模板同步**：修改 Wrapper 逻辑时必须同步更新 templates/

 ### 风险与应对

@@ -300,7 +391,7 @@ GET http://localhost:3001/api/v1/ssa/sessions/{sessionId}/result

 ### MVP 阶段（当前）

- [ ] Phase 1：骨架搭建（T检验端到端跑通）
+- [x] Phase 1：骨架搭建（T检验端到端跑通）✅ 2026-02-19
 - [ ] Phase 2：智能与交互（RAG + HITL + 10工具）
 - [ ] Phase 3：打磨与调试（性能优化 + Bug修复）

@@ -313,7 +404,7 @@ GET http://localhost:3001/api/v1/ssa/sessions/{sessionId}/result

 ---

-**文档版本：** v1.0  
-**最后更新：** 2026-02-18  
-**当前状态：** 📋 MVP 开发计划 v1.3 完成，准予启动开发  
-**下一步：** Phase 1 骨架搭建
+**文档版本：** v1.5  
+**最后更新：** 2026-02-19  
+**当前状态：** 🎉 T 检验端到端测试通过，Phase 1 核心完成 85%  
+**下一步：** Phase 2 智能规划 + 更多统计方法（或完善配置中台）