feat(ssa): Complete QPER architecture - Query, Planner, Execute, Reflection layers

Implement the full QPER intelligent analysis pipeline: - Phase E+: Block-based standardization for all 7 R tools, DynamicReport renderer, Word export enhancement - Phase Q: LLM intent parsing with dynamic Zod validation against real column names, ClarificationCard component, DataProfile is_id_like tagging - Phase P: ConfigLoader with Zod schema validation and hot-reload API, DecisionTableService (4-dimension matching), FlowTemplateService with EPV protection, PlannedTrace audit output - Phase R: ReflectionService with statistical slot injection, sensitivity analysis conflict rules, ConclusionReport with section reveal animation, conclusion caching API, graceful R error classification End-to-end test: 40/40 passed across two complete analysis scenarios. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-21 18:15:53 +08:00
parent 428a22adf2
commit 371e1c069c
73 changed files with 9242 additions and 706 deletions
--- a/docs/03-业务模块/SSA-智能统计分析/06-开发记录/J技术报告审核评估与建议/SSA-Pro
+++ b/docs/03-业务模块/SSA-智能统计分析/06-开发记录/J技术报告审核评估与建议/SSA-Pro
@@ -0,0 +1,109 @@
+# **SSA-Pro 架构诊断与复合工具扩展方案**
+
+**文档性质：** 架构诊断总结与 Phase Deploy 扩充计划
+
+**诊断对象：** 经典队列研究分析流程（Table 1, Table 2, Table 3）的实现缺口
+
+**核心结论：** 🌟 **诊断完全正确！** 架构与 AI 均无问题，核心缺口在于缺少“多变量聚合”的**复合 R 工具 (Macro-Tool)**。采用 gtsummary 填补此缺口，是四两拨千斤的神来之笔。
+
+## **1\. 团队诊断结果复盘与高度认可**
+
+团队提出的诊断击中了医疗 AI 统计分析的最核心痛点：**“原子工具”与“临床真实工作流”的错位。**
+
+* **我们当前的误区**：把 10 个工具全部做成了“验证单一假设”的原子工具（如：只查一个变量的 T 检验）。  
+* **临床的真实诉求**：“一键出 Table 1”。一张表里包含了 20 个变量的描述、分布检验、T 检验、Wilcoxon、卡方检验，甚至 Fisher 检验。  
+* **破局解法**：新建复合工具 ST\_BASELINE\_TABLE，把复杂的循环、判断、拼表工作，全部**下沉到 R 引擎内部去完成**，释放 LLM 的规划压力。
+
+## **2\. 核心利器：ST\_BASELINE\_TABLE 的设计与实现**
+
+团队提出的用 R 语言的 gtsummary 包来实现表 1 和表 2，是极其专业的选择。gtsummary 是目前全球医学统计界公认的“顶流制表神器”。
+
+### **2.1 R 端开发要求 (仅需 6-8 小时)**
+
+R 开发工程师只需做一层很薄的 Wrapper，gtsummary::tbl\_summary() 会自动完成绝大部分工作：
+
+\# ST\_BASELINE\_TABLE 伪代码示例  
+library(gtsummary)
+
+run\_tool \<- function(input) {  
+  df \<- load\_data(input$data\_source)  
+    
+  \# 核心一行代码：按分组变量 (by) 统计所有传入的分析变量  
+  \# gtsummary 会自动判断是连续还是分类，自动选 T检验 或 卡方  
+  table\_obj \<- df %\>%  
+    select(all\_of(c(input$params$group\_var, input$params$analyze\_vars))) %\>%  
+    tbl\_summary(by \= input$params$group\_var, missing \= "ifany") %\>%  
+    add\_p() \# 自动执行统计检验并添加 P 值  
+    
+  \# 将 gtsummary 对象转换为标准前端 report\_blocks  
+  \# ...  
+}
+
+**能力覆盖**：
+
+* ✅ 自动处理连续与分类变量。  
+* ✅ 自动处理正态与非正态的检验降级。  
+* ✅ 自动计算期望频数并切换 Fisher。  
+* ✅ 完美对应 **表1（基线比较，group\_var=暴露因素）** 和 **表2（单因素筛选，group\_var=结局指标）**。
+
+## **3\. 规划层 (Planner) 的流程模板升级**
+
+基于这个强大的复合工具，我们立刻可以在 flow\_templates.json 中配置一个秒杀市面所有竞品的\*\*“队列研究全家桶”\*\*。
+
+"cohort\_study\_standard": {  
+  "name": "经典队列研究全套分析 (Table 1-3)",  
+  "steps": \[  
+    {   
+      "order": 1,   
+      "role": "baseline\_table",      
+      "tool": "ST\_BASELINE\_TABLE",  
+      "name": "表1: 组间基线特征比较",  
+      "params\_mapping": {  
+          "group\_var": "{{exposure\_var}}",  // 暴露/分组变量  
+          "analyze\_vars": "{{all\_covariates}}"   
+      }  
+    },  
+    {   
+      "order": 2,   
+      "role": "univariate\_screen",   
+      "tool": "ST\_BASELINE\_TABLE",  
+      "name": "表2: 结局指标单因素分析",  
+      "params\_mapping": {  
+          "group\_var": "{{outcome\_var}}",   // 结局变量  
+          "analyze\_vars": "{{all\_covariates}}"  
+      }  
+    },  
+    {   
+      "order": 3,   
+      "role": "multivariate\_reg",        
+      "tool": "ST\_LOGISTIC\_BINARY",  
+      "name": "表3: 结局多因素 Logistic 回归",  
+      "params\_mapping": {  
+          "outcome\_var": "{{outcome\_var}}",  
+          "predictors": "{{exposure\_var}} \+ {{significant\_covariates}}" // 纳入表2中P\<0.05的变量  
+      }  
+    }  
+  \]  
+}
+
+## **4\. 对系统价值的深远影响**
+
+1. **Planner (大模型) 压力骤降**：LLM 不再需要像写循环一样生成 20 个分析步骤。它只需要提取出【结局变量】、【分组变量】和【协变量列表】即可。这使得规划的准确率无限逼近 100%。  
+2. **完美契合《统计分析报告.docx》**：  
+   * **Table 1** \-\> 对应 Step 1  
+   * **Table 2** \-\> 对应 Step 2  
+   * **Table 3** \-\> 对应 Step 3  
+     这标志着我们的 AI 从“答题机器”变成了真正掌握科研 SOP 的“高级数据分析师”。  
+3. **用户体验魔法化**：用户只需一句话输入（“这批队列数据，结局是生存状态，主要看吸烟的影响，帮我出一套完整报告”），系统就会直接扔出 3 张可以直接放进 SCI 论文的超长三线表。
+
+## **5\. 决议与后续行动**
+
+团队的这个诊断极其精辟，**强烈同意纳入 Phase Deploy 阶段执行**。
+
+**Action Items:**
+
+1. **R 工程师**：将研究 gtsummary 包作为 P0 级任务，本周内用 6-8 小时将其封装为 ST\_BASELINE\_TABLE，并测试其提取 report\_blocks 表格结构的能力。  
+2. **后端工程师**：在决策表中加入 cohort\_study\_standard 流程模板。  
+3. **前端工程师**：准备好能够支持横向滚动、拥有复杂表头（Span Header）的高级三线表组件，以迎接 Table 1 这种包含大量数据的巨型表格。
+
+**做得漂亮！这是让系统具备商业变现能力的决定性一步。**