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

工具C MVP开发 - To-do List

文档版本：v1.4
创建日期：2025-12-06
最后更新：2025-12-10
预计工期：3周（15个工作日）
实际进度：Week 1-2完成，功能按钮Phase 1-2完成✅ + NA处理优化✅ + Pivot列顺序优化✅
参考文档：工具C_MVP开发计划_V1.0.md, 工具C_功能按钮开发计划_V1.0.md

---

📊 整体进度概览

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

最新更新：2025-12-08 16:00 功能按钮Phase 1-2完成 + 7个功能上线

---

🎉 最新进展（2025-12-10）

✅ 功能按钮开发（Phase 1-2）

7个核心功能已完成：

1. ✅ 高级筛选器（多条件AND/OR + 为空/不为空条件）
2. ✅ 数值映射（重编码 + NA处理选项：保持/映射/删除）
3. ✅ 生成分类变量（等宽/等频/自定义切点 + NA处理选项）
4. ✅ 条件生成列（IF-THEN-ELSE + 为空/不为空条件）
5. ✅ 删除缺失值（按行/列，阈值控制）
6. ✅ 计算列（方案B：安全列名映射，支持特殊字符列名）
7. ✅ Pivot转换（长表→宽表 + 保留未选列 + 原始列顺序）

技术架构：

• ✅ 预写Python函数架构（稳定、安全、高性能）
• ✅ 7个Python operations模块
• ✅ 7个API端点（/api/operations/*）
• ✅ 完整的前后端集成
• ✅ 友好的UI交互（Dialog + 实时验证）

✅ NA处理优化（2025-12-09~10）

4个功能支持空值处理：

1. ✅ 数值映射 - NA处理选项（保持NA/映射为指定值/删除行）
2. ✅ 高级筛选 - 为空/不为空条件（原有支持）
3. ✅ 生成分类变量 - NA处理选项（保持为空/标记为"缺失"/分配到指定组）
4. ✅ 条件生成列 - 为空/不为空运算符

✅ Pivot列顺序优化（2025-12-10）

• ✅ 保留未选择的列（可选功能）
• ✅ 未选列聚合方式（取第一个值/取众数/取均值）
• ✅ 保持原始列顺序（转换后列按原文件顺序排列）
• ✅ 透视列值按首次出现顺序排列

✅ UX优化（2025-12-09）

• ✅ 列头tooltip（鼠标悬停显示完整列名）
• ✅ 50行预览提示可关闭
• ✅ 页面滚动条优化（内部滚动，无整页滚动）

✅ 计算列方案B实施（2025-12-09）

• ✅ 前端安全列名映射（col_0, col_1...）
• ✅ 后端columnMapping存储和传递
• ✅ Python端使用columnMapping计算（支持特殊字符列名）

新增功能（2025-12-10下午）：

• ✅ 缺失值填补（6种方法：均值/中位数/众数/固定值/前向填充/后向填充）- 已开发
• 🚧 MICE多重插补 - 已集成，DataFrame shape问题待调试
• ✅ 自动精度检测 - 填补值自动匹配原始数据小数位数
• ✅ 分类列识别 - MICE自动跳过分类列并提示
• ✅ 功能按钮优化 - 移除"去重"和"多重插补"独立按钮，合并到"缺失值处理"
• ✅ 自动化测试脚本 - 18个测试用例（test_fillna_operations.py）

新增功能（2025-12-10晚上）- UX优化重大改进 ✅：

• ✅ 删除"前50行预览"提示条 - 用户体验优化
• ✅ 添加行号列 - 固定在表格左侧，灰色背景，#符号列头
• ✅ 列头筛选功能 - Excel风格，Community版本，中文本地化，显示唯一值及计数
• ✅ 全量数据加载 - 不再限制50行，筛选基于全量数据，结果精确
• ✅ 全量数据返回 - 所有快速操作（筛选/映射/分箱/条件/删NA/计算/Pivot）全量返回
• ✅ 滚动条终极修复 - 修改MainLayout为固定高度（h-screen），整个浏览器窗口无滚动条，只有AG Grid内部滚动
• ✅ 计算列全角字符修复 - 自动转换中文括号等全角字符
• ✅ 计算列特殊字符列名修复 - 完善列别名机制，支持任意特殊字符列名

当前状态：

• ✅ Tool C 整体完成度：98% - 核心功能全部完成，用户体验显著提升
• 📊 代码统计：Python ~1800行 + Node.js ~3500行 + 前端 ~4000行 + 通用Chat ~968行 = ~10268行

---

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

• M1：Python代码执行环境搭建完成（Day 1）✅ 2025-12-06
• M2：AI生成代码能力验证通过（Day 3）✅ 2025-12-07
• M3：前端MVP完成，端到端可用（Day 5）✅ 2025-12-07 完成！
• M4：总体成功率 > 80%（Day 6-7）⏸️ 待开始

---

🚀 最新进展（2025-12-07）

✅ 已完成

• Day 1 (2025-12-06): Python微服务扩展 ✅

  • dc_executor.py（427行）
  • AST安全检查 + Pandas执行
  • 测试通过率：100%

• Day 2 (2025-12-06): Session管理 + 数据处理 ✅

  • SessionService.ts（383行）
  • DataProcessService.ts（303行）
  • SessionController.ts（300行）
  • 数据库表：dc_tool_c_sessions
  • 测试通过率：100% (7/7 API)

• Day 3 (2025-12-07): AI代码生成服务 ✅

  • AICodeService.ts（550行）
  • AIController.ts（257行）
  • 数据库表：dc_tool_c_ai_history
  • 10个Few-shot示例
  • 自我修正机制（最多3次重试）
  • 测试通过率：81.8% (9/11场景)

• Day 4 (2025-12-07): 前端基础框架 ✅

  • index.tsx（258行）
  • Header + Toolbar + DataGrid (AG Grid)
  • Sidebar骨架
  • API封装（toolC.ts, 218行）
  • 路由配置完成
  • Portal启用Tool C

• Day 5 (2025-12-07): AI Chat面板完成 + Ant Design X 集成 ✅ 重大里程碑！

  • Ant Design 6.0 升级 ✅
  • @ant-design/x + x-sdk 集成 ✅
  • 通用 Chat 组件开发（~968行）✅
    • ChatContainer, MessageRenderer, CodeBlockRenderer
    • 完整类型定义和文档
  • Tool C 集成 ChatContainer ✅
  • 文件上传完整流程 ✅
  • API 完整对接 ✅
  • UI 优化（7个问题修复）✅
  • 端到端测试通过 ✅
  • 新增代码：~2100行

⏸️ 待开始

• Day 6-7: 优化与测试（成功率 > 80%）
• Day 8-10: 高级功能（撤销/重做、导出）
• Day 11-15: 全面测试与验收

---

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

Day 1：Python服务扩展 + 环境验证 ⭐ ✅ 已完成 2025-12-06

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服务 ✅

  • 启动服务 ✅
  • 测试健康检查 ✅
  • 测试代码验证 ✅
  • 测试代码执行 ✅
  • 验证AST拦截 ✅

Node.js后端集成

• P0 创建后端文件夹结构 ✅

• P0 实现 PythonExecutorService.ts ✅

  • 实现 executeCode(data, code) 方法 ✅
  • 实现 validateCode(code) 方法 ✅
  • 添加超时控制（30秒）✅
  • 添加日志记录 ✅
  • 添加错误处理和重试机制 ✅

• P1 环境变量配置 ✅

验收标准

• Python服务能成功执行简单Pandas代码 ✅
• AST检查能拦截危险代码 ✅
• Node.js能成功调用Python服务并获取结果 ✅
• 所有日志正常输出到控制台 ✅

---

Day 2：数据库 + Session管理 ✅ 已完成 2025-12-06

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