2026-07-27 11:22:22 +08:00
# PubMed 搜索合规修复全记录
> 本文档按修复轮次详细记录所有搜索功能合规性修复的背景、根因分析和修改内容。
>
2026-07-29 08:24:28 +08:00
> **累计**：
2026-07-28 12:59:38 +08:00
> **时间跨度**：
2026-07-28 18:42:04 +08:00
> **核心文件**： （ （
2026-07-27 11:22:22 +08:00
---
## 目录
1. [第一轮：Phase 0-7 基础修复（34 项） ](#第一轮phase-0-7-基础修复 )
2. [第二轮：第二轮审计修复（8 项） ](#第二轮第二轮审计修复 )
3. [第三轮：第三轮审计修复（14 项） ](#第三轮第三轮审计修复 )
4. [第四轮：字段补全与语义优化（11 项） ](#第四轮字段补全与语义优化 )
2026-07-27 11:55:03 +08:00
5. [第五轮：第 5 轮全面审计修复（4 项） ](#第五轮第-5-轮全面审计修复 )
2026-07-27 12:47:09 +08:00
6. [第六轮：第 6 轮全面审计修复（12 项） ](#第六轮第-6-轮全面审计修复 )
2026-07-28 11:02:29 +08:00
7. [第七轮：第 7 轮深度审计修复（20 项） ](#第七轮第-7-轮深度审计修复 )
8. [第八轮：第 8 轮深度审计修复（12 项） ](#第八轮第-8-轮深度审计修复 )
2026-07-28 11:26:35 +08:00
9. [第九轮：第 9 轮深度审计修复（5 项） ](#第九轮第-9-轮深度审计修复 )
2026-07-28 11:41:38 +08:00
10. [第十轮：第 10 轮深度审计修复（6 项） ](#第十轮第-10-轮深度审计修复 )
2026-07-28 12:09:55 +08:00
11. [第十一轮：第 11 轮深度审计修复（16 项） ](#第十一轮第-11-轮深度审计修复 )
2026-07-28 12:59:38 +08:00
12. [第十二轮：第 12 轮深度审计修复（21 项） ](#第十二轮第-12-轮深度审计修复 )
13. [第十三轮：第 13 轮深度审计修复（21 项） ](#第十三轮第-13-轮深度审计修复 )
2026-07-28 18:42:04 +08:00
14. [第十五轮（第 24 次审计修复） ](#round-24第-24-次全面审计修复 )
2026-07-29 07:30:36 +08:00
15. [R30（第 5 轮并行审计修复） ](#r30-2026-07-29-第五轮并行审计修复 )
2026-07-29 08:24:28 +08:00
16. [R31（第 6 轮并行审计修复） ](#r31-2026-07-29-第六轮并行审计修复 )
17. [遗留限制 ](#遗留限制 )
2026-07-27 11:22:22 +08:00
---
## 第一轮：Phase 0-7 基础修复
**提交** ： `723c4fc` / `62ca8fa` / `5f69277`
**日期** ：
**数量** ：
**触发** ：
### 背景
首次系统审计发现搜索功能存在大量阻塞性 Bug：MeSH 搜索因 INNER JOIN 返回 0 结果、布尔运算符 OR 被当作 AND 处理、PM C_ID 格式混乱、数据导入缺失 journal_iso 和 keywords 等关键字段。整体搜索几不可用。
### Phase 0 — 关键 Bug 修复（12 项）
| # | 修复项 | 文件 | 问题描述 | 根因分析 | 修改内容 |
|---|--------|------|---------|---------|---------|
| 0.1 | `_expand_mesh_tag_ids` INNER JOIN | `search_engine.py:518` | 所有 `[MH]` /`[MAJR]` 搜索返回 0 个结果。tree_numbers 表无 C04 数据，INNER JOIN 过滤掉所有标签 | `select(GlobalTag.id).join(GlobalTagTreeNumber)` 在有 tree_number 的标签时才返回行 | 改为 `select(GlobalTag.id).where(...)` ，使 MeSH 搜索在无 tree_number 展开时仍能工作 |
| 0.2 | `recent_subq` 条件化 | `search_engine.py:314-319` | 有搜索词时仍被 `pub_date > 90d` 子查询过滤，漏掉旧文章 | 未检查 `query.strip()` 就附加 recent 子句 | 有搜索词或历史查询时跳过 recent 子查询 |
| 0.3 | OR 布尔运算符 | `search_engine.py:394-414` | 同字段多个词始终 AND， `lung[TI] OR breast[TI]` 只返回同时命中 lung 和 breast 的文献 | `boolean` 参数只在文本搜索路径生效，未传入 `_field_conditions` | 同 field 按 `boolean_operator` 用 `or_()` 组合 |
| 0.4 | 多 [MH] 词 AND 组合 | `search_engine.py:516-519` | `lung neoplasms[MH] AND immunotherapy[MH]` 返回 0 结果 | 所有 mesh 词合并到一个 subq IN，必须所有标签同时关联同一篇文献 | 逐 term 独立 subq，按 boolean 组合（AND 用 intersect）
| 0.5 | PMC XPath 上下文 | `pubmed_api.py:440,447` | pmc_id/is_oa 解析错误，只有 9/1662 篇有值 | `article.findall('.//PMCID')` 在 `article` 而非 `article_elem` 上调用 | `article.findall` → `article_elem.findall` |
| 0.6 | 构造函数遗漏 | `pubmed_api.py:914-944` | `pubmed_revised` /`citation_status` /`date_completed` /`article_date` /`suppl_mesh_list` 未写入模型 | `_parse_pubmed_xml()` 返回值不包含这些字段 | 补全 5 字段传递 |
| 0.7 | ArticleTitle itertext | `pubmed_api.py:409` | 含 `<i>` /`<sub>` 等内联标记的标题截断 | `.text` 只返回第一个文本节点 | `"".join(itertext())` |
| 0.8 | PMC_ID 格式统一 | `pubmed_api.py:264` | "PMC1234567" vs "1234567" 混用 | `lstrip("PMC")` → 会误删 `PMC` 开头真实数字 | `art.get("pmcid", "").lstrip("PMC")` |
| 0.9 | 搜索端点异常处理 | `features.py:68` | 搜索异常暴露 500 内幕 | 无 try/except | 加异常处理返回 400 |
| 0.10 | field:all 硬编码 | `SearchView.vue:83` | 前端固定发送 `field: "all"` | 模板字符串手误 | 替换为动态 `field.value` |
| 0.11 | journal_iso 导入修复 | `pubmed_api.py` | 0% 覆盖率 | Journal ISOAbbreviation 未解析 | 增补 ISOAbbreviation 提取 |
| 0.12 | keywords 导入修复 | `pubmed_api.py` | 0% 覆盖率 | KeywordList 未解析 | 增补 KeywordList 解析 |
### Phase 1 — P0 新功能（8 项）
| # | 任务 | 文件 | 说明 |
|---|------|------|------|
| 1.1 | MeSH 树号导入 | `scripts/import_mesh_tags.py` | 导入 NLM `mtrees2025.bin` ，填充 `GlobalTagTreeNumber` |
| 1.2 | `entrez_date` 解析 | `pubmed_api.py` + migration | 解析 `PubmedData/History/PubMedPubDate[@PubStatus="entrez"]` → `[EDAT]` 可搜 |
| 1.3 | `[AD]` 标签 | `search_engine.py` + `pubmed_query_parser.py` | 机构字段映射到 `authors` JSONB cast |
| 1.4 | `[LA]` 标签 | 同上 | 语言字段 = `GlobalLiterature.language` |
| 1.5 | `[EDAT]` /`[CRDT]` /`[MHDA]` /`[LR]` /`[DCOM]` /`[DEP]` | 同上 | 6 个日期字段的范围+独立语法 |
| 1.6 | setweight 迁移 | 迁移脚本 | ⏳ 待办：tsvector 重建带 A/B 权重 |
| 1.7 | ATM 引擎 v1 | `query_expansion.py` | SynonymExpander + MeSH 翻译 + 期刊翻译 |
| 1.8 | best_match 权重调优 | `search_engine.py` | ⏳ 待 setweight 后调优 |
### Phase 2 — 字段标签覆盖（14 项）
| # | 任务 | 状态 | 说明 |
|---|------|------|------|
| `[OT]` | keywords 搜索 | ✅ | 映射到 `all` （第四轮修复为独立 keywords JSONB）
| `[GR]` | grants 搜索 | ✅ | `jsonb_array_elements` + ILIKE |
| `[NM]` | 化学物质名 | ✅ | `chemical_list` JSONB contains |
| `[RN]` | Registry Number | ✅ | `chemical_list.registry_number` |
| `[SH]` | Subheading | ✅ | `mesh_headings.qualifiers` |
| `[SI]` | DataBank | ✅ | `databank_list.accession_numbers` |
| `[PA]` | Pharmacological Action | ✅ | `pharmacological_actions` JSONB |
| `[TW]` | 文本词 | ✅ | 映射到 `all` |
| `[TA]` /`[JT]` | 期刊全称+缩写 | ✅ | journal ILIKE + journal_iso ILIKE |
| `[CN]` /`[FAU]` /`[LAU]` | 作者变体 | ✅ | 均映射到 `author` 路径 |
| Entry Terms | MeSH 入口词 | ✅ | `desc2025.asc` → `GlobalTag.entry_terms` |
| 中文搜索 | CJK 支持 | ✅ | `simple` 词典而非 `english` |
| 多 affiliation | 捕获所有 | ✅ | `find` → `findall` + `\|` 连接 |
### Phase 3 — E-utilities 补充抽取（含 pubmed_api.py 修复）
- 反向兼容阶段，确保 pubmed_api.py 正确抽取所有字段
- PMC/trial_reg/retraction 等补充数据通路修复
### Phase 4 — 搜索质量
- 历史搜索查询 + 日期筛选整合
- `best_match` 排序引入 `cited_by_count` + 年度梯度
- 缺省排序降级保护
### Phase 5 — 解析器健壮性
- 括号嵌套超过 10 层保护
- 空查询短路
- token 超限截断
- 未知字段标签静默降级
- Unicode normalization（全角数字、零宽字符）
### Phase 6 — 前端搜索 UX
- SearchView URL 状态全量持久化（24 个参数）
- HomeView → SearchView 参数正确传递
- LiteratureCard `search` 事件冒泡
- 响应式布局适配（移动端搜索栏隐藏）
### Phase 7 — API 验证
- 请求参数 Pydantic validator
- `field` 只接受预定义值
- 查询长度限制
---
## 第二轮：第二轮审计修复
**提交** ： `e688241`
**日期** ：
**数量** ：
**触发** ：审计发现 Phase 1-7 修复中的遗留 Bug
### 背景
8 项在首次审计中遗漏的中高级 Bug，全部在后端搜索核心路径。
### 修复清单
#### F1: `[MH:noexp]` 顶层 `_noexp` 标志丢失
- **文件**： `search_engine.py` `_pubmed_conditions()` L640-650
- **问题**： `mesh_terms` 处理时只提取 `.text` ，丢弃了 `_noexp` 标志，导致 `asthma[MH:noexp]` 在顶层使用时仍然树展开，和 `[MH]` 无异
- **根因**：循环处理 vs 括号组内调用 `_single_term_condition()` 两条路径——后者正确传递 `noexp` ，前者未分组
- **修复**：将 `mesh_terms` 按 `_noexp` 拆为两组，分别调用 `_expand_mesh_tag_ids` ：
```python
noexp_names = [t.text for t in pp.mesh_terms if t._noexp]
exp_names = [t.text for t in pp.mesh_terms if not t._noexp]
` ``
#### F2: 组内 NOT 违反 De Morgan 律
- **文件**： search_engine.py` L862-877
- **问题**： NOT (A AND B)` → 被解析为 ` not_(A) AND not_(B)` = ` NOT (A OR B)`，语义完全翻转
- **根因**：全 NOT 组内每个 term 独立 ` not_()`，然后 AND 组合
- **修复**：组的 ` all_not=True` 时，对所有 term 不做独立 NOT，改为 ` not_(combined)` 包裹组合条件
#### F3: ` _parse_not_expr` 不支持重复 NOT
- **文件**： pubmed_query_parser.py` L428-433
- **问题**： NOT NOT cancer` → 第二个 "NOT" 被降级为搜索字面词，变成 ` NOT "NOT" AND cancer`
- **根因**：语法定义 ` not_expr → NOT not_expr | primary`，但实现直接跳到 ` _parse_primary(result, negated=True)`，丢失递归
- **修复**：改为递归调用 ` _parse_not_expr` 并 toggle ` is_not`
#### F4: SearchView Custom Range 不发送日期
- **文件**： SearchView.vue` L296-309
- **问题**：选择"自定义年份范围"→ 搜索，请求体不含任何日期参数，返回全库结果
- **根因**： datePreset === 'custom'` 分支未处理。仅 ` !datePreset.value` 和 ` datePreset.value !== 'custom'` 两个条件都失败
- **修复**：增加 ` datePreset === 'custom'` 分支发送 ` year_from`/` year_to`
#### F5: HomeView.restoreFromUrl 恢复不全
- **文件**： HomeView.vue` L348-364
- **问题**： ?q=cancer&retracted=only` 时，retracted 参数丢失
- **根因**：只恢复了 ` tag`/` date_from`/` date_to`/` q`，缺失 ` sort`/` field`/` retracted`/` negative_result`
- **修复**：补全 4 个缺失参数的读取
#### F6+F7: 死代码清理 — precision_mode + is_oa
- **文件**： AdvancedSearchPanel.vue` / ` types/index.ts`
- **问题**：
- **修复**：全链路移除 precision_mode 控件和类型字段
#### F8: ` _expand_mesh_tag_ids` N+1 查询 → 批量
- **文件**： search_engine.py` L1119-1143
- **问题**： db.execute` + 2 次树查询 = 8 轮数据库往返
- **根因**： for m in mesh_names:` 循环内每次执行 2 次独立查询
- **修复**：
---
## 第三轮：第三轮审计修复
**提交**： a37cc50`
**日期**：
**数量**： × × × ）
**触发**：6 Agent 并行深度代码审计
### 背景
第三轮审计聚焦于隐藏较深的逻辑缺陷：PubMed 子集/状态/UID 字段的网关检查遗漏、字段到领域的错误映射、括号组的单 NOT 边缘情况、前端日期精度丢失等。
### P0 — 搜索结果错误（5 项）
#### P0-1: sb/stat/uid/dep 门控遗漏
- **文件**： search_engine.py` 两个 ` has_pubmed_terms` 检查点（L162-179, L189-205）
- **问题**： medline[SB]` 等解析后产出了 ` pp.sb_terms`，但 ` has_pubmed_terms` 未检查它，导致走纯文本路径，` [SB]` 条件被丢弃
- **根因**： has_pubmed_terms` gate 随字段新增未同步更新
- **修复**：在条件判断中添加 ` pp.sb_terms`, ` pp.stat_terms`, ` pp.uid_terms`, ` pp.dep_from`
#### P0-2: ` [SB]` 映射到错误领域
- **文件**： search_engine.py` L830-839
- **问题**： medline[SB]` 被映射到 ` nlm_subsets`（期刊级），但 PubMed 的 ` medline[SB]` 是指记录级别 ` citation_status=medline`
- **根因**：所有 ` [SB]` 值笼统走 ` nlm_subsets overlap` 路径
- **修复**：
- ` MEDLINE` → ` citation_status == "medline"`
- ` PUBMED` → no-op（所有记录都是 PubMed）
- 单字母代码（AIM/S/D 等）→ ` nlm_subsets overlap`（期刊级）
- 其他文本 → ` citation_status == val.lower()`
#### P0-3: 括号组单 NOT 词丢失否定
- **文件**： search_engine.py` L882
- **问题**： NOT (cancer)` — 组内只有 1 个词，` len(group_conds) > 1` 条件失败，NOT 被丢失
- **根因**：全 NOT 组的包裹检查是 ` > 1`（针对多词 NOT 组优化），但 1 个词的组也被 NOT 包裹才正确
- **修复**： > 1` → ` >= 1`
#### P0-4: HomeView watch 丢弃参数
- **文件**： HomeView.vue`
- **问题**： sort`, ` field`, ` retracted`, ` negative_result` 在 ` watch(searchKey)` 的 URL 同步中被丢弃
- **修复**：把这些参数加入 ` searchKey` computed 依赖和 URL 替换逻辑
#### P0-5: 日期精度丢失
- **文件**： SearchView.vue`
- **问题**： date_from=2025-03-15` 恢复后变成 ` 2025-03-14` 或丢失
- **根因**：使用 ` date_from`/` date_to` ref 存储（受 DatePicker 组件双向绑定影响），而非原始 URL 值
- **修复**：增加 ` urlDateFrom`/` urlDateTo` ref 直接存储原始日期字符串
### P1 — 功能缺失（4 项）
#### P1-1: ` [ALL]` 未注册
- **文件**： pubmed_query_parser.py`
- **问题**： [ALL]` tag 未在 ` _FIELD_TAG_MAP` 和 ` _ALL_FIELD_TAGS` 中注册，导致被 ` is_pubmed_syntax()` 识别但 tokeniser 不识别 → ` UNKNOWN_FIELD` → 静默降级
- **修复**：在 ` _FIELD_TAG_MAP` 添加 ` "ALL": "all"`，在 ` _ALL_FIELD_TAGS` 添加 ` "ALL"`
#### P1-2: 独立日期字段降级
- **文件**： pubmed_query_parser.py` ` _dispatch_term`
- **问题**： 2024-01-01[DP]` 作为日期范围使用时正确，但作为独立字段值时（term.field 非 None 且非范围语法）被降级到 ` plain_terms`
- **根因**： _dispatch_term` 缺少 ` term.field` 为日期字段名称时的独立处理分支
- **修复**： _dispatch_term` 增加 DP/EDAT/CRDT/MHDA/LR/DCOM/DEP 裸字段处理→设置 ` from=to=日期`
#### P1-3: 浮点日期范围不交换
- **文件**： pubmed_query_parser.py` ` _parse_range`
- **问题**： 2026:2024[DP]` 只对纯 digit 做了交换，` 2024-12-01:2024-01-01[DP]` 这种完整日期不交换
- **修复**：
#### P1-5: MeSH entry_terms 大小写不敏感
- **文件**： scripts/import_mesh_full.py`
- **问题**： ， @>` 匹配区分大小写，导致 ` cancer` 无法匹配 ` Cancer`
- **修复**： .lower()` 统一存储
### P3 — 健壮性（5 项）
| # | 修复项 | 文件 | 问题 | 修复 |
|---|--------|------|------|------|
| P3-2 | MeSH 展开无保护 | ` search_engine.py` | ` _expand_mesh_tag_ids` 和 ` expand_atm` 的 DB 查询未包裹异常 | ` try/except` 包裹 DB 查询块 |
| P3-4 | 参数无验证 | ` features.py` | ` sort`/` field`/` boolean` 参数接受任意值 | ` field_validator` |
| P3-5 | GET 搜索无限制 | ` literature.py` | 超长查询可耗尽资源 | 100 词上限 |
| P3-6 | 中文正则不一致 | ` query_expansion.py` | 中文检测正则与 search_engine 不一致 | ` [一-鿿㐀-䶿豈-]` 同步 |
| P1-8 | page_size 未恢复 | ` SearchView.vue` | URL 翻页参数丢失 | ` restoreFromQuery` + ` syncSearchToUrl` |
---
## 第四轮：字段补全与语义优化
**提交**： 807972d`
**日期**：
**数量**：
**触发**：系统跟踪遗留限制的逐个解决
### 背景
前三轮修复后仍有多项已知限制：8 个 PubMed 字段标签未注册、` [OT]` 语义过宽（映射到 ` all`）、精确短语用 ILIKE 而非 GIN 索引。第四轮系统性地清理了这些残留项。
### 字段注册（8 项）
| # | 字段标签 | 映射目标 | 说明 |
|---|---------|---------|------|
| P4-1 | ` [Title/Abstract]` | ` all` | PubMed 长标签，等同 ` [TIAB]` |
| P4-2 | ` [OAB]` | ` all` | Other Abstract |
| P4-3 | ` [WORD]` | ` all` | Word in text |
| P4-4 | ` [FI]` | ` GR` 同路径 | Funder Identifier，搜索 grant_id |
| P4-5 | ` [SO]`/` [PL]` | ` journal` | Source / Place of Publication（近似映射） |
| P4-6 | ` [GEN]` | ` gene_symbols` JSONB | 基因符号精确搜索（数据覆盖率依赖实际导入） |
| P4-7 | ` [PMC]` | ` pmc_id` 列 | PMCID 精确匹配（数据覆盖率依赖实际导入） |
**涉及修改**：
- ` _ALL_FIELD_TAGS` set：新增 8 个标签名
- ` _FIELD_TAG_MAP`：注册映射关系
- ` _SPECIAL_FIELDS`：加 ` OT`、` GEN`、` PMC`
- ` ParsedPubmedQuery`：加 ` ot_terms`/` gene_terms`/` pmc_terms` list
- ` _dispatch_term`：加 3 个 elif 分支
- ` search_engine.py`：两个 ` has_pubmed_terms` gate 加新字段
### 语义修复（3 项）
#### P4-8: ` [OT]` → keywords JSONB（不再映射到 all）
- **问题**： [OT]` 映射到 "all" 意味着在标题/摘要/PMID/DOI 全字段搜索，语义过宽。PubMed 的 ` [OT]` 只搜索 Other Keywords（ keywords` JSONB 列）
- **修复**：
- ` _dispatch_term` 将 ` OT` 路由到 ` ot_terms`（而非 ` _FIELD_TAG_MAP` → ` all` → ` tiab_terms`）
- ` _pubmed_conditions` 增加 ` ot_terms` 处理块：` GlobalLiterature.keywords.cast(JSONB).contains([t.text])`
- ` _single_term_condition` 增加 OT 分支
#### P4-10: phraseto_tsquery 精确短语
- **问题**：精确短语 ` "immune checkpoint"` 用 ILIKE ` %immune checkpoint%` 实现，无法利用 GIN 索引，全表扫描
- **修复**： _field_condition` 的 ` "all"` 字段精确短语路径从 ILIKE 改为 ` search_tsv @@ phraseto_tsquery('english', term)`
- **限制**：通配符 ` *` 时仍需 ILIKE（
### 引擎改进（1 项）
#### P4-9: ` [PMC]` 搜索 SQL
- ` _pubmed_conditions` 增加第 9 块：` pmc_id == term.text` 精确匹配
- ` _single_term_condition` 增加 PMC 分支
---
2026-07-27 11:55:03 +08:00
## 第五轮：第 5 轮全面审计修复
2026-07-27 11:55:21 +08:00
**提交**： 275a9f6`
2026-07-27 11:55:03 +08:00
**日期**：
**数量**：
**触发**：
### 背景
第 4 轮后启动第 5 轮全面审计，5 个 agent 并行扫描 parser、engine、前端、文档。首先与第 2 轮审计计划（F1-F8）逐项核对，确认以下 8 项已在之前轮次完成：
| 计划 ID | 项目 | 完成轮次 | 状态 |
|---------|------|---------|------|
| F1 | ` [MH:noexp]` 顶层支持 | 第 3/4 轮 | 已修复 |
| F2 | 组内 NOT De Morgan 律 | 第 2 轮 | 已验证正确 |
| F3 | ` _parse_not_expr` NOT NOT 递归 | 第 4 轮 | 已修复 |
| F4 | SearchView Custom Range 日期 | 第 3 轮 | 已工作正常 |
| F5 | HomeView restoreFromUrl | 第 3 轮 | 已工作正常 |
| F6 | precision_mode 死代码 | 此前轮次 | 已移除 |
| F7 | is_oa 死字段 | 此前轮次 | 已注释 ` unused` |
| F8 | ` _expand_mesh_tag_ids` N+1 | 第 3/4 轮 | 已批量优化 |
实际在第 5 轮修复的 4 项均为 parser 边缘案例：
### P5-1: 尾部 NOT 导致 IndexError 降级
- **文件**： pubmed_query_parser.py` ` _parse_not_expr` L498
- **问题**： cancer NOT` — 解析器 ` _is_primary_start` 包含 ` NOT`，隐式 AND 逻辑尝试将 NOT 作为新词开始，但 NOT 之后无 token → ` peek()` 越界抛 ` IndexError` → 整个查询降级为纯文本拆分，` NOT` 作为字面搜索词（影响极小但产生异常）
- **根因**： _parse_not_expr` 不检查是否已到 EOF
- **修复**：消费 NOT token 后立即检查 ` peek().type == TokenType.EOF`，直接返回 ` []` 静默忽略
### P5-2: 单数字日期格式不被识别
- **文件**： pubmed_query_parser.py` ` parse_pubmed_query` L679
- **问题**： 2024-1-1[DP]` — tokeniser 的 DATE 模式只匹配 ` \d{4}-\d{2}-\d{2}`，单数字月/日被解析为 ` WORD('2024-1-1')` → ` _dispatch_term` 设置 ` date_from='2024-1-1'` → ` date.fromisoformat()` 抛 ` ValueError` → 日期条件被静默丢弃
- **根因**：
- **修复**：在 ` parse_pubmed_query` 的 NFKC 归一化后增加 ` YYYY-M-D → YYYY-MM-DD` 正则替换
### P5-3: ` is_pubmed_syntax` 不处理全角字符
- **文件**： pubmed_query_parser.py` ` is_pubmed_syntax` L652
- **问题**：全角括号 ` ［ ］ ` 不被 ` \[...\]` 识别 → 检出失败 → 走纯文本路径（解析器内 ` parse_pubmed_query` 做 NFKC 但已不会进入）
- **根因**： is_pubmed_syntax` 未做 NFKC 归一化、与 ` parse_pubmed_query` 行为不一致
- **修复**：函数开头增加 ` query = unicodedata.normalize('NFKC', query)`
### P5-4: ` extract_pubmed_query_for_prisma` 不能处理 ` [Title/Article]`
- **文件**： pubmed_query_parser.py` ` extract_pubmed_query_for_prisma` L706
- **问题**：归一化 regex ` \[([\w:]+)\]` 不含 ` /`， [Title/Article]` 不被匹配、保持原文
- **根因**： /`
- **修复**： [\w:]` → ` [\w/:]`
2026-07-27 12:47:09 +08:00
### P5-5: Tokeniser 缺口字符被静默丢弃（BUG-7）
- **文件**： pubmed_query_parser.py` ` tokenise()` L150
- **问题**： finditer` 只输出匹配到的片段，` $`、` @` 等匹配不到的字符无声丢失
- **根因**： _TOKEN_PATTERNS` 未覆盖所有可能字符，且无 fallback
- **修复**：在 ` tokenise()` 中检测相邻 match 间的 gap，将非空 gap 作为 WORD 加入 token 流
---
## 第六轮：第 6 轮全面审计修复（12 项）
**日期**：
**数量**：12 项（6 项已在前轮中应用 + 6 项新增）
**触发**： ）
### P6-1: Title/Abstract 字段标签大小写不匹配
- **文件**： pubmed_query_parser.py` ` _FIELD_TAG_MAP` L54
- **问题**： _FIELD_TAG_MAP` 只有 ` "Title/Abstract"` 键，但解析器 ` .upper()` 产生 ` "TITLE/ABSTRACT"`，导致查表失败，该字段标签退化到 ` plain_terms`（走 "all" 路径，结果正确但掩盖了 bug）
- **根因**：初始化 ` FieldTagMapping` 时只写了原始大小写
- **修复**：增加 ` "TITLE/ABSTRACT"` 大写键值对映射到 "all"
### P6-2: 末尾 OR 产生空 Term（ ）
- **文件**： pubmed_query_parser.py` ` _parse_or_expr()` L466
- **问题**： cancer OR ` 末尾操作符导致解析器尝试读取空 token，生成 ` Term(text="")`，引起 ` plainto_tsquery("english", "")` 报错
- **根因**：OR 后无表达式时，解析器仍尝试调用 ` _parse_and_expr`，最终生成空 term
- **修复**：在 ` _parse_or_expr` 中，advance 后检查 EOF 并 break
### P6-3: PubMed 降级路径 field 标签 regex 未覆盖 ` /`（ ）
- **文件**： search_engine.py` L222
- **问题**： re.sub(r'\[[\w-]+\]', '', query)` —— ` [\w-]` 不含 ` /`， [Title/Abstract]` 不会被擦除，留在降级查询中作为普通文本
- **根因**：字符类缺 ` /`
- **修复**： [\w-]` → ` [\w/-]`
### P6-4: ATM 展开未剥离括号（Flat Text BUG 5）
- **文件**： search_engine.py` L284
- **问题**： _atm_query` 仅执行 ` replace('"', '').replace("'", '')`，未去除 ` (` 和 ` )`。` (lung cancer)` 作为 ATM 查询导致 ` expand_atm` 搜索到 ` (lung cancer)` 而非 ` lung cancer`，可能零匹配
- **修复**：增加 ` replace('(', '').replace(')', '')`
### P6-5: 中文 MeSH name_zh 查询无 LIMIT（ ）
- **文件**： search_engine.py` L229-235
- **问题**： GlobalTag.name_zh.ilike(...)` 可能返回大量匹配（如 "癌"），导致 subquery 膨胀
- **修复**：追加 ` .limit(100)` 限制
### P6-6: year_from / year_to 使用 falsy 检测（BUG-15）
- **文件**： search_engine.py` L312-315
- **问题**： if year_from:` 使 ` year_from=0` 被当作假值跳过（0 不是有效年份，但语义上 "0" 应被忽略；改为 ` is not None` 更安全）
- **根因**：
- **修复**： if year_from:` → ` if year_from is not None:`
### P6-7: ` _parse_range` 混合类型日期范围无反向交换（BUG-8）
- **文件**： pubmed_query_parser.py` _parse_range L601-606
- **问题**： 2026:2024-01-01[DP]` 不触发任何 swap（一个纯数字一个不是），导致 ` year_from=2026`, ` date_to=2024-01-01`（空范围）
- **根因**：反向 swap 条件只处理两端同类型
- **修复**：增加第三条件 ` _start_is_digit and not _end_is_digit and int(start_val) > int(end_val[:4])`
### P6-8: Tokeniser 内部 gap 字符恢复（BUG-7 补充）
- **文件**： pubmed_query_parser.py` tokenise L150
- **问题**：无 gap 处理时部分特殊字符丢失
- **修复**：记录 ` last_end`，gap 中的非空白字符作为 WORD 输出
### P6-9: ` [MH:noexp]` 顶层支持（F1）
- **文件**： search_engine.py` _pubmed_conditions L660-674
- **状态**：已在第一阶段实现，审计确认正确（按 ` _noexp` 标志分组处理）
### P6-10: 组内 NOT 语义 De Morgan（ ）
- **文件**： search_engine.py` _pubmed_conditions L922-941
- **状态**：已在第二阶段实现，审计确认正确（` all_not` 标志 → ` not_(combined)` 包裹）
### P6-11: ` _parse_not_expr` 递归支持（F3）
- **文件**： pubmed_query_parser.py` L498-509
- **状态**：已在第五阶段实现，审计确认正确（递归调用 ` _parse_not_expr`）
### P6-12: 前端日期发送 + restoreFromUrl（ ）
- **文件**： SearchView.vue` L300-302、` HomeView.vue` L364-367
- **状态**：已在第五阶段实现，审计确认正确（custom range 已发送年/月参数、restoreFromUrl 已覆盖 sort/field/retracted/negative）
2026-07-27 11:55:03 +08:00
---
2026-07-27 11:22:22 +08:00
## 各轮变更摘要
2026-07-27 12:47:09 +08:00
| 维度 | 第一轮 | 第二轮 | 第三轮 | 第四轮 | 第五轮 | 第六轮 |
|------|--------|--------|--------|--------|--------|--------|
| 修复数 | 34 | 8 | 14 | 11 | 4 | 12 |
| 后端文件变更 | 全部 | engine + parser | engine + parser + api | engine + parser | parser | engine + parser |
| 前端文件变更 | SearchView + HomeView + Card | SearchView + HomeView + Panel | SearchView + HomeView | 0 | 0 | 0 |
| 测试变更 | 新增 | +6 项 | 已有覆盖 | 0 | 0 | 0 |
| 新功能 | ` [MH]`/` [EDAT]`/` [AD]`/` [LA]` 等 | — | — | ` [GEN]`/` [PMC]`/` [Title/Abstract]` | — | — |
| 性质 | 从零搭建 | 审计修复 | 深度审计修复 | 字段补全 | 审计修复 | 深度审计修复 |
2026-07-27 11:22:22 +08:00
---
2026-07-27 13:01:52 +08:00
## 第七轮：第 7 轮深度审计修复（20 项）
**日期**：
**数量**：
**触发**：用户"再次全面、深入地检查、分析，消除漏洞"
**测试**：
### P7-1: ` isdecimal()` 非 ASCII 数字崩溃 PMID 检测（HIGH）
- **文件**： search_engine.py` ` search()` L245-246
- **问题**： str.isdecimal()` 对阿拉伯数字 U+0660 等返回 True，但 ` int()` 不接受非 ASCII 数字 → ` ValueError`，搜索返回 500
- **根因**：
- **修复**： t.isdecimal()` → ` re.match(r'^\d{1,15}$', t)`
### P7-2: 降级 regex ` [\w/: -]` 兼容冒号
- **文件**： search_engine.py` ` search()` L219
- **问题**： [MH:noexp]` 标签中的冒号不在 ` [\w/-]` 内，降级后冒号残留
- **根因**： :` 和空格
- **修复**： [\w/-]` → ` [\w/: -]`
### P7-3: Parse 异常处理器清除字段标签/布尔符/引号
- **文件**： pubmed_query_parser.py` ` parse_pubmed_query()` L719-726
- **问题**：降级时 ` query.strip().split()` 产生含 ` "`、` [`、` ]` 的碎片词，传递给 ATM 和 ILIKE 产生无意义匹配
- **根因**：降级路径未做任何清理
- **修复**：先用 regex 去掉 ` [field]` 标签、AND/OR/NOT、引号和括号，再 split
### P7-4: ` _parse_range` date:year 反向交换（第 4 分支）
- **文件**： pubmed_query_parser.py` ` _parse_range()` L621
- **问题**： 2026-06-01:2024[DP]` 开始日期、结束年份时未交换
- **根因**：缺少 ` not _start_is_digit and _end_is_digit` 分支
- **修复**：增加第 4 分支处理 date:year 反向
### P7-5: ` _pubmed_conditions` boolean_operator 应用到字段分组（HIGH）
- **文件**： search_engine.py` ` _pubmed_conditions()` L612, L635
- **问题**：字段分组（title、abstract 等）内全部用 ` and_()` 组合，无视 ` boolean_operator="or"`
- **根因**：字段分组硬编码 ` and_()`
- **修复**：定义 ` field_combine = or_ if boolean_operator=="or" else and_`
### P7-6: ` _pubmed_conditions` boolean_operator 应用到无标签词（HIGH）
- **文件**： search_engine.py` ` _pubmed_conditions()` L652-659
- **问题**：纯文本词固定 AND，分开写的 ` cancer OR tumor` 实际变 AND
- **根因**： and_()`
- **修复**：全部改用 ` field_combine`
### P7-7: best_match 排序剥离字段标签
- **文件**： search_engine.py` ` search()` L497
- **问题**： [TI]` 参与 ts_rank 产生噪音
- **根因**：条件只检查 ` sort == "relevance"`
- **修复**：改为 ` sort in ("relevance", "best_match")`
### P7-8: year_from/year_to 精确空值检测
- **文件**： search_engine.py` ` _pubmed_conditions()` L969-972
- **问题**： if pp.year_from:` 当 year_from=0 时 falsy → 条件跳过
- **根因**：
- **修复**： if pp.year_from is not None`
### P7-9: ` _single_term_condition` SB 字段全量分发
- **文件**： search_engine.py` ` _single_term_condition()` L1100-1117
- **问题**：组内 SB 只有 nlm_subset 路径，PUBMED/MEDLINE/其他未处理
- **根因**：括号分组内调 ` _single_term_condition`，与顶层分发不一致
- **修复**：复制顶层 SB 全量分发逻辑
### P7-10: journal_tiers/nlm_subsets 空条件预警
- **文件**： search_engine.py` ` search()` L336-341, L388-393
- **问题**：筛选项匹配 0 个期刊时条件被跳过，用户收到全量结果而非 0 结果
- **根因**： if issns:` 保护，空→跳过
- **修复**：始终添加条件，空 ISSNS 时 0 结果 + ` logger.warning`
### P7-11: ATM 展开异常日志化
- **文件**： search_engine.py` ` search()` L287, ` _pubmed_conditions()` L655
- **问题**： except Exception: pass`
- **修复**：改为 ` logger.exception()`
### P7-12: ` _expand_mesh_tag_ids` 异常日志化
- **文件**： search_engine.py` ` _expand_mesh_tag_ids()` L1239, L1276
- **问题**： except Exception: pass`
- **修复**：改为 ` logger.exception()`
### P7-13: 中文 name_zh ILIKE 加 LIMIT 100
- **文件**： query_expansion.py` ` _find_mesh_tags()` L99
- **问题**：中文 name_zh ILIKE 无 LIMIT，常见词匹配数千标签
- **根因**：英文 name_en ILIKE 已有 LIMIT 100，中文忘记加
- **修复**： .limit(100)`
### P7-14: Cursor 分页使用 pub_date 优先（HIGH）
- **文件**： SearchView.vue` L358
- **问题**：
- **修复**：改为 ` pub_date || article_date`
### P7-15: Null cursor 日期安全守卫
- **文件**： SearchView.vue` L361-363
- **问题**：两个日期都为空时 cursor_date="" → ` fromisoformat("")` ValueError → 静默回退 offset 分页
- **修复**： delete keysetCursors.value[p+1]` 当两日期都为空
### P7-16: syncSearchToUrl 移到 finally 块
- **文件**： SearchView.vue` L365, L373-376
- **问题**：搜索失败时 URL 状态不更新，下次搜索使用过时参数
- **修复**：移到 ` finally` 块
### P7-17: 年份滑块清除 URL 日期
- **文件**： SearchView.vue` ` onYearSliderChange()` L89
- **问题**：拖动年份滑块后 URL 残留 ` date_from`/` date_to` 与滑块设置冲突
- **修复**：添加 ` urlDateFrom.value=''; urlDateTo.value=''`
### P7-18: resetAllFilters 清除 URL 日期
- **文件**： SearchView.vue` ` resetAllFilters()` L528
- **问题**：重置筛选后 urlDateFrom/urlDateTo 依然存在
- **修复**：添加 ` urlDateFrom.value=''; urlDateTo.value=''`
### P7-19: MAX_TERMS 保护
- **文件**： pubmed_query_parser.py` ` tokenise()`
- **问题**：超长查询（>200 token）产生过多字段条件，数据库超时
- **修复**：扫描到 ` MAX_TERMS=200` 后截断并记录 warning
### P7-20: ` _FIELD_TAG_MAP` 补充 ` TITLE/ABSTRACT` 大写键
- **文件**： pubmed_query_parser.py` ` _FIELD_TAG_MAP`
- **问题**：解析器 ` .upper()` 产生 ` "TITLE/ABSTRACT"` 但 map 只有 ` "Title/Abstract"`
- **修复**：增加大写键
2026-07-27 14:23:34 +08:00
### P7-21: PubMed 路径中文 tsquery 降级（D2）
- **文件**： search_engine.py` ` _field_condition("all")` L1198
- **问题**：PubMed 路径对无标签中文词（如 ` 肺癌` 在 ` lung cancer OR 肺癌` 中）使用 ` plainto_tsquery("english", 肺癌)` → tsvector 是英语配置 → 返回空 → 零结果。仅当 ` [TI]`/` [AB]` 加字段标签或有通配符时才走 ILIKE
- **根因**：
- **修复**： _field_condition("all")` 默认路径新增中文检测 → ILIKE title/abstract 回退
### P7-22: 裸混合布尔 A OR B AND C 保留 AND 分组（D3）
- **文件**： pubmed_query_parser.py` ` _parse_or_expr()` L475
- **问题**： A OR B AND C` 被拉平为 3 个 term OR： A OR B OR C`。PubMed 语义应是 ` A OR (B AND C)`
- **根因**： _parse_or_expr` 对 ` left`/` right` 做 ` extend`，
2026-07-27 15:15:36 +08:00
- **修复**：收集各 ` _parse_and_expr` 结果为独立 cluster， group_operators="and"`。引擎 OR/mixed 模式将所有正条件 OR 合并，组内 AND
### P7-23: 混合布尔引擎分支 — boolean_operator="mixed" 丢失 OR
- **文件**： search_engine.py` ` _pubmed_conditions()` L616, L952
- **问题**： A OR B AND C` → parser 产 ` boolean_operator="mixed"`。引擎只处理了 ` =="or"`， "mixed"` 落到 else（AND），组间 OR 完全丢失
- **根因**： boolean_operator` 有三种值（and/or/mixed），引擎只有二分支
- **修复**： field_combine` 和 ` term_conditions` 合并都改为 ` in ("or", "mixed")`
2026-07-27 14:23:34 +08:00
2026-07-27 13:01:52 +08:00
---
2026-07-28 11:02:29 +08:00
## 第八轮：第 8 轮深度审计修复（12 项）
**日期**：
**数量**：
**触发**：用户第 4/5 次要求全面检查
**测试**：1007 全部通过，前端构建成功
### P8-1: ATM 缓存未失效（CRITICAL）
- **文件**： cache.py:161-168`
- **修复**： invalidate_search_cache()` 新增 ` await self.delete_pattern("atm:*")` 清理 MeSH 自动词表映射缓存
- **根因**：管道运行后 ` atm:*` 缓存保留，新 MeSH 标签在一小时内不被发现
### P8-2: Pro 方案配额低于 Free（ ）
- **文件**： plans.py:37`
- **修复**： api_quota_per_day: 1_000` → ` 10_000`
- **影响**：Pro 用户不再比 Free 用户更受限
### P8-3: Redis 连接失败永不重试（CRITICAL）
- **文件**： cache.py:20-36`、` rate_limiter.py:37-49`
- **修复**： redis_failed` 标记 60 秒后自动复位，两处统一添加 ` _redis_retry_at` + 60s 退避
### P8-4: 普通搜索中文标签匹配缺失（CRITICAL）
- **文件**： literature.py:276-290`
- **修复**：检测中文输入后查询 ` GlobalTag.name_zh`，匹配时注入 ` GlobalLiterature.id IN (子查询)` 标签条件
- **根因**：普通搜索只做 tsvector + title/abstract ILIKE，完全绕过 MeSH 标签。中文"肺癌"在英文 tsvector 中命中率极低
### P8-5: 限速器突发窗口内存泄漏（HIGH）
- **文件**： rate_limiter.py`
- **修复**：添加 ` _cleanup_stale_burst_windows()` 每 500 次请求清理过期 key，添加 ` _burst_cleanup_counter`
- **影响**：每唯一 IP 在 ` _burst_windows` 留下条目，生产环境数千 IP 可能累积
### P8-6: ASC 排序缺 id tiebreaker（ ）
- **文件**： search_engine.py:1568-1574`
- **修复**： GlobalLiterature.id.asc()` 作为次级排序列
- **根因**： _keyset_condition` 假设 id 是 tiebreaker（ AND id > uid`），但 ` _apply_order_by` 未在 ORDER BY 中包含 id → 值相同的行在翻页时非确定排序
### P8-7: keyset NULL 值缺 id tiebreaker（ ）
- **文件**： search_engine.py:1595-1631`
- **修复**：所有 ` is_(None)` 子句添加 ` and_(col.is_(None), GlobalLiterature.id < uid / > uid)`
- **修复 2**： _cursor_from_item` 对 NULL 列返回 ` "__NULL__"` 哨兵值 → ` _keyset_condition` 新增 ` __NULL__` 精准处理分支
- **根因**：当游标落在 NULL 行后，` is_(None)` 无条件返回所有 NULL 行→重复
### P8-8: ` _field_condition("all")` 缺 journal/affiliation 兜底（MEDIUM）
- **文件**： search_engine.py:1381-1415`
- **修复**：
- tsvector 默认路径追加 ` or_(journal ILIKE, journal_iso ILIKE)`
- ` "/"` 路径追加 abstract、author_names_text、journal
- 中文 ILIKE 路径追加 author_names_text、journal
- **根因**：
### P8-9: Cron 任务缺搜索缓存失效（HIGH）
- **文件**： worker.py:25-28`
- **修复**： daily_ftp_update()` 末尾调用 ` cache.invalidate_search_cache()`
- **根因**： POST /admin/pipeline/run` 做了缓存失效，但 ARQ 定时任务 ` daily_ftp_update`（
### P8-10: AdvancedPubSearchView 交替 #N 循环引用（CRITICAL）
- **文件**： frontend/.../AdvancedPubSearchView.vue:221-239`
- **修复**： resolveQuery()` 添加 ` seen Set<string>` 检测交替循环（#1→#2→#1）
- **根因**：原循环检测只检查 ` current === prev`，对交替引用无效→10 轮迭代产生嵌套垃圾
### P8-11: URL date_preset/year_from/year_to 冲突（MEDIUM）
- **文件**： frontend/.../SearchView.vue:380-396`
- **修复**： restoreFromQuery` 中 ` date_preset` 优先；date_preset 存在时清空 year_from/year_to；无 date_preset 且无 date_from/date_to 时再读 year_from/year_to
### P8-12: 增加中文搜索路径（enhancement）
- **文件**： search_engine.py:1397-1414`
- **修复**： _field_condition("all")` 的 ` /` 路径和中文路径补充 author_names_text、journal ILIKE 覆盖
---
2026-07-28 11:26:35 +08:00
## 第九轮：第 9 轮深度审计修复（5 项）
**日期**：
**数量**：
**触发**：用户第 5 次要求全面检查
**测试**：
### P9-1: MeSH headings 完全从 search_tsv 缺失（CRITICAL）
- **文件**： alembic/versions/g0h1i2j3k4l5_*.py:37-40,83-86`
- **根因**： g0h1i2j3k4l5` 迁移在 trigger 公式中用 ` value->>'name'` 提取 mesh_headings，但所有数据源（PubMed XML 解析、E-utilities、FTP baseline）均使用 ` {'descriptor': desc, 'ui': ui, 'major': major}` 结构，descriptor 存在 ` 'descriptor'` 键而非 ` 'name'`
- **影响**： search_tsv` 的贡献**完全丢失**。纯文本搜索 ` "neoplasms"` 不会通过 tsvector 命中 MeSH 标签。全文搜索回归和 ` ts_rank` 排序也受影响。结构化的 ` [MH]` 字段搜索不受影响（直接查 JSONB）
- **修复**： af4a8b2ec873` 迁移将 ` ->>'name'` 修正为 ` ->>'descriptor'`，并回填全库数据
### P9-2: Affiliation 被从 search_tsv 中剥离（HIGH）
- **文件**： alembic/versions/f1a2b3c4d5e6_*.py:54-56`
- **根因**： f1a2b3c4d5e6` 迁移引入 ` author_names_text` 列（仅含 family），替换了原来在 trigger 中直接 ` value->>'family' || ' ' || COALESCE(value->>'affiliation', '')` 的方式。affiliation 从此从 tsvector 中消失
- **影响**：搜索机构名（如 "Mayo Clinic"、"MD Anderson"）无法通过 tsvector 匹配。ILIKE 兜底也未覆盖 affiliation（只在 ` _field_condition("affiliation")` 专用路径中有 JSONB 子查询）
- **修复**：已在第 8 轮 ` _field_condition("all")` tsvector 路径中补充 journal/journal_iso ILIKE。affiliation 完全恢复需未来迁移将机构名加入 ` author_names_text` 或单独加入 tsvector
### P9-3: 搜索测试套件几乎无断言价值（HIGH）
- **文件**： tests/test_service_search_engine.py`
- **根因**：
- 模块级 ` _cache_patch` 杀死所有缓存路径测试（` _cache.get` 恒为 None）
- 所有 ` search()` 调用只断言 ` result["total"] == 0`——13 个测试全是"不崩溃"烟雾测试
- ` _field_condition` 测试只检查 ` is not None`，不验证生成的 SQL 条件是否正确
- ` db.execute.side_effect` 使用 ` [_smart_mock() for _ in range(N)]`，侧效应列表顺序不验证
- **风险**：搜索引擎 SQL 生成的任何 bug 都不会被这些测试捕获。缓存反序列化、SQL 条件正确性、过滤器逻辑均无断言
### P9-4: ` backfill_search_tsv.py` 严重过期（MEDIUM）
- **文件**： scripts/backfill_search_tsv.py:17-31`
- **根因**：该脚本的 tsvector 公式停留在 ` e341edea85e2` 迁移时代，缺少 ` chemical_list`、` gene_symbols`、` mesh_headings`、` keywords`
- **风险**：任何人运行此脚本会回退全库 search_tsv，丢失所有 C-weight 组分
- **修复**：已重写为包含完整七组分公式并与当前 trigger 一致
### P9-5: 无 ` query` 字符长度限制（LOW）
- **文件**： features.py:52,93-99`
- **根因**： query: str = ""` 无 ` max_length`。只有词数限制（100 词），单个 10K 字符的词可通过验证
- **风险**： ILIKE '%10K_char_word%'` 是大表全扫描，可被用于资源耗尽
---
2026-07-28 11:41:38 +08:00
## 第十轮：第 10 轮深度审计修复（6 项）
**日期**：
**提交**： a985d07`
**数量**：
**测试**：
### P10-1: 缓存键 PubMed/纯文本路径碰撞（MEDIUM）
- **文件**： search_engine.py:33-86,88-144`
- **根因**： _search_cache_key` 和 ` _facet_cache_key` 只对 query 做 ` strip().lower()` 归一化，不区分 PubMed 路径和纯文本路径。相同文本先走 PubMed 路径被缓存，后续纯文本路径命中同样的 key 返回不匹配的结果
- **修复**：在 norm dict 中加入 ` "pm": _is_pm(query)` 标志，两路径缓存键自动分离
### P10-2: OR 模式 NOT 语义错误（HIGH）
- **文件**： search_engine.py:1151-1153`
- **根因**： boolean_operator == "or"` 路径中，代码提取 ` neg_conds` 然后 ` and_(pos_conds + neg_conds)`。正确语义应为 ` A OR NOT B` 等价于 ` A OR (NOT B)`，而非 ` (A) AND (NOT B)`
- **修复**： or_(*term_conditions)`，不做 NOT 分离
- **验证**：原有 ` test_or_mode_mixed_not` 等测试正确通过
### P10-3: Affiliation 始终不在全字段搜索中（MEDIUM）
- **文件**： search_engine.py:1388-1433`
- **根因**： _field_condition("all")` 的 5 条分支（exact/phraseto_tsquery、wildcard ILIKE、"/" 路径、中文路径、tsvector 默认）均未包含 affiliation ILIKE 兜底。虽然 tsvector 默认路径注释写"affiliation 不在 tsvector 中，以 ILIKE 兜底"，但代码中并未实现
- **修复**：所有 5 条分支均添加 ` jsonb_array_elements(authors)` 的 ` ->>'affiliation' ILIKE` 子查询
- **影响**：搜索"mayo clinic"或"MD Anderson"等机构名在全字段搜索中生效
### P10-4: 高级搜索无 query max_length（ ）
- **文件**： features.py:52`
- **修复**： query: str = Field("", max_length=2000)`
- **注意**：延续 P9-5 的修复，Pydantic 层面增加长度限制
### P10-5: 前端缺少 OR 模式切换（MEDIUM）
- **文件**： SearchView.vue:45-46,278-284,547-550`
- **根因**： boolean: 'and'` 硬编码，前端无法发起 OR 搜索
- **修复**：
- 搜索栏添加 AND/OR 选择器（NSelect）
- ` booleanOp` ref 驱动 ` body.boolean`
- URL 同步：` route.query.boolean === 'or'` 恢复
- ` resetAllFilters` 重置
### P10-6: 前端缺少精确短语模式（LOW）
- **文件**： SearchView.vue:45-46,284,548-550`
- **根因**： exact_phrase` 在 TypeScript 接口中存在但从未从前端发送
- **修复**：
- 搜索栏添加"精确短语"复选框
- ` body.exact_phrase` 条件发送
- URL 同步/恢复
---
2026-07-28 12:09:55 +08:00
## 第十一轮：第 11 轮深度审计修复（16 项）
**日期**：
**提交**： 090938f`
**数量**：
**触发**：用户第 6 次要求全面检查
**测试**：
### P0-1: Keyset 翻页 ` title="" or "__NULL__"` 导致下一页空（CRITICAL）
- **文件**： search_engine.py:1692-1695`
- **根因**： _cursor_from_item` 中 ` lit.title or "__NULL__"` — 当 title 为空字符串 ` ""` 时，Python 的 ` or` 短路抛出 ` ""` 产生 ` "__NULL__"` 哨兵值。后续 ` _keyset_condition` 生成 ` title IS NULL AND id > :uid`，由于 title 有 ` NOT NULL` 约束，此条件永远返回零行
- **修复**： lit.title`（无哨兵）；` journal` 列（可为 NULL）保留 ` ... if ... is not None else "__NULL__"` 而非 ` or`
- **同行修复**：相同的 ` lit.journal or "__NULL__"` 也修复为 ` ... if ... is not None else ...`，因为 ` ""` 是 journal 的合法值，不应被哨兵化
### P1-1: 布尔操作符 ` boolean_operator` 受括号内 AND/OR 污染（HIGH）
- **文件**： pubmed_query_parser.py:312-322`
- **根因**： boolean_operator` 检测对全 token 流扫描 AND/OR，不区分括号内外。` (A OR B) AND C` 中 OR 在括号内，但代码同时看到 OR 和 AND → 判定为 ` "mixed"`（抛出错误）
- **修复**：新增 ` depth` 追踪，只在 ` depth=0` 时统计 AND/OR
- **验证**： test_complex_nested`、` test_a4e_double_paren`、` test_a4e_double_paren_operators` 的 ` boolean_operator` 预期从 ` "mixed"` 修正为 ` "and"`
### P1-2: ` is_pubmed_syntax()` 误识别英文单词「and/or/not」（HIGH）
- **文件**： pubmed_query_parser.py:752`
- **根因**： re.search` 使用 ` re.IGNORECASE` 标志。` "diet and exercise in cancer"` 中的 ` and` 被识别为 PubMed 布尔符 → 触发 PubMed 路径 → 删除 "and"、"in" 等 stop words → 搜索结果恶化
- **修复**：移除 ` re.IGNORECASE`。PubMed 官方仅识别**大写** ` AND/OR/NOT` 为布尔符
- **验证**： test_lowercase_boolean_detected` 断言从 ` assert is_pubmed_syntax` 改为 ` assert not is_pubmed_syntax`
2026-07-28 16:33:16 +08:00
- **P20 修订**： is_pubmed_syntax()` 重新添加 ` re.IGNORECASE`（ cancer and therapy` 等小写 PubMed 查询
2026-07-28 12:09:55 +08:00
### P1-3: ` _relevance_query` 对 MeSH-only 查询为空（HIGH）
- **文件**： search_engine.py:605-612`
- **根因**： " ".join(plain_parts).strip() or ""` — ` breast[MAJR]` 这类纯 MeSH 查询的 ` plain_parts` 为空，` _relevance_query` 返回 ` ""` → ` best_match` 路径不会对 tsvector 排序 → 退化到 date sort
- **修复**：改为 ` "...".strip() or query`，保留原始查询作为相关性排序回退
- **影响**：修复后 MeSH-only 查询的正确相关性排序工作
### P1-4: ` pmid_terms` 缺少 int() 异常处理（HIGH）
- **文件**： search_engine.py:1229-1233`
- **根因**： pmid_terms` 处理路径将文本直接 ` int(term.text)`，非数字 PMID 格式（如 DOI 格式内容）导致 ` ValueError` 崩溃
- **修复**：添加 ` try/except ValueError` + DOI ILIKE 兜底，匹配 ` _single_term_condition` 已有的模式
- **验证**： 10.1000/xyz[PMID]` 这类非数字输入不再崩溃
### P1-5: 部分日期 ` YYYY-MM[DP]` 展开为单日而非整月（MEDIUM）
- **文件**： pubmed_query_parser.py:408-447`
- **根因**： 2024-01[DP]` 被解析器直接当作日期值 ` 2024-01-01` 处理，范围查询 ` 2024-01-01:2024-01-01` 只能命中 1 天而非整月
- **修复**：新增 ` _PARTIAL_DATE_RE` 和 ` _expand_partial_date()` 辅助函数，` YYYY-MM` 格式展开为 ` YYYY-MM-01:YYYY-MM-31`（
- **影响**：修复 ` DP`、` EDAT`、` CRDT` 三个字段的部分日期展开
### P1-6: 前端 ` #N ` 引用重复导致循环引用误判（MEDIUM）
- **文件**： AdvancedPubSearchView.vue:resolveQuery()`、` useSearchHistory.ts:expandQuery()`
- **根因**：历史引用 ` #N ` 展开时，若同一个 ` N` 在展开列表中多次出现（如同一条 ` #1 ` 在两个位置被引用），` refs` 数组包含重复元素。循环检测逻辑 ` refs.includes(ref)` 遇到重复 ` #1 ` 误判为循环
- **修复**：两处都加入 ` const uniqueRefs = [...new Set(refs)]` 去重
### P2-1: cache ` invalidate_search_cache` 未清理 ` filter-options`
- **文件**： cache.py:173`
- **修复**： await self.delete("filter-options")` 加入失效列表
### P2-2: worker 管道异常时缓存未清理
- **文件**： worker.py:28-33,44-50`
- **根因**： daily_ftp_update` 和 ` daily_citation_update` 的 ` cache.invalidate_search_cache()` 在正常路径执行，但异常退出时跳过清理
- **修复**： try/finally` 包裹，保证无论成功还是异常都清理搜索缓存
### P2-3: keyset ` cursor_val` 空字符串通过 ` is None` 检查
- **文件**： search_engine.py:1624`
- **根因**： cursor_val is None or cursor_id is None` — 空字符串 ` ""` 不满足 ` is None`，检查通过，后续 SQL 出错后静默回退到 OFFSET
- **修复**：改为 ` not cursor_val or cursor_id is None`
### P2-4: 前端模板条件 ` sort === 'date'` 硬编码
- **文件**： SearchView.vue:908`
- **根因**：只有 ` date` 排序触发 keyset 条件渲染，实际 ` KEYSET_COLUMN_SORTS` 包含 ` date/cited/title/journal/first_author` 五种
- **修复**： sort === 'date'` → ` KEYSET_SORTS.has(sort)`
### P2-5: ` resetAllFilters` 未重置 ` showCustomYear`
- **文件**： SearchView.vue`
- **修复**：重置时补充 ` showCustomYear.value = false`
### P2-6: ` _field_condition("all")` 中文路径遗漏 author/journal ILIKE（ ）
- **备注**：第 10 轮修复了中文路径加入 author/journal ILIKE，已在文档中补全。代码已正确
---
2026-07-27 11:22:22 +08:00
2026-07-28 12:38:17 +08:00
## 第十二轮：第 12 轮深度审计修复（21 项）
**日期**：
2026-07-28 12:38:23 +08:00
**提交**： 6f861c8`
2026-07-28 12:38:17 +08:00
**数量**：
**触发**：用户第 7 次要求全面检查
**测试**：
### P0-1: ` _normalize_field_label` 函数缺失导致 ` (a OR b)[TI]` 崩溃（CRITICAL）
- **文件**： pubmed_query_parser.py:619`
- **根因**： _parse_primary` 对括号组后带字段标签的语法 ` (a OR b)[TI]` 调用 ` _normalize_field_label(_raw_field)`，但此函数从未定义 → ` NameError`。此语法在 PubMed 官方合法，表现为"将整个括号组的搜索结果在 TI 字段中再过滤"
- **修复**：新增 ` _normalize_field_label()` 函数，通过 ` _FIELD_TAG_MAP` 和 ` _SPECIAL_FIELDS` 查找标签映射，` MH:NOEXP` 特殊处理返回 ` "MH"`
- **验证**： (lung OR breast)[TI]` 不再崩溃
### P0-2: 共享列表变异导致 ` result.groups` 被污染（CRITICAL）
- **文件**： pubmed_query_parser.py:577-587`
- **根因**： _parse_and_expr` 中 ` left = self._parse_not_expr(result)` 返回的是 ` result.groups` 中**同一个 Python list 对象**的引用。随后 ` left.extend(right)` 直接修改了 ` result.groups` 中存储的列表，导致后续遍历时出现重复/错乱项
- **修复**：改为 ` left = list(self._parse_not_expr(result))` — 创建副本后再 extend
- **影响**：修复 ` (A OR B) AND C` 类查询中 ` result.groups` 被意外修改的 bug
### P0-3: ` POST /search/advanced` 缺少用户认证（CRITICAL）
- **文件**： features.py:278-283`
- **根因**：高级搜索端点只声明了 ` Depends(get_db)`，没有 ` Depends(get_current_user)`。虽然多租户隔离在 ` get_current_user` 中设置，` AdvancedSearchEngine.search` 内部不依赖 user 参数，但此端点可被未认证用户调用，且缺少统一的审计入口
- **修复**：添加 ` user: dict = Depends(get_current_user)` 参数
- **影响**：高级搜索端点与普通搜索端点（` literature.py`）认证策略一致
### P1-1: ` has_not` 忽略括号内 NOT 词（HIGH）
- **文件**： pubmed_query_parser.py:345-347`
- **根因**： has_not` 属性只检查 ` _ungrouped`（ group_id < 0` 的顶级词）。` NOT (A OR B)` 时 ` a.is_not=True` 正确设置，但词属于 group，不在 ` _ungrouped` 中 → ` result.has_not = False`
- **修复**：添加 ` or any(t.is_not for g in result.groups for t in g)` 检查所有分组内的 ` is_not`
- **验证**： NOT (cancer OR tumor)[TI]` 的 ` has_not` 从 False 修正为 True
### P1-2: 紧凑日期 ` YYYYMMDD` 未归一化（HIGH）
- **文件**： pubmed_query_parser.py:736-749`
- **根因**： _parse_range` 中的日期格式处理只支持 ` YYYY-MM-DD` 和 ` YYYY/MM/DD` 等含分隔符的格式。PubMed 官方支持 8 位紧凑格式 ` 20240115[DP]`，原代码直接传递给 SQL → 类型不匹配错误
- **修复**：新增正则检测 ` ^\d{8}$` 的紧凑日期值，自动归一化为 ` YYYY-MM-DD`
- **验证**： 20240115[DP]` 正确解析为 ` 2024-01-15`
### P1-3: 日期字段传入非日期文本导致 SQL 错误（HIGH）
- **文件**： pubmed_query_parser.py:760-775`
- **根因**： abc:def[DP]` 被拆分为 ` abc` 和 ` def` 两个 Term，后续直接拼接 SQL 范围查询 → ` invalid input syntax for type date` 错误。第三方 API 或其他系统误传非日期内容到日期字段时崩溃
- **修复**：新增 ` _valid_date()` 函数校验日期合法性（格式 + 月份/日范围）；无效值回退为普通文本 ` Term`（字段标签变为普通搜索词），不抛出异常
- **验证**： abc:def[DP]` 不再崩溃，退化到文本搜索
### P1-4: Keyset NULLSLAT 过渡导致 ~50% 空值行跳过（HIGH）
- **文件**： search_engine.py:1637-1681`
- **根因**：每个 sort 分支的第三 ORDER BY 子句 ` nullslast()` 对应的 ` _keyset_condition` 生成 ` and_(col.is_(None), id < cursor_id)`。随机 UUID 无排序语义，` id < cursor_id` 条件会过滤掉约 50% 的 NULL 行
- **修复**：三级 keyset 条件移除 ` id` 约束，仅保留 ` col.is_(None)`
- **影响**：修复后排序列为 NULL 的行不再被随机跳过，翻页结果完整
### P1-5: ` _cursor_from_item` first_author 对非 dict JSON 报错（HIGH）
- **文件**： search_engine.py:1703`
- **根因**： authors[0].get("family")` 假设 ` authors[0]` 是 dict。当 ` authors` JSON 数组包含非 dict 值（如 ` null` 或字符串）时 → ` AttributeError: 'NoneType' object has no attribute 'get'`
- **修复**：添加 ` if authors and isinstance(authors[0], dict):` 保护，否则返回 ` "__NULL__"`
- **验证**： authors: [null]` 或 ` authors: ["Molnar, V"]` 不再崩溃
### P1-6: ` _expand_mesh_tag_ids` 返回 None 时条件静默丢弃（HIGH）
- **文件**： search_engine.py:856-882, 1280-1282`
- **根因**： _expand_mesh_tag_ids()` 未找到匹配的 MeSH 词时返回 ` None`。调用方直接将 ` None` 追加到 ` term_conditions` 列表 → 等同于忽略此搜索条件。用户搜索一个不存在/未收录的 MeSH 词时无任何反馈，隐式返回全部文献
- **修复**：当 ` cond is None` 且 ` not is_neg` 时，追加 ` text("FALSE")`（无匹配 = 零结果，正确语义）。NOT 路径下 ` None` 仍然合法（否定一个不存在的 MeSH = 全部通过）
- **验证**： nonexistent_mesh[MeSH]` 不再返回全部文献，返回零结果
### P1-7: ` _relevance_query` 包含否定词（HIGH）
- **文件**： search_engine.py:608-611`
- **根因**：构建 ` plain_parts` 时遍历所有 ` terms` 未过滤 ` t.is_not`。否定词 "NOT X" 中的 X 被纳入相关性排序 tsquery → 相关性分数被不应出现的否定词影响
- **修复**：四个 ` plain_parts.append` 路径全部添加 ` if not t.is_not` 过滤
### P1-8: 普通搜索 PubMed 语法检测在词数限制之后（HIGH）
- **文件**： literature.py:275-332`
- **根因**： len(q.split()) > 100` 的词数检查在 ` is_pubmed_syntax()` 解析/清洗之前。PubMed 带字段标签的查询 ` cancer[TI] OR tumor[TI] OR ...` 虽然语义上只有少数真实词，但 ` split()` 将每个 ` cancer[TI]` 算作一词 → 密集字段标签查询被错误拒绝
- **修复**：先执行 ` is_pubmed_syntax()` 和 field tag 清洗，再检查清洗后的文本长度
- **验证**： cancer[TI] AND (lung[TI] OR breast[TI] OR colon[TI])`（清洗后仅 5 词）不再被误阻止
### P1-9: 普通搜索缺少错误处理（HIGH）
- **文件**： literature.py:275-332`
- **根因**：整个 DB 查询块无 try/except。搜索缓存 MISS + DB 故障时返回 500 给用户，前端无降级展示
- **修复**： try/except Exception` 包裹，返回 ` {"items":[], "total":0, "error":"搜索服务暂不可用"}`
- **影响**：用户可见的"搜索服务暂不可用"提示，而非白页或 500
### P1-10: ` #N ` 引用解析引号感知不完整（HIGH）
- **文件**： AdvancedPubSearchView.vue:227-235`、` useSearchHistory.ts:28-35`
- **根因**： expandQuery()` / ` resolveQuery()` 中 ` /#(\d+)/g` 全局匹配未排除引号内的 ` #N `。历史记录中 ` "PD-1 #1 biomarker"` 的 ` #1 ` 被错误展开
- **修复**：替换为 ` "[^"]*"|'[^']*'|#(\d+)` 正则，先匹配引号内容（直接返回原文），再匹配引号外的 ` #N `
- **验证**： "mechanism #1 " 和 "review #1 "` 中的 ` #1 ` 不再被展开
### P2-1: ` _expand_partial_date` 月越界（LOW）
- **文件**： pubmed_query_parser.py:700-730`
- **根因**： YYYY-13` 这类非法月份传入 ` _expand_partial_date` 后直接构建 ` YYYY-13-01` → SQL 日期解析报错
- **修复**：添加月份范围检查 ` 1 <= int(month) <= 12`；非法月份回退为全年范围 ` YYYY-01-01` 到 ` YYYY-12-31`
### P2-2: ` _single_term_condition` MH/MAJR 返回 FALSE 而非 None
- **文件**： search_engine.py:1280-1282`
- **修复**： _expand_mesh_tag_ids` 返回 None 时，MH/MAJR 返回 ` text("FALSE")` 替代原先的 ` None`，保持与 P1-6 一致的语义
### P2-3: ` field` 验证器缺少 language/volume/issue/pages/lid
- **文件**： features.py:108-114`
- **根因**： @field_validator ('field')` 的白名单只包含 ` all/title/abstract/author/affiliation/journal`，实际搜索引擎支持 ` language/volume/issue/pages/lid` 的全路径搜索
- **修复**：添加 ` 'language', 'volume', 'issue', 'pages', 'lid'` 到允许列表
### P2-4: ` @field_validator ` 缺失 ` retracted`/` negative_result`/` tag_ids`
- **文件**： features.py:116-140`
- **根因**：高级搜索接口 ` AdvancedSearchRequest` 模型未对枚举值 ` retracted`（ negative_result`（ tag_ids` 未做 UUID 格式验证。异常值直接传入 DB 查询
- **修复**：新增三个 ` @field_validator `： check_retracted`、` check_negative_result`、` check_tag_ids`
### P2-5: 高级搜索 ` resolveQuery` 重复调用
- **文件**： AdvancedPubSearchView.vue:307-323`
- **根因**： validateQuery` 内部先调用了一次 ` resolveQuery`，外层 ` expanded` 又调用一次。重复解析消耗性能且可能暴露循环引用漏洞
- **修复**： validateQuery` 返回解引用后的结果，外层复用
### P2-6: ` SearchRequestBody.page` 声明为 required 但运行期删除
- **文件**： types/index.ts:329`
- **根因**： page: number`（必填），但 ` features.py` 的 ` get_search_cache_key` 在构建缓存键时对 ` page=1` 调用 ` del norm["page"]`。前端类型声明与后端实际行为不一致
- **修复**： page: number` → ` page?: number`（可选）
### P2-7: ` restoreFromQuery` 未设置 ` showCustomYear`
- **文件**： SearchView.vue`
- **根因**：从 URL query string 恢复 ` year_from` 和 ` year_to` 时重置了筛选面板但忘记设置 ` showCustomYear.value = true`，导致年份输入框不可见
- **修复**：在 ` year_from` 和 ` year_to` 恢复路径后添加 ` showCustomYear.value = true`
---
2026-07-28 12:59:38 +08:00
## 第十三轮：第 13 轮深度审计修复（21 项）
**日期**：
2026-07-28 12:59:44 +08:00
**提交**： 1d34535`
2026-07-28 12:59:38 +08:00
**数量**： ）
**触发**：用户第 8 次要求全面检查
**测试**：
### P0-1: ` _SPECIAL_FIELDS` 为 ` set` 类型，误调用 ` .get()` 导致 ` AttributeError`（ ）
- **文件**： pubmed_query_parser.py:44-49`
- **根因**： _normalize_field_label()` 函数在第 48 行调用 ` _SPECIAL_FIELDS.get(raw)`。但 ` _SPECIAL_FIELDS` 是 Python ` set` 字面量（` {...}`），没有 ` .get()` 方法。Python 在求值 ` _FIELD_TAG_MAP.get(raw, _SPECIAL_FIELDS.get(raw))` 时会先计算第二个参数，无论 ` raw` 是否在 ` _FIELD_TAG_MAP` 中都会触发 ` AttributeError`。` parse_pubmed_query` 的 ` except` 只捕获 ` (ParseError, IndexError, ValueError)`， AttributeError` 传播到调用方 → 500 错误
- **修复**：拆分为三行：` if raw in _FIELD_TAG_MAP: return _FIELD_TAG_MAP[raw]` + ` if raw in _SPECIAL_FIELDS: return raw` + ` return None`
- **影响**： (cancer)[TI]`、` (a OR b)[DP]` 等所有带字段标签的括号组全面崩溃。本轮修复后恢复正常
- **验证**： (lung cancer OR breast cancer)[TI]` 不再崩溃
### P1-1: ` exclude_preprints` 丢弃 ` is_preprint=NULL` 记录（HIGH）
- **文件**： search_engine.py:541-542`
- **根因**： GlobalLiterature.is_preprint == False` 生成 ` WHERE is_preprint = false`。` is_preprint` 为 ` NULL` 的旧文献（未解析此字段）被排除。` NULL = false` 在 SQL 三值逻辑中为 ` NULL` → 被 WHERE 过滤
- **修复**：改为 ` GlobalLiterature.is_preprint != True`，生成 ` is_preprint IS DISTINCT FROM true`（
- **验证**：开启 ` exclude_preprints` 筛选后，` is_preprint=NULL` 的记录不再被静默丢弃
### P1-2: 普通搜索 ` boolean="or"` 模式下数字词和文本词被 AND 连接（HIGH）
- **文件**： search_engine.py:341-405`
- **根因**： boolean="or"` 时数字词条件（如 PMID 匹配）和文本词条件各自 OR 化后作为独立的元素加入 ` conditions` 列表。最终 ` and_(*conditions)` 将两者 AND 连接。例如 ` "12345 cancer"` 且 ` boolean="or"`：用户期望 ` PMID=12345 OR 包含cancer`，实际执行 ` PMID=12345 AND 包含cancer`
- **修复**：在数字词和文本词处理完成后，如果 ` boolean == "or"`，将 ` _term_start` 之后的所有词条件合并为一个 ` or_(*_term_conds)`
- **验证**： "30221571 pembrolizumab"` 且 ` boolean="or"`，结果应为 PMID 30221571 或包含 pembrolizumab 的文章（OR），而非同时满足
### P1-3: Journal 排序 keyset 忽略 ` journal_iso` 排序列（HIGH）
- **文件**： search_engine.py:1618-1621`
- **根因**： _apply_order_by("journal")` 返回 ` [journal ASC, journal_iso ASC, id ASC]`。但 ` _keyset_condition` 只处理 ` journal` 和 ` id`，完全忽略 ` journal_iso`。同名期刊不同 ISO 缩写（如 ` Nature` / ` Nature (Lond.)` / ` Nature (London)`）的文献在 keyset 翻页时被错误跳过
- **修复**：从 journal ORDER BY 中移除 ` journal_iso`（
- **影响**：
### P2-1: 日期字段 ` _dispatch_term` 未验证非日期文本（MEDIUM）
- **文件**： pubmed_query_parser.py:436-533`
- **根因**： cancer[DP]`、` foo[EDAT]` 等非日期文字传入日期字段时，` _dispatch_term` 的 else 分支直接赋值 ` result.date_from = term.text`。` "cancer"` 作为非法日期值传入 PostgreSQL 查询 → ` invalid input syntax for type date`
- **修复**： _validate_date_str()` 检查，非法文本路由到 ` plain_terms`
- **验证**： cancer[DP]` 不再导致 SQL 错误，退化到文本搜索
### P2-2: 日期范围回退保留日期字段标签（MEDIUM）
- **文件**： pubmed_query_parser.py:752-754`
- **根因**： lung:cancer[DP]` 范围中 ` cancer` 不是合法日期，` _parse_range` 返回 ` Term(txt, field="DP", ...)`。` _dispatch_term` 的 DP 分支将 ` "lung:cancer[DP]"` 作为非法日期值处理
- **修复**：回退 Term 的 ` field` 设为 ` None`（而非保留 ` field`），使其路由到 ` plain_terms`
- **影响**：非法日期范围内容降级到纯文本搜索
### MINOR-1: ` 二月` 始终被扩展为 29 天，非闰年产生非法日期
- **文件**： pubmed_query_parser.py:31-41`
- **根因**： _LAST_DAY[2] = 29` 对所有年份生效。` 2023-02[DP]` 被展开为 ` 2023-02-01` 到 ` 2023-02-29`，其中 ` 2023-02-29` 是非法日期
- **修复**：新增 ` _is_leap_year()` 函数；` _expand_partial_date()` 中对 ` month == 2 and last_day == 29` 且非闰年时置 ` last_day = 28`
### MINOR-2: ` _validate_date_str` 缺失日历正确性校验
- **文件**： pubmed_query_parser.py:749-751`
- **根因**： _valid_date` lambda 只校验格式（是否为 YYYY 或 YYYY-MM-DD），不校验月份范围（1-12）和日期范围（1-月末）。` 2024-13-01`、` 2024-01-32` 等非法日历日期通过校验
- **修复**：新增 ` _validate_date_str()` 替代原 lambda，完整校验格式 + 月份范围 + 日期范围 + 闰年 2 月
### MINOR-3: 尾部 AND 产生空 Term
- **文件**： pubmed_query_parser.py:595-597`
- **根因**： _parse_and_expr` 消耗 AND token 后未检查 EOF。` cancer AND` 中 ` AND` 后的 ` _parse_not_expr` 推进到 EOF 后返回空 Term
- **修复**： self.advance()` 后检查 ` self.peek().type == TokenType.EOF → break`
### MINOR-4: 精确短语 "all" 搜索缺少 journal ILIKE 回退
- **文件**： search_engine.py:1415-1424`
- **根因**： exact=True` 时 ` _field_condition("all")` 只搜索 tsvector（
- **修复**：在精确短语路径中加入 ` GlobalLiterature.journal.ilike(pat)` 和 ` GlobalLiterature.journal_iso.ilike(pat)`
---
2026-07-28 13:21:24 +08:00
## 第十四轮：第 14 轮深度审计修复（21 项）
**日期**：
2026-07-28 13:21:38 +08:00
**提交**： daf169d`
2026-07-28 13:21:24 +08:00
**数量**： ）
**触发**：用户第 9 次要求全面检查
**测试**：
### BUG-1 (HIGH): 非 DP 日期字段单年值未设置专用 ` *_from`/` *_to`
- **文件**： pubmed_query_parser.py:480-561`
- **根因**： 2024[EDAT]`、` 2024[CRDT]` 等非 DP 日期字段的单年值只设置了共享的 ` year_from`/` year_to`，未设置专用的 ` edat_from`/` edat_to`。` _pubmed_conditions`（ DATE_FIELD_COLS` 并使用专用属性构建列条件，但解析器从未填充这些属性 → EDAT/CRDT/MHDA/LR/DCOM/DEP 的单年值过滤完全静默失效
- **影响**：用户输入 ` 2024[EDAT]` 期望按入库日期过滤，实际得到的是 ` pub_year >= 2024`（近似日期，语义错误）。EDAT 列过滤完全 skipped
- **修复**：6 个非 DP 日期字段的单年值分支改为设置专用的 ` *_from`=` YYYY-01-01` 和 ` *_to`=` YYYY-12-31`，不再设置 ` year_from`/` year_to`
### BUG-2 (HIGH): 跨日期字段 ` year_from`/` year_to` 互相覆盖
- **文件**： pubmed_query_parser.py:480-561`
- **根因**： year_from`/` year_to` 是 ` ParsedPubmedQuery` 的共享属性。` 2024[DP] AND 2025[EDAT]` 中 DP 先设置 ` year_from=2024`， year_from=2025` → DP 条件完全丢失。最终引擎只看到 ` pub_year >= 2025`
- **影响**：用户查询 ` 2024[DP] AND 2025[EDAT]` 期望「2024年出版 AND 2025年入库」，实际得到「2025年出版」（DP 条件丢失）
- **修复**：非 DP 日期字段不再设置 ` year_from`/` year_to`（仅设置专用字段）。DP 字段保持设置 ` year_from`/` year_to`。引擎 section 6b 已通过专用字段正确生成 SQL 条件
### BUG-3 (MINOR): MHDA/LR/DCOM/DEP 缺少 ` _PARTIAL_DATE_RE` 分支
- **文件**： pubmed_query_parser.py:510-561`
- **根因**： elif _PARTIAL_DATE_RE.match(term.text)` 的展开步骤。` 2024-02[MHDA]` 被降级为纯文本搜索而非展开为整月范围。DP/EDAT/CRDT 已有此分支
- **修复**：为 4 个字段各添加 ` _PARTIAL_DATE_RE` 展开分支，使用各自的专用属性（` mhda_from/mhda_to` 等）
### BUG-4 (MINOR): ` _single_term_condition` 未处理括号组内日期字段
- **文件**： search_engine.py:1358-1362`
- **根因**： _single_term_condition` 处理了所有 30+ 特殊字段（MH/PT/GR/SH/RN 等），但完全遗漏了日期字段（DP/EDAT/CRDT/MHDA/LR/DCOM/DEP）。括号组 ` (2024[DP] OR 2025[DP])` 中的日期词回退到全文本 ILIKE ` %2024%`
- **修复**：在回退前添加日期字段处理：4 位数年份展开为全年范围列条件，完整日期使用列等值条件。` DP → pub_year/pub_date`， EDAT → entrez_date`， CRDT → create_date`， MHDA → meshed_date`， LR → pubmed_revised`， DCOM → date_completed`， DEP → pub_date`
- **验证**： (2024[EDAT] OR 2025[EDAT])` 正确生成 ` entrez_date 年内范围 OR` 条件
---
2026-07-28 13:50:37 +08:00
## 第十五轮：第 15 轮审计（1 项修复）
**日期**：
**提交**： 5698d94`
**数量**： ）
**触发**：用户第 10 次要求全面检查
**测试**：
**审计范围**：端到端字段分发审计、缓存/Facet 一致性审计、前端参数发送审计（3 并行 agent）
### ` __RANGE_*` 标记在括号组内被错误过滤
- **文件**： search_engine.py:1138`
- **根因**： _parse_range()` 在解析 ` 2024:2025[EDAT]` 等日期范围时，为表明此语法已在顶层 ` _parse_range` 中直接设置 ` result.edat_from/edat_to`，生成了一个副作用的 ` __RANGE_EDAT__` 标记 Term（ _is_range_end=True`）。该标记在顶层被正确过滤（不进入 ` _dispatch_term`），但出现在括号组内 ` (2024:2025[EDAT] AND cancer)` 时，` _parse_primary` 将其与组内其他词一起放入 ` result.groups`。` _pubmed_conditions` 遍历组内词调用 ` _single_term_condition()` 时，` __RANGE_EDAT__` 无对应 handler → 回退到 ` _field_condition("all", "2024:2025")`，将范围值当作纯文本搜索 → SQL 中多出一条无意义条件 ` search_tsv @@ plainto_tsquery('2024:2025')`，返回零结果（静默数据丢失）
- **影响**：任何包含 ` (start:end[date-field] ...)` 括号组的 PubMed 查询，日期范围条件按顶层 AND 正确应用，但括号组内多出一条多余的假条件，导致符合条件的文献被错误排除。单条 ` 2024:2025[EDAT]`（无括号组）不受影响
- **修复**：在 ` _pubmed_conditions` 的组遍历循环中，在调用 ` _single_term_condition` 前检查 ` getattr(t, '_is_range_end', False)`，是则跳过
- **验证**： (2024:2025[EDAT] AND cancer)` 不再因为多余的 ` __RANGE_EDAT__` 过滤而返回零结果。完全等效于 ` 2024:2025[EDAT] AND cancer`
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| 端到端字段分发（parser→engine） | ✅ 所有 30+ 字段标签正确分发。` __RANGE_*` 在组内回退已修复 |
| 缓存键参数完备性 | ✅ ` _search_cache_key` + ` _facet_cache_key` 包含全部参数 |
| Facet 查询与主查询一致性 | ✅ 条件完全一致 |
| ` DATE_FIELD_COLS` 列名映射 | ✅ 6 列全部正确 |
| 前端参数发送 | ✅ SearchView.vue 完整发送全部 28 个参数 |
| Plan P1-4/P1-7/P1-8/F-1 | ✅ 前期轮次已全部实现 |
---
2026-07-28 14:08:46 +08:00
## 第十六轮：第 16 轮审计修复（4 项修复 + 3 项记录）
**日期**：
2026-07-28 15:12:13 +08:00
**提交**： de1f4a4`
2026-07-28 14:08:46 +08:00
**数量**：4 项修复 + 3 项记录
**触发**：用户第 11 次要求全面检查（Round 16， ：
**测试**：
### Bug-1 (MEDIUM): ` _parse_primary` 括号组内重复 group 赋值
- **文件**： pubmed_query_parser.py:706-709`
- **根因**： _parse_or_expr` 在 ` A OR B AND C` 时为 ` [B, C]` 创建 sub-group。随后 ` _parse_primary` 将所有 terms（含已 sub-group 的）再统一加到 parent group。sub-group 内的 term 同时出现在两个 group → ` _pubmed_conditions` 遍历 group 列表时为其生成两套条件 → SQL 中产生重复/多余的过滤条件，静默排除合法结果
- **影响**： NOT (A OR B AND C)` 类带 sub-group 的括号组查询可能返回零结果
- **修复**： _parse_primary` 只从 ` t.group_id < 0`（未分配）的 term 创建 parent group。sub-group 已分配的不再加入。同时增加 depth 守卫：` _parse_or_expr` 在 ` self._depth > 0`（括号内）时直接 flat 返回，不创建 sub-group
### Bug-2 (MEDIUM): ` all_not` 混淆外部 NOT 与内部 NOT
- **文件**： search_engine.py:1134-1172`
- **根因**： all_not = all(t.is_not for t in group)` 无法区分 ` NOT (A OR B)`（外部 NOT：应生成 ` not_(or_(A, B))`） (NOT A OR NOT B)`（内部 NOT：应生成 ` or_(not_(A), not_(B))`）。两者都 ` all_not=True`，但语义完全不同
- **修复**：
- 解析器端：新增 ` ParsedPubmedQuery.group_negated: list[bool]` 字段，` _parse_primary` 在创建 parent group 时记录是否为外部 NOT wrapper
- 引擎端：用 ` group_negated[idx]` 替代 ` all_not`，外部 NOT 走 ` not_(combine_fn(g_neg))`，内部 NOT 走 ` combine_fn(g_pos + g_neg_with_not_)`
- **验证**： NOT (A OR B)` 与 ` (NOT A OR NOT B)` 生成不同的 SQL 条件组合
### Bug-3 (MEDIUM): 搜索错误显示为"no results"
- **文件**： SearchView.vue:365-367`
- **根因**： toast.apiError()`（瞬态通知提示），但 ` results = []` 导致 ` <NEmpty>` 显示"未找到匹配文献"，用户以为搜索有结果只是条件过严，实际是后端错误
- **修复**：新增 ` searchError` ref，catch 时设置明确错误信息，模板条件渲染 ` <NResult>` 错误面板替代 ` NEmpty`。成功搜索时清除 ` searchError`
### Bug-4 (LOW): UUID 类型转换在中文标签子查询中
- **文件**： literature.py:293-294`
- **根因**： [str(t) for t in _tag_matches]` 将 UUID 转字符串后传给 ` in_(...)`，某些驱动下可能导致类型不匹配
- **修复**：改为 ` list(_tag_matches)` 传递原生 UUID 对象
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| Normal 搜索边缘情况 | ✅ ` _parse_primary` 重复 group 已修复。PubMed 降级路径 field tag 清洗已正确。ATM 展开括号剥离已正确 |
| 前端参数发送 | ✅ SearchView.vue 完整发送全部 28 个参数，` SearchRequestBody` 类型正确 |
| NOT 检测 | ✅ ` group_negated` 新增 track， all_not` 已替换。NOT-wrapped parens 与 sub-group 交互部分缓解（depth guard）。剩余 De Morgan 双重否定场景（LOW，理论正确性，实际罕见） |
---
2026-07-28 15:46:20 +08:00
## 第十八轮：第 18 轮审计修复（6 项）
**日期**：
**提交**： 5fa2fbe`（与第 17 轮同一提交）
**数量**： ）
**触发**：用户第 13 次要求全面检查（Round 18， ：
**测试**：
### Bug-R18-1 (MEDIUM): MH:NOEXP 在括号组内被忽略
- **文件**： pubmed_query_parser.py:710-712`
- **根因**： (lung OR breast)[MH:NOEXP]` 的 ` [MH:NOEXP]` 末尾字段标签被 ` _normalize_field_label` 返回 ` "MH"`，但 ` _noexp=True` 未传播到括号组内的各个 term。组内每个 term 照常走 MeSH 展开路径（` mesh_headings JSONB contains`），无视 NOEXP 要求
- **修复**：在 ` _parse_primary` 中，` _raw_field.startswith("MH:") and "NOEXP" in _raw_field.upper()` 时，将该 field 对应 group 内所有 term 标记 ` _noexp=True`
- **验证**： (lung OR breast)[MH:NOEXP]` 正确使用 ` mesh_headings JSONB contains` 而非 ` explode`
### Bug-R18-2 (MEDIUM): 日期范围 full_date:year 同一年份不交换
- **文件**： pubmed_query_parser.py:806,812`
- **根因**： 2024-12-31:2024[DP]` 的 swap 条件 ` int(start_val[:4]) > int(end_val)` → ` 2024 > 2024` 为 False，不触发交换。` 2024-12-31`（完整日期）作为 start， 2024`（纯年份）作为 end， _parse_range` 解释器要求 start ≤ end 才能正确生成范围条件
- **修复**：将两个 swap 条件从 ` >` 改为 ` >=`
- **验证**： 2024-12-31:2024[DP]` 正确交换为 ` 2024:2024-12-31`
### Bug-R18-3 (HIGH): 非 DOI "/" 路径缺失 journal_iso ILIKE
- **文件**： search_engine.py:1538-1547`
- **根因**： _field_condition("all")` 的 "/" 分支（非 DOI、非 Chinese、非通配符）包含 ` journal ILIKE` 但缺少 ` journal_iso ILIKE`。其他所有 ILIKE 分支（wildcard、text、Chinese）都同时包含 ` journal` 和 ` journal_iso`。只有此分支遗漏了 ` journal_iso`
- **影响**：PubMed 等数据库中大量缩写刊名通过 ` journal_iso` 存储，纯文本搜索不含斜杠的词时，缩写刊名匹配性能低于应有水平
- **修复**：在 ` or_(...)` 中加入 ` GlobalLiterature.journal_iso.ilike(like_val)`
### Bug-R18-4 (MEDIUM): Chinese 路径缺失 journal_iso/pmid/doi ILIKE
- **文件**： search_engine.py:1549-1557`
- **根因**： or_(...)` 仅包含 ` title/abstract/author_names_text/journal ILIKE` + ` affiliation EXISTS`，比通配符分支少了 ` journal_iso`、` pmid` 和 ` doi` 字段
- **修复**：补全 ` journal_iso.ilike(like_val)`、` cast(GlobalLiterature.pmid, String).ilike(like_val)`、` GlobalLiterature.doi.ilike(like_val)`
### Bug-R18-5 (MEDIUM): PA 仅检查 name 不检查 ui
- **文件**： search_engine.py:1011,1015,1369`
- **根因**： pharmacological_actions JSONB contains` 只检查 ` {"name": t.text}`。但 PubMed PA 字段允许按 UI（唯一标识符）搜索，如 ` d015056[PA]`（ pharmacological_actions` JSONB 中同时存储 ` name` 和 ` ui`，但代码只匹配 ` name`
- **影响**：按 UI 搜索 PA 时返回零结果
- **修复**：批量路径（` _pubmed_conditions` 的 PA 块）和单路径（` _single_term_condition`）均改为 ` or_(contains({"name": ...}), contains({"ui": ...}))`
### Bug-R18-6 (MEDIUM): text 变量遮蔽 SQLAlchemy text()
- **文件**： search_engine.py:1417`
- **根因**： _single_term_condition` 中日期字段分支内 ` text = term.text` 将 ` text` 作为局部变量。虽然此后该分支未再调用 ` text()`，但 ` text` 命名会遮蔽 Python 内置/导入的 ` text()`。若未来在该分支后增加 SQL text() 调用，将产生不易追踪的错误
- **修复**：重命名为 ` _term_text`
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| SQL 生成全路径 | ✅ "/" 分支 journal_iso 、Chinese 分支补全、PA ui 检查均已修复 |
| Pub 高级搜索前端 | ✅ 无代码级 bug（auth 限制属设计决策、#N 解析由前端覆盖、公共路由约束合理） |
| 解析器/搜索 parity | ✅ MH:NOEXP 组内传播、日期 swap 边界均已修复 |
| text() 变量名 | ✅ 已重命名为 ` _term_text` |
---
2026-07-28 16:11:19 +08:00
## 第十九轮：第 19 轮审计修复（10 项）
**日期**：
**提交**： 1401bb7`
**数量**： ）
**触发**：用户第 14 次要求全面检查（Round 19，
**测试**：
### Bug-R19-1 (HIGH): ` NOT (A OR B)` 与 ` (NOT A OR NOT B)` 结构完全一致
- **文件**： pubmed_query_parser.py:680-691`
- **根因**： _parse_not_expr` 对 ` NOT (A OR B)` 的处理是遍历组内所有 term 并翻转 ` t.is_not`，但不设置 ` group_negated[gid]=True`。引擎端看到的是：组 operator=or、所有 term 的 ` is_not=True`、` group_negated=False` → 生成 ` or_(not_(cond_A), not_(cond_B))`。但 PubMed 语义是 ` not_(or_(cond_A, cond_B))` = ` NOT (A OR B)` = ` NOT A AND NOT B`。两者 De Morgan 不等价（一个是 AND，一个是 OR）。
- **影响**：任何 ` NOT (...)` 查询的组内布尔逻辑完全错误。例如 ` NOT (lung OR breast)` 返回 ` NOT A OR NOT B` 结果而非 ` NOT A AND NOT B`。
- **修复**：当 ` _parse_not_expr` 翻转 inner term 的 ` is_not` 后，检查是否所有 term 都属于组（` group_id >= 0`）。若是，则**撤销** per-term 翻转，改为设置 ` result.group_negated[gid] = True`。
### Bug-R19-2 (MEDIUM): R18 日期 swap year:full_date 边界过宽
- **文件**： pubmed_query_parser.py:810`
- **根因**：R18 将两个 swap 条件统一改为 ` >=`，但 year:full_date 和 full_date:year 应区别对待。` 2024:2024-03-01[DP]`（ int(2024) >= int(2024)` → True → 错误 swap 为 Q2-Q4。
- **修复**： >`（仅 start year > end year 时才 swap），full_date:year 分支保留 ` >=`。
### Bug-R19-3 (MEDIUM): ` group_negated` 长度与 ` groups` 不匹配
- **文件**： pubmed_query_parser.py:648-649`
- **根因**： _parse_or_expr` 的 AND 聚类创建 sub-group 时追加到 ` groups` 和 ` group_operators`，但未追加到 ` group_negated`。当父括号组和 AND sub-group 同时存在时，` groups` 长度 > ` group_negated` → ` _pubmed_conditions` 中 ` group_negated[idx]` → ` IndexError`。
- **修复**： result.group_negated.append(False)`。
### Bug-R19-4 (LOW): 括号内 AND 聚类丢失
- **文件**： pubmed_query_parser.py:638-640`
- **根因**： _depth > 0` 守卫跳过括号内的 AND subgroup 创建。` (A OR B AND C)` 被扁平化为 ` [A, B, C]` 后用 OR 组合 → 输出 ` A OR B OR C` 而非正确语义 ` A OR (B AND C)`。
- **修复**：移除 ` if self._depth > 0: return all_terms` 守卫（依赖 Bug-R19-3 的 ` group_negated.append(False)`）。
### Bug-R19-5 (MEDIUM): 混合大小写引号短语丢失 exact 标记
- **文件**： search_engine.py:430,433`
- **根因**： _phrase_terms_set = set(p.lower() ...)` 使用小写键，但 ` term in _phrase_terms_set` 用原始大小写比较。` "Lung Cancer" in {"lung cancer"}` → False → exact_phrase 不被强制。
- **影响**： "Lung Cancer"` 在 ` exact_phrase=False` 模式下退化为 ` plainto_tsquery`（词序无关），可能匹配 "Cancer Lung"。
- **修复**：改为 ` term.lower() in _phrase_terms_set`。
### Bug-R19-6 (HIGH): 公共搜索完全不可用
- **文件**： features.py:282`, ` literature.py:256`
- **根因**： /features/search/advanced` 和 ` /literature/search` 两个搜索端点都依赖 ` get_current_user`， user` 参数未被任何函数体使用。匿名用户访问时返回 401。公共搜索路由完全无法使用。
- **修复**：移除两个端点的 ` user: dict = Depends(get_current_user)` 依赖。
### Bug-R19-7 (MEDIUM): ` message.warning()` 副作用在 Vue computed 中
- **文件**： AdvancedPubSearchView.vue:244-246`
- **根因**： resolveQuery()` 在 ` #N ` 引用不存在时调用 ` message.warning()`。该函数从 ` translated` computed 调用（每次 queryText 变化时重评估），导致响应式循环中弹出 toasts。
- **修复**：移除 ` message.warning()` 调用。` #N ` 不存在时直接返回原样（` validateQuery` 已在校验时给出错误提示，此处冗余）。
### Bug-R19-8 (MEDIUM): 搜索错误信息不区分状态码
- **文件**： SearchView.vue:369`
- **根因**：catch 块对所有错误使用统一提示"，忽略 401/400/429/500 的差异化信息。公共搜索用户看到"网络问题"提示，实际是未登录。
- **修复**：检查 ` e?.response?.status`，区分 401（未登录）、400（参数错误）、429（限流）、500（服务异常）的场景。
### Bug-R19-9 (HIGH): R18 text 重命名遗留未引用
- **文件**： search_engine.py:1445,1448`
- **根因**： text = term.text` 重命名为 ` _term_text = term.text`，但两处引用 ` _vds(text)` 和 ` fromisoformat(text)` 仍使用原变量名 ` text`（解析为 SQLAlchemy ` text` 函数对象 → AttributeError → 降级）。
- **影响**：括号组内非 4 位数字的日期字段（如 ` (2024-01-01[DP] OR cancer)`）静默降级到纯文本搜索。
- **修复**：两处 ` text` → ` _term_text`。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R18 回归（text 重命名） | ✅ ` _vds(_term_text)` + ` fromisoformat(_term_text)` 已修复 |
| R18 回归（日期 swap） >`， >=` |
| 解析器 NOT 语义 | ✅ ` NOT (A OR B)` 现已正确使用 ` group_negated` |
| 解析器组结构 | ✅ ` group_negated` 长度对齐、AND 聚类括号内启用 |
| 搜索引擎路径 | ✅ 混合大小写短语 exact 标记已修复 |
| 前端搜索 | ✅ 公共搜索可用、错误信息区分、` message.warning` 副作用消除 |
---
2026-07-28 16:30:03 +08:00
## 第二十轮：第 20 轮审计修复（6 项）
**日期**：
**提交**： 2b6ffd6`（与第 19 轮同一提交基础上追加）
**数量**： ）
**触发**：用户第 15 次要求全面检查（Round 20， ：
**测试**：
### Bug-R20-1 (HIGH): AND 子组在括号内被提升为顶层 AND 条件
- **文件**： pubmed_query_parser.py`（ _parse_primary` + ` _parse_or_expr`）、` search_engine.py`（组处理循环）
- **根因**：第 19 轮移除了 ` _depth > 0` 守卫，` _parse_or_expr` 在括号内创建 AND 子组（如 ` (A OR B AND C)` → sub-group ` [B,C]`， [A]`）。但引擎将两个组独立处理后全部 AND 在一起 → ` A AND B AND C`。正确语义应为 ` A OR (B AND C)`。
- **影响**：任何括号内混用 AND/OR 的查询（如 ` (lung OR breast cancer)`）结果被严重过滤。
- **修复**：
- 解析器：新增 ` ParsedPubmedQuery.sub_group_refs: list[list[int]]` 记录 parent→child 关系
- ` _parse_primary` 在创建父组时记录子组 GID
- 引擎跳过子组（由父组处理），父组处理时包含自身 term + 子组条件，用父组操作符组合
- **验证**： (A OR B AND C)` 正确生成 ` or_(A, and_(B, C))`
### Bug-R20-2 (HIGH): OR 模式 NOT 条件未独立 AND
- **文件**： search_engine.py:1234-1236`
- **根因**： boolean_operator == "or"` 时所有条件（含 ` not_(cond)`）被 OR 在一起：` or_(cond_A, not_(cond_B))` → 匹配 A OR 非 B（几乎全库）。PubMed 语义：` A OR B NOT C` = ` (A OR B) AND NOT C`。
- **影响**：任何 OR+NOT 混合查询（如 ` cancer OR NOT review`）返回结果极大膨胀。
- **修复**： mixed` 模式的 NOT 分离逻辑：将 ` UnaryExpression` NOT 条件分离出来独立 AND。
### Bug-R20-3 (MEDIUM): ` is_pubmed_syntax()` 不识别小写布尔运算符
- **文件**： pubmed_query_parser.py:917`
- **根因**：布尔运算符正则 ` r'\b(AND|OR|NOT)\b'` 缺少 ` re.IGNORECASE`。` is_pubmed_syntax("cancer and tumor")` 返回 ` False` → 查询不触发 PubMed 路径。
- **影响**：使用小写布尔运算符的 PubMed 查询丢失所有字段语义。
- **修复**： re.search(..., re.IGNORECASE)`。
### Bug-R20-4 (MEDIUM): 长格式字段标签不被识别
- **文件**： pubmed_query_parser.py`（ _ALL_FIELD_TAGS` + ` _FIELD_TAG_MAP`）
- **根因**： [Title]`、` [All Fields]`、` [MeSH Terms]` 等长格式标签不在 ` _ALL_FIELD_TAGS` 中，被降级为普通 WORD。示例：` cancer[Title]` → 三个普通词。
- **修复**： _ALL_FIELD_TAGS` 新增 40+ 长格式标签；` _FIELD_TAG_MAP` 新增到规范内部名的映射。
- **验证**： cancer[Title]` → field="title"、` breast[MeSH Major Topic]` → field="MAJR"
### Bug-R20-5 (MEDIUM): 400 错误 URL 持久化导致刷新循环
- **文件**： SearchView.vue:379`
- **根因**： syncSearchToUrl()` 在 ` finally` 中无条件运行，400 参数被持久化到 URL。刷新后恢复相同参数 → 再 400 → 死循环。
- **修复**： syncSearchToUrl()` 移到 ` try` 块末尾（仅成功时同步）。
### Bug-R20-6 (LOW): 空括号 ` []` 产生空 Term
- **文件**： pubmed_query_parser.py:221-224`
- **根因**： []`， strip('[]')` 产生空字符串 → 创建空 Term。
- **修复**： stripped` 为空时跳过。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R19 回归（AND 子组） | ✅ ` sub_group_refs` 层级追踪 + 引擎层级处理 |
| OR 模式 NOT 语义 | ✅ 分离 NOT 条件独立 AND |
| 分词器/边界 | ✅ ` re.IGNORECASE`、长格式标签、空括号跳过 |
| 前端集成 | ✅ 400 URL 持久化循环修复 |
---
2026-07-28 16:11:19 +08:00
2026-07-28 15:12:13 +08:00
## 第十七轮：第 17 轮审计修复（3 项）
**日期**：
2026-07-28 15:46:20 +08:00
**提交**： 5fa2fbe`
2026-07-28 15:12:13 +08:00
**数量**： ）
**触发**：用户第 12 次要求全面检查（Round 17， ： _is_flat_text` 降级路径、facet 一致性、前端参数映射）
**审计**：facet 一致性和缓存键验证通过，未发现问题
**测试**：
### P0-1 (HIGH): ` _search_cache_key` 在 sub-path A 中被污染
- **文件**： search_engine.py:314-318`
- **根因**： _search_cache_key` 在第 186 行用原始 ` query` 预计算。第 314-318 行在 sub-path A 中对 ` query` 原地修改（剥离 field tags/布尔符/引号/括号），但缓存键未更新。后续请求命中此缓存时，返回的是剥离后的空查询结果。
- **触发条件**：仅当 ` is_pubmed_syntax(query)=True` 但 ` parse_pubmed_query(query)` 返回空有效字段时（如 ` "NOT"`、` "AND OR"` 等无意义查询）。实际影响极小，但属于正确性 bug。
- **修复**：在 ` query` 原地修改后重新调用 ` _search_cache_key()` 和 ` _facet_cache_key()`，确保缓存键反映剥离后的查询内容。
### P0-2 (MEDIUM): ` _pubmed_conditions` 无异常保护
- **文件**： search_engine.py:282-284`
- **根因**： _pubmed_conditions()` 调用无 try/except。内部虽有零散异常处理，但 ` AttributeError`/` TypeError` 等会传播到 ` search()` 外 → 500 错误（` literature.py:330` 已有全局保护，但高级搜索引擎没有）。
- **修复**：包裹 try/except Exception，异常时 ` logger.exception()` 并降级到 flat text 路径：` _is_flat_text = True; conditions = []`
### P0-3 (MEDIUM): 引号短语不强制 exact_phrase
- **文件**： search_engine.py:334-393`
- **根因**： "lung cancer"` 作为独立词，但传入 ` _field_condition(term, exact_phrase)` 时使用全局 ` exact_phrase` 参数。` exact_phrase=False` 时，引号短语被拆散为 ` lung AND cancer` 而非保持 ` <->` 短语搜索。
- **修复**：记录引号短语集 ` _phrase_terms_set`，传入 ` _field_condition` 时：引号短语始终 ` exact=True`，其他词使用全局 ` exact_phrase`。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| ` _is_flat_text` 降级路径 | ✅ 缓存键中毒(P0-1)已修复、异常保护(P0-2)已添加、引号短语(P0-3)已修复 |
| Fragment/缓存完整性 | ✅ ` parse_pubmed_query` 异常降级 clean、回退路径比普通搜索更全面 |
| ` year_counts` facet 一致性 | ✅ 筛选条件与主查询完全一致、缓存键差异仅限于分页参数（设计意图）、无问题 |
| Facet 缓存键完备性 | ✅ ` _facet_cache_key` 包含全部 26 个筛选参数，无缺失 |
| 前端参数映射 | ✅ SearchView.vue 发送全部 28 个参数、HomeView 参数子集缩小属设计意图、` is_oa` 后端功能被 ` is_free_full_text` 覆盖、无实际 gap |
---
2026-07-28 12:59:38 +08:00
截至 2026-07-29，剩余 7 项已知限制：
2026-07-27 11:22:22 +08:00
| ID | 问题 | 原因 | 影响 |
|----|------|------|------|
| L2 | Affiliation JSONB cast 假阳性 | 需独立 affiliation 列 + Alembic 迁移 + 重新填充 | 低 |
| L3 | retracted "yes"="only" | 命名语义，SQL 条件相同 | 无影响 |
| L4 | OR-mode NOT 检测不可靠 | ` UnaryExpression + _sa_ops.inv` 不可靠用于复合 NOT | 低 |
2026-07-27 15:18:36 +08:00
| L5 | 历史引用 ` #N ` 仅前端支持 | ` #N ` 是 localStorage UX 功能，仅在高级搜索前端内联展开 ` resolveQuery()` 后发送到 API。后端无 ` #` token 类型。API 直传 ` #1 ` 被当普通文本。属于设计决策，非 bug | 无影响（前端已覆盖所有 user 路径） |
2026-07-27 15:19:39 +08:00
| L6 | ` [SH]`/` [MAJR]` 依赖 MeSH 抽取质量 | 引擎逻辑正确（` mesh_headings JSONB contains qualifiers` / ` global_literature_tag.is_major=True`），但结果完整性取决于 pipeline 的 XML 抽取是否漏标。2026-07-27 审计抽检 981 篇：漏标率 0.1%、误标率 0.0%。脚本见 ` scripts/audit_mesh_major.py` | 低（当前数据质量良好） |
| L7 | 字段标签 REF/ISBN 未注册 | 低使用频率或数据缺失 | 低 |
| L8 | GIN 索引缺失（基因/chemicals 等） | 需 DBA 操作，生产数据量大 | 中（大表性能） |
2026-07-28 13:50:37 +08:00
| L9 | ` _dispatch_term` 回归不可见 | 需字段级测试。第 15 轮修复了 ` __RANGE_*` 组内回退 | 低 |
2026-07-28 16:52:31 +08:00
| L10 | ` _has_or` 深度盲区 | ` _parse_primary` 在父组范围内搜索 OR token，不限制括号深度。` (A AND (B OR C))` 中父组操作符错误为 "or" | 极低（仅在复杂嵌套触发） |
---
## 第二十一轮：第 21 轮审计修复（10 项）
**日期**：
**提交**： 53cf1d6..`（第 20 轮后追加）
**数量**： ）
**触发**：用户第 16 次要求全面检查（第 21 轮，4 并行审计 agent）
**测试**：
### Bug-R21-1 (CRITICAL): OR 模式 NOT 分离过度 — ` A OR NOT B` 语义错误
- **文件**： search_engine.py:1265-1278`
- **根因**： or_(*term_conditions)` 改为分离 UnaryExpression NOT 后独立 AND。` cancer OR NOT review` 被编译为 ` cancer AND NOT review`（仅检索 cancer 且不是 review 的文献），而非正确的 PubMed 语义 ` cancer OR NOT review`（所有 cancer 文献 + 所有非 review 文献）。
- **影响**：OR+NOT 组合查询结果严重过窄。违反"搜索功能必须与 PubMed 完全一致"硬性要求。
- **修复**：恢复为 ` conditions.append(or_(*term_conditions))`。
### Bug-R21-2 (CRITICAL): 双重嵌套括号 ` sub_group_refs` 虚条目 — 搜索词被丢弃
- **文件**： pubmed_query_parser.py:791-798`
- **根因**： _parse_primary` 在 ` _ungrouped` 为空（所有词已在前一层分好组）时仍写入 ` sub_group_refs`，导致 ` sub_group_refs` 比 ` groups` 多一项。组索引 0 出现在虚条目的子列表中 → 引擎 ` _is_child` 为 True → 整个组被 ` continue` 跳过。
- **触发**：任何双重嵌套括号 ` ((cancer[MH]))` 或外层括号内全部是已分组内容的表达式。
- **修复**：仅当 ` _ungrouped` 非空（即真正创建父组）时才写入 ` sub_group_refs`。
### Bug-R21-3 (HIGH): ` negated_date_ranges` 被覆盖而非合并
- **文件**： pubmed_query_parser.py:461`
- **根因**：第 461 行 ` =` 直接覆盖集合，` _dispatch_term` 中单日期 NOT 的 ` add()` 被丢弃。` NOT "2024-01-01"[DP]` → 引擎误以正日期过滤。
- **修复**： =` 改为 ` |=`。
### Bug-R21-4 (MEDIUM): 日期/PMID/DOI/PMC 条件在 OR 模式下始终 AND
- **文件**： search_engine.py:1377-1380`
- **根因**： _pubmed_conditions` 末尾所有日期/ID 条件 ` conditions.append()` → ` and_(*conditions)` 强制 AND。` cancer OR 2000:2020[DP]` 实际等同 ` cancer AND pub_date in 2000-2020`。
- **修复**： conditions = [or_(*conditions)]`。
### Bug-R21-5 (MEDIUM): ` _parse_atom` 无条件消费任何词符
- **文件**： pubmed_query_parser.py:836-839`
- **根因**： self.advance()` 不验证类型。` cancer OR OR lung` → 第二个 OR 被当作 WORD。
- **修复**：读取前验证 ` self.peek().type` 是原子类型。
### Bug-R21-6 (MEDIUM): 模态框触发两次 ` goToPage(1)`
- **文件**： SearchView.vue:961/981/997`
- **根因**：按钮 ` @click ` 同时设置 ` showModal = false`（触发 watcher）和直接 ` goToPage(1)`。
- **修复**：按钮只设置 ` showModal = false`，搜索由 watcher 触发。
### Bug-R21-7 (MEDIUM): ` page.value` 失败后不回退
- **文件**： usePagination.ts:23-26`
- **根因**： goToPage` 在 ` fetchFn` 前设置 ` page.value = n`。
- **修复**：捕获异常后恢复 ` page.value`。
### Bug-R21-8 (LOW): 空引号 ` ""[TI]` 产生空 Term
- **文件**： pubmed_query_parser.py:843-846`
- **根因**： ""` 被 tokeniser 匹配为 QUOTED， strip('"')` 后为空。
- **修复**： if not text: return []`。
### Bug-R21-9 (LOW): 冗余函数内 ` import re`
- **文件**： pubmed_query_parser.py:997`、` search_engine.py:358/372`
- **修复**：移除冗余函数级导入，使用模块级 ` import re`。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R20 回归（OR NOT 分离） | ✅ 已 revert |
| R20 回归（sub_group_refs 虚条目） | ✅ _ungrouped 守卫 |
| 搜索引擎代码 | ✅ negated_date_ranges、OR 模式日期条件、冗余导入 |
| 解析器/分词器 | ✅ _parse_atom 类型验证、空引号守卫 |
| 前端集成 | ✅ 双重 goToPage、page 回滚 |
| 已知限制更新 | L4 已修复移除、新增 L10 _has_or 深度盲区 |
2026-07-27 11:22:22 +08:00
---
2026-07-28 17:05:27 +08:00
## 第二十二轮：第 22 轮审计修复（8 项）
**日期**：
**提交**： c68aa06..`（第 21 轮后追加）
**数量**： ）
**触发**：用户第 17 次要求全面检查（第 22 轮，4 并行审计 agent）
**测试**：
### Bug-R22-1 (MEDIUM): OR 模式下特殊字段 NOT 产生错误 De Morgan 语义
- **文件**： search_engine.py:944-1167`
- **根因**： term_conditions.append(not_(or_(*neg_conds)))` 在 OR 模式下产生 ` NOT(A OR B)` = ` NOT A AND NOT B`。正确应为 ` or_(not_(A), not_(B))` = ` NOT A OR NOT B`。
- **影响**： NOT "Review"[PT] OR NOT "Clinical Trial"[PT]` 搜索结果过窄。
- **修复**：将全部 17 处 ` term_conditions.append(not_(or_(*neg_conds)))` 改为 ` term_conditions.extend(not_(c) for c in neg_conds)`。AND 模式下语义等价，OR/mixed 模式语义修正。
### Bug-R22-2 (MEDIUM): ` has_not` 不反映日期范围 NOT
- **文件**： pubmed_query_parser.py:446`
- **根因**： _ungrouped` 过滤掉 ` _is_range_end=True` 的标记，` has_not` 不检查 ` _date_range_markers`。
- **修复**： has_not` 额外检查 ` result._date_range_markers`。
### Bug-R22-3 (MEDIUM): ` YYYY-MM[DP]` 未引号部分日期无法解析
- **文件**： pubmed_query_parser.py:1010-1015`
- **根因**： 2024-01[DP]` 分词为 ` NUMBER(2024) WORD(-01) FIELD([DP])`。` -01` 不匹配 ` _PARTIAL_DATE_RE`。
- **修复**：预处理器将 ` YYYY-MM[date_field]` 标准化为 ` YYYY-MM-01[date_field]`。
### Bug-R22-4 (MEDIUM): ` date_preset=custom` URL 恢复丢失年份范围
- **文件**： SearchView.vue:393-396`
- **根因**： restoreFromQuery` 在 custom 分支无条件清空 yearFromStr/yearToStr。
- **修复**： year_from/year_to`。
### Bug-R22-5 (MEDIUM): 错误状态下分页总数残留
- **文件**： SearchView.vue:274-276`
- **根因**：
- **修复**：搜索开始时重置 ` total.value = 0`。
### Bug-R22-6 (LOW): 搜索错误状态未在开始时清除
- **文件**： SearchView.vue:274-276`
- **根因**：
- **修复**：搜索开始时设置 ` searchError.value = ''`。
### Bug-R22-7 (LOW): DATE token 不在未消耗标记恢复处理器中
- **文件**： pubmed_query_parser.py:456`
- **根因**：未消耗标记处理器仅捕获 WORD/QUOTED/NUMBER。
- **修复**：添加 ` TokenType.DATE`。
### Bug-R22-8 (LOW): 外部 NOT 组内 ` is_not` 被忽略
- **文件**： search_engine.py:1203`
- **根因**： NOT (A OR NOT B)` → ` not_(or_(A, B))`，内部 NOT B 被吞掉。
- **修复**：组内保留 ` t.is_not`。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R21 回归 | ✅ 无回归 |
| 搜索引擎代码 | ✅ De Morgan 语义 17 处修正、negated 组内 is_not |
| 解析器/分词器 | ✅ YYYY-MM 预处理器、has_not 日期范围、DATE 恢复 |
| 前端集成 | ✅ custom URL 恢复、total/error 清理 |
---
2026-07-27 11:22:22 +08:00
## 附录：测试覆盖统计
| 测试文件 | 用例数 | 范围 |
|---------|--------|------|
| ` test_pubmed_query_parser.py` | ~40 | tokeniser、解析器、语法正确性 |
| ` test_pubmed_search_integration.py` | ~60 | 字段映射、API 集成、前端格式 |
| ` test_comprehensive_verify.py` | ~27 | 字段完整、NOT 语义、括号、日期 |
2026-07-27 13:01:52 +08:00
| ` test_comprehensive_verify.py` | ~55 | 第 7 轮新增覆盖（full dispatch、boolean_operator、cursor 等） |
2026-07-28 13:50:37 +08:00
| 全量测试套件 | **1006** | 全部通过（含前 15 轮 287 项搜索专项 + 719 项通用测试） |
2026-07-27 13:01:52 +08:00
> **预存失败（13 项）**： feed_engine` ` StopAsyncIteration`（测试数据缺失） + 4 项 ` pubmed_api` ` _tag_article` import（函数已移入 pipeline）
2026-07-28 18:02:16 +08:00
---
## Round 23：第 18 次全面审计修复（2026-07-28）
### 审计发现总览
4 路并行审计 agent 覆盖：回归检查、搜索引擎代码、解析器/分词器、前端集成。发现 8 个新 bug + 1 个回归 bug（
### Bug-R23-1 (CRITICAL): Tokenizer 尾随字符捕获在循环内
- **文件**： pubmed_query_parser.py:287-291`
- **根因**：尾随间隙捕获代码缩进在 ` for m in _TOKEN_RE.finditer()` 循环体内，每匹配一个 token 后都会执行。对 ` 36261522[PMID]`：匹配 NUMBER 后 ` [PMID]` 被误判为"间隙"加入 WORD 列表，FIELD 被跳过。导致全部 field 标签失效。
- **修复**：缩进外移一级，仅在所有 match 结束后运行。
### Bug-R23-2 (LOW): ` _parse_range` 无字段归一化
- **文件**： pubmed_query_parser.py:876-880`
- **根因**： NUMBER:NUMBER[AU]` → ` field="AU"` 未映射为 ` "author"`。
- **修复**：字段标签解析后调用 ` _normalize_field_label()`。
### Bug-R23-3 (MEDIUM): YYYY-M 单月日期不匹配
- **文件**： pubmed_query_parser.py:1021-1025`
- **根因**：正则 ` \d{2}` 需恰好 2 位，` 2024-1[DP]` 不匹配 → 没补 -01。
- **修复**：改为 ` \d{1,2}` + lambda 零填充。
### Bug-R23-4 (MEDIUM): ` has_not` 未检查 ` group_negated`
- **文件**： pubmed_query_parser.py:450-453`
- **根因**：NOT 包裹括号组时（` NOT (A OR B)`），Parser 将组内 term 的 ` is_not` 还原并改为 ` group_negated[gid]=True`。但 ` has_not` 只检查 ` t.is_not`，不检查 ` group_negated`。
- **修复**：添加 ` any(result.group_negated)`。
### Bug-R23-5 (CRITICAL): NOT 组内日期范围的 De Morgan 错误
- **文件**： search_engine.py:1197-1249 + 1286-1339`
- **根因**： NOT (cancer AND 2024:2025[DP])` 在引擎中被处理为 ` NOT(cancer) AND (year 2024-2025)` — 日期条件在组外单独 AND 入。但正确 De Morgan 是 ` NOT(cancer AND date) = NOT(cancer) OR NOT(date)`。根本原因是日期范围在组外作为顶层 AND 条件构建，不受组内 NOT 影响。
- **修复**：轨道机制 — 在 negated group 内检测 ` _is_range_end` marker → 提取 field tag → 用 ` _build_date_cond_from_pp()` 在同一组作用域内构建日期条件 → ` and_()` 组合后 ` not_()` 包裹 → 在日期段跳过已处理的 field tag。新增 ` AdvancedSearchEngine._build_date_cond_from_pp()` 静态方法。
- **影响范围**：所有 field tag 的日期范围（DP/EDAT/CRDT/MHDA/LR/DCOM/DEP）在 NOT 组内均正确。
### Bug-R23-6 (HIGH): 空查询返回全部文献
- **文件**： search_engine.py:674-675`
- **根因**： conditions` 列表为空时跳过 WHERE 子句，全表扫描返回。
- **修复**：添加 ` elif not _keyset_cond: q = q.where(text("FALSE"))`。
### Bug-R23-7 (MEDIUM): NULL JSONB/TEXT + NOT 交互
- **文件**： search_engine.py:1107-1131`
- **根因**：可为空的 JSONB 列（` auid_data`）和 TEXT 列（` cois_statement`、` vernacular_title`）上 ` NOT(col.contains(...))` 对 NULL 行求值为 NULL 而非 TRUE → NULL 行被排除，但 NOT 语义应为包含 NULL。
- **修复**：对 ` auid_data`、` cois_statement`、` vernacular_title` 的 NOT 条件添加 ` or_(col.is_(None))` 包装。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R22 回归 | ✅ 无回归 |
| 搜索引擎代码 | ✅ De Morgan 组内日期、空查询守卫、NULL JSONB |
| 解析器/分词器 | ✅ 尾随间隙缩进、字段归一化、YYY-M、has_not group_negated |
| 前端集成 | ✅ router.replace 标记已知 |
### 测试覆盖
**1007 tests passed**（全量套件，含全部前 22 轮 248 项搜索专项 + 通用测试）
2026-07-28 18:42:04 +08:00
---
## Round 24：第 24 次全面审计修复（2026-07-28）
### 审计发现总览
4 路并行审计 agent 覆盖回归检查、搜索引擎代码、解析器/分词器、前端集成。发现 ~20 项问题，其中 HIGH 2 项、MEDIUM 4 项、LOW 10+ 项。
### H2 (CRITICAL): ` _dispatch_term` 单日期覆盖已设置的范围值
- **文件**： pubmed_query_parser.py:_dispatch_term`（所有 7 个日期字段分支）
- **根因**： _parse_range` 先设置 ` date_from/date_to`，随后 ` _parse_atom` 解析 ` 2024[DP]` 时 ` _dispatch_term` 无条件覆盖 ` year_from=2024`、` year_to=2024`。当 ` 2024:2028[DP] AND 2026[DP]` 时，范围被后续单日期覆盖。
- **修复**：所有日期字段的 single-year 和 single-date 分支改为 intersect 模式：
` ``python
if result.year_from is not None:
result.year_from = max(result.year_from, y)
else:
result.year_from = y
` ``
同样模式用于 ` year_to`（ dep_from/edat_from/...`（ dep_to/edat_to/...`（
- **影响**：多日期条件 AND 组合时保持正确的日期交集而非后写覆盖。
### H1 (MEDIUM): 混合日期范围交换使用 ` >=` 而非 ` >`
- **文件**： pubmed_query_parser.py:910`
- **根因**： 2024-06-15:2024[EDAT]` 混合日期范围交换判断：` if int(start_val[:4]) >= int(end_val)` → 左端年份 >= 右端值时交换。但等值年份不应交换（` 2024-06-15:2024` 正确），其他三个交换分支都已用 ` >`。
- **修复**： >=` → ` >`
### BUG-1 (MEDIUM): Keyset 分页日期游标重复
- **文件**： search_engine.py:_cursor_from_item()`
- **根因**： pub_date=NULL` 时回退 ` article_date` 创建游标值，但主查询排序只用 ` pub_date`。排序列和游标列不一致 → 结果重复/跳跃。
- **修复**： _cursor_from_item()` 只使用 ` lit.pub_date`，忽略 ` article_date`。
### BUG-2 (MEDIUM): 单 ` *` 通配符匹配全部
- **文件**： search_engine.py:_field_condition()`
- **根因**：纯星号 ` *` 通配符进入 wildcard 分支后 ` _stem = ""`， %%` 匹配所有行。
- **修复**： if not _stem: return text("FALSE")`
### BUG-3 (MEDIUM): ` page_size` 无上限
- **文件**： search_engine.py:search()` 入口
- **根因**： page_size` 直接传递给 SQL LIMIT，前端可请求任意大（如 100000）→ OOM 风险。
- **修复**： page_size = min(page_size, 100)`
### BUG-4 (MEDIUM): ` tag_ids` 无上限
- **文件**： search_engine.py:search()` 入口
- **根因**： tag_ids` 直接入 IN 子句。` /api/v1/literature/?tag_ids=1,2,...,1000` → 超大 IN 子句，性能差。
- **修复**： tag_ids = list(set(str(t) for t in tag_ids))[:200]`
### BUG-6 (LOW): ` _has_any_filter` 中 ` query.strip()` 误杀空白查询
- **根因**： _has_any_filter` 内 ` query.strip()` 在括号和布尔符被剥离前判断。空格查询 ` " "` 被淘汰 → 跳到 ` FALSE` 守卫，返回 0 结果。
- **修复**： query.strip()` 改为 ` query`（ " "` 空格在剥离后变 ` ""` → 正确处理）。
### BUG-7 (LOW): ` exact_phrase` + 数字词未含 PMID
- **文件**： search_engine.py` flat text 路径的 numeric branch
- **根因**： exact_phrase=True` 时数字词只做 ILIKE 精确匹配，不检查 PMID 字段。
- **修复**： GlobalLiterature.pmid == int(t)` 同时包含在 ` or_()` 中。
### BUG-8 (LOW/MEDIUM): ` _phrase_terms_set` NameError 回归
- **文件**： search_engine.py` flat text 路径
- **根因**： _phrase_terms_set` 在 ` terms` 列表推导之后定义，但由于 Python 闭包延迟求值，运行时报 ` NameError`。
- **修复**：将 ` _phrase_terms_set` 移至 ` terms` 之前。同时用 ` .lower()` 做 case-insensitive dedup。
### Parser M1 (LOW): NOT 递归深度无限制
- **文件**： pubmed_query_parser.py:_parse_not_expr()`
- **根因**：连续 NOT（ NOT NOT NOT ... term`）可无限递归。
- **修复**：添加 ` _not_depth` 参数，超过 ` MAX_PAREN_DEPTH(10)` 时 ` raise ParseError`。
### Parser M3 (LOW): ` is_pubmed_syntax` 和 ` _TOKEN_RE` ASCII 标志不一致
- **文件**： pubmed_query_parser.py:is_pubmed_syntax()`
- **根因**： _TOKEN_RE` 使用 ` re.ASCII` 使 ` \b` 只识别 ASCII 词边界。` is_pubmed_syntax` 使用 ` re.IGNORECASE` 无 ASCII 标志，对非 ASCII 字符行为不同。
- **修复**：两个正则搜索都添加 ` re.ASCII`。
### BUG-5 (LOW): ` _escape_ilike` 双重转义
- **文件**： search_engine.py:_escape_ilike()`
- **根因**：用户输入 ` EGFR\%`（有意搜索百分号）→ ` replace('\\', '\\\\')` 后为 ` EGFR\\%` → ` replace('%', '\\%')` 后为 ` EGFR\\\%` → ILIKE 里匹配 ` EGFR\%` 而非 ` EGFR%`。
- **修复**：先反转义 ` \\%` → ` %` 和 ` \\_` → ` _`，再整体转义。
### 前端修复
- **` router.replace` → ` router.push`**： syncSearchToUrl` 用 ` replace` 导致浏览器后退按钮跳过中间搜索状态。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R23 回归 | ✅ 尾随间隙缩进回归已修复 |
| 搜索引擎代码 | ✅ keyset 游标、通配符、上限、escape_ilike 等 8 项修复 |
| 解析器/分词器 | ✅ intersect 日期、NOT 深度、re.ASCII、date swap 等 6 项修复 |
| 前端集成 | ✅ router.replace→push |
### 测试覆盖
**53 parser + search engine tests passed**（非回归验证）。全量测试结果：722 passed，223 failed（全部为外部服务连接失败）+ 62 errors（全部为 ` test_teams` 外部服务 + ` feed_engine` 测试数据）。
### 剩余已知 LOW 项（未修复）
| # | 描述 | 原因 |
|---|------|------|
| M2 | ` _parse_atom` vs ` _parse_range` 不同字段归一化路径 | 代码一致性，无实际 bug |
| P1 | 前端 ` is_oa` UI 切换控件未实现 | 功能添加，非修复 |
| BUG-9 | ` year_from/year_to` 无合法性校验 | 反向范围返回空结果（语义正确），非必须 |
| P2 | OR 模式冗余 ` or_()` 嵌套 | 无害，SQL 优化器扁平化 |
| savedPmids | 前端挂载时不从服务器加载 | 前端功能缺失 |
| 429 | 搜索时重复 429 反馈 | 前端 UI 问题 |
2026-07-28 19:19:10 +08:00
---
## Round 25：第 25 次全面审计修复（2026-07-28）
### 审计发现总览
4 路并行审计 agent 覆盖：R24 回归检查、搜索引擎代码、解析器/分词器、前端集成。发现 10+ 项问题，含 1 CRITICAL、4 MEDIUM、5 LOW。
### Bug-25-1 (CRITICAL): ` _parse_range` 覆盖已存在的日期条件
- **文件**： pubmed_query_parser.py:_parse_range()`（
- **根因**： _parse_range` 使用 ` setattr(result, attr, val)` 无条件覆盖已设置的值。当 ` 2024[EDAT] 2022:2025[EDAT]` 时：` _dispatch_term` 先设置 ` edat_from=2024-01-01, edat_to=2024-12-31`，然后 ` _parse_range` 用 ` setattr` 覆盖为 ` edat_from=2022-01-01, edat_to=2025-12-31`。这与 R24 在 ` _dispatch_term` 中错误使用的 intersect 形成对比——真正的修正应该在 ` _parse_range`。
- **修复**：所有 4 个 range 子路径改为 intersect 模式（` max(current, new)` 或 ` min(current, new)`），与 ` _dispatch_term` 的原子段处理一致。同时 ` _dispatch_term` 所有 7 个日期字段恢复为简单赋值（消除 R24 H2 intersect + OR 回归）。
### Bug-25-2 (MEDIUM): 年份计数缓存被文本查询污染
- **文件**： search_engine.py:620-645`
- **根因**： _has_any_filter` 排除 ` query`（ elif not _has_any_filter:` 分支，使用全局缓存键 ` "search:year_counts:all"`。不同查询共享同一缓存，年份计数柱状图显示错误的全局分布。
- **修复**： elif not _has_any_filter:` → ` elif not _has_any_filter and not conditions:`。
### Bug-25-3 (MEDIUM): NULL 安全 NOT 仅覆盖 3 个字段
- **文件**： search_engine.py:950-1220`
- **根因**： NOT col.contains(...)` 对 NULL 行求值为 NULL 而非 TRUE → NULL 行被排除。R23-3 只为 ` auid_data`、` cois_statement`、` vernacular_title` 添加了 ` or_(..., col.is_(None))` 包装。其他 12 个 JSONB/TEXT 字段（` pub_types`、` grants`、` mesh_headings`、` chemical_list`、` databank_list`、` pharmacological_actions`、` keywords`、` gene_symbols`、` authors`、` investigators`、` personal_name_subjects`、` publication_notes`、` citation_status`）缺少此保护。
- **修复**：所有 JSONB/TEXT 字段的 NOT 条件添加 ` or_(..., col.is_(None))` 包装。
### Bug-25-4 (MEDIUM): De Morgan ` _handled_neg_group_date_fields` 跨组污染
- **文件**： search_engine.py:1355-1392`
- **根因**： _handled_neg_group_date_fields` 是全局集合。当日期字段同时出现在否定组内和顶层（如 ` 2020:2025[DP] NOT (cancer AND 2020:2022[DP])`），顶层的 DP 条件被错误抑制。
- **修复**：新增 ` _top_level_date_fields` 集合（` ParsedPubmedQuery`），追踪顶层（未分组）日期字段引用。抑制条件改为 ` field in _handled_neg_group_date_fields AND field not in _top_level_date_fields`。
### Bug-25-5 (MEDIUM): DP 无效日期字符串静默丢弃
- **文件**： pubmed_query_parser.py:_dispatch_term()` DP 分支
- **根因**： _validate_date_str()` 为 False 时的 ` else` 子句。无效 DP 字符串（如 ` abc[DP]`）被静默丢弃。所有其他 6 个日期字段（EDAT、CRDT 等）有正确的 ` else { plain_terms.append; return }`。
- **修复**：添加缺失的 ` else: result.plain_terms.append(term); return`。
### Bug-25-6 (LOW): ` MESH:NOEXP` 未识别为合法字段标签
- **文件**： pubmed_query_parser.py:69-77, 185`
- **根因**： _ALL_FIELD_TAGS` 有 ` MH:NOEXP` 和 ` MESH`，但没有 ` MESH:NOEXP`。` _normalize_field_label` 只检查 ` raw == "MH:NOEXP"`，不检查 ` "MESH:NOEXP"`。
- **修复**： _normalize_field_label` 支持 ` raw in ("MH:NOEXP", "MESH:NOEXP")`。` _ALL_FIELD_TAGS` 添加 ` "MESH:NOEXP"`。
### Bug-25-7 (LOW): ` is_first_page` 对空字符串 ` cursor_val` 处理不当
- **文件**： search_engine.py:192`
- **根因**： is_first_page = (cursor_val is None and cursor_id is None)` → ` cursor_val=""` 时 ` is_first_page=False`，不计算总计数。但 ` _keyset_condition` 用 ` not cursor_val` 判断，返回 None（无 keyset 条件）。
- **修复**： is_first_page = (not cursor_val and cursor_id is None)`。
### 审计结果汇总
| 审计维度 | 结果 |
|---------|------|
| R24 回归 | ✅ _dispatch_term intersect 已回退（消除 OR 回归）；_has_any_filter 已修正 |
| 搜索引擎代码 | ✅ _parse_range intersect、年份缓存、NULL 安全 NOT、De Morgan 跨组 等 12 项修复 |
| 解析器/分词器 | ✅ DP 无效日期降级、MESH:NOEXP、top_level_date_fields 追踪 等 5 项修复 |
| 前端集成 | ✅ 无变更 |
### 测试覆盖
**986 tests passed**（全量套件，排除外部服务连接失败）。前端 build 通过。
2026-07-28 20:14:05 +08:00
---
# 第26轮审计修复 (R26)
## 背景
第 26 轮审计由 agent 独立完成代码审查，发现了 7 个解析器 bug 和 1 个引擎 bug。全部修复，0 个 defer。
## 修复清单
### Bug-26-1 (CRITICAL): 部分日期 YYYY-MM 不匹配 DATE token
**文件**：
**根因**： DATE` token 的正则表达式 ` \d{4}-\d{2}-\d{2}` 要求完整 ` YYYY-MM-DD`。输入 ` 2024-01[DP]` 时，` 2024-01` 不匹配 DATE，退化为普通 NUMBER。` _parse_range` 无法解析，导致查询返回错误结果。
**修复**：将 DATE token 正则放宽为 ` \d{4}-\d{2}(?:-\d{2})?`，接受 ` YYYY-MM` 和 ` YYYY-MM-DD`。同时简化 R23-3 的部分日期归一化：去掉 ` -01` 后缀，保留 ` YYYY-MM` 格式。
### Bug-26-2 (CRITICAL): MESH:NOEXP 在 ` _parse_atom` 中未识别
**文件**：
**根因**： _parse_atom` 的 ` if ":" in token` 分支没有将 ` MESH:NOEXP` 视为合法的 ` FIELD:SUBQUALIFIER` 组合。它被解释为 ` field=MESH, subqualifier=NOEXP`，导致 ` "NOEXP"` 被传入 ` _normalize_field_label()` → 找不到匹配 → 抛异常。
**修复**： _normalize_field_label` 支持 ` "MESH:NOEXP"`）。
### Bug-26-3 (CRITICAL): 分组 ` MESH:NOEXP` 不支持
**文件**：
**根因**： (stem cell[Title]) AND (MESH:NOEXP)` 引发内部错误。分组表达的 ` MESH:NOEXP` 经过解析器嵌套调用，某些路径未处理 ` NOEXP` 标记。
**修复**：
### Bug-26-4 (HIGH): 否定日期 + 肯定范围交互
**文件**：
**根因**： NOT 2024[DP] 2020:2025[DP]` 意图是"2020-2025 排除 2024"。但原先处理方式是将 2024 和 2020:2025 做 intersect，结果为空 → 正确结果被丢弃。否定日期应在条件层面用 ` NOT()` 包裹，而非在字段值层面 intersect。
**修复**：
- ` ParsedPubmedQuery` 新增 ` _neg_single_dates: dict[str, list[tuple[str | None, str | None]]]`，存储被否定的单日期边界
- ` _dispatch_term` 所有 7 个日期字段：否定时存入 ` _neg_single_dates`，不参与 intersect
- ` _parse_range` 所有 4 个子路径：否定时存入 ` _neg_single_dates`
- ` _pubmed_conditions` DP 和非 DP 日期字段：独立发出肯定范围（AND）和否定条件（NOT）
- ` _parse_not_expr` 传递 ` negated=(_not_depth % 2 == 1)` 以正确识别双层 NOT 的取反状态
### Bug-26-5 (MEDIUM): 简单赋值 vs intersect 不一致
**文件**：
**根因**： min(prev, new)` / ` max(prev, new)` intersect，但 DP 使用简单赋值（后写的覆盖先写的）。` NOT 2024[DP] 2020:2025[DP]` 中 DP 被赋值为 2020:2025 的 intersect（否定信息丢失），丢失了 NOT。
**修复**：所有 7 个日期字段统一使用 intersect。
### Bug-26-6 (dead code): ` negated` 参数赋值为 False，从未被使用
**文件**：
**根因**： _parse_primary` 和 ` _parse_atom` 的 ` negated` 参数始终传 ` False`。` _parse_not_expr` 虽然接收了否定语义，但没有向下传递。
**修复**： _parse_not_expr` 通过 ` negated=(_not_depth % 2 == 1)` 传递。所有 term 创建路径将 ` is_not=False`（不在 term 级别标记否定，只在 ` _neg_single_dates` 级别追踪）。
### Bug-26-7 (dead code): ` _expand_partial_date` 从未被调用
**文件**：
**根因**： YYYY-MM-DD`，所以 ` YYYY-MM` 永远无法到达分词结果 → ` _expand_partial_date` 永远不会被调用。
**修复**： YYYY-MM` 被正确识别为 DATE， _expand_partial_date` 现在可达。
### Engine Bug: 混合模式 NOT 检测不完整
**文件**：
**根因**： _pubmed_conditions` 生成的 NULL-safe NOT 包装为 ` or_(not_(cond), col.is_(None))`，这在 SQLAlchemy 中是一个 ` BooleanClauseList`（不是 ` UnaryExpression`）。混合模式 NOT 检测只检查 ` UnaryExpression` + ` _sa_ops.inv`，遗漏了 NULL-safe 包装的否定条件。
**修复**：新增 ` _is_negated_cond()` 辅助函数，同时检测两种模式：
` ``python
def _is_negated_cond(c):
if isinstance(c, UnaryExpression) and c.modifier == _sa_ops.inv:
return True
try:
if hasattr(c, 'operator') and c.operator is _sa_ops.or_:
clauses = list(getattr(c, 'clauses', ()))
if len(clauses) >= 2 and isinstance(clauses[0], UnaryExpression) and clauses[0].modifier == _sa_ops.inv:
return True
except Exception:
pass
return False
` ``
## 验证
- ✅ **1007 tests passed**（全量套件，0 failed）
- 涉及 NOT 日期的 10 个新增测试全部通过
## 待修复（LOW，本轮未处理）
| 编号 | 严重度 | 描述 |
|------|--------|------|
| Bug 3 | LOW | Facet cache 从未写入 p2+（ total=0` 回退） |
| Bug 4 | LOW | 无效日期字段标签静默降级为全字段搜索 |
| Bug 5 | LOW | 否定组内冗余日期条件（单个年份 + 全范围） |
2026-07-28 22:56:04 +08:00
---
# 第27轮审计修复 (R27)
## 背景
第 27 轮由 3 个并行审计 agent 覆盖：解析器、引擎、前端/集成。发现 2 个 CRITICAL 引擎-解析器交互 bug、1 个 MEDIUM 解析器 bug，以及若干 LOW 问题。
## 修复清单
### R27-1 (CRITICAL): 日期范围属性跨作用域污染
**文件**：
**根因**： _parse_range` 对所有非否定日期范围都用 ` max/min` intersect 更新全局 ` edat_from/edat_to` 属性。当同一日期字段同时出现在顶层和括号组内（如 ` 2000:2010[EDAT] NOT (cancer AND 2005:2006[EDAT])`），顶层范围被组内范围错误缩小：` edat_from` 从 ` 2000-01-01` 变成 ` 2005-01-01`， edat_to` 从 ` 2010-12-31` 变成 ` 2006-12-31`。加上 ` _top_level_date_fields` 未追踪 ` __RANGE_*` 标记，导致 ` _neg_only` 判定跳过整个日期节。
**修复**：
- ` _parse_range` 增加 ` if self._depth == 0` 守卫——仅顶层范围更新全局属性，组内范围不再污染
- ` parse()` 循环 ` terms` 追踪 ` __RANGE_*` 标记的 ` _top_level_date_fields`
- 新增 ` _build_marker_condition()` 静态方法——从标记内嵌的 ` start_val:end_val` 文本重建 SQL 条件
- 组循环中处理标记：非否定组 → ` g_pos.append`，否定组 → ` g_neg.append`
- 移除 ` _build_date_cond_from_pp` 在否定组中的调用（已被标记直接处理取代）
### R27-2 (MEDIUM): 范围语法中的部分日期 YYYY-MM 静默降级
**文件**：
**根因**： _validate_date_str` 只接受 ` YYYY` 或 ` YYYY-MM-DD`。` 2024-01:2024-06[DP]` 中两个端点无法通过验证，整个范围降级为纯文本。单值部分日期（` 2024-01[DP]`）因 R26 的 ` _expand_partial_date` 调用路径已正确处理，但 ` _parse_range` 缺少相同调用。
**修复**：在 ` _parse_range` 的验证前添加 ` _PARTIAL_DATE_RE` 匹配 + ` _expand_partial_date` 展开：
` ``python
if _PARTIAL_DATE_RE.match(start_val):
start_val, _ = _expand_partial_date(start_val)
if _PARTIAL_DATE_RE.match(end_val):
_, end_val = _expand_partial_date(end_val)
` ``
### R27-3 (MEDIUM): ` _is_negated_cond` NULL-safe 模式验证不完整
**文件**：
**根因**： or_` 的第一个子句是 ` not_(...)`，没有验证第二个子句是 ` is_(None)`。潜在误报：` or_(not_(X), Y)` 会被错误识别为否定。
**修复**：增加对第二子句的 ` is_(None)` / ` isnot(None)` 验证。
### R27-4 (LOW): ` _neg_single_dates` NOT 条件缺少 NULL 安全
**文件**：
**根因**： not_(and_(col >= from, col <= to))` — 当 ` col` 为 NULL 时，` NULL >= date` → NULL， NOT(NULL)` → NULL（
**修复**：使用 ` or_(not_(_range_cond), col.is_(None))`。
### R27-5 (LOW): 空白字符引号文本不跳过
**文件**：
**根因**： " "[TI]` — ` text = " "`（两个空格），` if not text` 为 False，创建搜索条件包含双空格。
**修复**：改为 ` if not text or not text.strip(): return []`。
## 前端审计发现（R27 未修复）
| 编号 | 严重度 | 描述 | 文件 |
|------|--------|------|------|
| C-1 | CRITICAL | 非 keyset 排序（best_match/relevance）第 2 页起总分页消失 | SearchView.vue:278 |
| C-2 | CRITICAL | ` #N ` 引用在 SearchView 中不解析 | SearchView.vue:865 |
| H-1 | HIGH | offset 分页第 2 页起 total 显示为 0 | SearchView.vue:278,353 |
| H-2 | HIGH | 错误时 goToPage 不回退页码 | SearchView.vue:369-380 |
| M-1 | MEDIUM | 空查询时年份直方图与"未找到"同时显示 | SearchView.vue:625 |
| M-3 | MEDIUM | URL 同时存储 ` date_preset` 和绝对日期 | SearchView.vue:512-521 |
| L-3 | LOW | 空查询无筛选时返回全库年份分布 | search_engine.py:622-641 |
## 验证
- ✅ **110 search tests passed**（ ）
- 解析器 36 测试全部通过
- 5 个新增 R27 正确性检查通过
- 全量套件中仅外部服务连接失败（httpx.ConnectError），与改动无关
2026-07-29 05:33:21 +08:00
## R28 (2026-07-29): 第三轮并行审计修复
### R28-1 (MEDIUM): 组作用域标记污染 ` negated_date_ranges`
**文件**：
**根因**： __RANGE_*` 标记的 ` negated_date_ranges` 聚合未过滤组内标记（` group_id >= 0`），导致组内 NOT 日期范围被错误地应用到顶层日期字段的 ` not_(cond)`，产生 ` NOT (pub_year >= X AND pub_year <= Y)` 而非正确的组内处理。
**修复**：过滤 ` t.group_id < 0`（仅顶层标记），组内标记由 ` _build_marker_condition` + group processing 路径独立处理。
### R28-2 (LOW): 标记 field 被组 field 覆盖
**文件**：
**根因**：组 field 标签赋值循环未跳过 ` __RANGE_*` 标记，导致标记的 ` field` 属性从 ` __RANGE_DP__` 被覆盖为 ` dp`，破坏后续标记识别。
**修复**：跳过 ` getattr(t, '_is_range_end', False)` 的标记项。
### R28-3 (CRITICAL): DP 否定范围使用 ` pub_date` 而非 ` pub_year`
**文件**：
**根因**： _neg_single_dates` DP 分支对所有否定范围使用 ` pub_date` 比较，但当范围是完整年份（如 ` 2024:2024`）且用户在 ` pub_year` 列上有不同数据质量时，` pub_date` 可能产生不准确的结果。
**修复**：检测 ` _neg_from` 以 ` -01-01` 结尾且 ` _neg_to` 以 ` -12-31` 结尾时，切换到 ` pub_year` 比较，同时保持 NULL 安全（` or_(not_(cond), pub_year.is_(None))`）。
### R28-4 (CRITICAL): ` _pubmed_conditions` 异常导致未清理查询
**文件**：
**根因**： _pubmed_conditions()` 内未捕获的异常传播到 ` search()` 外导致 500 错误，且解析失败后的文本降级检查 ` not any([...])` 未包含此路径。
**修复**：添加 ` _pubmed_failed` 标志，` except` 块中设为 ` True` 并强制文本降级和查询清理。
### R28-5 (HIGH): YYYY-MM 在组内路径中未处理
**文件**：
**根因**： _single_term_condition()` 处理日期字段时，仅在 ` len(_term_text) == 4`（年份）和完整 ISO 日期（YYYY-MM-DD）之间处理。` YYYY-MM` 格式（如 ` 2024-06`）既不匹配 4 位数字也不匹配完整日期，静默降级。R27 修复仅在顶层路径生效，组内 ` _single_term_condition` 路径遗漏。
**修复**：插入 ` _PARTIAL_DATE_RE` + ` _expand_partial_date` 处理，将 ` YYYY-MM` 展开为 ` YYYY-MM-01`~` YYYY-MM-30/31` 的日期范围条件。
### R28-6 (MEDIUM): NULL 安全 NOT 缺失
**文件**：
**根因**：多处 ` not_(date_condition)` 未包装 NULL 安全，导致 ` pub_date`/` pub_year` 等日期列为 NULL 的行被错误排除：
- 顶层 DP ` not_(cond)` 路径（line 1446）
- 非 DP 字段 ` negated_date_ranges` 路径（line 1505）
- 组标记 NOT 路径（非否定组中的 ` is_not` 标记，line 1271）
- 否定组包装 ` not_(combined)`（ _neg_group_date_fields` 跟踪）
**修复**：对所有路径使用 ` or_(not_(cond), col.is_(None))`。组标记路径按 ` _tag` 查找对应列（DP 同时加上 ` pub_year.is_(None)` + ` pub_date.is_(None)`）。
## 验证
- ✅ **1007 tests passed, 0 failed**
- 全部搜索测试通过（parser 36 + search engine 集成测试）
- 无回归
2026-07-29 06:16:11 +08:00
## R29 (2026-07-29): 第四轮并行审计修复
### 审计范围
4 路并行 agent，分别覆盖：
1. ` pubmed_query_parser.py` 语法正确性（递归下降解析器）
2. ` search_engine.py` 条件构建（_pubmed_conditions 全字段路径）
3. 纯文本降级路径（_is_flat_text 决策、缓存键、引号短语、facet 一致性）
4. 前端搜索参数映射（前后端参数完整性、URL 同步、分页）
### R29-1 (P0): ` _expand_partial_date` 未导入
**文件**：
**根因**： _single_term_condition()` 的 YYYY-MM 部分日期分支调用 ` _expand_partial_date()` 但该函数未从 ` pubmed_query_parser` 导入。导入语句只导入了 ` _PARTIAL_DATE_RE` 和 ` _validate_date_str`。
**影响**：组内 YYYY-MM 日期（如 ` (2024-06[DP] OR cancer)`）触发 ` NameError`，被 ` except Exception` 吞没后降级到纯文本。
**修复**：添加 ` _expand_partial_date` 到 inline import。
### R29-2 (P0): 非日期范围 field 标签混入文本
**文件**：
**根因**： _parse_range()` 对非日期范围（如 ` term1:term2[MH]`）的 fallthrough 路径将 ` [MH]` 追加入 term 文本，导致 ` text="term1:term2[MH]"` 而 ` Term.field="MH"` 已正确设置。引擎按 ` field` 路由（正确到 MeSH 路径），但 ` text` 中的 ` [MH]` 被作为字面搜索词。
**修复**：去除 ` [{field}]` 文本拼接，只保留 ` start_val:end_val`。
### R29-3 (P0): 中文精确短语缺少 title/abstract ILIKE
**文件**：
**根因**： _field_condition("all", exact=True)` 分支使用 ` phraseto_tsquery('english', ...)` 无法匹配非英文文本（如中文）。缺少 title/abstract ILIKE 回退。非精确分支（line 1832）正确包含这些 ILIKE。
**影响**： "肺癌"[TIAB]` 等中文精确短语返回零结果。
**修复**：在 exact 分支中添加 ` title.ilike(pat)` 和 ` abstract.ilike(pat)`。
### R29-4 (P1): 子组日期范围标记被丢弃
**文件**：
**根因**：子组（sub-group，由 ` _parse_or_expr` AND 集群 OR 拆分产生）的日期范围标记在 child processing 循环中被 ` continue` 跳过。
**影响**： (A OR B AND 2020:2024[DP])` 等查询中日期范围丢失。
**修复**：子组循环中添加 ` _build_marker_condition` + NULL 安全 NOT，逻辑与父组一致。
### R29-5 (P1): 开区间日期范围不支持
**文件**：
**根因**： :2024[DP]`（截止到 2024）和 ` 2024:[DP]`（从 2024 起）的 COLON 在首个位置或无第二个 NUMBER 的模式不被范围检测匹配。
**修复**：在 ` _parse_atom` 中增加 ` :NUMBER[FIELD]` 和 ` NUMBER:[FIELD]` 检测，路由到新方法 ` _handle_date_range_edge()`，正确设置全局属性、标记和 ` _neg_single_dates`。
### R29-6 (P2): field_map NOT 条件缺少 NULL 安全
**文件**：
**根因**： [TI]`/` [AB]`/` [AU]` 等字段标签的否定词使用裸 ` not_(cond)`，导致字段为 NULL 的行被错误排除。
**修复**：添加 ` _NULL_SAFE_COL_MAP`，对每个字段的否定条件使用 ` or_(not_(cond), col.is_(None))`。
### R29-7 (LOW): PRISMA 导出正则不匹配含空格的字段标签
**文件**：
**修复**： [\w/:]+` → ` [\w/: -]+` 以匹配 ` [MeSH Terms]`、` [Date - Publication]` 等。
### R29-8 (LOW): ` is_free_full_text` 在 ` is_oa` 已设时被跳过
**文件**：
**修复**：移除 ` is_oa is None` 守卫，` is_free_full_text` 始终独立生效。
## 验证
- ✅ **1007 tests passed, 0 failed**
- 全部搜索测试通过
- 无回归
2026-07-29 07:30:36 +08:00
## R30 (2026-07-29): 第五轮并行审计修复
> **变更类型**：6 项修复（1 HIGH 已在前序会话修复 + 5 项新增）
### R30-1 (HIGH): 否定组 NULL 安全包裹整个组合条件
**文件**：
**根因**：R28 为否定组添加的 NULL 安全 NOT 包裹过于宽泛：` or_(not_(date_cond + keyword_combined), col1.is_(None), col2.is_(None))`。当日期列为 NULL 时，关键词匹配也通过 NULL 安全逃逸，导致否定组中的关键词条件失效。
**修复**：完全移除此 NULL 安全包裹层。否定组现在使用纯 ` not_(combined)`，不附加列 NULL 检查。日期列的 NULL 安全由列精确的 ` dp_negated` 路径单独处理。
### R30-2 (MEDIUM): ` dp_negated` 双列 NULL 安全不精确
**文件**：
**根因**：顶层 ` dp_negated` 路径始终同时添加 ` pub_year.is_(None)` 和 ` pub_date.is_(None)`，即使条件仅使用其中一列（如纯年范围 ` 2024:2025[DP]` 只使用 ` pub_year`）。
**修复**：检查条件使用了哪些列（` year_from/to` → ` pub_year`， date_from/to` → ` pub_date`），仅对实际使用的列添加 NULL 安全。
### R30-3 (MEDIUM): 嵌套括号 ` _has_or` 跨越作用域边界
**文件**：
**根因**： _has_or` 通过扫描 ` start_pos:end_pos` 范围内所有 token 检测 OR 运算符。嵌套括号如 ` ((A OR B AND C) AND D)` 中，外层括号的 ` _has_or` 扫描到内层 OR，导致外层分组操作符被设为 "or" 而非 "and"。
**修复**：在扫描过程中跟踪括号深度，仅计数当前深度（` _or_depth == 0`）的 OR token。
### R30-4 (MEDIUM): ` _child_gids` 包含传递性子组
**文件**：
**根因**： _child_gids` 从所有返回的 Term 中收集 group_id，包括嵌套括号创建的传递性父组。这些传递性组不应作为当前组的子组引用。
**修复**：过滤掉 (a) 已在现有 ` sub_group_refs` 中的 gid（传递性子组）和 (b) 自身就是父组的 gid（` sub_group_refs` 非空）。
### R30-5 (MEDIUM): 非否定组 DP 标记 NULL 安全列不精确
**文件**：
**根因**：非否定组中的 DP 标记 ` is_not=True`（如 ` NOT 2024:2025[DP]` 在非否定组内）和子组路径中的 DP 标记始终同时添加 ` pub_year.is_(None)` 和 ` pub_date.is_(None)`。
**修复**：根据标记文本中的范围值类型（4 位年份 → ` pub_year`，日期格式 → ` pub_date`）选择性地添加 NULL 安全列。
### R30-6 (LOW): ` query=None` 崩溃
**文件**：
**根因**： query.strip()` 在 ` query` 为 ` None` 时抛出 ` AttributeError`。
**修复**：改为 ` if query and query.strip():`。
### R30-7 (LOW): 搜索错误详情丢失
**文件**：
**根因**：
**修复**：对 400 错误优先展示 ` e?.response?.data?.detail`。
2026-07-29 08:24:28 +08:00
## R31 (2026-07-29): 第六轮并行审计修复
> **变更类型**： ）
### R31-1 (HIGH): 否定组日期标记缺乏 NULL 安全
**文件**：
**根因**：否定组中的日期标记（` NOT (DP:2020:2025)`）直接加入 ` g_neg` 作为裸 ` _marker_cond`。外层 ` not_(combined)` 包装后产生 ` NOT(marker_cond)`， NOT(NULL BETWEEN ...)` = NULL（非 TRUE），导致 pub_date 为 NULL 的论文被排除——用户预期 NULL 日期论文应被 NOT 条件包含。
**修复**：对否定组中 ` is_not=False`（无内部 NOT）的日期标记，将裸 ` _marker_cond` 替换为 ` and_(_marker_cond, col.is_not(None))`。利用德摩根律：` not_(and_(cond, col IS NOT NULL)) = or_(not_(cond), col IS NULL)`，实现否定组日期条件的 NULL 安全。对 DP 标记使用列精确 NULL 安全（纯年范围用 ` pub_year`，日期格式用 ` pub_date`）。
### R31-2 (MEDIUM): ` _NULL_SAFE_COL_MAP` "all" 字段假阳性
**文件**：
**根因**： _NULL_SAFE_COL_MAP` 将 "all" 字段映射到 ` GlobalLiterature.title`。当 ` title` 为 NULL 但其他字段（如 abstract）匹配否定词时，` or_(not_(cond), title.is_(None))` 产生 TRUE，导致匹配否定词的论文被错误包含。
**修复**：从 ` _NULL_SAFE_COL_MAP` 中移除 "all" 条目。多列 OR 条件通过 SQL 三值逻辑正确处理 NULL（ ，
### R31-3 (CRITICAL): year_counts 与主查询不一致
**文件**：
**根因**：主查询因条件冲突（如 ` text("FALSE")`、语义矛盾的组合）返回 0 结果时，year_counts 在早前阶段计算，可能包含完整分布。
**修复**：总计数计算完成后，若 ` total == 0` 且 year_counts 非空，清空 year_counts。确保 facet 缓存不会保存错误分布。
### R31-4 (MEDIUM): 缓存键空格未归一化
**文件**：
**根因**： _search_cache_key` 和 ` _facet_cache_key` 使用 ` query.strip().lower()` 归一化查询文本，但 ` strip()` 只去除首尾空格。` lung cancer`（双空格）和 ` lung cancer`（单空格）产生不同缓存键但相同搜索结果，导致缓存命中率下降。
**修复**：改为 ` " ".join(query.strip().lower().split())`，折叠所有内部空白序列为单空格。
### R31-5 (LOW): AND 聚类混合分组+未分组词
**文件**：
**根因**： A OR B AND C` 中 ` A OR B` 构成预分组，` C` 未分组。聚类后产生混合分组 ID（正负值混合），后续处理崩溃。
**修复**：未分组词分配到新组，预分组 ID 记录为子组引用。
### R31-6 (LOW): 提高分页上限硬限制
**文件**：
**根因**： page_size = max(1, min(page_size, 100))` 将分页上限限制为 100 条/页。
**修复**：主动硬限制，防止滥用。
### R31-7 (LOW): 缓存 TTL 1800→300 秒
**文件**：
**根因**：搜索缓存 TTL 为 1800 秒（30 分钟），新文献入库后用户需等半小时才能看到最新结果。
**修复**：TTL 统一降为 300 秒（5 分钟）。
### R31-8 (LOW): 引用数组字段 NOT 的 NULL 安全
**文件**：
**根因**： NOT` 否定词在 ` _NULL_SAFE_COL_MAP` 中映射了单列进行 NULL 安全包裹。对于 ` author`（ authors_names_text` + JSONB）和 ` affiliation`（ EXISTS` 自然处理 NULL（ jsonb_array_elements(NULL)` → 空集 → EXISTS FALSE → NOT(EXISTS FALSE) = TRUE），实践中影响极小。
**修复**：保留 ` author` 和 ` affiliation` 的单列映射，不影响正确性。
2026-07-29 07:30:36 +08:00
### R30-8 (LOW): 日期范围正则遗漏 YYYY-MM-DD
**文件**：
**根因**：日期范围正则只匹配 ` YYYY:YYYY` 和 ` YYYY/MM/DD:YYYY/MM/DD`，遗漏 ` YYYY-MM-DD:YYYY-MM-DD`（
**修复**：添加 ` -` 作为可选日期分隔符。` (\d{4}(?:[-\/]\d{2}[-\/]\d{2})?)`。
