AIclinicalresearch/docs/03-业务模块/DC-数据清洗整理/07-技术债务/Tool-B技术债务清单.md

Tool B - 病历结构化机器人 技术债务清单

创建日期： 2025-12-03
状态： 待处理
优先级： P1=高优先级, P2=中优先级, P3=低优先级

---

📋 技术债务列表

[P1] #1 - Excel导出与前端显示结果不一致

问题描述：

• 用户在步骤4交叉验证页面看到的提取结果，与导出的Excel文件内容不一致
• 列顺序混乱，部分字段缺失或数据错位

重现步骤：

1. 完成双模型提取并进入步骤4
2. 点击"导出当前结果"或在步骤5点击"下载结果Excel"
3. 打开Excel，对比前端显示的结果

根本原因：

• JavaScript对象展开...extractedData时顺序不固定
• 未按模板定义的字段顺序构建Excel列

当前状态：

• ✅ 已部分修复：按targetFields顺序导出
• ❌ 仍需验证：多次导出结果是否稳定一致

解决方案：

1. 严格按照task.targetFields定义的字段顺序导出
2. 添加表头样式（加粗、冻结首行）
3. 添加数据验证（确保所有字段都存在）
4. 添加导出测试用例

预计工时： 2小时
影响范围： 后端 ExtractionController.exportResults方法

---

[P2] #2 - 步骤3进度条显示不够细腻

问题描述：

• 当前进度条直接从0%跳到100%，缺少中间过程
• 用户无法感知大模型正在处理第几条记录
• 没有实时反馈当前处理状态（如"正在处理第3/9条"）

期望效果：

提取进度: 33% (3/9条已完成)

日志输出：
[13:43:12] 正在创建提取任务...
[13:43:12] 任务创建成功 (ID: xxx)
[13:43:12] 初始化双模型引擎 (DeepSeek-V3 & Qwen-Max)...
[13:43:13] [1/9] 正在提取: 【右肺下叶】浸润性腺癌...
[13:43:18] [1/9] ✅ 提取完成 (DeepSeek: 549 tokens, Qwen: 627 tokens)
[13:43:19] [2/9] 正在提取: 【右肺上叶】浸润性腺癌...
[13:43:24] [2/9] ✅ 提取完成 (DeepSeek: 486 tokens, Qwen: 551 tokens)
...
[13:43:30] PII 脱敏完成
[13:43:30] ✅ 所有记录提取完成！

解决方案：

后端改动：

1. 在DualModelExtractionService.batchExtract的for循环中，每处理完一条记录就更新进度
2. 添加currentItem字段到Task表（可选，用于实时显示当前处理的记录）
3. 或者使用Redis存储实时进度信息（更云原生）

前端改动：

1. 轮询API时，解析processedCount和totalCount
2. 动态生成日志：[${processedCount}/${totalCount}] 正在提取...
3. 进度条平滑过渡（CSS transition）

预计工时： 3小时
影响范围：

• 后端：DualModelExtractionService.batchExtract
• 前端：Step3Processing.tsx

---

[P1] #3 - Excel文件预处理与脏数据清洗

问题描述： 医疗科研场景下，Excel文件质量参差不齐，存在大量脏数据导致解析失败或结果错误。

子问题1：表头特殊字符

• 现象： 列名包含换行符\n、空格、制表符等，导致列名匹配失败
• 示例： "病人ID\n(Patient ID)" → 前端下拉框显示异常
• 影响： 用户无法选择正确的列

子问题2：公式 (Formulas)

• 现象： 单元格包含公式=A1+B1，xlsx库读取时返回公式文本而非计算结果
• 示例：
  • 原始值：=SUM(A1:A10)
  • 读取结果：字符串"=SUM(A1:A10)"（而非数字）
  • 外部引用：=[外部文件]Sheet1!A1 → #REF!
• 影响： 数值型字段（如年龄、血糖值）变成文本，无法统计

子问题3：合并单元格 (Merged Cells)

• 现象： 医生习惯合并"住院号"列，对应多行化验记录
• 示例：

  住院号    检查项目    结果
  H001     血常规      正常  ← 只有这行有住院号
  (合并)    肝功能      异常  ← 这行住院号为null
  (合并)    肾功能      正常  ← 这行住院号为null
  

• 影响： 后续行的关联字段丢失，无法追溯到患者

子问题4：日期地狱 (Date Parsing Hell)

• 现象： Excel日期存储为数字（Serial Number），或多种文本格式
• 示例：
  • 44927 → 应该解析为 2023-01-01
  • 2023.1.1（文本）
  • 2023年1月1日（中文）
  • Jan 1, 2023（英文）
• 影响： 日期字段无法排序、筛选、统计

子问题5：不可见字符与脏文本 (Ghost Characters)

• 现象： 看起来是"男"，实际包含不可见字符
• 示例：
  • "男 " (尾部空格)
  • "男\u200b" (零宽空格 Zero-Width Space)
  • "男\ufeff" (BOM字符)
• 影响： 条件判断失败：if (sex === '男') → false
• 医学场景特例：
  • 化验单复制粘贴时带入富文本格式
  • 不同医院HIS系统导出编码不统一

解决方案：

架构设计：独立的Excel预处理服务

// backend/src/modules/dc/services/ExcelPreprocessor.ts
export class ExcelPreprocessor {
  /**
   * 清洗表头
   */
  cleanHeaders(headers: string[]): string[] {
    return headers.map(h => h
      .replace(/[\n\r\t]/g, ' ')  // 移除换行、制表符
      .trim()                      // 去除首尾空格
      .replace(/\s+/g, ' ')        // 多个空格合并为一个
    );
  }
  
  /**
   * 处理公式单元格
   */
  processFormulas(worksheet: xlsx.WorkSheet): void {
    // 使用 xlsx 的 { cellFormula: false } 选项
    // 或手动遍历单元格，计算公式结果
  }
  
  /**
   * 展开合并单元格
   */
  unflattenMergedCells(worksheet: xlsx.WorkSheet): void {
    // 1. 找到所有合并区域 worksheet['!merges']
    // 2. 将主单元格的值填充到所有子单元格
  }
  
  /**
   * 统一日期格式
   */
  normalizeDates(value: any): string | null {
    if (typeof value === 'number') {
      // Excel Serial Number → ISO Date
      return this.excelSerialToDate(value);
    }
    if (typeof value === 'string') {
      // 尝试多种格式解析
      return this.parseChineseDate(value) || 
             this.parseSlashDate(value) ||
             this.parseDotDate(value);
    }
    return null;
  }
  
  /**
   * 清除不可见字符
   */
  cleanInvisibleChars(text: string): string {
    return text
      .replace(/\u200b/g, '')     // 零宽空格
      .replace(/\ufeff/g, '')     // BOM
      .replace(/\u00a0/g, ' ')    // 不间断空格 → 普通空格
      .trim();
  }
}

使用位置：

1. uploadFile API - 上传后立即预处理，返回清洗后的列名
2. healthCheck API - 使用清洗后的数据进行检查
3. createTask API - 使用清洗后的数据创建items

预计工时： 16小时（复杂度高，需要大量测试）
影响范围：

• 新增：ExcelPreprocessor.ts (~400行)
• 修改：ExtractionController.ts 的文件处理逻辑
• 测试：覆盖各种脏数据场景

依赖：

• xlsx库的高级功能（cellFormula、!merges等）
• dayjs或date-fns（日期解析）

---

[P2] #4 - 支持用户自定义提取模板

问题描述： 当前系统只支持3个预设模板（肺癌病理、糖尿病入院、高血压门诊），无法满足用户的多样化需求。

需求场景：

1. 科研人员研究罕见病（如：系统性红斑狼疮、重症肌无力）
2. 需要提取的字段与预设模板不同
3. 每个研究项目的数据规范可能不同

期望功能：

1. 前端：自定义模板编辑器

步骤2.1：选择模板来源
- [ ] 使用系统预设模板
- [x] 创建自定义模板

步骤2.2：定义模板信息
- 模板名称：[我的肺癌研究模板]
- 疾病类型：[自定义：系统性红斑狼疮]
- 报告类型：[自定义：实验室检查]

步骤2.3：定义提取字段（可视化编辑）
┌─────────────────────────────────────┐
│ 字段1: [抗核抗体滴度]               │
│ 描述:  [如 1:320, 1:640]            │
│ 宽度:  [w-32] ▼                     │
│ [ 删除 ]                            │
├─────────────────────────────────────┤
│ 字段2: [补体C3]                     │
│ 描述:  [单位g/L]                    │
│ [ 删除 ]                            │
└─────────────────────────────────────┘
[+ 添加字段]

步骤2.4：AI生成Prompt（自动化）
[ 🤖 让AI帮我生成提示词 ]

后台自动生成：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
你是一名风湿免疫科专家。请从以下系统性红斑狼疮
患者的实验室检查报告中提取关键信息。

提取字段（必须返回以下所有字段）：
- 抗核抗体滴度：如 1:320, 1:640
- 补体C3：单位g/L

**输出格式：严格的JSON格式：**
```json
{
  "抗核抗体滴度": "...",
  "补体C3": "..."
}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ 编辑Prompt ] [ 预览效果 ] [ 保存模板 ]

#### **2. 后端：模板管理API**
```typescript
// 新增API端点
POST   /api/v1/dc/tool-b/templates          // 创建自定义模板
PUT    /api/v1/dc/tool-b/templates/:id      // 更新模板
DELETE /api/v1/dc/tool-b/templates/:id      // 删除模板
GET    /api/v1/dc/tool-b/templates/:id      // 获取模板详情

// Prompt自动生成服务
POST   /api/v1/dc/tool-b/templates/generate-prompt
Request:
{
  "diseaseType": "系统性红斑狼疮",
  "reportType": "实验室检查",
  "fields": [
    { "name": "抗核抗体滴度", "desc": "如 1:320, 1:640" },
    { "name": "补体C3", "desc": "单位g/L" }
  ]
}

Response:
{
  "promptTemplate": "你是一名风湿免疫科专家...",
  "estimatedTokens": 450
}

3. AI Prompt生成逻辑

// 使用元Prompt（Meta-Prompt）
async generatePrompt(
  diseaseType: string,
  reportType: string,
  fields: { name: string; desc: string }[]
): Promise<string> {
  const metaPrompt = `
你是一名医学AI Prompt工程师。请为病历结构化提取任务生成专业的提示词。

任务背景：
- 疾病类型：${diseaseType}
- 报告类型：${reportType}

提取字段：
${fields.map((f, i) => `${i + 1}. ${f.name}：${f.desc}`).join('\n')}

要求：
1. 模拟该疾病领域的专家角色
2. 清晰说明每个字段的提取规则
3. 要求输出严格的JSON格式
4. 处理"未提及"的情况

请生成完整的Prompt。`;

  // 调用GPT-5或Claude生成Prompt
  const llm = LLMFactory.getAdapter('gpt-5');
  const response = await llm.chat([
    { role: 'user', content: metaPrompt }
  ]);
  
  return response.content;
}

技术亮点：

• ✨ Prompt即代码（Prompt-as-Code）：模板可版本控制、A/B测试
• ✨ AI生成AI的Prompt（Meta-Prompt）：降低用户门槛
• ✨ 模板市场（未来）：用户可分享、下载优质模板

预计工时： 12小时
影响范围：

• 新增：CustomTemplateService.ts (~300行)
• 新增：PromptGeneratorService.ts (~200行)
• 前端：Step2Schema.tsx 新增自定义模板编辑UI
• 数据库：DCTemplate表已支持，无需改动

---

📊 优先级评估

债务ID	问题	优先级	工时	影响用户	技术风险
#1	Excel导出不一致	P1	2h	高（核心功能）	低
#2	进度条显示优化	P2	3h	中（体验优化）	低
#3	Excel预处理	P1	16h	高（数据质量）	中
#4	自定义模板	P2	12h	中（扩展性）	中

总计： 33小时（约4个工作日）

---

🎯 建议处理顺序

Sprint 1：核心功能修复（P1优先）

1. ✅ #1 - Excel导出修复（2小时）→ 立即处理
2. #3 - Excel预处理（16小时）→ 分阶段实现
   • Phase 1：表头清洗（2小时）
   • Phase 2：合并单元格展开（4小时）
   • Phase 3：公式处理（3小时）
   • Phase 4：日期统一（3小时）
   • Phase 5：不可见字符清理（2小时）
   • Phase 6：集成测试（2小时）

Sprint 2：体验优化（P2）

1. #2 - 进度条优化（3小时）
2. #4 - 自定义模板（12小时）
   • Phase 1：后端模板CRUD（4小时）
   • Phase 2：Prompt自动生成（4小时）
   • Phase 3：前端模板编辑器（4小时）

---

💡 长期优化建议

1. 数据质量评分系统

为上传的Excel文件打分（0-100分）：

• ✅ 90-100：优质数据，直接处理
• ⚠️ 60-89：一般质量，提示可能问题
• ❌ 0-59：低质量，强制要求用户清洗后再上传

2. Excel模板标准化

提供标准Excel模板下载，用户按模板填写，减少脏数据：

病历结构化标准模板 v1.0.xlsx
- 表头行冻结
- 数据验证（下拉框）
- 字段说明（批注）
- 示例数据

3. 智能修复建议

检测到问题时，AI给出修复建议：

⚠️ 检测到22个合并单元格，可能导致数据丢失
建议操作：
[ 自动展开合并单元格 ]  [ 忽略并继续 ]

---

📝 开发记录

日期	处理内容	状态	备注
2025-12-03	创建技术债务文档	✅	初始记录4个问题
2025-12-03	#1 Excel导出顺序修复	🔄	已修改代码，待验证
-	#2 进度条优化	⏸️	待开发
-	#3 Excel预处理	⏸️	待开发
-	#4 自定义模板	⏸️	待开发

---

🔗 相关文档

• 技术设计文档：工具 B
• API设计文档
• 开发计划
• 云原生开发规范

---

文档维护： 每次处理技术债务时更新此文档