feat(dc/tool-c): Day 2 - Session管理与数据处理完成
核心功能: - 数据库: 创建dc_tool_c_sessions表 (12字段, 3索引) - 服务层: SessionService (383行), DataProcessService (303行) - 控制器: SessionController (300行, 6个API端点) - 路由: 新增6个Session管理路由 - 测试: 7个API测试全部通过 (100%) 技术亮点: - 零落盘架构: Excel内存解析, OSS存储 - Session管理: 10分钟过期, 心跳延长机制 - 云原生规范: storage/logger/prisma全平台复用 - 完整测试: 上传/预览/完整数据/删除/心跳 文件清单: - backend/prisma/schema.prisma (新增DcToolCSession模型) - backend/prisma/migrations/create_tool_c_session.sql - backend/scripts/create-tool-c-table.mjs - backend/src/modules/dc/tool-c/services/ (SessionService, DataProcessService) - backend/src/modules/dc/tool-c/controllers/SessionController.ts - backend/src/modules/dc/tool-c/routes/index.ts - backend/test-tool-c-day2.mjs - docs/03-业务模块/DC-数据清洗整理/00-工具C当前状态与开发指南.md - docs/03-业务模块/DC-数据清洗整理/06-开发记录/2025-12-06_工具C_Day2开发完成总结.md 代码统计: ~1900行 测试结果: 7/7 通过 (100%) 云原生规范: 完全符合
This commit is contained in:
765
docs/03-业务模块/DC-数据清洗整理/00-工具C当前状态与开发指南.md
Normal file
765
docs/03-业务模块/DC-数据清洗整理/00-工具C当前状态与开发指南.md
Normal file
@@ -0,0 +1,765 @@
|
||||
# 工具C（Tool C）- 科研数据编辑器 - 当前状态与开发指南
|
||||
|
||||
> **最后更新**: 2025-12-06
|
||||
> **当前版本**: Day 2 MVP开发完成
|
||||
> **开发进度**: Python微服务 ✅ | Session管理 ✅ | AI代码生成 ⏸️ | 前端开发 ⏸️
|
||||
|
||||
---
|
||||
|
||||
## 📊 模块整体进度
|
||||
|
||||
| 组件 | 进度 | 代码行数 | 状态 |
|
||||
|------|------|---------|------|
|
||||
| **Python微服务** | 100% | ~450行 | ✅ Day 1完成 |
|
||||
| **Node.js后端** | 40% | ~1700行 | 🟡 Day 2完成 |
|
||||
| **前端界面** | 0% | 0行 | ⏸️ 未开始 |
|
||||
| **数据库Schema** | 100% | 1表 | ✅ Day 2完成 |
|
||||
| **总体进度** | **25%** | **~2150行** | 🟡 **MVP阶段** |
|
||||
|
||||
---
|
||||
|
||||
## ✅ 已完成功能（Day 1-2）
|
||||
|
||||
### Day 1: Python微服务扩展 ✅
|
||||
|
||||
---
|
||||
|
||||
### 1. Python微服务扩展
|
||||
|
||||
#### 文件结构
|
||||
```
|
||||
extraction_service/
|
||||
├── services/
|
||||
│ └── dc_executor.py # 427行 ✅ 新增
|
||||
├── main.py # 617行（新增2个端点）✅
|
||||
├── test_module.py # 27行（测试脚本）✅
|
||||
├── quick_test.py # 64行（快速测试）✅
|
||||
└── test_execute_simple.py # 51行（简单测试）✅
|
||||
```
|
||||
|
||||
#### 核心功能
|
||||
|
||||
**1.1 AST静态代码检查** ✅
|
||||
- **模块**: `dc_executor.py::validate_code()`
|
||||
- **功能**:
|
||||
- 解析Python代码的抽象语法树（AST）
|
||||
- 检测危险模块导入（os, sys, subprocess等）
|
||||
- 检测危险函数调用（eval, exec, open等）
|
||||
- 检测是否操作df变量
|
||||
- **安全黑名单**:
|
||||
```python
|
||||
DANGEROUS_MODULES = {
|
||||
'os', 'sys', 'subprocess', 'shutil', 'glob',
|
||||
'socket', 'urllib', 'requests', 'http',
|
||||
'pickle', 'shelve', 'dbm',
|
||||
'importlib', '__import__',
|
||||
'eval', 'exec', 'compile',
|
||||
'open', 'input', 'file',
|
||||
}
|
||||
|
||||
DANGEROUS_BUILTINS = {
|
||||
'eval', 'exec', 'compile', '__import__',
|
||||
'open', 'input', 'file',
|
||||
'getattr', 'setattr', 'delattr',
|
||||
'globals', 'locals', 'vars',
|
||||
}
|
||||
```
|
||||
|
||||
**1.2 Pandas代码沙箱执行** ✅
|
||||
- **模块**: `dc_executor.py::execute_pandas_code()`
|
||||
- **功能**:
|
||||
- 创建安全的执行环境（限制可用函数）
|
||||
- 执行Pandas数据处理代码
|
||||
- 捕获print输出
|
||||
- 30秒超时保护
|
||||
- 返回执行结果和元数据
|
||||
- **安全措施**:
|
||||
- 限制可用内置函数（仅允许安全函数如len, range等）
|
||||
- 禁止文件操作
|
||||
- 禁止网络访问
|
||||
- 禁止系统调用
|
||||
- 超时自动终止（Unix系统）
|
||||
|
||||
**1.3 FastAPI端点** ✅
|
||||
- **端点1**: `POST /api/dc/validate`
|
||||
- 功能：代码安全验证
|
||||
- 请求：`{"code": "..."}`
|
||||
- 响应：`{"valid": bool, "errors": [], "warnings": []}`
|
||||
|
||||
- **端点2**: `POST /api/dc/execute`
|
||||
- 功能：Pandas代码执行
|
||||
- 请求：`{"data": [...], "code": "..."}`
|
||||
- 响应：`{"success": bool, "result_data": [...], "output": "", ...}`
|
||||
|
||||
#### 测试验证结果
|
||||
|
||||
✅ **测试1：正常代码执行**
|
||||
```python
|
||||
# 输入
|
||||
data = [{"age": 25}, {"age": 65}, {"age": 45}]
|
||||
code = "df['old'] = df['age'] > 60"
|
||||
|
||||
# 输出
|
||||
{
|
||||
"success": true,
|
||||
"result_data": [
|
||||
{"age": 25, "old": false},
|
||||
{"age": 65, "old": true},
|
||||
{"age": 45, "old": false}
|
||||
],
|
||||
"execution_time": 0.004,
|
||||
"result_shape": [3, 2]
|
||||
}
|
||||
```
|
||||
|
||||
✅ **测试2：危险代码拦截**
|
||||
```python
|
||||
# 输入
|
||||
code = "import os"
|
||||
|
||||
# 输出
|
||||
{
|
||||
"valid": false,
|
||||
"errors": ["🚫 禁止导入危险模块: os (行 1)"],
|
||||
"warnings": ["⚠️ 代码中未使用 df 变量，可能无法操作数据"]
|
||||
}
|
||||
```
|
||||
|
||||
✅ **测试3：医疗数据清洗**
|
||||
```python
|
||||
# 输入
|
||||
data = [
|
||||
{"patient_id": "P001", "age": 25, "sbp": 120, "dbp": 80},
|
||||
{"patient_id": "P002", "age": 65, "sbp": 150, "dbp": 95},
|
||||
{"patient_id": "P003", "age": None, "sbp": 160, "dbp": 100}
|
||||
]
|
||||
code = """
|
||||
import numpy as np
|
||||
df['age'] = df['age'].apply(lambda x: np.nan if x is None or x > 120 else x)
|
||||
df['hypertension'] = df.apply(
|
||||
lambda row: '高血压' if row['sbp'] >= 140 or row['dbp'] >= 90 else '正常',
|
||||
axis=1
|
||||
)
|
||||
"""
|
||||
|
||||
# 输出
|
||||
{
|
||||
"success": true,
|
||||
"result_data": [
|
||||
{"patient_id": "P001", "age": 25, "sbp": 120, "dbp": 80, "hypertension": "正常"},
|
||||
{"patient_id": "P002", "age": 65, "sbp": 150, "dbp": 95, "hypertension": "高血压"},
|
||||
{"patient_id": "P003", "age": null, "sbp": 160, "dbp": 100, "hypertension": "高血压"}
|
||||
],
|
||||
"execution_time": 0.008
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Day 2: Session管理 + 数据处理 ✅
|
||||
|
||||
#### 文件结构（新增）
|
||||
```
|
||||
backend/src/modules/dc/tool-c/
|
||||
├── services/
|
||||
│ ├── PythonExecutorService.ts # 177行 ✅ Day 1
|
||||
│ ├── SessionService.ts # 383行 ✅ Day 2 新增
|
||||
│ └── DataProcessService.ts # 303行 ✅ Day 2 新增
|
||||
├── controllers/
|
||||
│ ├── TestController.ts # 131行 ✅ Day 1
|
||||
│ └── SessionController.ts # 300行 ✅ Day 2 新增
|
||||
└── routes/
|
||||
└── index.ts # 62行 ✅ Day 2 更新
|
||||
```
|
||||
|
||||
#### 核心功能
|
||||
|
||||
**2.1 SessionService** ✅
|
||||
- **功能**: Session生命周期管理
|
||||
- **方法**:
|
||||
```typescript
|
||||
class SessionService {
|
||||
createSession(userId, fileName, buffer): Promise<SessionData>
|
||||
getSession(sessionId): Promise<SessionData>
|
||||
getPreviewData(sessionId): Promise<PreviewDataResponse>
|
||||
getFullData(sessionId): Promise<any[]>
|
||||
deleteSession(sessionId): Promise<void>
|
||||
updateHeartbeat(sessionId): Promise<Date>
|
||||
cleanExpiredSessions(): Promise<number>
|
||||
}
|
||||
```
|
||||
- **特性**:
|
||||
- ✅ 零落盘：Excel内存解析，直接上传OSS
|
||||
- ✅ 10分钟过期机制
|
||||
- ✅ 心跳延长功能
|
||||
- ✅ 自动清理过期Session
|
||||
- ✅ 完整的错误处理
|
||||
|
||||
**2.2 DataProcessService** ✅
|
||||
- **功能**: Excel文件解析和验证
|
||||
- **方法**:
|
||||
```typescript
|
||||
class DataProcessService {
|
||||
parseExcel(buffer): ParsedExcelData
|
||||
validateFile(buffer, fileName): ValidationResult
|
||||
inferColumnTypes(data): ColumnType[]
|
||||
formatFileSize(bytes): string
|
||||
}
|
||||
```
|
||||
- **特性**:
|
||||
- ✅ 内存解析（零落盘）
|
||||
- ✅ 10MB文件大小限制
|
||||
- ✅ 支持.xlsx, .xls, .csv
|
||||
- ✅ 列类型推断（可选）
|
||||
|
||||
**2.3 SessionController** ✅
|
||||
- **功能**: Session管理API端点
|
||||
- **端点**:
|
||||
- `POST /sessions/upload` - 上传Excel创建Session ✅
|
||||
- `GET /sessions/:id` - 获取Session信息 ✅
|
||||
- `GET /sessions/:id/preview` - 获取预览数据（前100行）✅
|
||||
- `GET /sessions/:id/full` - 获取完整数据 ✅
|
||||
- `DELETE /sessions/:id` - 删除Session ✅
|
||||
- `POST /sessions/:id/heartbeat` - 更新心跳 ✅
|
||||
|
||||
**2.4 数据库表** ✅
|
||||
- **表名**: `dc_schema.dc_tool_c_sessions`
|
||||
- **字段**: 12个（id, user_id, file_name, file_key, total_rows, total_cols, columns, encoding, file_size, created_at, updated_at, expires_at）
|
||||
- **索引**: 3个（主键 + user_id + expires_at）
|
||||
- **迁移脚本**: `backend/scripts/create-tool-c-table.mjs`
|
||||
|
||||
#### API测试结果（Day 2）
|
||||
|
||||
✅ **测试数据**:
|
||||
```
|
||||
文件名: test-medical-data.xlsx
|
||||
数据: 8行 x 7列医疗数据
|
||||
列名: patient_id, name, age, gender, diagnosis, sbp, dbp
|
||||
文件大小: 17.42 KB
|
||||
```
|
||||
|
||||
✅ **测试结果**:
|
||||
| 测试项 | 状态 | 说明 |
|
||||
|--------|------|------|
|
||||
| 上传文件创建Session | ✅ | 返回201，Session创建成功 |
|
||||
| 获取Session信息 | ✅ | 元数据正确返回 |
|
||||
| 获取预览数据（前100行）| ✅ | 8行数据全部返回 |
|
||||
| 获取完整数据 | ✅ | 从OSS读取成功 |
|
||||
| 更新心跳 | ✅ | 过期时间延长10分钟 |
|
||||
| 删除Session | ✅ | OSS+DB清理成功 |
|
||||
| 验证删除 | ✅ | 返回404确认删除 |
|
||||
| **总计** | **7/7 (100%)** | **所有测试通过** |
|
||||
|
||||
✅ **云原生规范检查**:
|
||||
- ✅ 使用 `storage` 服务（零落盘）
|
||||
- ✅ 使用 `logger` 服务（结构化日志）
|
||||
- ✅ 使用 `prisma` 全局实例
|
||||
- ✅ Excel内存解析，无本地文件存储
|
||||
- ✅ 无硬编码配置
|
||||
|
||||
---
|
||||
|
||||
### 2. Node.js后端集成（Day 1）
|
||||
|
||||
#### 文件结构
|
||||
```
|
||||
backend/src/modules/dc/tool-c/
|
||||
├── services/
|
||||
│ └── PythonExecutorService.ts # 177行 ✅ 新增
|
||||
├── controllers/
|
||||
│ └── TestController.ts # 131行 ✅ 新增
|
||||
├── routes/
|
||||
│ └── index.ts # 29行 ✅ 新增
|
||||
└── README.md # 172行（技术文档）✅
|
||||
```
|
||||
|
||||
#### 核心服务
|
||||
|
||||
**2.1 PythonExecutorService** ✅
|
||||
- **功能**: 封装Python微服务HTTP调用
|
||||
- **方法**:
|
||||
```typescript
|
||||
class PythonExecutorService {
|
||||
validateCode(code: string): Promise<ValidateCodeResponse>
|
||||
executeCode(data: any[], code: string): Promise<ExecuteCodeResponse>
|
||||
healthCheck(): Promise<boolean>
|
||||
}
|
||||
```
|
||||
- **特性**:
|
||||
- 完整的错误处理和重试机制
|
||||
- 30秒超时控制
|
||||
- 连接状态检测
|
||||
- 详细的日志记录
|
||||
|
||||
**2.2 TestController** ✅
|
||||
- **功能**: Day 1测试端点控制器
|
||||
- **端点**:
|
||||
- `GET /test/health` - 测试Python服务健康
|
||||
- `POST /test/validate` - 测试代码验证
|
||||
- `POST /test/execute` - 测试代码执行
|
||||
|
||||
**2.3 路由注册** ✅
|
||||
- **前缀**: `/api/v1/dc/tool-c`
|
||||
- **状态**: 已在 `dc/index.ts` 中注册
|
||||
- **可访问**: ✅ 服务启动后即可调用
|
||||
|
||||
---
|
||||
|
||||
## ⏸️ 待开发功能（Day 2-15）
|
||||
|
||||
### Week 1: 基础架构（Day 2-5）
|
||||
|
||||
#### Day 2: 数据库 + Session管理 ✅
|
||||
|
||||
**数据库Schema**（已创建）:
|
||||
```prisma
|
||||
// dc_tool_c_sessions 表 ✅
|
||||
model DcToolCSession {
|
||||
id String @id @default(uuid())
|
||||
userId String
|
||||
fileName String
|
||||
fileKey String // OSS存储key
|
||||
totalRows Int
|
||||
totalCols Int
|
||||
columns Json // 列名数组
|
||||
encoding String? // 编码格式
|
||||
fileSize Int
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
expiresAt DateTime // 过期时间
|
||||
|
||||
@@index([userId])
|
||||
@@index([expiresAt])
|
||||
@@map("dc_tool_c_sessions")
|
||||
@@schema("dc_schema")
|
||||
}
|
||||
```
|
||||
|
||||
**已完成服务**:
|
||||
- [x] `SessionService.ts` - Session管理（383行）✅
|
||||
- [x] `createSession()` - 创建会话（上传Excel到OSS）
|
||||
- [x] `getSession()` - 获取会话元数据
|
||||
- [x] `getPreviewData()` - 获取预览数据（前100行）
|
||||
- [x] `getFullData()` - 获取完整数据（从OSS）
|
||||
- [x] `deleteSession()` - 删除会话（OSS+DB）
|
||||
- [x] `updateHeartbeat()` - 更新心跳（延长10分钟）
|
||||
- [x] `cleanExpiredSessions()` - 清理过期Session
|
||||
- [x] `DataProcessService.ts` - 数据处理（303行）✅
|
||||
- [x] Excel文件解析（xlsx库，内存解析）
|
||||
- [x] 文件验证（大小、格式、内容）
|
||||
- [x] 列类型推断（可选）
|
||||
- [x] 文件大小限制（10MB）
|
||||
- [x] `SessionController.ts` - Session控制器（300行）✅
|
||||
- [x] 6个API端点全部实现
|
||||
|
||||
#### Day 3: AI代码生成服务 ⏸️
|
||||
|
||||
**待开发服务**:
|
||||
- [ ] `AICodeService.ts` - AI代码生成
|
||||
- [ ] 集成LLMFactory
|
||||
- [ ] System Prompt设计（含10个Few-shot示例）
|
||||
- [ ] 代码生成和自我修正
|
||||
- [ ] 上下文管理（Session元数据）
|
||||
|
||||
**System Prompt要点**:
|
||||
```typescript
|
||||
const systemPrompt = `
|
||||
你是一个医疗科研数据清洗专家，负责生成Pandas代码。
|
||||
|
||||
数据集信息：
|
||||
- 文件名：${fileName}
|
||||
- 行数：${totalRows}
|
||||
- 列数：${totalCols}
|
||||
- 列名：${columns.join(', ')}
|
||||
|
||||
安全规则：
|
||||
1. 只能操作df变量
|
||||
2. 禁止导入os、sys等危险模块
|
||||
3. 禁止使用eval、exec等危险函数
|
||||
4. 必须进行异常处理
|
||||
|
||||
Few-shot示例：
|
||||
[示例1] 标记老年组
|
||||
用户: 把年龄大于60的标记为老年组
|
||||
代码: df['age_group'] = df['age'].apply(lambda x: '老年' if x > 60 else '非老年')
|
||||
...
|
||||
`;
|
||||
```
|
||||
|
||||
#### Day 3-5: AI代码生成和控制器 ⏸️
|
||||
|
||||
**待开发控制器**:
|
||||
- [ ] `AIController.ts`
|
||||
- [ ] POST `/ai/chat` - AI对话生成代码
|
||||
- [ ] POST `/ai/execute` - 执行AI生成的代码
|
||||
- [ ] GET `/ai/history/:sessionId` - 获取对话历史
|
||||
|
||||
**待开发服务**:
|
||||
- [ ] `AICodeService.ts` - AI代码生成
|
||||
- [ ] 集成LLMFactory
|
||||
- [ ] System Prompt设计（10个Few-shot）
|
||||
- [ ] 上下文管理
|
||||
- [ ] 自我修正机制
|
||||
|
||||
### Week 2: 前端开发（Day 6-10）
|
||||
|
||||
**待开发组件**:
|
||||
- [ ] `ToolCEditor.tsx` - 主编辑器页面
|
||||
- [ ] `DataGrid.tsx` - AG Grid数据表格
|
||||
- [ ] `AICopilot.tsx` - AI助手侧边栏
|
||||
- [ ] `FileUpload.tsx` - 文件上传组件
|
||||
- [ ] `CodeBlock.tsx` - 代码显示组件
|
||||
- [ ] `ActionCard.tsx` - AI操作卡片
|
||||
|
||||
### Week 3: 测试优化（Day 11-15）
|
||||
|
||||
**测试任务**:
|
||||
- [ ] 15个医疗数据清洗场景测试
|
||||
- [ ] 性能测试（10MB文件）
|
||||
- [ ] 并发测试（多用户）
|
||||
- [ ] 安全测试（代码沙箱）
|
||||
- [ ] UI/UX测试
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ 数据库状态
|
||||
|
||||
### 当前表结构
|
||||
|
||||
**dc_schema 中的表**:
|
||||
```sql
|
||||
-- Tool B相关表（已存在）
|
||||
dc_schema.dc_templates -- 预设模板 ✅
|
||||
dc_schema.dc_extraction_tasks -- 提取任务 ✅
|
||||
dc_schema.dc_extraction_items -- 提取记录 ✅
|
||||
dc_schema.dc_health_checks -- 健康检查 ✅
|
||||
|
||||
-- Tool C相关表
|
||||
dc_schema.dc_tool_c_sessions -- ✅ 已创建（Day 2）
|
||||
dc_schema.dc_tool_c_ai_history -- ⏸️ 待创建（Day 3）
|
||||
```
|
||||
|
||||
**创建方式**（已完成）:
|
||||
```bash
|
||||
# Day 2 已执行
|
||||
cd backend
|
||||
node scripts/create-tool-c-table.mjs # ✅ 成功
|
||||
npx prisma generate # ✅ 成功
|
||||
```
|
||||
|
||||
**表结构详情**:
|
||||
```sql
|
||||
-- dc_tool_c_sessions 表（12字段，3索引）
|
||||
CREATE TABLE dc_schema.dc_tool_c_sessions (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id VARCHAR(255),
|
||||
file_name VARCHAR(500),
|
||||
file_key VARCHAR(500), -- OSS路径
|
||||
total_rows INTEGER,
|
||||
total_cols INTEGER,
|
||||
columns JSONB, -- ["age", "gender", ...]
|
||||
encoding VARCHAR(50),
|
||||
file_size INTEGER,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
expires_at TIMESTAMP -- 10分钟过期
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 API端点清单
|
||||
|
||||
### Python微服务 (http://localhost:8000)
|
||||
|
||||
| 方法 | 端点 | 功能 | 状态 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| GET | `/api/health` | 健康检查 | ✅ | 检查服务状态 |
|
||||
| POST | `/api/dc/validate` | 代码验证 | ✅ | AST安全检查 |
|
||||
| POST | `/api/dc/execute` | 代码执行 | ✅ | Pandas代码执行 |
|
||||
|
||||
### Node.js后端 (http://localhost:3000)
|
||||
|
||||
#### 测试端点（Day 1）
|
||||
| 方法 | 端点 | 功能 | 状态 | 说明 |
|
||||
|------|------|------|------|------|
|
||||
| GET | `/api/v1/dc/tool-c/test/health` | 测试Python服务 | ✅ | Day 1测试用 |
|
||||
| POST | `/api/v1/dc/tool-c/test/validate` | 测试代码验证 | ✅ | Day 1测试用 |
|
||||
| POST | `/api/v1/dc/tool-c/test/execute` | 测试代码执行 | ✅ | Day 1测试用 |
|
||||
|
||||
#### Session管理端点（Day 2 已完成）✅
|
||||
| 方法 | 端点 | 功能 | 状态 | 测试 |
|
||||
|------|------|------|------|------|
|
||||
| POST | `/api/v1/dc/tool-c/sessions/upload` | 上传Excel | ✅ | 201 成功 |
|
||||
| GET | `/api/v1/dc/tool-c/sessions/:id` | 获取Session | ✅ | 200 成功 |
|
||||
| GET | `/api/v1/dc/tool-c/sessions/:id/preview` | 获取预览数据 | ✅ | 200 成功 |
|
||||
| GET | `/api/v1/dc/tool-c/sessions/:id/full` | 获取完整数据 | ✅ | 200 成功 |
|
||||
| DELETE | `/api/v1/dc/tool-c/sessions/:id` | 删除Session | ✅ | 200 成功 |
|
||||
| POST | `/api/v1/dc/tool-c/sessions/:id/heartbeat` | 心跳更新 | ✅ | 200 成功 |
|
||||
|
||||
#### AI功能端点（待开发）
|
||||
| 方法 | 端点 | 功能 | 状态 | 计划 |
|
||||
|------|------|------|------|------|
|
||||
| POST | `/api/v1/dc/tool-c/ai/chat` | AI对话生成代码 | ⏸️ | Day 3 |
|
||||
| POST | `/api/v1/dc/tool-c/ai/execute` | 执行AI代码 | ⏸️ | Day 3 |
|
||||
| GET | `/api/v1/dc/tool-c/ai/history/:sessionId` | 获取历史 | ⏸️ | Day 3 |
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 环境配置
|
||||
|
||||
### 必需环境变量
|
||||
|
||||
在 `backend/.env` 中配置：
|
||||
```bash
|
||||
# Python微服务地址（必需）
|
||||
EXTRACTION_SERVICE_URL=http://localhost:8000
|
||||
|
||||
# OSS存储（Day 2使用）
|
||||
OSS_REGION=your-region
|
||||
OSS_BUCKET=your-bucket
|
||||
OSS_ACCESS_KEY_ID=your-key-id
|
||||
OSS_ACCESS_KEY_SECRET=your-secret
|
||||
|
||||
# LLM配置（Day 3使用）
|
||||
LLM_PROVIDER=openai
|
||||
LLM_API_KEY=your-api-key
|
||||
LLM_MODEL=gpt-4
|
||||
```
|
||||
|
||||
### 服务启动顺序
|
||||
|
||||
1. **启动Python微服务** (必需)
|
||||
```bash
|
||||
cd extraction_service
|
||||
.\venv\Scripts\activate
|
||||
python main.py
|
||||
# 服务运行在 http://localhost:8000
|
||||
```
|
||||
|
||||
2. **启动Node.js后端** (必需)
|
||||
```bash
|
||||
cd backend
|
||||
npm run dev
|
||||
# 服务运行在 http://localhost:3000
|
||||
```
|
||||
|
||||
3. **启动前端** (Day 6后)
|
||||
```bash
|
||||
cd frontend-v2
|
||||
npm run dev
|
||||
# 服务运行在 http://localhost:5173
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 代码结构
|
||||
|
||||
### Python微服务
|
||||
```
|
||||
extraction_service/
|
||||
├── services/
|
||||
│ ├── dc_executor.py # DC代码执行模块 ✅
|
||||
│ ├── pdf_extractor.py # PDF提取
|
||||
│ ├── docx_extractor.py # Docx提取
|
||||
│ └── txt_extractor.py # Txt提取
|
||||
├── main.py # FastAPI主文件 ✅
|
||||
├── requirements.txt # Python依赖
|
||||
└── venv/ # 虚拟环境
|
||||
```
|
||||
|
||||
### Node.js后端
|
||||
```
|
||||
backend/src/modules/dc/tool-c/
|
||||
├── services/
|
||||
│ ├── PythonExecutorService.ts # Python调用服务 ✅
|
||||
│ ├── SessionService.ts # Session管理 ⏸️
|
||||
│ ├── AICodeService.ts # AI代码生成 ⏸️
|
||||
│ └── DataProcessService.ts # 数据处理 ⏸️
|
||||
├── controllers/
|
||||
│ ├── TestController.ts # 测试控制器 ✅
|
||||
│ ├── SessionController.ts # Session控制器 ⏸️
|
||||
│ └── AIController.ts # AI控制器 ⏸️
|
||||
├── routes/
|
||||
│ └── index.ts # 路由定义 ✅
|
||||
└── utils/
|
||||
└── (待添加)
|
||||
```
|
||||
|
||||
### 前端
|
||||
```
|
||||
frontend-v2/src/modules/dc/tool-c/
|
||||
├── pages/
|
||||
│ └── ToolCEditor.tsx # 主编辑器页面 ⏸️
|
||||
├── components/
|
||||
│ ├── DataGrid.tsx # AG Grid表格 ⏸️
|
||||
│ ├── AICopilot.tsx # AI助手 ⏸️
|
||||
│ ├── FileUpload.tsx # 文件上传 ⏸️
|
||||
│ └── CodeBlock.tsx # 代码块 ⏸️
|
||||
├── hooks/
|
||||
│ ├── useSession.ts # Session Hook ⏸️
|
||||
│ └── useAI.ts # AI Hook ⏸️
|
||||
└── types/
|
||||
└── index.ts # 类型定义 ⏸️
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 测试清单
|
||||
|
||||
### Day 1 测试（已完成）✅
|
||||
|
||||
- [x] Python服务健康检查
|
||||
- [x] AST代码验证（正常代码）
|
||||
- [x] AST代码验证（危险代码拦截）
|
||||
- [x] Pandas代码执行（简单场景）
|
||||
- [x] Pandas代码执行（医疗数据清洗）
|
||||
- [x] Node.js服务集成
|
||||
- [x] HTTP通信正常
|
||||
|
||||
### Day 2-15 测试（待执行）⏸️
|
||||
|
||||
#### 基础功能测试
|
||||
- [ ] Excel文件上传（<10MB）
|
||||
- [ ] 文件编码检测
|
||||
- [ ] Session创建和删除
|
||||
- [ ] OSS存储读写
|
||||
- [ ] 心跳机制
|
||||
|
||||
#### AI功能测试
|
||||
- [ ] LLM代码生成
|
||||
- [ ] 代码自我修正
|
||||
- [ ] Few-shot效果验证
|
||||
- [ ] 上下文理解准确性
|
||||
|
||||
#### 15个医疗数据清洗场景
|
||||
**基础场景（成功率>90%）**:
|
||||
- [ ] 场景1：标记老年组（age > 60）
|
||||
- [ ] 场景2：删除缺失患者ID的行
|
||||
- [ ] 场景3：性别编码（男1女0）
|
||||
- [ ] 场景4：计算BMI
|
||||
- [ ] 场景5：删除缺失率>50%的列
|
||||
|
||||
**中等场景（成功率>80%）**:
|
||||
- [ ] 场景6：血压分类（正常/高血压）
|
||||
- [ ] 场景7：计算住院天数
|
||||
- [ ] 场景8：删除重复患者ID
|
||||
- [ ] 场景9：清理异常年龄值（>120）
|
||||
- [ ] 场景10：按性别分组统计
|
||||
|
||||
**高级场景（成功率>60%）**:
|
||||
- [ ] 场景11：复杂分组聚合
|
||||
- [ ] 场景12：时间序列分析
|
||||
- [ ] 场景13：医学规则验证
|
||||
- [ ] 场景14：多列联合清洗
|
||||
- [ ] 场景15：缺失值智能填充
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 开发者快速上手
|
||||
|
||||
1. **启动Python微服务**
|
||||
```bash
|
||||
cd extraction_service
|
||||
.\venv\Scripts\activate
|
||||
python main.py
|
||||
```
|
||||
|
||||
2. **测试Python服务**
|
||||
```bash
|
||||
# PowerShell测试
|
||||
Invoke-WebRequest -Uri "http://localhost:8000/api/health"
|
||||
```
|
||||
|
||||
3. **启动Node.js后端**
|
||||
```bash
|
||||
cd backend
|
||||
npm install # 首次运行
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. **测试Node.js集成**
|
||||
```bash
|
||||
curl http://localhost:3000/api/v1/dc/tool-c/test/health
|
||||
```
|
||||
|
||||
### API调用示例
|
||||
|
||||
**代码验证**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/dc/tool-c/test/validate \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"code":"df[\"age_group\"] = df[\"age\"] > 60"}'
|
||||
```
|
||||
|
||||
**代码执行**:
|
||||
```bash
|
||||
curl -X POST http://localhost:3000/api/v1/dc/tool-c/test/execute \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"data": [{"age": 25}, {"age": 65}],
|
||||
"code": "df[\"old\"] = df[\"age\"] > 60"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 开发记录
|
||||
|
||||
| 日期 | 里程碑 | 详细记录 |
|
||||
|------|--------|---------|
|
||||
| 2025-12-06 | Day 1完成 | [2025-12-06_工具C_Day1开发完成总结.md](./06-开发记录/2025-12-06_工具C_Day1开发完成总结.md) |
|
||||
| 2025-12-06 | Day 2完成 | [2025-12-06_工具C_Day2开发完成总结.md](./06-开发记录/2025-12-06_工具C_Day2开发完成总结.md) |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 下一步行动
|
||||
|
||||
### 立即执行（Day 2）
|
||||
1. [ ] 创建 `dc_tool_c_sessions` 数据库表
|
||||
2. [ ] 实现 `SessionService.ts`
|
||||
3. [ ] 实现 `DataProcessService.ts`
|
||||
4. [ ] 集成OSS存储服务
|
||||
5. [ ] 创建 `SessionController.ts`
|
||||
|
||||
### 本周目标（Week 1）
|
||||
- [ ] 完成Session管理和数据处理
|
||||
- [ ] 完成AI代码生成服务
|
||||
- [ ] 完成后端所有API端点
|
||||
- [ ] 通过Postman测试所有API
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- **需求文档**: [PRD：Tool C - 科研数据编辑器 (MVP V1.1).md](./01-需求分析/PRD：Tool%20C%20-%20科研数据编辑器%20(MVP%20V1.1).md)
|
||||
- **技术设计**: [技术设计文档：工具 C - 科研数据编辑器 (V7 云端沙箱抗风险版).md](./02-技术设计/技术设计文档：工具%20C%20-%20科研数据编辑器%20(V7%20云端沙箱抗风险版).md)
|
||||
- **开发计划**: [工具C_MVP开发计划_V1.0.md](./04-开发计划/工具C_MVP开发计划_V1.0.md)
|
||||
- **TODO清单**: [工具C_MVP开发_TODO清单.md](./04-开发计划/工具C_MVP开发_TODO清单.md)
|
||||
- **UI原型**: [工具C_原型设计V6.html](./03-UI设计/工具C_原型设计V6%20.html)
|
||||
|
||||
---
|
||||
|
||||
## 🔐 安全说明
|
||||
|
||||
### 代码执行安全
|
||||
- ✅ AST静态检查拦截危险操作
|
||||
- ✅ 沙箱环境限制可用函数
|
||||
- ✅ 30秒超时保护
|
||||
- ✅ 禁止文件和网络操作
|
||||
- ⏸️ 资源使用限制（待实现）
|
||||
|
||||
### 数据安全
|
||||
- ✅ 10MB文件大小限制
|
||||
- ⏸️ OSS加密存储（待实现）
|
||||
- ⏸️ 10分钟Session过期（待实现）
|
||||
- ⏸️ 用户隔离（待实现）
|
||||
|
||||
---
|
||||
|
||||
**维护者**: AI Assistant
|
||||
**联系方式**: 请查看项目README
|
||||
**最后更新**: 2025-12-06
|
||||
|
||||
Reference in New Issue
Block a user