# **SSA-Pro 方案深度审查与风险评估报告**

**审查对象：** SSA-Pro MVP 开发计划套件 (v1.1)

**包含文档：** MVP计划总览、任务清单、R服务指南、后端指南、前端指南

**审查时间：** 2026-02-18

**总体评级：** **A- (优秀，但存在关键一致性漏洞)**

## **1\. 🚨 关键一致性漏洞 (Critical Inconsistency)**

**这是当前计划中最大的风险点，必须在开工前修复。**

### **漏洞：混合数据传输协议在 R 指南中缺失**

* **架构定义 (V4.1)**：明确定义了“混合数据传输协议”，即 \<1MB 走 Inline JSON，1-20MB 走 OSS 引用。  
* **后端指南 (Doc 03\)**：正确实现了 data\_source 逻辑，会发送 OSS Key。  
* **R 服务指南 (Doc 02\)**：❌ **严重缺失**。  
  * 在 5.2 Wrapper 实现 示例代码中，依然假设 input$data 直接就是数据对象：  
    \# 错误代码 (Doc 02\)  
    df \<- tryCatch(as.data.frame(input$data), ...)

  * **后果**：如果后端发来的是 OSS Key，R 服务会直接报错或崩溃，导致 1MB 以上文件无法处理。

### **🛠️ 修正建议**

在 R 服务开发指南中，必须增加一个标准化的 **Data Loader** 工具函数，并在所有 Wrapper 入口处调用：

\# utils/data\_loader.R  
load\_input\_data \<- function(input\_json) {  
  \# 兼容旧协议（纯数据）和新协议（data\_source 对象）  
  if (\!is.null(input\_json$data\_source)) {  
    source \<- input\_json$data\_source  
    if (source$type \== "inline") {  
      return(as.data.frame(source$content))  
    } else if (source$type \== "oss") {  
      \# ⬇️ 必须实现 OSS 下载逻辑  
      return(download\_and\_read\_oss(source$key))  
    }  
  }  
  \# Fallback  
  return(as.data.frame(input\_json$data))  
}

## **2\. 架构层面的潜在风险 (Architecture Risks)**

### **2.1 R 服务的“单线程阻塞”风险**

* **现状**：R 语言是单线程的。Plumber 默认也是同步处理。  
* **场景**：假设 SAE 分配了 1 个实例。用户 A 提交了一个需要跑 10 秒的 Bootstrap 任务。此时用户 B 提交了一个简单的 T 检验。  
* **后果**：用户 B 的请求会被阻塞 10 秒，甚至超时。HTTP 接口没有排队机制，体验极差。  
* **建议**：  
  1. **SAE 层面**：设置较激进的扩容策略（并发数 \> 2 即扩容）。  
  2. **应用层面**：考虑在 Plumber 中使用 future 包将长任务丢到后台 Promise 中运行（虽然这会增加复杂度），或者简单粗暴地在 Docker 容器中启动多个 R 进程（利用 PM2 管理 Rscript）。**MVP 阶段建议至少部署 2 个 SAE 实例做负载均衡。**

### **2.2 OSS 内网穿透的配置陷阱**

* **现状**：文档强调了使用“VPC 内网 Endpoint”。  
* **风险**：  
  * 开发环境（本地 Docker）通常不在 VPC 内，无法访问内网 Endpoint。  
  * 生产环境（SAE）在 VPC 内，必须访问内网 Endpoint。  
* **建议**：  
  * R 代码中的 OSS Endpoint **必须通过环境变量注入**，绝不能硬编码。  
  * docker-compose.yml (开发) 注入公网 Endpoint。  
  * SAE 环境变量 (生产) 注入内网 Endpoint。

## **3\. 工程细节的优化建议 (Engineering Improvements)**

### **3.1 代码生成的“可维护性”问题**

* **现状**：在 R 代码中使用 glue 拼接字符串。  
* **问题**：将大量的 R 代码（如下载逻辑、绘图逻辑）以字符串形式写在 Wrapper 里，不仅难写，而且**没有语法高亮，容易拼错**。  
* **建议**：  
  * 采用 **"模板文件分离"** 策略。  
  * 在 templates/ 目录下存放完整的 .R 文件（如 t\_test\_template.R），在其中用 {{variable}} 占位。  
  * Wrapper 只负责读取文件并替换变量，不要在代码里写大段字符串。

### **3.2 统计结果的“精度陷阱”**

* **现状**：R 返回的 p\_value 是浮点数。  
* **问题**：JSON 序列化时，极小的 P 值（如 1.23e-16）在前端 JavaScript 中可能会显示不友好，或者精度丢失。  
* **建议**：  
  * R 服务在返回 JSON 前，建议增加一个格式化后的字段，如 p\_value\_fmt: "\< 0.001"，由 R 来决定如何科学计数显示，而不是让前端去猜。

### **3.3 护栏（Guardrails）的“一刀切”风险**

* **现状**：正态性检验失败 \-\> 自动降级。  
* **问题**：对于大样本（N \> 5000），Shapiro-Wilk 检验过于敏感，哪怕极微小的偏态也会 P \< 0.05。但实际上大样本下 T 检验是鲁棒的（中心极限定理）。  
* **建议**：  
  * 优化 guardrails.R 逻辑：当 N \> 500 时，放宽正态性检验的阈值，或者直接跳过 Shapiro 检验，改用 Q-Q 图的峰度/偏度判断（虽然这很难自动化）。  
  * **MVP 修正**：至少加上 if (N \> 5000\) return PASS 的逻辑，避免大样本被错误降级。

## **4\. 测试数据的缺失 (Missing Test Data)**

文档中提到了“端到端测试”，但缺少\*\*“标准测试数据集 (Golden Datasets)”\*\*。

* **问题**：怎么证明你的 T 检验算得是对的？  
* **建议**：  
  * 建立一个 tests/fixtures 目录。  
  * 准备几组 **“标准答案”**：  
    1. normal\_data.csv (R 算出来应该是 P=0.042)  
    2. skewed\_data.csv (应该触发护栏降级)  
    3. missing\_data.csv (应该报错或自动剔除)  
  * 在 CI/CD 流程中，自动跑这几组数据，比对结果是否与标准答案一致。

## **5\. 结论与修正计划**

### **✅ 总体评价**

方案架构设计合理，技术栈选型（Node+R+Plumber）成熟。只要修复数据协议的不一致，MVP 成功率极高。

### **📝 需立即执行的修正 (Must-Do)**

1. **修正 Doc 02 (R 开发指南)**：  
   * \[ \] 增加 utils/data\_loader.R 模块，实现混合协议解析。  
   * \[ \] 修改 Dockerfile 和 Env 配置，支持 OSS\_ENDPOINT 动态注入。  
   * \[ \] 修改 Wrapper 模板，使用 load\_input\_data() 替代直接读取。  
2. **修正 Doc 03 (后端指南)**：  
   * \[ \] 确认 RClientService 发送给 R 的 Payload 结构与 R 端的解析逻辑完全匹配。  
3. **补充测试资源**：  
   * \[ \] 准备 3-5 个涵盖边缘情况（空值、单行、非正态）的标准 CSV 文件。

**建议项目经理（PM）将上述 3 点加入 "Phase 1: 骨架搭建" 的首要任务。**