Files

HaHafeng 8137e3cde2 feat(ssa): Complete SSA-Pro MVP development plan v1.3

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>

2026-02-18 21:58:37 +08:00

7.3 KiB

Raw Blame History

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

审查对象： SSA-Pro V4.1 架构及配套开发计划 (v1.0)

审查视角： 系统架构、工程落地、安全性、可维护性

审查结论： 总体优秀 (A-)，架构逻辑清晰，但 R 服务工程化细节存在隐患，需在开发前修正。

1. 架构层面的潜在风险 (Architecture Risks)

1.1 R 服务并发瓶颈 (The Single-Threaded Bottleneck)

现状：设计采用同步 HTTP (Plumber) 调用 R。
问题：R 是单线程的。虽然 MVP 限制了数据量，但如果 SAE 实例配置为单进程，当一个 T 检验正在计算（耗时 2秒）时，第二个请求会被阻塞。如果并发量稍大（如 20 人同时点击），请求会排队导致超时。
建议：
1. SAE 弹性策略：必须配置 SAE 的自动扩容策略（例如 CPU > 60% 或并发数 > 5 时扩容）。
2. Plumber 配置：在生产环境，建议使用 future 包或在 Docker 中配置多个 R Worker 进程（利用 pm2 或类似工具管理多个 R 进程端口，前端 Nginx 做负载均衡），而不仅仅依赖 SAE 的容器级扩容。

1.2 "网络隔离"与"OSS下载"的矛盾

现状：
- 架构文档提到：R 容器配置 Egress Deny（禁止外网）。
- 数据协议提到：R 服务需要从 OSS 下载大于 1MB 的文件。
问题：如果 OSS 是公网 Endpoint，配置 Egress Deny 后 R 服务将无法下载数据，导致系统瘫痪。
建议：
- 务必使用阿里云 OSS 的 VPC 内网 Endpoint（oss-cn-beijing-internal.aliyuncs.com）。
- 网络策略应配置为：Deny All Public Internet，但 Allow VPC Internal Traffic。

1.3 临时文件堆积 (Storage Leak)

现状：R 服务会生成临时图片 (tempfile) 和下载 OSS 数据。
问题：文档中未提及清理策略。长期运行后，/tmp 目录会爆满，导致 Docker 容器崩溃。
建议：
- 在 plumber.R 中添加 on.exit(unlink(tmp_files)) 逻辑。
- 或者在 Docker 启动脚本中添加定时清理任务（Cron）。

2. R 工程化细节审查 (R Engineering Review)

2.1 代码生成方式过于脆弱 (Fragile Code Gen)

现状：02-R服务开发指南.md 中使用 code_lines <- c(..., paste0(...)) 进行字符串拼接。
问题：
- 这种硬编码方式非常难以维护。一旦需要修改代码模板，很容易拼错引号或括号。
- 生成的代码缺乏缩进和格式化，用户下载后可读性差。
建议：
- 引入 模板引擎（如 R 的 glue 包或 whisker）。
- 将代码模板存为独立的 .R 模板文件（如 templates/t_test.R.template），运行时读取并填充参数。
- 强力推荐：使用 styler 包在生成代码后自动美化格式。

2.2 依赖包管理的隐患 (Dependency Hell)

现状：Dockerfile 中通过 install.packages 安装了一堆包。
问题：100 个工具可能依赖 50+ 个包。如果不锁定版本，下个月重新构建镜像时，某个包升级（如 ggplot2 API 变动）可能导致整个服务挂掉。
建议：
- 使用 renv 进行包管理。生成 renv.lock 文件，确保生产环境安装的包版本与开发环境完全一致。
- 或者使用 RStudio Public Package Manager (P3M) 的快照日期源（已在指南中提及，需严格执行）。

2.3 错误处理的颗粒度

现状：Wrapper 使用 tryCatch 捕获所有错误并返回 message。
问题：R 的报错信息（如 object 'x' not found）对 LLM 来说可能不够明确，或者包含了系统路径等敏感信息。
建议：
- 在 Wrapper 中区分 "业务错误"（如列名不存在、数据类型不对）和 "系统错误"。
- 对于业务错误，返回特定的 error_code，方便 Planner 进行针对性的参数自愈。

3. 后端逻辑审查 (Backend Review)

3.1 LLM 生成 JSON 的稳定性

现状：依赖 Prompt 让 LLM 输出 JSON。
问题：DeepSeek 虽然强，但偶尔也会输出 Markdown 包裹的 JSON，或者 JSON 格式错误（如末尾多逗号）。单纯的 JSON.parse 很容易挂。
建议：
- 引入 json-repair 库或使用正则表达式提取 JSON 块。
- 或者使用 Structured Output (JSON Mode) 如果模型支持。
- 增加一层 Schema Validation (Zod)：在收到 LLM 的 Plan 后，先用 Zod 校验参数结构是否符合 tools_library 中的定义，如果不符合，直接触发重试，不要发给 R。

3.2 数据 Schema 提取的隐私风险

现状：DataParserService 计算数值列的 Min/Max/Mean。
问题：对于罕见病或小样本数据（N<10），极值（Min/Max）可能导致患者身份泄露（如：年龄=102岁）。
建议：
- 增加 隐私阈值：如果行数 < 10，不计算 Min/Max，或者进行模糊化处理（如向下取整）。

4. 前端交互审查 (Frontend Review)

4.1 大图与多图渲染

现状：R 返回 Base64 图片。
问题：如果图片很大（高DPI），或者一次返回 10 张图（如相关性矩阵拆解），Base64 字符串会极大，导致 HTTP 响应慢，且前端卡顿。
建议：
- 对于复杂图表，R 服务应将图片上传到 OSS，返回 URL 而不是 Base64。
- Base64 仅限于 MVP 阶段的小图预览。

4.2 长连接与超时

现状：同步 HTTP，超时 60s。
问题：虽然大部分 T 检验很快，但如果是 Bootstrap 或 MCMC，很容易超过 60s。前端 Nginx 或浏览器可能会提前断开连接。
建议：
- 前端 axios 请求需显式设置 timeout: 120000 (2分钟)。
- 增加 "正在计算..." 的动态文案（如：正在进行第 500 次置换检验...），这需要 R 支持流式日志输出（SSE），但在同步架构下较难实现。MVP 阶段至少要有一个假的进度条动画，缓解焦虑。

5. 补充的任务清单 (Missing Items)

在当前的开发计划中，缺少以下关键任务，建议补充进 Phase 2 或 3：

🔍 审计日志查看器：后台管理端（ADMIN）需要一个界面查看 execution_logs，方便运营人员排查 AI 为什么规划错了。
🧹 自动清理任务：编写 CronJob，定期清理 R 容器的 /tmp 和 OSS 中的临时数据文件（24小时过期）。
📊 资源监控：在运营看板中增加 R 服务的内存/CPU 监控，防止内存泄漏导致的 OOM。
📚 帮助文档生成：不仅是 R 代码生成 JSON，还需要一个脚本将 R 的注释自动生成前端可见的“工具说明书”，展示在 Chat 的侧边栏或悬停提示中。

6. 最终修订建议

请研发团队在开工前，重点落实以下 3 点变更：

R 代码生成：放弃 paste0 拼接，改用 glue 模板技术。
网络配置：确认 SAE 与 OSS 的内网连通性，配置精确的 ACL。
JSON 容错：后端增加 LLM 输出的 JSON 修复与 Zod 强校验层。

7.3 KiB Raw Blame History Unescape Escape