AIclinicalresearch/docs/03-业务模块/ASL-AI智能文献/04-开发计划/08b-工具3-M2-HITL工作台冲刺清单.md

M2：血肉丰满 — The HITL Workbench

所属： 工具 3 全文智能提取工作台 V2.0
架构总纲： 08-工具3-全文智能提取工作台V2.0开发计划.md
代码手册： 08d-工具3-代码模式与技术规范.md（所有代码模式均在此手册中，开发时按需查阅）
前置依赖： M1 全部完成（Fan-out 管线已验证、PKB ACL 已通、纯文本提取可跑通）
建议时间： Week 2-3（8-9 天）
核心目标： 接入 MinerU 视觉大模型提升表格准确率，完成前端最复杂的 HITL 审核抽屉，交付一个"完全可用"的 V1 产品。

---

Demo 形态

完整的 V1 体验：前端有打字机风格的终端日志流、右侧滑出包含 Quote 高亮比对的审核抽屉、能导出标准科研 Excel 宽表。虽然不能自定义字段，但用标准 RCT 模板提取文献已经足够惊艳。

---

任务清单

M2-1：接入 MinerU 表格引擎 + Clean Data 缓存（2 天）

做什么：

• PdfProcessingPipeline.ts 升级：M1 的纯文本降级 → 完整双引擎流水线
• 从 PKB storageKey 下载 PDF Buffer → 调用 MinerU Cloud API → 返回结构化 HTML 表格
• MinerU Clean Data OSS 缓存（Cache-Aside）：调用前先检查 pkb/{kbId}/{docId}_mineru_clean.html，命中则 <1 秒返回
• 注册 asl_mineru_extract 子队列（teamConcurrency: 2）
• Child Worker 内部通过 pgBoss.send('asl_mineru_extract', ...) 派发 MinerU 子任务

不做什么：

• 不改 Fan-out 架构（M1 已稳定）
• 不做动态 Prompt（M3），继续用写死的 RCT Schema

验收标准：

• MinerU 返回 HTML 表格，含 <table> + colspan/rowspan
• OSS 缓存命中时跳过 MinerU 调用（日志可见 "Cache hit"）
• asl_mineru_extract 队列 teamConcurrency: 2 生效（3 Pod 环境下全局最多 2 个并行）
• MinerU 超时（>3min）自动降级到纯文本

📖 缓存代码模式见架构总纲 Task 2.2
📖 研发红线 2（计算卸载）：Node.js 禁碰 MinerU 解析，仅 HTTP 调用 Cloud API

---

M2-2：XML 隔离 Prompt + fuzzyQuoteMatch 算法（1.5 天）

做什么：

• DynamicPromptBuilder.ts（M2 阶段仅支持基座模板，不做动态 Schema）：
  • User Prompt 中用 <FULL_TEXT> 和 <HIGH_FIDELITY_TABLES> XML 标签隔离双引擎输出
  • System Prompt 中声明表格优先级规则
• ExtractionValidator.ts：实现 fuzzyQuoteMatch 算法
  • buildQuoteSearchScope()：MinerU HTML 用 html-to-text 剥离标签 + 拼接 pymupdf4llm Markdown
  • Unicode NFKC 标准化 → 剥离非字母数字 → 精确包含检查 → Levenshtein ≤5% 容错
  • 返回三级置信度：≥0.95（绿色）/ 0.80-0.95（黄色）/ <0.80（红色）

验收标准：

• LLM 收到的 Prompt 中 <FULL_TEXT> 和 <HIGH_FIDELITY_TABLES> 标签正确隔离
• fuzzyQuoteMatch 搜索范围 = pymupdf4llm 全文 + MinerU 纯文本（非仅 Markdown）
• 对 8 篇测试 PDF 的 Quote 验证误报率 < 5%
• LLM 引用 MinerU 表格中的数字（如 "410 (22.4%)"）能被正确匹配

📖 XML 隔离设计见架构总纲 Task 2.1
📖 fuzzyQuoteMatch 代码见架构总纲 Task 2.3 补丁 1
📖 红线 8：Quote 搜索池必须含 MinerU 文本

---

M2-3：SSE 终端日志流（1 天）

做什么：

• ExtractionController.ts 新增 SSE 端点 GET /tasks/:taskId/stream
• SSE 事件类型：sync（首帧）、progress、log、complete、error
• 首帧 sync 降级方案：recentLogs: []（不依赖内存 logBuffer），前端检测到空日志时打印 "--- 监控已重新连接 ---"
• ProcessingTerminal.tsx 组件：深色终端风格，来源颜色区分（MinerU 蓝 / DeepSeek 紫 / System 绿）
• useExtractionLogs.ts Hook：仅驱动日志区，不影响主业务流

M1 已完成的不动：

• useTaskStatus.ts（React Query 轮询）继续驱动进度条和步骤跳转

验收标准：

• SSE 连接后立即收到 sync 首帧
• 日志实时打字机效果（[MinerU]、[DeepSeek]、[System] 分色）
• SSE 断开后进度条不受影响（React Query 继续轮询）
• 多 Pod 环境下 SSE 重连到其他 Pod → 显示 "监控已重新连接" 提示
• 🆕 v1.5 NOTIFY/LISTEN 跨 Pod 实时日志： Worker 在 Pod B 提取 → Pod A 的 SSE 客户端能实时收到日志

🆕 v1.5 额外任务：SSE 跨 Pod 广播 — NOTIFY/LISTEN（含在 M2-3 工期内）：

• SseNotifyBridge.ts：Pod 启动时创建独立 PgClient 长连接（不从连接池借），执行 LISTEN asl_sse_channel
• 收到 NOTIFY 后检查本机是否有该 taskId 的 SSE 客户端，有则推送，无则静默忽略
• ExtractionChildWorker 中替代 sseEmitter.emit()：改用 prisma.$executeRawUnsafe('NOTIFY asl_sse_channel, ...')
• complete 事件同样走 NOTIFY 广播，确保"Last Child Wins"翻转后所有 Pod 收到

📖 双轨制架构见架构总纲 Task 4.1
📖 SSE Hydration 降级见架构总纲 Task 2.4 补丁 2
📖 NOTIFY/LISTEN 代码模式见 08d §7.6

---

M2-4：智能审核抽屉（3 天）⚠️ M2 核心战役

做什么：

Step A — ExtractionDrawer 主体（1.5 天）：

• 700px 右侧抽屉，4 大模块：基础元数据 / 基线特征 / RoB 2.0 / 结局指标
• Collapse 折叠面板懒渲染（默认仅展开"基础元数据"）
• 每个字段下方展示 QuoteBlock：灰色背景 + 关键数字黄色 <mark> 高亮
• 字段可编辑，修改追踪到 manualOverrides
• 底部：[取消] + [核准保存] → PUT /results/:resultId/review

Step B — HITL 死锁解套（0.5 天）：

• Quote 红色警告旁新增 [强制认可] + [手动修改数值] 双按钮
• 所有红色警告必须被处置后 "核准保存" 才可点击
• manualOverrides 记录 { fieldName_quote_force_accepted: true } 用于审计

Step C — 性能优化（0.5 天）：

• 每个 FieldGroup 用 React.memo 包裹
• 使用 Ant Design Form.shouldUpdate 精确控制字段级重渲染
• manualOverrides 通过 Form.onValuesChange 差量追踪

Step D — 签名 URL 懒加载（0.5 天）：

• "查看源 PDF" 按钮点击时才生成签名 URL（10 分钟有效期）
• 前端 usePdfViewer Hook 监听 403 → 自动重签

验收标准：

• 抽屉打开 < 200ms（Collapse 懒渲染生效）
• Quote 三级置信度正确展示（绿/黄/红）
• 红色 Quote 的 [强制认可] 和 [手动修改数值] 按钮可用
• 未处置红色警告时 "核准保存" 按钮禁用
• 核准后该篇状态变为 Approved
• "查看源 PDF" → 10 分钟内可正常查看 → 过期后 403 自动重签
• 修改字段值后 manualOverrides 正确记录

📖 抽屉布局见架构总纲 Task 5.2
📖 HITL 解锁见架构总纲 Task 5.2 v1.4 修正
📖 签名 URL 见架构总纲 Task 5.3

---

M2-5：Excel 宽表导出（0.5 天）

做什么：

• ExtractionExcelExporter.ts：标准科研 Excel 数据宽表
• 每个变量列右侧紧跟 _quote 原文列
• 仅导出 reviewStatus = approved 的文献
• 表头双行：第一行中文名，第二行英文 JSON Key
• GET /tasks/:taskId/export 端点

验收标准：

• 导出的 Excel 列顺序正确（变量 + Quote 交替）
• 仅含 Approved 文献
• 双行表头

📖 宽表格式见架构总纲 Task 2.5

---

M2-6：联调 + 集成测试（1 天）

做什么：

• Step 1 → Step 2 → Step 3 完整流程走通（含 MinerU + 审核抽屉 + Excel）
• fuzzyQuoteMatch 边界测试（连字符替换、空格差异、换行吞掉）
• 断点恢复测试（关闭浏览器 → 重新打开 → 恢复正确步骤）
• Fan-out 10 篇并发提取压力测试

验收标准：

• 8 篇测试 PDF 全链路跑通：PKB → MinerU + LLM → 抽屉审核 → Excel 导出
• 中途关闭浏览器后恢复正确
• 10 篇并发无数据丢失、无重复

---

M2 结束时的状态

✅ M1 全部 +
✅ MinerU 表格引擎 + OSS 缓存
✅ XML 隔离 Prompt + 表格优先级
✅ fuzzyQuoteMatch 三级置信度验证
✅ SSE 终端日志（双轨制：React Query 主驱 + SSE 日志增强 + NOTIFY/LISTEN 跨 Pod 广播）
✅ 完整审核抽屉（Collapse + Quote + HITL 解锁 + 签名 URL）
✅ Excel 宽表导出
❌ 无自定义字段（仅系统基座模板）
❌ 无 Prompt 注入防护（无用户输入，不需要）
❌ 无 E2E 自动化测试

M2 的核心价值： 此时工具 3 已是一个"完全可用且高度可用"的产品。用标准 RCT 模板提取文献已经足够惊艳。如果项目赶进度，可以直接拿 M1+M2 给真实医生试用，M3 作为 v2.1 后续迭代。