HaHafeng
8be741cd52
Summary: - Update Tool C MVP Development Plan (V1.3) * Clarify Python execution as core feature * Add 15 real medical data cleaning scenarios (basic/medium/advanced) * Enhance System Prompt with 10 Few-shot examples * Discover existing Python service (extraction_service) * Update to extend existing service instead of rebuilding - Create Tool C MVP Development TODO List * 3-week plan with 30 tasks (Day 1-15) * 4 core milestones with clear acceptance criteria * Daily checklist and risk management * Detailed task breakdown for each day Key Changes: - Python service: Extend existing extraction_service instead of new setup - Test scenarios: 15 scenarios (5 basic + 5 medium + 5 advanced) - Success criteria: Basic >90%, Medium >80%, Advanced >60%, Total >80% - Development time: Reduced from 3 weeks to 2 weeks (reuse infrastructure) Status: Planning complete, ready to start Day 1 development
164 lines
8.3 KiB
Markdown
164 lines
8.3 KiB
Markdown
# **技术设计文档：工具 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 处理中”的全屏锁定交互。 |