backend/docs/11-数据质量报告.md

# 文献数据质量报告

> 最后更新：2026-07-23 · 来源：`global_literature` 表统计 · 基线导入后

## 数据总览

| 维度 | 数值 | 覆盖率 | 状态 |
|------|------|--------|------|
| 总文献 | 1,222,688 | 100% | — |
| 有摘要 | 1,110,080 | 90.8% | ✅ |
| 有 DOI | 1,171,276 | 95.8% | ✅ |
| 有研究设计 | 436,748 | 35.7% | 🟡 见下方说明 |
| 有引用次数 (>0) | 1,744 | 0.1% | 🟡 见下方说明 |
| 已打标（GlobalTag） | 928,830+ | 76.0% | ✅ |
| 有 MeSH 头 | 899,275+ | 73.6% | ✅ |
| 无 MeSH（文本过滤入库） | 323,094+ | 26.4% | ✅ |
| 有 PICO | 0 | 0% | 🔴 待处理 |
| 有 OA 全文 | 490 | 0.04% | ✅（PMC 平台覆盖率预期值） |
| 有 AI 摘要 | 1 | ~0% | 🔴 待处理 |
| 有格兰特信息 | 252,476 | 20.7% | 🟡 |

## 数据来源分布

| 来源 | 文献数 | 占比 |
|------|--------|------|
| pubmed_ftp（基线导入） | 1,219,536 | 99.7% |
| pubmed_api（日常精搜） | 2,668 | 0.2% |
| europe_pmc | 484 | <0.1% |

**99.7% 来自基线导入**，日常 API 管道目前在补充最新文献。

### 基线导入状态

PubMed 2026 基线共 1,334 个文件（n0001–n1334）。其中：

| 文件 | 状态 | 处理结果 |
|------|------|----------|
| n0001（pubmed26n0001.xml.gz） | ❌ gzip 损坏（`invalid compressed data`） | ✅ 已用 recover=True 修复，导入 195 篇肿瘤文献 |
| n0002（pubmed26n0002.xml.gz） | ❌ gzip 截断（`unexpected end of file`） | ✅ 已用 recover=True 修复，导入 124 篇肿瘤文献 |
| n0003–n1334 | ✅ 正常 | 原始导入已覆盖，跳过 |

**技术修复**：`import_xml_file()` 在 `for _event, elem in context:` 外层加了 try/except，确保 iterparse 因 XML 损坏抛出异常时，已解析的文章仍被 flush+commit，不会回滚。

**已处理文件**：n0001+n0002（共 +319 篇），其余文件的肿瘤文献已在原始基线导入中正确入库，无需重跑。

## 各维度详解

### 1. 有摘要（✅ 90.8%）

1,110,080/1,222,688 篇文献有英文摘要。112,289 篇无摘要主要是 PubMed 基线中的会议摘要、信件、评论等短类型文献，在过滤规则下会因标题命中关键词而被收录。

### 2. 研究设计分类（🟡 35.7% → 目标 70%+）

436,748 篇已通过 `classify_study_design()` 自动分类（基于 PubMed `PublicationType`）。Python 侧的 `classify_study_design` 对部分文献未返回结果，剩余文献的 `study_design` 为空。

**提升途径**：运行 `POST /admin/pipeline/backfill-study-designs` 回填。

### 3. MeSH 标签覆盖（✅ 76.0% 已打标）

**关键指标**：

| 指标 | 数值 |
|------|------|
| 有 MeSH 头 | 899,275+ (73.6%) |
| 有 MeSH 且已打标 | 899,275+ (100%) |
| 无 MeSH（文本过滤） | 323,094+ (26.4%) |
| 已打标总结 | 928,830+ (76.0%) |

**打标完整性 100%**：所有有 MeSH Headings 的文献都已关联 `global_literature_tags`。这是因为 `tag_service.py` 的**懒创建机制**在打标时自动补建不存在的标签。

**打标流程**（自 2026-07-23 修复后）：
1. 按 `mesh_ui` 精确匹配 → 命中存量标签（auto/manual/mesh）
2. **同时按 `name_en` 匹配 C04 导入标签**（2026-07-23 新增，确保无 mesh_ui 的 C04 标签也被关联）
3. 仍未匹配 → 自动懒创建标签（`source=auto, is_active=false`）

**标签活跃度分布**：

| 来源 | 活跃 | 数量 | 说明 |
|------|------|------|------|
| `manual` | ✅ 活跃 | 99 | 手工维护的 116 个种子标签 |
| `mesh` | ✅ 活跃 | 505 | C04 导入标签（level ≤ 3，is_selectable） |
| `mesh` | ❌ 未激活 | 165 | C04 导入标签（深层，仅用于搜索展开） |
| `auto` | ❌ 未激活 | 20,150 | 懒创建标签，待人工审核 |

**20,150 个懒创建标签**来自打标时发现的不在 `global_tags` 中的 MeSH Descriptor。这些标签已标记 `is_active=false`，用户端不可见，但搜索时 `[MH]` 树号展开仍能匹配。

### 4. C04 肿瘤分类覆盖

| 指标 | 数值 |
|------|------|
| 已导入 C04 Descriptor | 701 个 |
| 已注册 C04 树号 | 1,070 + 985（回填）条 |
| C04 树号确认的文献 | **375,072 篇** |
| 按 tag_category=cancer 分类 | 573,751 篇 |
| C04 占 cancer 类 | 65.3% |

**2026-07-23 修正**：此前报告的 161,636 篇是**仅通过 C04 导入标签（有 tree_number）确认**的文献。实际 C04 覆盖为 **375,072 篇**，差距是**时序问题**导致的：

- 基线导入先执行 → `tag_service.py` 懒创建了 auto 标签（有 mesh_ui，无 tree_number）
- `import_mesh_tags.py` 后执行 → C04 导入标签（有 tree_number，无 mesh_ui）成为孤儿
- 两个修复已部署：
  1. `tag_service.py` 增加 `name_en` 并行匹配（不做 mesh_ui 独占）
  2. 给已在库的 auto 标签回填 tree_number（985 条记录）

### 5. 引用次数（🟡 0.1% >0，待刷新）

1,744 篇文献有引用次数。当前引用数分布呈两极（仅 0 和 1001+），说明引用数据尚未经过全量刷新：

- 基线导入时 `cited_by_count=0`（新文献）
- `cited_by_count > 1000` 可能是 elink API 返回格式异常导致（参见第 6 节）

**下一步**：运行 `POST /admin/pipeline/refresh-citations` 全量刷新。每日定时任务 `daily_citation_update` 05:13 UTC 自动刷新。

### 6. 文本覆盖率

| 字段 | 覆盖率 | 数值 |
|------|--------|------|
| 有摘要 | 90.8% | 1,110,080 |
| 有 DOI | 95.8% | 1,171,276 |
| 有关键词 | <0.1% | 334 |
| 有基金信息 | 20.7% | 252,476 |
| 有化学物质 | <0.1% | 885 |
| 有基因符号 | 0% | 0 |

### 7. 年度分布

文献时间跨度合理：

| 年份范围 | 文献数 |
|----------|--------|
| 2026-2027 | 32,214 |
| 2024-2025 | 133,935 |
| 2022-2023 | 346,237 |
| 2020-2021 | 330,259 |
| 2016-2019 | 374,240 |

### 8. 语种分布

| 语种 | 文献数 | 占比 |
|------|--------|------|
| 英语 | 1,187,243 | 97.1% |
| 中文 | 13,118 | 1.1% |
| 其他 | 22,008 | 1.8% |

### 9. 标签分类覆盖

按 `global_tags.tag_category` 分类的文献覆盖：

| 分类 | 覆盖文献数 | 标签种类 |
|------|-----------|---------|
| cancer（癌种） | 573,751 | 533 |
| mesh_other（其他 MeSH） | 222,895 | 1,207 |
| gene（基因/靶点） | 204,264 | 18,956 |
| treatment（治疗） | 144,920 | 9 |
| endpoint（终点） | 144,409 | 9 |
| scenario（场景） | 117,041 | 10 |
| study_type（研究类型） | 56,127 | 7 |

注：gene 标签种类多（18,956）因 MeSH Chemical/Drug 条目被自动分类为 gene 类。

### 10. 期刊 Tier 分布

| Tier | 文献数 | 占比 |
|------|--------|------|
| 4（默认，未匹配） | 1,154,516 | 94.4% |
| 3 | 597 | <0.1% |
| 2 | 5,955 | 0.5% |
| 1 | 36 | <0.1% |
| unknown（无 ISSN 记录） | 61,265 | 5.0% |

**期刊 Tier 映射覆盖率极低** — `global_journals` 表只有 17 个预定义期刊。94.4% 的文献落入 tier 4 默认值。如需基于期刊质量的排序或过滤，需要扩充期刊索引。

## 已知问题

### 🟡 引用次数刷新滞后
基线导入后引用次数尚未全量刷新。可通过 `daily_citation_update` 定时任务逐步补全。

### 🟡 研究设计分类仅 35.7%
`classify_study_design()` 对基线导入的 XML 解析覆盖率不够。运行 `backfill-study-designs` 接口可提升。

### 🟡 PICO 要素未提取
0 篇文献有 PICO 数据。需执行 `POST /admin/pipeline/extract-pico`。

### 🟡 AI 摘要仅 1 篇
尚未批量运行 AI 摘要生成。需执行 `POST /admin/ai/summarize`。

### 🟡 懒创建标签待审核
20,150 个 `source=auto, is_active=false` 的标签需要人工审核是否归属到正确分类、补充中文名。

### 🟡 期刊 Tier 映射几乎为空
`global_journals` 需要从外部源（如 SCImago Journal Rank）批量导入期刊 Tier 数据。

### 🟡 两个基线文件 gzip 损坏
`pubmed26n0001.xml.gz` 和 `pubmed26n0002.xml.gz` 在下载或解压过程中发生损坏。已通过 `etree.XMLParser(recover=True)` 在修复后的 `import_xml_file()` 中正确导入，共恢复 319 篇肿瘤文献。

## 生产环境监控

### Dashboard 数据质量面板

管理后台 → 首页 Dashboard 已有数据质量卡片，展示 7 个进度条：
- 有摘要 / 已打标 / 有引用次数 / 有研究设计 / 有DOI / 有OA全文 / 有PICO

### 建议的监控频率

| 指标 | 检查频率 | 预警阈值 |
|------|----------|----------|
| 总文献数 | 每日 | 连续 3 天增长 < 50 篇 |
| 已打标率 | 每周 | < 70% |
| C04 树号覆盖率 | 每周 | < 60% of tag_category=cancer |
| 应用覆盖率 | 每月 | < 85% |
| 引用刷新成功率 | 每日 | 连续 3 天 error > 0 |
| 管道运行成功率 | 每日 | 任何失败 |
| 懒创建标签积压 | 每周 | > 25,000 |