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>
This commit is contained in:
128
docs/03-业务模块/SSA-智能统计分析/00-系统设计/Planner 统计分析计划与配置映射.md
Normal file
128
docs/03-业务模块/SSA-智能统计分析/00-系统设计/Planner 统计分析计划与配置映射.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# **专家视角：统计分析计划 (SAP) 的解构与配置映射**
|
||||
|
||||
**文档版本：** v1.0
|
||||
|
||||
**创建日期：** 2026-02-18
|
||||
|
||||
**核心议题：** 从医学统计专家的视角，重新定义 Planner 的规划逻辑与 Admin 的配置要素。
|
||||
|
||||
## **1\. 统计专家的“问诊”逻辑 (The Statistician's Mindset)**
|
||||
|
||||
当医生拿着数据来找我（统计专家）时，我脑子里的思维路径是这样的：
|
||||
|
||||
### **第一步：明确研究目的 (Objective)**
|
||||
|
||||
* **专家会问**：你是要描述现状？比较差异？探索关联？还是预测未来？
|
||||
* **系统映射**：**意图识别配置**。
|
||||
* *Config*: 关键词映射表（"影响因素" \-\> 回归分析；"疗效对比" \-\> 差异检验）。
|
||||
|
||||
### **第二步：明确数据特征 (Data Characteristics)**
|
||||
|
||||
* **专家会问**：你的结局变量（Y）是什么类型的？（连续/分类/生存时间）你的分组变量（X）是几组？数据是独立采样的，还是同一个病人前后的对比（配对）？
|
||||
* **系统映射**：**变量角色定义**。
|
||||
* *Config*: 工具的适用数据类型约束（如：ST\_T\_TEST\_IND 要求 Y=Numeric, X=Categorical(2 levels), Design=Independent）。
|
||||
|
||||
### **第三步：制定分析策略 (Strategy)**
|
||||
|
||||
* **专家会想**：既然是比较两组连续变量，先看正态性。如果正态，用 T 检验；如果不正态，用 Wilcoxon。最后还要画个图直观展示。
|
||||
* **系统映射**：**决策树与组合配置**。
|
||||
* *Config*: 不仅仅配置“一个工具”，而是配置 **"标准分析流 (SOP)"**。
|
||||
|
||||
## **2\. 一份标准的 SAP 包括什么？ (Anatomy of SAP)**
|
||||
|
||||
Planner 生成的不仅仅是一个 Tool Code，而应该是一份完整的**作战地图**。
|
||||
|
||||
### **2.1 SAP 的核心要素**
|
||||
|
||||
1. **分析集定义 (Analysis Set)**：全分析集 (FAS) 还是符合方案集 (PPS)？（MVP 阶段默认全数据）。
|
||||
2. **变量操作 (Data Manipulation)**：需要计算 BMI 吗？需要把年龄分段吗？
|
||||
3. **描述性统计 (Descriptive)**：基线表怎么做？（连续变量算 Mean±SD，分类变量算 N(%)）。
|
||||
4. **推断性统计 (Inference)**：核心假设检验方法（方法论 \+ 假设前提）。
|
||||
5. **图表规划 (Visualization)**：用什么图展示结果最直观？
|
||||
|
||||
### **2.2 我们的 Planner 应该输出什么？**
|
||||
|
||||
用户看到的“预习卡片”，本质上就是 SAP 的摘要版：
|
||||
|
||||
**🎯 统计分析计划**
|
||||
|
||||
1. **研究假设**：男性与女性的血糖水平存在差异。
|
||||
2. **数据清洗**：剔除 GLU 为空的样本；自动计算 BMI \= Weight/Height^2。
|
||||
3. **统计方法**：
|
||||
* 优先使用 **独立样本 T 检验**。
|
||||
* **前置条件**：需满足正态性（Shapiro-Wilk P \> 0.05）。
|
||||
* **替代方案**：若不满足，转为 **Mann-Whitney U 检验**。
|
||||
4. **图表展示**：分组箱线图 (Boxplot) 叠加散点。
|
||||
|
||||
## **3\. 这种视角下，后台需要配置什么？ (Config Requirements)**
|
||||
|
||||
我们要配置的不是“API 参数”，而是\*\*“统计学家的知识图谱”\*\*。我们需要在 Excel 中增加这几列：
|
||||
|
||||
### **3.1 决策逻辑配置 (Decision Logic)**
|
||||
|
||||
这是 Planner 的核心。专家需要定义：
|
||||
|
||||
| 配置项 | 含义 | 示例 (T检验) |
|
||||
| :---- | :---- | :---- |
|
||||
| **Goal\_Type** | 分析目的 | Difference (差异比较) |
|
||||
| **Y\_Type** | 因变量类型 | Continuous (连续数值) |
|
||||
| **X\_Type** | 自变量类型 | Categorical\_2 (二分类) |
|
||||
| **Design\_Type** | 设计类型 | Independent (独立) |
|
||||
| **Pre\_Conditions** | 前置假设 | Normality, Homogeneity |
|
||||
|
||||
**Planner 的逻辑**：
|
||||
|
||||
用户输入 \-\> 提取 (Goal, X, Y) \-\> **查配置表匹配** \-\> 命中 ST\_T\_TEST\_IND。
|
||||
|
||||
### **3.2 完整分析流配置 (Analysis Flow)**
|
||||
|
||||
一个工具往往伴随着一套动作。专家需要定义“套餐”：
|
||||
|
||||
| 配置项 | 含义 | 示例 |
|
||||
| :---- | :---- | :---- |
|
||||
| **Main\_Method** | 主方法 | t.test |
|
||||
| **Desc\_Method** | 描述方法 | mean\_sd (均值标准差) |
|
||||
| **Plot\_Type** | 推荐图表 | boxplot \+ jitter |
|
||||
| **Alt\_Method** | 替代方法 | wilcox.test (非参数) |
|
||||
|
||||
### **3.3 结果解读模板 (Narrative Template)**
|
||||
|
||||
专家要教 AI 怎么写论文里的“结果”部分。
|
||||
|
||||
* **配置内容**：
|
||||
"本研究共纳入 {{n}} 例样本。{{group\_col}} 各组间 {{val\_col}} 的差异 {{significance}} (t={{statistic}}, P={{p\_value}})。如图 1 所示，{{high\_group}} 的数值显著高于 {{low\_group}}。"
|
||||
|
||||
## **4\. 对架构的深层影响**
|
||||
|
||||
您的质疑直接推动了 **Config Center (配置中台)** 的升维。
|
||||
|
||||
1. **Planner 变重了**：它不能只做简单的 RAG 检索。它需要内置一个**轻量级的推理机**（基于专家配置的决策表），来模拟专家“看病”的过程。
|
||||
2. **Executor 变纯粹了**：它只需要忠实地执行 SAP 中的指令（包括主方法、替代方法、画图）。
|
||||
3. **Excel 配置表变复杂了**：我们需要设计一个更结构化的 Excel，让专家能把这些逻辑填进去。
|
||||
|
||||
### **新版 Excel 配置结构预览**
|
||||
|
||||
**Sheet: Knowledge\_Graph (知识图谱)**
|
||||
|
||||
* Scenario\_ID: 场景代码 (如 DIFF\_NUM\_2GRP\_IND)
|
||||
* User\_Intent: 用户意图 (差异比较)
|
||||
* Data\_Pattern: 数据特征 (Y=数值, X=2分类, 独立)
|
||||
* Rec\_Tool\_Code: 推荐工具 (ST\_T\_TEST\_IND)
|
||||
|
||||
**Sheet: Tool\_Definition (工具定义)**
|
||||
|
||||
* Tool\_Code: ST\_T\_TEST\_IND
|
||||
* Workflow: \[Check\_Normality, Check\_Variance, Run\_Test, Plot\_Box\] (定义一连串动作)
|
||||
* Report\_Template: 结果解释模板...
|
||||
|
||||
## **5\. 总结**
|
||||
|
||||
您是对的。**统计分析规划（Planner）的核心不是“检索”，而是“匹配”和“决策”。**
|
||||
|
||||
我们需要了解用户的：
|
||||
|
||||
1. **目的** (差异/相关/预测)
|
||||
2. **变量类型** (数值/分类/等级)
|
||||
3. **实验设计** (独立/配对/随访)
|
||||
|
||||
**我们的系统配置，必须围绕这三个维度展开。** 只有这样，SSA-Pro 才能生成一份让医生信服的 SAP，而不仅仅是扔给用户一个 T 检验代码。
|
||||
120
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Executor_专家配置要素.md
Normal file
120
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Executor_专家配置要素.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# **SSA-Executor 专家配置要素清单 (Configuration Specs)**
|
||||
|
||||
**文档版本：** v1.0
|
||||
|
||||
**创建日期：** 2026-02-18
|
||||
|
||||
**核心目标：** 定义统计专家需要在“配置中心”为每个 R 工具录入的详细信息。
|
||||
|
||||
**隐喻：** 如果 R 代码是“药方”，这个配置单就是“药品说明书”。
|
||||
|
||||
## **1\. 基础元数据 (Identity)**
|
||||
|
||||
*给这个 R 脚本一个系统内唯一的身份。*
|
||||
|
||||
| 配置项 | 说明 | 示例 |
|
||||
| :---- | :---- | :---- |
|
||||
| **Tool Code** | 唯一标识符 (Primary Key) | ST\_T\_TEST\_IND |
|
||||
| **Tool Name** | 显示名称 | 独立样本 T 检验 |
|
||||
| **Version** | 版本号 | v1.0.2 (用于回滚) |
|
||||
| **R Script File** | **上传文件** | t\_test\_ind.R (专家直接上传脚本) |
|
||||
| **Entry Function** | 入口函数名 | run\_analysis |
|
||||
|
||||
## **2\. 输入参数映射 (Input Contract)**
|
||||
|
||||
*告诉 Executor：这个 R 脚本需要什么原料？*
|
||||
|
||||
| 参数名 (JSON Key) | R 函数参数名 | 数据类型 | 校验规则 (Validator) | 默认值 |
|
||||
| :---- | :---- | :---- | :---- | :---- |
|
||||
| group\_col | group\_var | String | Must be column name | \- |
|
||||
| val\_col | value\_var | String | Must be numeric column | \- |
|
||||
| conf\_level | conf\_level | Float | 0.90 \- 0.99 | 0.95 |
|
||||
| alternative | alt | String | "two.sided", "less", "greater" | "two.sided" |
|
||||
|
||||
## **3\. 统计护栏配置 (Guardrails Config) ⭐ 核心**
|
||||
|
||||
*告诉 Executor：在跑核心代码前，先做什么体检？*
|
||||
|
||||
**配置模式：** 规则链 (Rule Chain)
|
||||
|
||||
1. **检查项 (Check)**: Shapiro-Wilk Normality Test
|
||||
* **目标变量**: val\_col (按 group\_col 分组)
|
||||
* **阈值 (Threshold)**: P \< 0.05
|
||||
* **失败动作 (Action)**:
|
||||
* \[ \] **Block**: 报错并终止 ("数据不正态，无法计算")
|
||||
* \[ \] **Warn**: 继续执行，但在结果中标记警告
|
||||
* \[x\] **Switch**: 自动切换到工具 ST\_WILCOXON (非参数检验)
|
||||
2. **检查项 (Check)**: Sample Size
|
||||
* **规则**: Min(N) \< 3
|
||||
* **失败动作**: **Block** ("样本量太少，无法计算")
|
||||
|
||||
## **4\. 输出结果定义 (Output Definition)**
|
||||
|
||||
*告诉 Executor：跑完代码后，要给用户看什么？*
|
||||
|
||||
### **4.1 结构化数据 (Table)**
|
||||
|
||||
定义返回的三线表里包含哪些指标。
|
||||
|
||||
* **指标 1**: Statistic (t值 / F值)
|
||||
* **指标 2**: P-Value (保留 3 位小数，\<0.001 显示为 "\<0.001")
|
||||
* **指标 3**: Mean ± SD (描述性统计)
|
||||
* **指标 4**: CI (95%) (置信区间)
|
||||
|
||||
### **4.2 图表配置 (Visualization)**
|
||||
|
||||
定义 R 脚本生成的图表规范（ggplot2 模板）。
|
||||
|
||||
* **图表类型**: Boxplot with Jitter (箱线图+散点)
|
||||
* **X 轴映射**: group\_col
|
||||
* **Y 轴映射**: val\_col
|
||||
* **配色方案**: Nature / Lancet (期刊风格)
|
||||
* **其它元素**: 是否标注 P 值？(Yes/No)
|
||||
|
||||
### **4.3 智能解读模板 (Narrative Template)**
|
||||
|
||||
这是给 AI (Critic) 参考的“填空题”，或者是 R 直接生成的结论。
|
||||
|
||||
* **模板**:"本研究纳入 {{N}} 例样本。{{group\_col}} 各组间 {{val\_col}} 的差异 **{{significance\_text}}** (t={{statistic}}, P={{p\_value}})。具体而言，{{high\_group}} 的均值 ({{mean\_1}}) 显著高于 {{low\_group}} ({{mean\_2}})。"
|
||||
|
||||
## **5\. 代码交付配置 (Code Handover)**
|
||||
|
||||
*告诉 Executor：用户点击“下载代码”时，给他什么？*
|
||||
|
||||
这是一个 **glue 字符串模板**，用于生成可复现的 R 代码。
|
||||
|
||||
\# 模板示例
|
||||
library(ggplot2)
|
||||
library(stats)
|
||||
|
||||
\# 1\. 读取数据
|
||||
data \<- read.csv("your\_data.csv")
|
||||
|
||||
\# 2\. 统计检验
|
||||
res \<- t.test({{val\_col}} \~ {{group\_col}}, data=data, var.equal={{var\_equal}})
|
||||
print(res)
|
||||
|
||||
\# 3\. 绘图
|
||||
ggplot(data, aes(x={{group\_col}}, y={{val\_col}})) \+
|
||||
geom\_boxplot(fill="\#3C5488") \+
|
||||
theme\_bw() \+
|
||||
labs(title="Difference Analysis")
|
||||
|
||||
## **6\. 环境依赖 (Dependencies)**
|
||||
|
||||
*告诉 Executor：运行这个脚本需要装什么包？*
|
||||
|
||||
* **Packages**: ggplot2, dplyr, car, ggpubr
|
||||
* **System Libs**: libcairo2 (如果涉及特殊绘图)
|
||||
|
||||
## **7\. 总结：专家的工作流**
|
||||
|
||||
统计学专家在“配置中心”要做的事情就是：
|
||||
|
||||
1. **上传** 写好的 t\_test.R。
|
||||
2. **勾选** 这个脚本需要的输入参数（列名）。
|
||||
3. **设置** 护栏（P \< 0.05 切换 Wilcoxon）。
|
||||
4. **粘贴** 代码模板（供用户下载）。
|
||||
5. **预览** 这一套配置是否能跑通测试数据。
|
||||
|
||||
**这才是真正的“专家协同”。**
|
||||
228
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro_v2.0_双引擎架构版 V2.1.md
Normal file
228
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro_v2.0_双引擎架构版 V2.1.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# **PRD: SSA-Pro 智能统计分析 (v2.0 双引擎架构版)**
|
||||
|
||||
**文档状态：** v2.1 (Optimized for User Scenarios)
|
||||
|
||||
**发布日期：** 2026-02-18
|
||||
|
||||
**文档密级：** 内部绝密
|
||||
|
||||
**核心变更：** \> 1\. 重构业务流程，确立“智能分析（混合模式）”为主流程。
|
||||
|
||||
2\. 明确“执行模式”为“标准化复用”场景，而非手动填参。
|
||||
|
||||
3\. 强化“专家配置”在架构中的核心地位。
|
||||
|
||||
## **1\. 核心变革说明 (Executive Summary)**
|
||||
|
||||
**致研发团队：为什么要进行这次架构升级？**
|
||||
|
||||
经过前几轮的技术验证与业务推演，我们发现原有的“上传-\>规划-\>执行”一条龙模式存在两个致命的业务死角：
|
||||
|
||||
1. **用户意图模糊**：用户往往不知道自己要做什么（如“帮我分析一下”），直接跑代码会报错或产生无意义结果。
|
||||
2. **统计专家缺位**：护栏规则硬编码在代码里，统计专家无法维护，导致系统缺乏“灵魂”。
|
||||
|
||||
因此，我们将架构解耦为**两个独立子系统**，通过编排满足不同场景：
|
||||
|
||||
* **Planner（大脑）**：负责陪聊、澄清意图、生成方案。**（独立上线，无需数据）**
|
||||
* **Executor（四肢）**：负责接收明确指令、跑数、出结果。**（复用之前的 R 开发成果）**
|
||||
|
||||
**架构拆分与用户体验的关系：**
|
||||
|
||||
架构上的拆分（Planner/Executor）是为了技术上的解耦和复用，但在用户体验端，对于最常见的“智能分析”场景，我们将这两者**无缝串联**，给用户提供“一站式”体验。
|
||||
|
||||
## **2\. 研发背景与业务价值**
|
||||
|
||||
### **2.1 用户真实痛点**
|
||||
|
||||
* **场景 A (无数据)**：医生在写基金本子，还没收病人，但他急需一份《统计学分析计划书》来填表。原方案不支持此场景。
|
||||
* **场景 B (数据脏)**：医生上传的 Excel 列名全是中文，且有特殊字符。原方案直接跑 R 会崩溃。
|
||||
* **场景 C (隐私顾虑)**：医生不敢把数据上传到云端，但又想知道该用什么统计方法。
|
||||
|
||||
### **2.2 产品解决方案：双引擎 \+ 配置中台**
|
||||
|
||||
1. **独立咨询 (SSA-Planner)**：无需上传数据，通过多轮对话澄清意图，输出专业的 SAP (分析计划)。
|
||||
2. **独立计算 (SSA-Executor)**：用户确认方案后，再上传数据，一键执行计算，交付代码。
|
||||
3. **专家协同 (Config Center)**：统计专家通过 Excel 配置规则，系统动态加载，不再硬编码。
|
||||
|
||||
### **2.3 商业价值**
|
||||
|
||||
* **降低门槛**：用户不用传数据就能体验 AI 能力（Planner），极大地提高了转化率。
|
||||
* **数据安全**：实现了逻辑（云端）与数据（本地/隔离）的彻底解耦。
|
||||
|
||||
## **3\. 系统架构与模块定义**
|
||||
|
||||
### **3.1 总体架构图**
|
||||
|
||||
graph TD
|
||||
subgraph "用户触点"
|
||||
Chat\[前端 Chat 界面\]
|
||||
end
|
||||
|
||||
subgraph "Module A: 智能规划师 (SSA-Planner)"
|
||||
Intent\[意图识别引擎\]
|
||||
Clarify\[澄清引导模块\]
|
||||
GenSAP\[SAP 生成模块\]
|
||||
end
|
||||
|
||||
subgraph "Module B: 智能执行器 (SSA-Executor)"
|
||||
API\[Executor API\]
|
||||
R\_Core\[R Docker 容器\]
|
||||
Guard\[统计护栏\]
|
||||
end
|
||||
|
||||
subgraph "Module C: 统计配置中台 (Admin)"
|
||||
Meta\[元数据管理\]
|
||||
Rules\[规则引擎\]
|
||||
Templates\[代码模板\]
|
||||
end
|
||||
|
||||
Chat \--"1. 咨询/方案"--\> Intent
|
||||
Intent \<--\> Clarify
|
||||
Intent \--\> GenSAP
|
||||
|
||||
Chat \--"2. 执行/计算"--\> API
|
||||
API \--\> R\_Core
|
||||
|
||||
Meta \-.-\> Intent
|
||||
Rules \-.-\> Guard
|
||||
|
||||
### **3.2 模块功能详述**
|
||||
|
||||
#### **🧩 模块 A：SSA-Planner (智能规划师)**
|
||||
|
||||
* **定位**：纯 NLP 应用，不涉及 R 计算。
|
||||
* **输入**：自然语言 \+ (可选) 数据 Schema。
|
||||
* **核心能力**：
|
||||
* **意图澄清**：当用户指令模糊时，主动反问（"您是想做差异分析还是相关性分析？"）。
|
||||
* **方案生成**：检索 RAG 库，生成结构化的 JSON 计划和 Markdown 报告。
|
||||
* **交付物**：《统计分析计划书》 (PDF/Word)。
|
||||
|
||||
#### **🧩 模块 B：SSA-Executor (智能执行器)**
|
||||
|
||||
* **定位**：纯计算服务，无状态 API。
|
||||
* **输入**：skill\_code \+ params \+ data\_source。
|
||||
* **核心能力**：
|
||||
* **混合数据加载**：支持 JSON 和 OSS 数据源。
|
||||
* **护栏检查**：执行正态性、方差齐性检查。
|
||||
* **结果交付**：生成三线表、高清图、R 源码。
|
||||
* **技术备注**：**这部分完全复用原 V1.3 计划中的 R 服务开发内容。**
|
||||
* **注意**：Executor 无法直接处理用户的自然语言。必须经由 Planner 将自然语言转化为结构化参数后，才能被调用。
|
||||
|
||||
#### **🧩 模块 C：统计配置中台 (Config Center)**
|
||||
|
||||
* **定位**：专家知识注入入口。
|
||||
* **MVP 实现**：**Excel 导入工具**。
|
||||
* **配置内容**：
|
||||
* 工具定义（Name, Desc, Usage）。
|
||||
* 护栏阈值（P \< 0.05）。
|
||||
* R 代码模板（Glue Template）。
|
||||
|
||||
## **4\. 核心业务流程 (User Journey)**
|
||||
|
||||
### **流程一：智能分析模式 (Intelligent Analysis Mode) \- ⭐ 最常见场景**
|
||||
|
||||
**场景**：用户有数据，有模糊的意图（如“帮我对比一下差异”），希望一站式出结果。
|
||||
|
||||
**架构逻辑**：串联调用 Planner \-\> Executor。
|
||||
|
||||
1. **用户**：上传 data.csv 并输入：“帮我对比一下吸烟组和非吸烟组的体重差异”。
|
||||
2. **Planner**（后台隐形介入）：
|
||||
* 读取 Data Schema，识别出 Group 和 Weight 列。
|
||||
* 理解用户意图（"对比差异"），结合变量类型（二分类 vs 连续），推荐“独立样本 T 检验”。
|
||||
* 生成 Executor 能听懂的 JSON 参数。
|
||||
3. **交互**：系统弹出 **\[ 方案确认卡片 \]**（由 Planner 生成）。
|
||||
* *设计意图*：给用户一种“专家先审视，再执行”的安全感。
|
||||
4. **用户**：点击 **\[ 确认并执行 \]**。
|
||||
5. **Executor**：接收 Planner 的 JSON \-\> 跑 R 代码 \-\> 返回结果。
|
||||
6. **用户**：获得结果。
|
||||
|
||||
### **流程二：纯咨询模式 (Consultation Mode) \- 科研设计场景**
|
||||
|
||||
**场景**：用户还没收集数据（无数据），在写开题报告或基金标书，需要设计统计方案。
|
||||
|
||||
**架构逻辑**：仅调用 Planner。
|
||||
|
||||
1. **用户**：“我想研究阿司匹林对心血管事件的影响，该怎么设计统计？”
|
||||
2. **Planner**：检索知识库，生成《统计分析计划书 (SAP)》。
|
||||
* 包含：研究假设、变量定义、推荐方法（Cox 回归）、样本量估算建议。
|
||||
3. **用户**：下载 SAP 文档。**（流程结束）**
|
||||
|
||||
### **流程三：标准化复用模式 (Standardized Reuse Mode) \- 专家/高阶场景**
|
||||
|
||||
**场景**：
|
||||
|
||||
1. **复用**：上周生成了一个完美的 SAP，这周新数据来了，直接套用，不想再跟 AI 废话。
|
||||
2. **专家下发**：科室主任定义好了标准分析流程，存为模板，研究生直接上传数据运行。
|
||||
**架构逻辑**：跳过 Planner 推理，直接调用 Executor。
|
||||
1. **用户**：上传 new\_data.csv，并从“我的方案库”中选择“肺癌生存分析标准模板”（或加载之前的 SAP ID）。
|
||||
2. **系统**：自动校验新数据是否符合模板要求的列名（Schema Check）。
|
||||
3. **Executor**：直接读取模板参数 \-\> 跑数 \-\> 出结果。
|
||||
4. **用户**：下载结果。
|
||||
|
||||
## **5\. 接口与数据协议 (Schema)**
|
||||
|
||||
### **5.1 Planner 输出协议 (Plan JSON)**
|
||||
|
||||
这是连接 Planner 和 Executor 的契约。
|
||||
|
||||
{
|
||||
"analysis\_id": "uuid",
|
||||
"tool\_code": "ST\_T\_TEST\_IND",
|
||||
"reasoning": "因变量为连续数值，自变量为二分类...",
|
||||
"params": {
|
||||
"group\_col": "Gender",
|
||||
"val\_col": "BMI",
|
||||
"conf\_level": 0.95
|
||||
},
|
||||
"guardrails": {
|
||||
"check\_normality": true,
|
||||
"action\_on\_fail": "switch\_to\_wilcoxon"
|
||||
}
|
||||
}
|
||||
|
||||
## **6\. 实施路线图 (Updated Roadmap)**
|
||||
|
||||
基于新架构，我们将开发顺序调整为 **“Planner 先行，Executor 并行”**。
|
||||
|
||||
### **Phase 1: 智能规划师上线 (Week 1-2)**
|
||||
|
||||
* **目标**：上线“统计咨询 Chatbot”。
|
||||
* **后端**：开发 Excel 配置导入脚本；开发 Planner Service (DeepSeek)。
|
||||
* **前端**：开发咨询模式 UI。
|
||||
* **专家**：整理 Top 10 工具的 Excel 配置。
|
||||
* *注：此阶段不需要 R 服务参与。*
|
||||
|
||||
### **Phase 2: 执行器与联调 (Week 3-4)**
|
||||
|
||||
* **目标**：打通计算闭环。
|
||||
* **R 团队**：完成 Docker 封装、数据加载器 (Data Loader)、T 检验 Wrapper。
|
||||
* **后端**：对接 R API，透传 Planner 的参数。
|
||||
* **前端**：开发结果展示卡片。
|
||||
|
||||
### **Phase 3: 量产与优化 (Week 5+)**
|
||||
|
||||
* **目标**：覆盖更多工具。
|
||||
* **R 团队**：批量复制开发剩余 9 个工具。
|
||||
* **专家**：持续优化配置 Excel。
|
||||
|
||||
## **7\. 风险与应对**
|
||||
|
||||
| **风险点** | **影响** | **应对策略** |
|
||||
|
||||
| **Planner 瞎指挥** | 生成的参数 Executor 无法执行 | 引入 **Zod Schema 强校验**，参数不合法直接让 AI 重试。 |
|
||||
|
||||
| **数据列名不匹配** | R 代码报错 "Column not found" | 在 Executor 入口增加 **模糊匹配/同义词映射** 逻辑。 |
|
||||
|
||||
| **专家配置进度慢** | 阻塞 Planner 上线 | 提供标准模板，先配 1 个工具（T检验）跑通全流程。 |
|
||||
|
||||
## **8\. 结语**
|
||||
|
||||
这次架构调整不是推翻过去，而是**升维**。
|
||||
|
||||
我们保留了最核心的 **R 计算引擎 (Executor)**，它是我们的硬实力；
|
||||
|
||||
我们剥离出了 **AI 规划师 (Planner)**，它是我们的软实力；
|
||||
|
||||
我们引入了 **配置中台**，它是我们的护城河。
|
||||
|
||||
请大家基于此文档，放心开工。
|
||||
57
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro_架构一致性与调整分析.md
Normal file
57
docs/03-业务模块/SSA-智能统计分析/00-系统设计/SSA-Pro_架构一致性与调整分析.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# **SSA-Pro 架构一致性与调整分析报告**
|
||||
|
||||
**分析对象：** PRD V2.0 "智能分析模式" vs. V1.3 开发计划套件 (5文档)
|
||||
|
||||
**分析结论：** **核心逻辑完全一致，无需重构，仅需解耦接口。**
|
||||
|
||||
## **1\. 核心结论：我们绕弯路了吗？**
|
||||
|
||||
**没有。我们只是把“隐性”的逻辑“显性化”了。**
|
||||
|
||||
* **V1.3 计划（原计划）**：设计了一个“串联”系统。
|
||||
* 逻辑：用户上传 \-\> 系统规划(Planner) \-\> 系统执行(Executor) \-\> 结果
|
||||
* **现状**：这正是 PRD V2.0 中的 **“流程一：智能分析模式”**。这是用户 90% 的使用场景。
|
||||
* **V2.0 架构（新概念）**：提出了“双引擎”概念。
|
||||
* 逻辑：把上述串联系统中的 规划 和 执行 两个步骤，定义为两个可以**独立调用**的模块。
|
||||
|
||||
**结论：**
|
||||
|
||||
**V1.3 的开发计划（代码、Docker、数据库）依然是 100% 可用的基础。** 我们不需要推翻它，只需要在写代码时，注意把 Planner 和 Executor 的代码写在不同的 Service 文件里，不要写死在一个大函数里即可。
|
||||
|
||||
## **2\. 详细对比与复用策略**
|
||||
|
||||
我们来看之前的 5 个文档，看看哪些可以直接用，哪些需要微调。
|
||||
|
||||
| 原文档 | V1.3 内容 | V2.0 架构要求 | 调整建议 |
|
||||
| :---- | :---- | :---- | :---- |
|
||||
| **02-R服务开发指南** | 定义了 R Docker、Wrapper、护栏、混合数据协议。 | 需要一个独立的计算引擎。 | **无需调整 (0%)**。 R 服务本身就是 Executor，它生来就是被调用的，不关心是谁调用的。 |
|
||||
| **03-后端开发指南** | 定义了 RClientService (执行) 和 PlannerService (规划)。 | 需要 Planner 和 Executor 解耦。 | **微调接口 (10%)**。 原计划中可能有一个 runAnalysis() 函数把两步连起来写了。**调整为：** 写两个函数 plan() 和 execute()，然后在 Controller 层串联它们。 |
|
||||
| **04-前端开发指南** | 定义了 PlanCard, ExecutionTree, ResultCard。 | 需要支持“咨询模式”和“执行模式”。 | **微调路由 (10%)**。 增加一个 /consult 页面（复用 Chat 组件）。PlanCard 增加一个“仅下载方案”的按钮。 |
|
||||
| **00/01 计划任务** | 定义了开发里程碑。 | 强调 Planner 先行。 | **无需调整**。 原计划也是先做 RAG/Planner，再做 Executor。顺序本就一致。 |
|
||||
|
||||
## **3\. 为什么“双引擎”概念依然重要？（即使流程没变）**
|
||||
|
||||
既然流程一样，为什么还要提“双引擎”？是为了解决 **边界情况（Corner Cases）**：
|
||||
|
||||
1. **无数据咨询 (The "No-Data" Problem)**：
|
||||
* 如果按照旧的 V1.3 思维，代码可能会写成 if (\!file) throw Error("请上传文件")。
|
||||
* 引入“双引擎”概念后，后端代码会写成 if (\!file) return PlannerService.consult()。
|
||||
* **这就是唯一的区别：允许 Planner 独立工作。**
|
||||
2. **专家配置 (The "Config" Problem)**：
|
||||
* V1.3 计划里，工具的 Prompt 可能是写死在代码里的。
|
||||
* V2.0 强调配置中心，提醒我们把 Prompt 放到数据库里，让专家能改。
|
||||
|
||||
## **4\. 最终执行建议：如何使用现有的 5 个文档？**
|
||||
|
||||
**请直接使用之前的 5 个文档进行开发，但在实施时遵循以下 3 条“解耦原则”：**
|
||||
|
||||
1. **后端开发原则**：
|
||||
* 不要把 Planner 的逻辑和 Executor 的逻辑混在一个 Class 里。请创建 src/modules/ssa/planner/ 和 src/modules/ssa/executor/ 两个文件夹。
|
||||
2. **前端开发原则**：
|
||||
* 不要假设用户一定上传了文件。Chat 界面初始化时，允许 file 为空。
|
||||
3. **专家配置原则**：
|
||||
* 按原计划优先使用 **Excel** 导入配置。这是最快落地的方案，不需要改架构。
|
||||
|
||||
**一句话总结：**
|
||||
|
||||
**架构不需要大改。V1.3 的开发计划是稳健的。所谓的“架构调整”，只是要求开发人员在写代码时，“手起刀落”把逻辑拆得更干净一点，方便未来复用，仅此而已。**
|
||||
Reference in New Issue
Block a user