AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/02-技术设计/技术设计文档：工具 C - 科研数据编辑器 (V7 云端沙箱抗风险版).md

技术设计文档：工具 C - 科研数据编辑器 (V7 云端沙箱抗风险版)

文档类型	Technical Design Document (TDD)
对应原型	工具C_科研数据编辑器_原型设计_V6_修复版.html
版本	V7.1 (完整收录架构决策 ADR 与红队风险对策)
状态	Final Standard
核心目标	构建一个高可靠的云端 Python 数据清洗平台。在保障“数据不出域”的前提下，通过 Apache Arrow 和样式分离技术，解决服务端执行带来的延迟与格式丢失问题。

1. 总体架构设计 (System Architecture)

鉴于文件大小限制 (<20MB) 和脱敏前提，采用 “Node.js BFF + Python Microservice” 架构。
V7 核心升级： 引入 Apache Arrow 作为前后端数据交换标准，替代低效的 Excel 文件反复读写，将单次交互延迟从 8s 降低至 0.5s。

1.1 架构拓扑图 (V7 优化版)

graph TD
subgraph Client_Layer [用户端]
ReactApp[React 19 + AG Grid]
ArrowClient[Apache Arrow JS]
end

subgraph Aliyun\_SAE \[阿里云 Serverless 应用引擎\]  
    BFF\[Node.js Web 服务 (Fastify)\]  
    PythonService\[Python 计算微服务 (FastAPI)\]  
end

subgraph Cache\_Layer \[高速缓存层\]  
    Redis\_Session\[Redis (存 DataFrame Arrow 序列化)\]  
end

subgraph AI\_PaaS \[AI 能力层\]  
    Dify\[Dify 编排引擎\]  
    DeepSeek\[DeepSeek-V3 模型\]  
end

subgraph Cloud\_Infra \[持久化层\]  
    OSS\[对象存储 (存 Excel 底板)\]  
    RDS\[RDS PostgreSQL (存元数据)\]  
end

%% 交互流  
User\[用户\] \--\>|1. 上传| BFF  
BFF \--\>|2. 存原始Excel| OSS  
BFF \--\>|3. 预热 Session| PythonService  
PythonService \--\>|4. 加载并转为 Arrow| Redis\_Session

User \--\>|5. AI 指令| Dify  
Dify \--\>|6. Python 代码| BFF  
BFF \--\>|7. 发送代码| PythonService  
  
PythonService \--\>|8. 读取 Arrow (内存)| Redis\_Session  
PythonService \--\>|9. Pandas 执行| PythonService  
PythonService \--\>|10. 写回 Arrow| Redis\_Session  
  
PythonService \--\>|11. 返回 Preview 数据 (JSON/Arrow)| ReactApp  
  
User \--\>|12. 导出/保存| BFF  
BFF \--\>|13. 触发合并| PythonService  
PythonService \--\>|14. 读OSS底板 \+ 填入数据| OSS

2. 关键架构决策记录 (ADR)

本节记录了为何从“前端 Pyodide”转向“后端沙箱”的决策过程，供团队参考。

决策点：前端运行 (WASM) vs 后端运行 (Server-side)

维度	方案 A：前端 Pyodide (WASM)	方案 B：后端 Python (本方案)	决策结论
启动延迟	极慢 (15s+)。需下载 ~20MB 引擎包，用户体验极差。	秒开。环境在服务器预热，即开即用。	后端胜
交互延迟	极快 (< 0.1s)。本地内存操作，无网络开销。	中等 (0.5s)。通过 Apache Arrow 优化后可接受。	前端胜
稳定性	高风险。浏览器 Tab 内存有限，易 OOM 崩溃。	高稳定。服务器内存充足，容器隔离，崩溃不影响前端。	后端胜
库支持	有限。不支持部分 C 扩展库 (如复杂统计库)。	无限。标准 Linux 环境，生态完整。	后端胜
开发难度	极高。需处理 JS-Python 通信、内存管理。	低。标准 Web API 开发。	后端胜

结论： 鉴于“数据已脱敏”且“文件较小”，后端执行方案 在稳定性、兼容性和开发成本上全面胜出。

3. 技术选型与融合 (Tech Stack Fusion)

3.1 核心组件更新

领域	选型	V7 新增理由
数据交换	Apache Arrow	关键升级。用于 Python 和 Node.js/前端之间的高性能数据传输，避免 JSON 序列化开销，解决 IO 延迟核心。
Excel 处理	openpyxl	替代纯 Pandas。用于在导出时保留原始 Excel 样式（如颜色、边框），解决格式丢失核心。
会话缓存	Redis	用于暂存用户的 DataFrame (序列化为 Parquet/Arrow)，避免每次操作都去 OSS 读文件。
计算服务	FastAPI + Celery	引入 Celery 处理异步任务，防止长计算阻塞 HTTP 线程。

4. 逆向风险评估与对策 (Red Teaming Analysis)

本节详细记录了“红队测试”中发现的潜在致命风险及其工程化解决方案。

风险一：交互延迟的“体感崩塌”

• 逆向拷问： 每次 AI 操作都走 OSS 下载 -> Pandas 读取 -> 计算 -> 上传，单次耗时可能超过 8秒，用户无法忍受。
• V7 解决方案： Session 驻留模式 (Memory-Resident)
  1. 初始化： 用户上传 Excel 后，后端将其加载为 DataFrame，并序列化为 Arrow 格式存入 Redis (TTL 30min)。
  2. 增量交互： 前端发送指令，Python 从 Redis 读取 Arrow 数据（毫秒级），执行 Pandas 计算，将结果写回 Redis。
  3. 轻量反馈： 计算完成后，只返回 前 100 行预览数据 给前端 AG Grid 渲染。
  4. 效果： 耗时缩短至 0.5s - 1s。

风险二：Excel 格式丢失 (The Format Loss)

• 逆向拷问： Pandas 的 to_excel 会重置所有单元格样式，医生标注的颜色和批注会丢失。
• V7 解决方案： 底板分离策略 (Template Separation)
  1. 上传时： 将原始 Excel 标记为 "Style Template" (样式底板)，永久保存在 OSS。
  2. 计算时： 只在内存/Redis 中处理纯数据 (Values)，不关心样式。
  3. 导出时： 使用 openpyxl 加载“样式底板”，将内存中的新数据填入到底板的对应坐标中，保留未修改区域的背景色和批注。

风险三：状态同步的“双写冲突”

• 逆向拷问： 用户手动修改了第 5 行，同时 AI 删除了第 5 行，导致数据状态不一致。
• V7 解决方案： UI 互斥锁 (UI Locking)
  • 当 AI 正在生成代码或后端正在计算时，AG Grid 强制进入 readOnly 模式，并在界面显示 "AI 正在处理..." 遮罩，物理层面上禁止并发操作。

风险四：安全沙箱逃逸

• 逆向拷问： AI 生成了 import os; os.system('rm -rf /')。
• V7 解决方案： AST 静态分析 + 容器隔离
  • 预检： 在执行 exec() 前，使用 Python ast 模块扫描代码树，检测到 import os 等关键词直接抛出异常。
  • 资源限额： 使用 Python resource 模块限制单次执行的 CPU 时间 (10s) 和 内存 (1GB)。

5. 数据库设计 (元数据层)

新增 TaskAudit 表用于记录每一次 AI 操作的上下文，便于回滚和审计。

model TaskAudit {
id String @id @default(uuid())
datasetId String
version Int // 操作后的版本号

actionType String // "AI_CODE" or "MANUAL_EDIT"
prompt String? // 用户的自然语言指令
code String? // AI 生成的 Python 代码

executionTime Int // 执行耗时 (ms)
status String // SUCCESS / FAILED

createdAt DateTime @default(now())
}

6. API 接口定义 (V7 优化)

• POST /api/session/init: 上传文件，初始化 Redis Session，返回 sessionId。
• POST /api/session/execute:
  • Input: { sessionId, code, version }
  • Output: { previewData: ArrowBase64, newVersion: int, logs: string }
  • 说明: 仅返回预览数据，不生成 Excel 文件。
• POST /api/session/save:
  • Input: { sessionId }
  • Output: { downloadUrl }
  • 说明: 触发 openpyxl 合并逻辑，生成最终 Excel 并上传 OSS。

7. 开发分工建议

• Python 组 (重中之重):
  • 实现 Arrow <-> Pandas 的序列化逻辑。
  • 封装 openpyxl 的样式回填逻辑。
  • 搭建 FastAPI + Redis 环境。
• Node.js 组:
  • 负责 Dify 转发和鉴权。
• 前端组:
  • 集成 apache-arrow JS 库，解析后端返回的二进制流并在 AG Grid 展示。
  • 实现“AI 处理中”的全屏锁定交互。