# 工具C MVP开发 - To-do List

> **文档版本**：v1.0  
> **创建日期**：2025-12-06  
> **预计工期**：3周（15个工作日）  
> **参考文档**：[工具C_MVP开发计划_V1.0.md](./工具C_MVP开发计划_V1.0.md)

---

## 📊 整体进度概览

| 阶段 | 任务数 | 已完成 | 进行中 | 待开始 | 完成率 |
|------|-------|-------|-------|-------|--------|
| **Week 1: 基础架构** | 12 | 0 | 0 | 12 | 0% |
| **Week 2: 核心功能** | 10 | 0 | 0 | 10 | 0% |
| **Week 3: 测试优化** | 8 | 0 | 0 | 8 | 0% |
| **总计** | **30** | **0** | **0** | **30** | **0%** |

---

## 🎯 核心里程碑（必须完成）

- [ ] **M1**：Python代码执行环境搭建完成（Day 1）
- [ ] **M2**：AI生成代码能力验证通过（Day 7）
- [ ] **M3**：基础场景成功率 > 90%（Day 12）
- [ ] **M4**：总体成功率 > 80%（Day 15）

---

## 📅 Week 1：基础架构搭建（Day 1-5）

### Day 1：Python服务扩展 + 环境验证 ⭐

#### Python微服务扩展
- [ ] **P0** 创建 `extraction_service/services/dc_executor.py`
  - [ ] 实现 `validate_code(code)` - AST静态检查
  - [ ] 实现 `execute_pandas_code(data, code)` - 代码执行
  - [ ] 添加危险模块黑名单（os、sys、subprocess等）
  - [ ] 添加超时保护（30秒）
  - [ ] 添加异常捕获和错误消息
  
- [ ] **P0** 扩展 `extraction_service/main.py`
  - [ ] 添加 `POST /api/dc/execute` 端点
  - [ ] 添加 `POST /api/dc/validate` 端点
  - [ ] 添加请求日志记录
  - [ ] 添加错误处理中间件
  
- [ ] **P0** 测试Python服务
  - [ ] 启动服务：`cd extraction_service && venv\Scripts\activate && uvicorn main:app --reload`
  - [ ] 测试健康检查：`GET http://localhost:8000/api/health`
  - [ ] 测试代码验证：发送简单Pandas代码
  - [ ] 测试代码执行：发送真实数据+代码
  - [ ] 验证AST拦截：发送危险代码（如 `import os`）

#### Node.js后端集成
- [ ] **P0** 创建后端文件夹结构
  ```
  backend/src/modules/dc/tool-c/
  ├── services/
  │   ├── SessionService.ts         # Session管理
  │   ├── AICodeService.ts          # AI代码生成
  │   ├── PythonExecutorService.ts  # Python执行（新增）
  │   └── DataProcessService.ts     # 数据处理
  ├── controllers/
  │   └── ToolCController.ts        # HTTP控制器
  ├── routes/
  │   └── index.ts                  # 路由定义
  └── utils/
      └── codeValidator.ts          # 前置验证
  ```

- [ ] **P0** 实现 `PythonExecutorService.ts`
  - [ ] 实现 `executeCode(data, code)` 方法
  - [ ] 实现 `validateCode(code)` 方法
  - [ ] 添加超时控制（30秒）
  - [ ] 添加日志记录（复用 `@/common/logging`）
  - [ ] 添加错误处理和重试机制

- [ ] **P1** 环境变量配置
  - [ ] 添加 `EXTRACTION_SERVICE_URL=http://localhost:8000` 到 `.env`
  - [ ] 验证环境变量加载

#### 验收标准
- [ ] Python服务能成功执行简单Pandas代码（如 `df['age'] > 60`）
- [ ] AST检查能拦截危险代码（如 `import os`）
- [ ] Node.js能成功调用Python服务并获取结果
- [ ] 所有日志正常输出到控制台

---

### Day 2：数据库 + Session管理

#### 数据库Schema设计
- [ ] **P0** 创建Prisma Schema（`prisma/schema.prisma`）
  ```prisma
  // @@schema("dc")
  model DcToolCSession {
    id            String    @id @default(uuid())
    userId        String
    fileName      String
    fileKey       String    // OSS存储key
    totalRows     Int
    totalCols     Int
    columns       Json      // 列名数组
    encoding      String?   // 编码格式
    createdAt     DateTime  @default(now())
    updatedAt     DateTime  @updatedAt
    
    @@index([userId])
    @@map("dc_tool_c_sessions")
  }
  ```

- [ ] **P0** 执行数据库迁移
  ```bash
  npx prisma db push
  npx prisma generate
  ```

- [ ] **P1** 验证表创建成功
  ```sql
  SELECT * FROM dc.dc_tool_c_sessions LIMIT 1;
  ```

#### SessionService实现
- [ ] **P0** 实现 `SessionService.ts`
  - [ ] `createSession(userId, fileName, fileBuffer)` - 创建会话
    - [ ] 上传Excel到OSS（复用 `storage.uploadBuffer`）
    - [ ] 解析Excel到JSON（使用xlsx库）
    - [ ] 保存元数据到数据库（prisma）
  - [ ] `getSession(sessionId)` - 获取会话
    - [ ] 从数据库读取元数据
    - [ ] 从OSS下载数据（如需要）
  - [ ] `deleteSession(sessionId)` - 删除会话
    - [ ] 删除OSS文件
    - [ ] 删除数据库记录

- [ ] **P1** 添加Excel解析逻辑
  - [ ] 使用 `xlsx` 库读取Excel
  - [ ] 转换为JSON格式（数组对象）
  - [ ] 检测编码（中文支持）
  - [ ] 提取列名和数据类型

#### 验收标准
- [ ] 能成功上传10MB以内的Excel文件
- [ ] 数据正确保存到OSS（零落盘）
- [ ] Session元数据正确存储到数据库
- [ ] 能通过sessionId检索到完整数据

---

### Day 3：AI代码生成服务

#### AICodeService实现
- [ ] **P0** 实现 `AICodeService.ts`
  - [ ] 集成LLMFactory（复用 `@/common/llm`）
  - [ ] 实现 `generateCode(prompt, dataContext)` 方法
    - [ ] 构建System Prompt（包含10个Few-shot示例）
    - [ ] 注入数据上下文（行数、列名、样本数据）
    - [ ] 调用LLM生成代码
    - [ ] 提取纯代码（去除Markdown格式）
  - [ ] 实现 `fixCode(originalCode, errorMsg, dataContext)` 方法
    - [ ] AI自我修复逻辑
    - [ ] 最多重试1次

- [ ] **P0** System Prompt设计
  - [ ] 基础场景示例（5个）
  - [ ] 中等场景示例（3个）
  - [ ] 高级场景示例（2个）
  - [ ] 安全规范说明
  - [ ] 输出格式要求

- [ ] **P1** 代码提取逻辑
  - [ ] 识别 ` ```python ... ``` ` 格式
  - [ ] 识别纯代码格式
  - [ ] 去除注释和说明

#### 验收标准
- [ ] AI能生成正确的Pandas代码（基础场景）
- [ ] 生成的代码符合安全规范（无危险导入）
- [ ] 能正确处理中文列名
- [ ] 代码提取准确率 > 95%

---

### Day 4：前端基础框架

#### 前端文件夹结构
- [ ] **P0** 创建前端目录
  ```
  frontend-v2/src/modules/dc/pages/tool-c/
  ├── index.tsx                # 主页面入口
  ├── components/
  │   ├── DataTable.tsx        # AG Grid数据表格
  │   ├── AICopilot.tsx        # AI对话侧边栏
  │   ├── FileUploader.tsx     # 文件上传
  │   ├── Toolbar.tsx          # 顶部工具栏
  │   └── ChatMessage.tsx      # 对话消息组件
  ├── hooks/
  │   ├── useSession.ts        # Session管理
  │   └── useAIChat.ts         # AI对话
  ├── types.ts                 # TypeScript类型定义
  └── api.ts                   # API封装
  ```

- [ ] **P0** 安装依赖
  ```bash
  cd frontend-v2
  npm install ag-grid-react ag-grid-community xlsx
  ```

#### 主页面布局
- [ ] **P0** 实现 `index.tsx`（主布局）
  - [ ] 左侧：数据表格区域（70%宽度）
  - [ ] 右侧：AI Copilot侧边栏（30%宽度）
  - [ ] 顶部：扁平工具栏（文件上传、导出、撤销）
  - [ ] 状态管理：useState/useReducer

- [ ] **P1** 实现 `FileUploader.tsx`
  - [ ] 拖拽上传支持
  - [ ] 文件类型验证（仅Excel）
  - [ ] 文件大小限制（10MB）
  - [ ] 上传进度显示

#### 验收标准
- [ ] 页面布局正确（左表格右AI）
- [ ] 能成功上传Excel文件
- [ ] 上传后能看到加载状态
- [ ] 响应式布局（最小宽度1280px）

---

### Day 5：数据表格实现（AG Grid）

#### DataTable组件
- [ ] **P0** 实现 `DataTable.tsx`
  - [ ] 集成AG Grid
  - [ ] 动态列定义（根据Excel自动生成）
  - [ ] 单元格编辑功能
  - [ ] 脏数据标记（黄色高亮）
  - [ ] 分页支持（每页100行）

- [ ] **P1** 配置AG Grid主题
  - [ ] 使用 `ag-theme-alpine`
  - [ ] 自定义样式（Ant Design风格）
  - [ ] 列宽自适应

- [ ] **P1** 表格功能
  - [ ] 列排序
  - [ ] 列筛选
  - [ ] 行选择（多选）
  - [ ] 导出CSV（AG Grid内置）

#### 验收标准
- [ ] 能正确显示Excel数据（100行+）
- [ ] 列宽自适应且可手动调整
- [ ] 单元格编辑后有黄色标记
- [ ] 表格性能流畅（1000行不卡顿）

---

## 📅 Week 2：核心功能实现（Day 6-10）

### Day 6：AI对话UI

#### AICopilot组件
- [ ] **P0** 实现 `AICopilot.tsx`
  - [ ] 对话消息列表（滚动）
  - [ ] 输入框（多行，支持Enter发送）
  - [ ] 发送按钮
  - [ ] 加载状态（AI思考中...）

- [ ] **P0** 实现 `ChatMessage.tsx`
  - [ ] 用户消息（右对齐，蓝色）
  - [ ] AI消息（左对齐，灰色）
  - [ ] 代码块高亮（使用 `react-syntax-highlighter`）
  - [ ] 时间戳显示

- [ ] **P1** 消息历史管理
  - [ ] 保存到localStorage
  - [ ] 最多保存50条
  - [ ] 清空历史按钮

#### 验收标准
- [ ] 对话界面美观（参考原型设计）
- [ ] 消息发送/接收流畅
- [ ] 代码块正确高亮
- [ ] 滚动到最新消息

---

### Day 7：AI生成代码集成 ⭐

#### API集成
- [ ] **P0** 实现 `api.ts`
  - [ ] `uploadFile(file)` - 上传Excel
  - [ ] `sendMessage(sessionId, message)` - 发送AI消息
  - [ ] `executeCode(sessionId, code)` - 执行代码
  - [ ] `getSessionData(sessionId)` - 获取数据

- [ ] **P0** 后端API实现（`ToolCController.ts`）
  - [ ] `POST /api/v1/dc/tool-c/upload` - 文件上传
  - [ ] `POST /api/v1/dc/tool-c/chat` - AI对话
  - [ ] `POST /api/v1/dc/tool-c/execute` - 执行代码
  - [ ] `GET /api/v1/dc/tool-c/sessions/:id` - 获取会话

#### 业务逻辑实现
- [ ] **P0** 实现完整流程
  1. [ ] 用户发送消息 → AICodeService生成代码
  2. [ ] 前端展示生成的代码（Markdown格式）
  3. [ ] 用户点击"执行"按钮 → 调用Python服务
  4. [ ] 执行成功 → 刷新表格数据
  5. [ ] 执行失败 → AI自我修复 → 重试

- [ ] **P1** 错误处理
  - [ ] AST检查失败 → 提示用户
  - [ ] 执行超时（30秒） → 提示用户
  - [ ] AI生成失败 → 重试机制

#### 验收标准
- [ ] **基础场景测试（5个）成功率 > 90%**
  - [ ] "把年龄大于60的标记为老年组"
  - [ ] "删除所有患者ID为空的行"
  - [ ] "把性别转为数字，男1女0"
  - [ ] "计算BMI = 体重 / (身高/100)^2"
  - [ ] "删除缺失率超过50%的列"

---

### Day 8：UI锁定机制

#### 互斥锁实现
- [ ] **P0** 前端状态管理
  - [ ] 添加 `isAIProcessing` 状态
  - [ ] AI对话中 → 锁定表格编辑
  - [ ] 显示友好提示："AI正在处理，请稍候..."

- [ ] **P0** 表格锁定逻辑
  - [ ] `isAIProcessing=true` → AG Grid设置为只读
  - [ ] 禁用工具栏按钮（导出除外）
  - [ ] 显示半透明蒙层

- [ ] **P1** 视觉反馈
  - [ ] 表格半透明（opacity: 0.6）
  - [ ] 显示加载动画
  - [ ] 顶部显示进度条

#### 验收标准
- [ ] AI处理时，表格无法编辑
- [ ] 锁定状态有明显的视觉反馈
- [ ] AI完成后，表格自动解锁
- [ ] 用户体验流畅（无卡顿）

---

### Day 9：自动检查点（Checkpoint）

#### 数据快照管理
- [ ] **P0** 实现检查点逻辑
  - [ ] 每次AI执行成功 → 自动保存快照
  - [ ] 最多保存10个检查点
  - [ ] 快照数据存储到OSS（压缩JSON）

- [ ] **P0** 回滚功能
  - [ ] 工具栏添加"撤销"按钮
  - [ ] 点击撤销 → 恢复到上一个检查点
  - [ ] 最多支持10次撤销

- [ ] **P1** 检查点列表UI
  - [ ] 侧边栏显示检查点列表
  - [ ] 每个检查点显示：时间、操作描述
  - [ ] 点击检查点 → 恢复到该状态

#### 验收标准
- [ ] 每次AI操作后自动保存检查点
- [ ] 撤销功能正常工作
- [ ] 快照数据正确存储到OSS
- [ ] 10个检查点后，自动删除最旧的

---

### Day 10：Excel导出

#### 导出功能实现
- [ ] **P0** 后端导出API
  - [ ] `POST /api/v1/dc/tool-c/export/:sessionId`
  - [ ] 使用 `openpyxl`（Python）或 `xlsx`（Node.js）
  - [ ] 保留原始Excel格式（可选，MVP可跳过）

- [ ] **P0** 前端导出按钮
  - [ ] 工具栏添加"导出"按钮
  - [ ] 点击 → 下载Excel文件
  - [ ] 文件名：`原文件名_cleaned_YYYYMMDD.xlsx`

- [ ] **P1** 导出选项（可选）
  - [ ] 仅导出修改的行
  - [ ] 保留样式（复杂，可延后）

#### 验收标准
- [ ] 能成功导出Excel文件
- [ ] 导出的数据与表格一致
- [ ] 文件名正确
- [ ] 下载速度快（< 3秒）

---

## 📅 Week 3：测试优化（Day 11-15）

### Day 11：中等场景测试 🟡

#### 测试用例执行
- [ ] **P0** 准备测试数据
  - [ ] 创建测试Excel文件（包含多个列）
  - [ ] 包含真实医疗数据示例

- [ ] **P0** 中等场景测试（5个）
  1. [ ] "把诊断日期和出院日期计算天数差，如果出院日期早于诊断日期则标记为异常"
  2. [ ] "根据白细胞、中性粒细胞、淋巴细胞三个指标，计算NLR，并按2.5分为高低两组"
  3. [ ] "从病理报告列中提取TNM分期，生成新列"
  4. [ ] "把血压列的'120/80'格式拆分成收缩压和舒张压，并判断是否高血压"
  5. [ ] "删除重复的患者ID，保留最新的一条记录（根据就诊日期）"

#### 优化AI Prompt
- [ ] **P1** 根据失败案例优化Prompt
  - [ ] 增加错误处理示例
  - [ ] 强化中文列名处理
  - [ ] 增加边界情况说明

#### 验收标准
- [ ] **中等场景成功率 > 80%（4/5成功）**

---

### Day 12：高级场景测试 🔴

#### 高级场景测试（5个）
- [ ] **P0** 复杂场景测试
  1. [ ] "对于每个患者，找出第一次化疗日期和最后一次化疗日期，计算化疗持续时间"
  2. [ ] "生成生存状态和生存时间"（复杂条件逻辑）
  3. [ ] "根据ALT、AST、ALP、TBIL判断肝功能分级"
  4. [ ] "按患者ID分组，计算每次随访相比上次的肿瘤大小变化率"
  5. [ ] "根据入院时间，计算季节变量，统计不同季节的发病人数"

#### Prompt深度优化
- [ ] **P1** 针对失败场景优化
  - [ ] 增加分组聚合示例
  - [ ] 增加时间序列示例
  - [ ] 增加医学规则示例

#### 验收标准
- [ ] **高级场景成功率 > 60%（3/5成功）**
- [ ] **总体成功率 > 80%（12/15成功）**

---

### Day 13：性能优化

#### 性能测试
- [ ] **P1** 测试性能指标
  - [ ] 文件上传速度（10MB文件 < 5秒）
  - [ ] AI代码生成速度（< 10秒）
  - [ ] Python执行速度（< 5秒）
  - [ ] 表格刷新速度（< 2秒）
  - [ ] 端到端流程（< 20秒）

#### 优化措施
- [ ] **P1** 前端优化
  - [ ] AG Grid虚拟滚动
  - [ ] React.memo优化渲染
  - [ ] 防抖输入（debounce 300ms）

- [ ] **P1** 后端优化
  - [ ] 数据压缩（OSS上传前）
  - [ ] 缓存会话数据（Redis可选）
  - [ ] 并发控制（限制同时执行数）

#### 验收标准
- [ ] 端到端操作 < 20秒
- [ ] 1000行数据表格不卡顿
- [ ] 无内存泄漏

---

### Day 14：集成测试

#### 端到端测试
- [ ] **P0** 完整流程测试（10次）
  1. [ ] 上传Excel文件
  2. [ ] 查看数据表格
  3. [ ] 发送AI指令
  4. [ ] 执行生成的代码
  5. [ ] 验证表格刷新
  6. [ ] 测试撤销功能
  7. [ ] 导出Excel文件
  8. [ ] 验证导出数据正确

- [ ] **P1** 异常场景测试
  - [ ] 上传损坏的Excel文件
  - [ ] 发送空消息
  - [ ] 执行危险代码（应被拦截）
  - [ ] 网络断开恢复

#### Bug修复
- [ ] **P1** 修复测试中发现的问题
  - [ ] 记录所有bug到GitHub Issues
  - [ ] 按优先级修复（P0 > P1 > P2）

#### 验收标准
- [ ] 端到端流程100%通过
- [ ] 无P0级别bug
- [ ] P1级别bug < 3个

---

### Day 15：MVP验收 🎉

#### 最终验收测试
- [ ] **P0** 15个场景全覆盖测试
  - [ ] 基础场景：5/5 ✅
  - [ ] 中等场景：4/5 ✅
  - [ ] 高级场景：3/5 ✅
  - [ ] **总体成功率 > 80%**

- [ ] **P0** 非功能性验收
  - [ ] 性能：端到端 < 20秒 ✅
  - [ ] 安全：AST拦截危险代码 ✅
  - [ ] 稳定：10次测试无崩溃 ✅
  - [ ] 易用：用户能独立完成任务 ✅

#### 文档完善
- [ ] **P1** 更新文档
  - [ ] 用户使用手册
  - [ ] API接口文档
  - [ ] 部署指南
  - [ ] 已知问题清单

#### 验收决策
- [ ] ✅ **通过**：总体成功率 > 80%，进入下一阶段
- [ ] ❌ **失败**：总体成功率 < 60%，需要Pivot到模板库模式

---

## 🔥 每日站会检查清单

### 每天工作开始前
- [ ] 查看昨日遗留问题
- [ ] 确认今日任务清单
- [ ] 检查环境是否正常（Python服务、数据库、前端dev server）

### 每天工作结束前
- [ ] 更新To-do List进度
- [ ] 提交代码到Git（✅ 重要！防止丢失）
- [ ] 记录遇到的问题和解决方案
- [ ] 规划明日任务

---

## ⚠️ 风险提示

### 技术风险
1. **AI生成质量不稳定**
   - 缓解：多轮测试，优化Prompt
   - 备选：失败后人工编写模板

2. **Python执行安全问题**
   - 缓解：AST静态检查 + 超时控制
   - 备选：Docker沙箱隔离（Phase 2）

3. **性能不达标**
   - 缓解：分步优化，设定性能基准
   - 备选：降低数据量要求（10MB → 5MB）

### 进度风险
1. **AI生成成功率 < 60%**
   - 应对：紧急会议，决定是否Pivot

2. **前端开发延期**
   - 应对：简化UI，聚焦核心功能

---

## 📊 成功标准（最终验收）

| 指标 | 目标 | 当前 | 状态 |
|------|------|------|------|
| **基础场景成功率** | > 90% | 0% | 🔴 |
| **中等场景成功率** | > 80% | 0% | 🔴 |
| **高级场景成功率** | > 60% | 0% | 🔴 |
| **总体成功率** | > 80% | 0% | 🔴 |
| **端到端性能** | < 20秒 | 0秒 | 🔴 |
| **代码安全性** | 100%拦截 | 0% | 🔴 |

---

## 🎯 下一步行动（启动开发）

### 立即开始（Day 1）
1. **扩展Python服务**（2小时）
   ```bash
   cd AIclinicalresearch/extraction_service
   # 创建dc_executor.py
   # 扩展main.py添加2个端点
   # 测试服务
   ```

2. **创建后端文件夹**（1小时）
   ```bash
   cd AIclinicalresearch/backend/src/modules/dc
   mkdir -p tool-c/services tool-c/controllers tool-c/routes tool-c/utils
   ```

3. **实现PythonExecutorService**（2小时）
   - 编写代码
   - 单元测试
   - 集成测试

---

**准备好了吗？让我们开始Day 1的开发！** 🚀