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>
119 lines
6.6 KiB
Markdown
119 lines
6.6 KiB
Markdown
# **SSA-Pro V1.2 终极审查与发令报告**
|
||
|
||
**审查对象：** SSA-Pro MVP 开发计划套件 (v1.2)
|
||
|
||
**审查时间：** 2026-02-18
|
||
|
||
**审查结论：** 🟢 **通过 (Green Light)** \- 准予启动开发
|
||
|
||
**风险等级：** 低 (Low)
|
||
|
||
## **1\. 核心改进验证 (Verification of Fixes)**
|
||
|
||
针对上一轮（V1.1）指出的致命问题，V1.2 已完成修复：
|
||
|
||
| 检查项 | 状态 | 证据 |
|
||
| :---- | :---- | :---- |
|
||
| **混合数据协议一致性** | ✅ **已修复** | **R指南**: utils/data\_loader.R 增加了 load\_input\_data 函数，支持 OSS 下载。 **后端指南**: RClientService 实现了 buildDataSource 逻辑，自动判断 \<2MB 和 \>2MB。 |
|
||
| **OSS 内网穿透** | ✅ **已修复** | **R指南**: Dockerfile 引入了 OSS\_ENDPOINT 环境变量，不再硬编码。 |
|
||
| **代码生成可维护性** | ✅ **已修复** | **R指南**: 引入 glue 包和 templates/ 目录，告别了 paste0 硬拼接。 |
|
||
| **大样本护栏误杀** | ✅ **已修复** | **R指南**: guardrails.R 增加了 LARGE\_SAMPLE\_THRESHOLD (5000)，大样本启用抽样检验。 |
|
||
|
||
**评价：** 团队响应迅速，核心架构隐患已消除。
|
||
|
||
## **2\. 深度风险挖掘 (Deep Dive Risks)**
|
||
|
||
虽然逻辑闭环，但在**高并发**和**运维**层面仍有 4 个隐形深坑：
|
||
|
||
### **2.1 Node.js 的“内存刺客” (Memory Spike)**
|
||
|
||
* **位置**：DataParserService.ts
|
||
* **问题**：使用 xlsx 库读取 Excel。该库会将整个文件读入内存。如果用户并发上传 10 个 20MB 的 Excel，Node.js 内存可能瞬间飙升 500MB+，导致 OOM (Out of Memory)。
|
||
* **建议**：
|
||
* **MVP 阶段**：在 SAE 设置 Node.js 内存上限为 2GB+。
|
||
* **长期方案**：改用 exceljs 的流式读取 (Stream Reader)，或将解析任务卸载给 Python (Tool C) 处理。
|
||
|
||
### **2.2 R 服务的“僵尸进程” (Zombie Process)**
|
||
|
||
* **位置**：R Docker
|
||
* **问题**：tryCatch 虽然捕获了错误，但如果底层的 C++ 库（如 read.csv 读取畸形文件）导致 Segmentation Fault，R 进程会直接 Crash 退出。SAE 虽然会重启容器，但会导致该请求直接 502 Bad Gateway，且没有明确的错误日志。
|
||
* **建议**：
|
||
* 配置 SAE 的 **Liveness Probe** (存活检查)，确保挂掉的容器能被立刻重启。
|
||
* 后端 RClientService 增加对 **HTTP 502/504** 的特殊处理，返回给用户：“服务繁忙或数据异常，请稍后重试”。
|
||
|
||
### **2.3 开发环境的“网络孤岛”**
|
||
|
||
* **位置**：本地 Docker
|
||
* **问题**：开发人员在本地跑 R Docker 时，试图下载阿里云 OSS 的文件。如果公司的 VPN 或网络环境不稳定，OSS 下载会超时，导致本地开发受阻。
|
||
* **建议**：
|
||
* 在 tests/fixtures 中，除了 CSV，**增加一个模拟的 OSS Downloader**（Mock）。
|
||
* 在 data\_loader.R 中增加一个 DEV\_MODE 开关，如果是开发环境且 OSS 不通，允许直接读取本地文件模拟下载。
|
||
|
||
### **2.4 代码交付的“环境依赖”**
|
||
|
||
* **位置**：用户下载的 .R 代码
|
||
* **问题**：用户下载代码后在自己的电脑运行，大概率会报错 Error: there is no package called 'ggplot2'。
|
||
* **建议**：
|
||
* 在生成的代码头部，自动注入一段 **“依赖检查与安装脚本”**：
|
||
\# 自动安装依赖
|
||
required\_packages \<- c("jsonlite", "ggplot2", "car")
|
||
new\_packages \<- required\_packages\[\!(required\_packages %in% installed.packages()\[,"Package"\])\]
|
||
if(length(new\_packages)) install.packages(new\_packages)
|
||
|
||
## **3\. "最后一公里" 优化建议**
|
||
|
||
### **3.1 增加 "Debug 模式"**
|
||
|
||
在 POST /execute 接口增加一个 debug: true 参数。
|
||
|
||
* **效果**：R 服务不删除 /tmp 下的中间文件（CSV、Plot），并返回这些文件的 OSS 地址。
|
||
* **价值**：极大方便 QA 和开发人员排查“为什么这张图画不出来”。
|
||
|
||
### **3.2 强化 P 值展示 (APA 格式)**
|
||
|
||
目前的 p\_value\_fmt 很好了，但建议补充 **显著性星号**。
|
||
|
||
* **建议**：R 返回结果增加 significance\_stars 字段 (\*\*\*, \*\*, \*, ns)，前端直接展示，显得更专业。
|
||
|
||
### **3.3 预埋 "用户反馈" 埋点**
|
||
|
||
在结果卡片下方增加 👍 / 👎 按钮。
|
||
|
||
* **价值**：收集用户对 AI 解释（Critic）的满意度，用于后续微调 Prompt。
|
||
|
||
### **4.1 R 代码生成的维护成本 (High)**
|
||
|
||
* **现状：使用 `glue` 模板技术。**
|
||
* **挑战：你需要维护 两套逻辑 —— 一套是 R Wrapper 里的真实执行逻辑，另一套是 `templates/*.R` 里的字符串模板。**
|
||
* **风险：如果修改了 Wrapper 的逻辑（比如换了 `leveneTest` 包），但忘了改模板，用户下载的代码就跑不通了。这需要极强的开发纪律。**
|
||
|
||
### **4.2 护栏机制的调试 (Medium)**
|
||
|
||
* **挑战：如何设定正态性检验的阈值？**
|
||
* **细节：对于 N=5000 的数据，Shapiro 检验极易显著（P\<0.05），导致 T 检验被误杀。**
|
||
* **对策：需要在 `guardrails.R` 中加入基于样本量的动态策略（例如：N \> 3000 时跳过正态性检查，直接使用 T 检验，依据中心极限定理）。**
|
||
|
||
### **4.3 异步交互的体验优化 (Medium)**
|
||
|
||
* **挑战：后端虽然是同步 API，但如果计算耗时 30秒，前端用户会焦虑。**
|
||
* **对策：`ExecutionProgress` 组件虽然做了模拟进度条，但最好能让后端支持 Server-Sent Events (SSE) 推送真实进度（如“正在进行第 500 次置换...”）。MVP 阶段可以暂缓，但 Phase 3 建议补上。**
|
||
|
||
## **4\. 潜在的其他问题 (Remaining Issues)**
|
||
|
||
### **5.1 隐私保护的漏网之鱼**
|
||
|
||
* **问题：`DataParserService` 在提取 Schema 时计算了 Min/Max。**
|
||
* **场景：如果某列数据是“HIV感染状态”，虽然是分类变量，但如果某一类只有 1 个人，`uniqueValues` 也会暴露隐私。**
|
||
* **建议：在 `DataParserService` 中增加逻辑：如果某列的唯一值计数 \< 5 且总行数 \> 10，仅返回 "Masked" 或不返回具体值给 LLM。**
|
||
|
||
### **5.2 错误信息的“黑盒化”**
|
||
|
||
* **问题：R 报错信息（如 `system is computationally singular`）对用户极其不友好。**
|
||
* **建议：建立一个 R 错误码字典。Wrapper 捕获错误后，尽量映射为 `E00x` 业务错误码。前端根据错误码显示“多重共线性警告”等人话，而不是原始报错。**
|
||
|
||
### **5.3 代码运行环境的一致性**
|
||
|
||
* **问题：用户下载代码在本地跑，本地没有装 R 包怎么办？**
|
||
* **建议：在下载的代码包里，除了 `.R` 文件，最好附带一个 `install_dependencies.R` 脚本，一键安装所有依赖包。**
|
||
|