HaHafeng
8137e3cde2
Summary: - Add PRD and architecture design V4 (Brain-Hand model) - Complete 5 development guide documents - Pass 3 rounds of team review (v1.0 -> v1.3) - Add module status guide document - Update system status document Key Features: - Brain-Hand architecture: Node.js + R Docker - Statistical guardrails with auto degradation - HITL workflow: PlanCard -> ExecutionTrace -> ResultCard - Mixed data protocol: inline vs OSS - Reproducible R code delivery MVP Scope: 10 statistical tools Status: Design 100%, ready for development Co-authored-by: Cursor <cursoragent@cursor.com>
124 lines
6.3 KiB
Markdown
124 lines
6.3 KiB
Markdown
# **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: 骨架搭建" 的首要任务。** |