AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/04-开发计划/工具C_MVP开发_TODO清单.md

工具C MVP开发 - To-do List

文档版本：v1.0
创建日期：2025-12-06
预计工期：3周（15个工作日）
参考文档：工具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）

  // @@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 执行数据库迁移

  npx prisma db push
  npx prisma generate
  

• P1 验证表创建成功

  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 安装依赖

  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小时）

   cd AIclinicalresearch/extraction_service
   # 创建dc_executor.py
   # 扩展main.py添加2个端点
   # 测试服务
   

2. 创建后端文件夹（1小时）

   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的开发！ 🚀