feat(dc/tool-c): 完成AI代码生成服务（Day 3 MVP）

核心功能： - 新增AICodeService（550行）：AI代码生成核心服务 - 新增AIController（257行）：4个API端点 - 新增dc_tool_c_ai_history表：存储对话历史 - 实现自我修正机制：最多3次智能重试 - 集成LLMFactory：复用通用能力层 - 10个Few-shot示例：覆盖Level 1-4场景技术优化： - 修复NaN序列化问题（Python端转None） - 修复数据传递问题（从Session获取真实数据） - 优化System Prompt（明确环境信息） - 调整Few-shot示例（移除import语句）测试结果： - 通过率：9/11（81.8%）达到MVP标准 - 成功场景：缺失值处理、编码、分箱、BMI、筛选、填补、统计、分类 - 待优化：数值清洗、智能去重（已记录技术债务TD-C-006） API端点： - POST /api/v1/dc/tool-c/ai/generate（生成代码） - POST /api/v1/dc/tool-c/ai/execute（执行代码） - POST /api/v1/dc/tool-c/ai/process（生成并执行，一步到位） - GET /api/v1/dc/tool-c/ai/history/:sessionId（对话历史）文档更新： - 新增Day 3开发完成总结（770行） - 新增复杂场景优化技术债务（TD-C-006） - 更新工具C当前状态文档 - 更新技术债务清单影响范围： - backend/src/modules/dc/tool-c/*（新增2个文件，更新1个文件） - backend/scripts/create-tool-c-ai-history-table.mjs（新增） - backend/prisma/schema.prisma（新增DcToolCAiHistory模型） - extraction_service/services/dc_executor.py（NaN序列化修复） - docs/03-业务模块/DC-数据清洗整理/*（5份文档更新） Breaking Changes: 无总代码行数：+950行 Refs: #Tool-C-Day3
2025-12-07 16:21:32 +08:00
parent 2348234013
commit f01981bf78
68 changed files with 6257 additions and 17 deletions
--- a/docs/03-业务模块/DC-数据清洗整理/04-开发计划/工具C_AI_Few-shot示例库.md
+++ b/docs/03-业务模块/DC-数据清洗整理/04-开发计划/工具C_AI_Few-shot示例库.md
@@ -0,0 +1,529 @@
+# 工具C - AI Copilot Few-shot示例库
+
+> **文档版本**: V1.0  
+> **创建日期**: 2025-12-06  
+> **用途**: System Prompt中的Few-shot示例  
+> **覆盖场景**: 从基础清洗到高级插补，10个核心场景
+
+---
+
+## 📋 示例总览
+
+| 编号 | 场景名称 | 级别 | 技术要点 | 医疗价值 |
+|------|---------|------|---------|---------|
+| 1 | 统一缺失值标记 | Level 1 | replace | 数据标准化 ⭐⭐⭐ |
+| 2 | 数值列清洗 | Level 1 | 正则+类型转换 | 检验值处理 ⭐⭐⭐⭐ |
+| 3 | 分类变量编码 | Level 2 | map | 统计建模 ⭐⭐⭐⭐⭐ |
+| 4 | 连续变量分箱 | Level 2 | cut | 分层分析 ⭐⭐⭐⭐ |
+| 5 | BMI计算与分类 | Level 3 | 公式+条件 | 临床指标 ⭐⭐⭐⭐⭐ |
+| 6 | 日期计算 | Level 3 | datetime | 时间间隔 ⭐⭐⭐⭐⭐ |
+| 7 | 条件筛选 | Level 3 | 多条件过滤 | 入组标准 ⭐⭐⭐⭐⭐ |
+| 8 | 简单缺失值填补 | Level 4 | fillna | 缺失处理 ⭐⭐⭐⭐ |
+| 9 | 多重插补(MICE) | Level 4 | IterativeImputer | 高级填补 ⭐⭐⭐⭐⭐ |
+| 10 | 智能去重 | Level 4 | sort+drop_duplicates | 数据质量 ⭐⭐⭐⭐ |
+
+---
+
+## 🎯 Level 1: 基础数据清洗（2个）
+
+### 示例1: 统一缺失值标记
+
+**用户指令**:
+```
+把所有代表缺失的符号（-、不详、NA、N/A）统一替换为标准空值
+```
+
+**AI生成代码**:
+```python
+# 统一缺失值标记
+df = df.replace(['-', '不详', 'NA', 'N/A', '\\', '未查'], np.nan)
+```
+
+**代码说明**:
+- 医疗数据常见多种缺失值表示方式
+- 统一为标准NaN便于后续统计分析
+- 适用场景: 数据清洗第一步
+
+**预期结果**:
+- 所有非标准缺失值标记被统一为NaN
+- 后续可使用isnull()等方法统一处理
+
+---
+
+### 示例2: 数值列清洗
+
+**用户指令**:
+```
+把肌酐列里的非数字符号去掉，<0.1按0.05处理，转为数值类型
+```
+
+**AI生成代码**:
+```python
+# 处理数值列的符号
+df['creatinine'] = df['creatinine'].astype(str).str.replace('>', '').str.replace('<', '')
+df.loc[df['creatinine'] == '0.1', 'creatinine'] = '0.05'
+df['creatinine'] = pd.to_numeric(df['creatinine'], errors='coerce')
+```
+
+**代码说明**:
+- 检验科导出数据常含符号（>、<、+等）
+- 需清理后才能进行数值计算和统计分析
+- errors='coerce'将无法转换的值设为NaN
+
+**预期结果**:
+- 肌酐列变为纯数值类型
+- 符号被正确处理
+- 异常值转为NaN
+
+**医疗场景**:
+- 检验报告：肌酐、白细胞、血红蛋白等
+- 常见符号：>100、<0.1、12.5+
+
+---
+
+## 🔧 Level 2: 变量编码与计算（2个）
+
+### 示例3: 分类变量编码
+
+**用户指令**:
+```
+把性别列转为数字，男=1，女=0
+```
+
+**AI生成代码**:
+```python
+# 性别编码
+df['gender_code'] = df['gender'].map({'男': 1, '女': 0})
+```
+
+**代码说明**:
+- 将文本分类变量转为数值
+- 便于Logistic回归、神经网络等建模
+- map方法简洁高效
+
+**预期结果**:
+- 新增gender_code列
+- 男→1, 女→0
+- 原gender列保持不变
+
+**扩展场景**:
+- 婚姻状态: 已婚=1, 未婚=0
+- 吸烟史: 是=1, 否=0
+- 教育程度: 小学=1, 初中=2, 高中=3, 大学=4
+
+---
+
+### 示例4: 连续变量分箱
+
+**用户指令**:
+```
+把年龄按18岁、60岁分为未成年、成年、老年三组
+```
+
+**AI生成代码**:
+```python
+# 年龄分组
+df['age_group'] = pd.cut(df['age'], 
+                         bins=[0, 18, 60, 120],
+                         labels=['未成年', '成年', '老年'],
+                         right=False)
+```
+
+**代码说明**:
+- 将连续变量离散化为有序分类变量
+- bins定义区间边界，labels定义标签
+- right=False表示左闭右开区间[0,18)
+
+**预期结果**:
+- 新增age_group列
+- 0-17岁→未成年
+- 18-59岁→成年
+- 60+岁→老年
+
+**医疗应用**:
+- 分层分析（各年龄段发病率）
+- 卡方检验（年龄组vs疾病）
+- 描述性统计（基线特征表）
+
+---
+
+## 🏥 Level 3: 医学计算与筛选（3个）
+
+### 示例5: BMI计算与分类
+
+**用户指令**:
+```
+根据身高(cm)和体重(kg)计算BMI，并标记BMI≥28为肥胖
+```
+
+**AI生成代码**:
+```python
+# 计算BMI
+df['BMI'] = df['weight'] / (df['height'] / 100) ** 2
+
+# 肥胖标记
+df['obesity'] = df['BMI'].apply(lambda x: '肥胖' if x >= 28 else '正常')
+```
+
+**代码说明**:
+- BMI公式: 体重(kg) / 身高(m)²
+- 中国标准: BMI≥28为肥胀
+- 向量化计算，无需循环
+
+**预期结果**:
+- 新增BMI列（数值）
+- 新增obesity列（分类）
+
+**临床标准**:
+- 偏瘦: BMI < 18.5
+- 正常: 18.5 ≤ BMI < 24
+- 超重: 24 ≤ BMI < 28
+- 肥胖: BMI ≥ 28
+
+**扩展场景**:
+- 体表面积(BSA): 化疗剂量计算
+- eGFR: 肾功能评估
+- APACHE评分: 危重症评估
+
+---
+
+### 示例6: 日期计算
+
+**用户指令**:
+```
+根据入院日期和出院日期计算住院天数
+```
+
+**AI生成代码**:
+```python
+# 计算住院天数
+df['admission_date'] = pd.to_datetime(df['admission_date'])
+df['discharge_date'] = pd.to_datetime(df['discharge_date'])
+df['length_of_stay'] = (df['discharge_date'] - df['admission_date']).dt.days
+```
+
+**代码说明**:
+- 先将日期列转为datetime类型
+- 日期相减得到Timedelta对象
+- .dt.days提取天数
+
+**预期结果**:
+- 新增length_of_stay列
+- 数值类型，单位为天
+
+**医疗应用**:
+- 住院天数分析
+- 平均住院日(ALOS)统计
+- 住院费用相关性分析
+
+**扩展场景**:
+- 计算年龄: (今天 - 出生日期) / 365.25
+- 随访时间: (随访日期 - 基线日期)
+- 生存时间: (死亡/末次随访 - 确诊日期)
+
+---
+
+### 示例7: 条件筛选（入组标准）
+
+**用户指令**:
+```
+筛选出年龄≥18岁、诊断为糖尿病、且血糖≥7.0的患者
+```
+
+**AI生成代码**:
+```python
+# 多条件筛选
+df_selected = df[
+    (df['age'] >= 18) & 
+    (df['diagnosis'] == '糖尿病') & 
+    (df['glucose'] >= 7.0)
+]
+```
+
+**代码说明**:
+- 布尔索引，多条件用&连接
+- 每个条件需加括号
+- 返回满足所有条件的行
+
+**预期结果**:
+- 新DataFrame，包含符合条件的病例
+- 原df不变
+
+**临床研究应用**:
+- 纳入标准筛选
+- 排除标准剔除
+- 亚组分析（如老年糖尿病患者）
+
+**扩展场景**:
+```python
+# 纳入标准
+included = df[
+    (df['age'] >= 18) & 
+    (df['age'] <= 75) &
+    (df['diagnosis'].isin(['肺腺癌', '肺鳞癌'])) &
+    (df['stage'].isin(['III', 'IV']))
+]
+
+# 排除标准
+excluded = df[
+    (df['pregnancy'] == 1) |  # 妊娠
+    (df['severe_liver'] == 1) |  # 严重肝病
+    (df['other_cancer'] == 1)  # 其他肿瘤
+]
+```
+
+---
+
+## 🔬 Level 4: 高级数据治理（3个）
+
+### 示例8: 简单缺失值填补
+
+**用户指令**:
+```
+用中位数填补BMI列的缺失值
+```
+
+**AI生成代码**:
+```python
+# 用中位数填补缺失值
+bmi_median = df['BMI'].median()
+df['BMI'] = df['BMI'].fillna(bmi_median)
+```
+
+**代码说明**:
+- median()计算中位数（排除NaN）
+- fillna()填补缺失值
+- 中位数受离群值影响小
+
+**预期结果**:
+- BMI列无缺失值
+- 缺失位置被中位数替代
+
+**填补方法选择**:
+| 方法 | 适用场景 | 优点 | 缺点 |
+|------|---------|------|------|
+| 均值 | 正态分布 | 简单 | 受离群值影响 |
+| 中位数 | 偏态分布 | 稳健 | 信息损失 |
+| 众数 | 分类变量 | 保留分布 | 可能不合理 |
+| 前向填充 | 时间序列 | 保留趋势 | 仅适用时序 |
+
+**注意事项**:
+- ⚠️ 仅适用于缺失率<5%
+- ⚠️ 假设缺失为MCAR（完全随机缺失）
+- ⚠️ 可能低估标准差
+
+---
+
+### 示例9: 多重插补（MICE）⭐ 核心场景
+
+**用户指令**:
+```
+使用多重插补法对BMI、年龄、肌酐列的缺失值进行填补
+```
+
+**AI生成代码**:
+```python
+from sklearn.experimental import enable_iterative_imputer
+from sklearn.impute import IterativeImputer
+
+# 选择需要插补的数值列
+cols = ['BMI', 'age', 'creatinine']
+
+# 多重插补
+imputer = IterativeImputer(max_iter=10, random_state=0)
+df[cols] = imputer.fit_transform(df[cols])
+```
+
+**代码说明**:
+- MICE (Multivariate Imputation by Chained Equations)
+- 利用变量间相关性预测缺失值
+- max_iter=10: 最多迭代10次
+- random_state=0: 可复现结果
+
+**算法原理**:
+1. 初始填补（如均值）
+2. 循环迭代：
+   - 对每个有缺失的变量，用其他变量预测
+   - 更新填补值
+3. 收敛后停止
+
+**适用场景**:
+- ✅ 缺失率5%-30%
+- ✅ 缺失机制为MAR（随机缺失）
+- ✅ 变量间存在相关性
+- ✅ 需要保持数据分布特征
+
+**优势**:
+- 利用变量间关系
+- 保持数据分布
+- 减少偏差
+- 统计学上更合理
+
+**vs 简单填补**:
+| 指标 | 简单填补 | 多重插补 |
+|------|---------|---------|
+| 复杂度 | 低 | 中等 |
+| 计算时间 | 快 | 较慢 |
+| 偏差 | 可能较大 | 较小 |
+| 标准误 | 低估 | 准确 |
+| 分布保持 | 差 | 好 |
+
+**注意事项**:
+- 仅适用于数值变量
+- 分类变量需先编码
+- 如有时间变量需先转换
+
+---
+
+### 示例10: 智能去重
+
+**用户指令**:
+```
+按患者ID去重，保留检查日期最新的记录
+```
+
+**AI生成代码**:
+```python
+# 智能去重：先按日期排序，再按ID去重保留最后一条
+df['check_date'] = pd.to_datetime(df['check_date'])
+df = df.sort_values('check_date').drop_duplicates(subset=['patient_id'], keep='last')
+```
+
+**代码说明**:
+- sort_values()先按日期升序排列
+- drop_duplicates()按patient_id去重
+- keep='last'保留最后一条（即最新日期）
+
+**预期结果**:
+- 每个患者只保留一条记录
+- 保留的是检查日期最新的那条
+
+**扩展场景**:
+
+**场景1: 保留数据最完整的记录**
+```python
+# 计算每行的完整度
+df['completeness'] = df.notna().sum(axis=1)
+df = df.sort_values('completeness', ascending=False).drop_duplicates(subset=['patient_id'], keep='first')
+```
+
+**场景2: 多字段组合去重**
+```python
+# 按患者ID+就诊日期去重
+df = df.drop_duplicates(subset=['patient_id', 'visit_date'], keep='first')
+```
+
+**场景3: 复杂逻辑去重**
+```python
+# 优先级：日期最新 > 完整度最高
+df = df.sort_values(['check_date', 'completeness'], ascending=[False, False]).drop_duplicates(subset=['patient_id'], keep='first')
+```
+
+**医疗场景**:
+- 删除重复录入的病例
+- 多次就诊取首次/末次
+- 检验结果去重（取最新）
+
+---
+
+## 📚 使用说明
+
+### System Prompt集成方式
+
+```python
+system_prompt = f"""
+你是医疗科研数据清洗专家，负责生成Pandas代码来清洗整理数据。
+
+## 当前数据集信息
+- 文件名: {session.fileName}
+- 行数: {session.totalRows}
+- 列数: {session.totalCols}
+- 列名: {', '.join(session.columns)}
+
+## 安全规则（强制）
+1. 只能操作df变量
+2. 禁止导入os、sys等危险模块
+3. 禁止使用eval、exec等危险函数
+4. 必须进行异常处理
+5. 返回格式: {{"code": "...", "explanation": "..."}}
+
+## Few-shot示例
+
+### 示例1: 统一缺失值标记
+用户: 把所有代表缺失的符号统一替换为标准空值
+代码:
+```python
+df = df.replace(['-', '不详', 'NA', 'N/A'], np.nan)
+```
+
+### 示例2: 数值列清洗
+用户: 把肌酐列里的非数字符号去掉，转为数值类型
+代码:
+```python
+df['creatinine'] = df['creatinine'].astype(str).str.replace('>', '').str.replace('<', '')
+df['creatinine'] = pd.to_numeric(df['creatinine'], errors='coerce')
+```
+
+[... 其他8个示例 ...]
+
+## 用户当前请求
+{user_message}
+
+请生成代码并解释。
+"""
+```
+
+---
+
+## 🎯 质量标准
+
+每个示例必须满足：
+- ✅ 代码可直接运行
+- ✅ 有详细注释
+- ✅ 有明确的输入输出
+- ✅ 符合Python最佳实践
+- ✅ 考虑异常情况
+- ✅ 有医疗场景说明
+
+---
+
+## 📊 测试用例设计
+
+基于这10个示例，Day 3测试应包含：
+
+**基础测试（4个）**:
+1. 示例1测试（缺失值统一）
+2. 示例2测试（数值清洗）
+3. 示例3测试（性别编码）
+4. 示例4测试（年龄分组）
+
+**中级测试（3个）**:
+5. 示例5测试（BMI计算）
+6. 示例6测试（住院天数）
+7. 示例7测试（条件筛选）
+
+**高级测试（3个）**:
+8. 示例8测试（中位数填补）
+9. 示例9测试（多重插补）⭐
+10. 示例10测试（智能去重）
+
+**扩展测试（5个）**:
+11. 混合场景测试（先清洗再计算）
+12. 错误场景测试（列不存在）
+13. 边界场景测试（全部缺失）
+14. 自我修正测试（代码报错后重试）
+15. 端到端测试（上传→AI处理→结果验证）
+
+---
+
+## 🔄 维护记录
+
+| 日期 | 版本 | 修改内容 | 修改人 |
+|------|------|---------|--------|
+| 2025-12-06 | V1.0 | 初始创建，10个核心示例 | AI Assistant |
+
+---
+
+**文档状态**: ✅ 已确认  
+**下一步**: 开始Day 3开发（AICodeService实现）
+