# 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 后续迭代。