# **技术设计文档：工具 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 处理中”的全屏锁定交互�