AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/00-工具C当前状态与开发指南.md

# 工具C（Tool C）- 科研数据编辑器 - 当前状态与开发指南

> **最后更新**: 2025-12-08 16:00  
> **当前版本**: Day 5-6 MVP + 功能按钮完成  
> **开发进度**: Python微服务 ✅ | Session管理 ✅ | AI代码生成 ✅ | 前端完整 ✅ | 通用组件 ✅ | 功能按钮✅（7个）

---

## 📊 模块整体进度

| 组件 | 进度 | 代码行数 | 状态 |
|------|------|---------|------|
| **Python微服务** | 100% | ~1500行 | ✅ Day 1完成 + Day 6扩展 |
| **Node.js后端** | 100% | ~3200行 | ✅ Day 2-3完成，Day 5-6增强 |
| **前端界面** | 95% | ~3500行 | ✅ Day 4-6完成 |
| **通用 Chat 组件** | 100% | ~968行 | ✅ Day 5完成（重大成就）|
| **功能按钮** | 87% | ~2300行 | ✅ Day 6完成7个功能 |
| **数据库Schema** | 100% | 2表 | ✅ Day 2-3完成 |
| **端到端测试** | 80% | - | ✅ 基础测试通过 |
| **总体进度** | **90%** | **~11468行** | ✅ **MVP + 功能按钮完成！** |

---

## ✅ 已完成功能（Day 1-6）

### 🚀 Day 6 功能按钮开发（2025-12-08）

#### 1. 预写Python函数架构 ✅
**重大架构重构**：从动态代码生成改为预写函数
- ✅ 创建 `extraction_service/operations/` 模块
- ✅ 7个预写函数文件（~1500行）
- ✅ 完整的类型注解和文档
- ✅ 严格的安全验证
- ✅ 智能类型转换（字符串→数值）

#### 2. 7个核心功能上线 ✅
| 功能 | Python函数 | 前端Dialog | 状态 |
|------|-----------|-----------|------|
| 高级筛选 | filter.py | FilterDialog.tsx | ✅ |
| 数值映射 | recode.py | RecodeDialog.tsx | ✅ |
| 生成分类变量 | binning.py | BinningDialog.tsx | ✅ |
| 条件生成列 | conditional.py | ConditionalDialog.tsx | ✅ |
| 删除缺失值 | dropna.py | DropnaDialog.tsx | ✅ |
| 计算列 | compute.py | ComputeDialog.tsx | ✅ |
| Pivot转换 | pivot.py | PivotDialog.tsx | ✅ |

#### 3. 问题修复与优化 ✅
- ✅ NaN序列化错误（统一处理）
- ✅ 自动类型转换（字符串数字→数值）
- ✅ 中英文逗号支持
- ✅ 分箱边界自动添加
- ✅ 列名特殊字符处理
- ✅ Ant Design警告修复

---

### 🎉 Day 5 重大成就（2025-12-07）

#### 1. Ant Design X 集成 ✅
- ✅ 升级到 Ant Design 6.0.1
- ✅ 安装 @ant-design/x (2.1.0) - UI 组件库
- ✅ 安装 @ant-design/x-sdk (2.1.0) - 数据流管理

#### 2. 前端通用能力层建设 ✅
创建 `frontend-v2/src/shared/components/Chat/`：
- ✅ ChatContainer.tsx（163行）- 核心容器组件
- ✅ MessageRenderer.tsx（64行）- 消息渲染器
- ✅ CodeBlockRenderer.tsx（71行）- 代码块渲染器
- ✅ types.ts（151行）- 完整类型定义
- ✅ chat.css（144行）- 样式文件
- ✅ README.md（297行）- 使用文档

**总计**：~968行，可复用于 AIA、PKB、Tool C 等模块

#### 3. Tool C MVP 完成 ✅
- ✅ 文件上传 → 显示数据表格
- ✅ AI 对话 → 生成代码
- ✅ 手动执行 → 更新表格
- ✅ 支持简单问答（不生成代码）
- ✅ UI 优化（7个问题修复）
- ✅ 端到端测试通过

---

### 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 3: AI代码生成服务 ✅

#### 文件结构（新增）
```
backend/src/modules/dc/tool-c/
├── services/
│   ├── PythonExecutorService.ts    # 177行 ✅ Day 1
│   ├── SessionService.ts           # 383行 ✅ Day 2
│   ├── DataProcessService.ts       # 303行 ✅ Day 2
│   └── AICodeService.ts            # 550行 ✅ Day 3 新增
├── controllers/
│   ├── TestController.ts           # 131行 ✅ Day 1
│   ├── SessionController.ts        # 300行 ✅ Day 2
│   └── AIController.ts             # 257行 ✅ Day 3 新增
└── routes/
    └── index.ts                    # 85行 ✅ Day 3 更新
```

#### 核心功能

**3.1 AICodeService** ✅
- **功能**: AI代码生成核心服务
- **方法**:
  ```typescript
  class AICodeService {
    generateCode(sessionId, userMessage): Promise<GenerateCodeResult>
    executeCode(sessionId, code, messageId): Promise<ExecuteCodeResult>
    generateAndExecute(sessionId, userMessage, maxRetries): Promise<ProcessResult>
    getHistory(sessionId, limit): Promise<Message[]>
  }
  ```
- **特性**:
  - ✅ 复用LLMFactory（通用能力层）
  - ✅ 10个Few-shot示例（Level 1-4）
  - ✅ 自我修正机制（最多3次重试）
  - ✅ 对话历史管理（最近5轮）
  - ✅ 从Session获取真实数据执行
  - ✅ 详细System Prompt（含环境说明）

**3.2 AIController** ✅
- **功能**: AI功能API端点
- **端点**:
  - `POST /ai/generate` - 生成代码（不执行）✅
  - `POST /ai/execute` - 执行代码 ✅
  - `POST /ai/process` - 生成并执行（一步到位）✅
  - `GET /ai/history/:sessionId` - 获取对话历史 ✅

**3.3 数据库表** ✅
- **表名**: `dc_schema.dc_tool_c_ai_history`
- **字段**: 14个（id, session_id, user_id, role, content, generated_code, code_explanation, execute_status, execute_result, execute_error, retry_count, model, created_at）
- **索引**: 3个（主键 + session_id + user_id）
- **迁移脚本**: `backend/scripts/create-tool-c-ai-history-table.mjs`

#### AI功能测试结果（Day 3）

✅ **测试通过率**: 9/11 (81.8%) **达到MVP标准**

**成功场景（9个）：**
1. ✅ 统一缺失值标记
2. ✅ 分类变量编码
3. ✅ 连续变量分箱
4. ✅ BMI计算
5. ✅ 条件筛选
6. ✅ 缺失值填补
7. ✅ 统计汇总
8. ✅ 复杂分类
9. ✅ 对话历史获取

**待优化场景（2个，已记录技术债务TD-C-006）：**
1. ❌ 数值列清洗（复杂字符串处理）
2. ❌ 智能去重（日期解析+排序）

**关键修复：**
- ✅ NaN序列化问题（Python端转None）
- ✅ 数据传递问题（从Session获取真实数据）
- ✅ System Prompt优化（明确告知环境信息）
- ✅ Few-shot示例调整（移除import语句）

---

### Day 4: 前端基础框架 ✅

#### 文件结构（新增）
```
frontend-v2/src/modules/dc/pages/tool-c/
├── index.tsx                        # 258行 ✅ 主入口
├── components/
│   ├── Header.tsx                   # 91行 ✅ 顶部栏
│   ├── Toolbar.tsx                  # 104行 ✅ 工具栏
│   ├── DataGrid.tsx                 # 111行 ✅ AG Grid表格
│   ├── Sidebar.tsx                  # 149行 ✅ 右侧栏（简化版）
│   └── ag-grid-custom.css           # 113行 ✅ 自定义样式
├── types/
│   └── index.ts                     # 62行 ✅ 类型定义
api/
└── toolC.ts                         # 218行 ✅ API封装（6个方法）

总代码：~1106行
```

#### 核心功能

**4.1 AG Grid集成** ✅
- **组件**: DataGrid.tsx
- **版本**: AG Grid Community 31.0.0
- **功能**:
  - ✅ Excel风格表格渲染
  - ✅ 列排序、过滤、调整宽度
  - ✅ 缺失值高亮显示（红色）
  - ✅ 数值右对齐
  - ✅ 斑马纹背景
  - ✅ 空状态提示
  - ⏸️ 单元格编辑（Day 6）

**4.2 页面布局** ✅
- **主入口**: index.tsx
- **布局**: 左右分栏（flex布局）
  - 左侧：Toolbar + DataGrid（flex-1）
  - 右侧：Sidebar（固定420px宽度）
- **特性**:
  - ✅ 响应式高度（h-screen）
  - ✅ 溢出滚动控制
  - ✅ Emerald绿色主题

**4.3 API封装** ✅
- **文件**: api/toolC.ts
- **方法数**: 8个
  ```typescript
  // Session管理
  uploadFile(file)
  getSession(sessionId)
  getPreviewData(sessionId)
  updateHeartbeat(sessionId)
  
  // AI功能
  generateCode(sessionId, message)
  executeCode(sessionId, code, messageId)
  processMessage(sessionId, message)  // ⭐ 核心API
  getChatHistory(sessionId, limit)
  ```

**4.4 路由集成** ✅
- **路径**: `/data-cleaning/tool-c`
- **状态**: Portal已启用（status: 'ready'）
- **懒加载**: 使用React.lazy()
- **测试**: Portal卡片可点击进入

#### Day 4完成状态

✅ **基础框架100%完成**:
- ✅ Header（返回按钮、文件名、导出）
- ✅ Toolbar（7个快捷按钮、搜索框）
- ✅ DataGrid（AG Grid完整集成）
- ✅ Sidebar（骨架版本，待Day 5完善）
- ✅ API封装（8个方法）
- ✅ 路由配置（Portal → Tool C）

⏸️ **待Day 5完成**:
- ⏸️ MessageItem组件（消息渲染）
- ⏸️ CodeBlock组件（代码高亮）
- ⏸️ InputArea组件（输入框）
- ⏸️ InsightsPanel组件（数据洞察）
- ⏸️ 文件上传完整流程
- ⏸️ AI对话完整交互
- ⏸️ 端到端测试

---

### 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功能端点（Day 3已完成）✅
| 方法 | 端点 | 功能 | 状态 | 测试 |
|------|------|------|------|------|
| POST | `/api/v1/dc/tool-c/ai/generate` | 生成代码 | ✅ | ✅ 通过 |
| POST | `/api/v1/dc/tool-c/ai/execute` | 执行代码 | ✅ | ✅ 通过 |
| POST | `/api/v1/dc/tool-c/ai/process` | 生成并执行 | ✅ | ✅ 81.8%通过 |
| GET | `/api/v1/dc/tool-c/ai/history/:sessionId` | 获取历史 | ✅ | ✅ 通过 |

---

## ⚙️ 环境配置

### 必需环境变量

在 `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/pages/tool-c/
├── index.tsx                        # 258行 ✅ Day 4（主入口+状态管理）
├── components/
│   ├── Header.tsx                   # 91行 ✅ Day 4（顶部栏）
│   ├── Toolbar.tsx                  # 104行 ✅ Day 4（7个快捷按钮）
│   ├── DataGrid.tsx                 # 111行 ✅ Day 4（AG Grid表格）
│   ├── Sidebar.tsx                  # 149行 ✅ Day 4（骨架版）
│   ├── ag-grid-custom.css           # 113行 ✅ Day 4（Emerald主题）
│   ├── MessageItem.tsx              # ⏸️ Day 5（消息渲染）
│   ├── CodeBlock.tsx                # ⏸️ Day 5（代码高亮）
│   ├── InputArea.tsx                # ⏸️ Day 5（输入框）
│   └── InsightsPanel.tsx            # ⏸️ Day 5（数据洞察）
├── hooks/
│   └── useToolC.ts                  # ⏸️ Day 5（核心Hook，可选）
├── types/
│   └── index.ts                     # 62行 ✅ Day 4（类型定义）
└── (API封装在 ../../api/toolC.ts)   # 218行 ✅ Day 4（8个方法）

✅ Day 4完成：~1106行
⏸️ Day 5待完成：~400-600行（Chat组件）
```

---

## 🧪 测试清单

### 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) |
| 2025-12-07 | Day 3完成 | [2025-12-06_工具C_Day3开发完成总结.md](./06-开发记录/2025-12-06_工具C_Day3开发完成总结.md) ✅ **后端MVP完成** |
| 2025-12-07 | Day 4完成 | [2025-12-07_工具C_Day4前端基础完成.md](./06-开发记录/2025-12-07_工具C_Day4前端基础完成.md) ✅ **AG Grid集成** |
| 2025-12-07 | Day 5完成 | [2025-12-07_Day5_Ant-Design-X重构完成.md](./06-开发记录/2025-12-07_Day5_Ant-Design-X重构完成.md) ✅ **Ant Design X集成** |
| 2025-12-07 | UI优化 | [2025-12-07_完整UI优化与功能增强.md](./06-开发记录/2025-12-07_完整UI优化与功能增强.md) ✅ **7个问题修复** |

---

## 🎯 下一步行动

### ✅ Week 1 已完成（Day 1-5）
- [x] 完成Python微服务扩展 ✅
- [x] 完成Session管理和数据处理 ✅
- [x] 完成AI代码生成服务 ✅
- [x] 完成后端所有API端点 ✅
- [x] 完成前端基础框架 ✅
- [x] 完成AI Chat面板 ✅
- [x] 集成 Ant Design X ✅
- [x] 开发通用 Chat 组件 ✅
- [x] 端到端流程测试通过 ✅

### Week 2 计划（Day 6-10）
1. [ ] 优化 AI 代码生成质量（成功率 > 90%）
2. [ ] 实现撤销/重做功能
3. [ ] 实现 Excel 导出功能
4. [ ] 性能优化（大数据集）
5. [ ] 错误处理增强

---

## 📚 相关文档

- **需求文档**: [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