Asfmq
8cc2b74abc
后端：
- 将 handlers.rs (1338行) 拆分为 helpers/papers/notes/sync 四模块
- 将 batch_sync.rs 拆分为 batch/{mod,meta,asset} 三模块
- 新增 POST /api/upload 多部件文件上传接口
- 新增 POST /api/no_resource 标记文献"无全文资源"
- 新增 GET/POST /api/active_bibcode 追踪活跃文献
- StandardPaper 结构体扩展 pdf_error / html_error 错误诊断字段
- download.rs 记录下载失败详情至数据库
- 新增 health_check 二进制工具，支持只读扫描与 --fix 自动修复
- 移除 scratch/ 目录、recovered_handlers.rs 及调试日志
前端：
- 新建 CustomSelect 可复用组件，替换全部原生 select
- LibraryPanel：同步按钮反馈动画、下载失败/无资源状态筛选与计数、
文献类型筛选、状态优先排序、搜索一键清空
- 详情弹窗：错误诊断展示、手动 PDF/HTML 上传区、无资源标记/恢复
- SearchPanel：扩展文献类型徽章、下载失败状态提示
- SyncPanel：同步启动乐观 UI 更新、日志容器内自动滚动
- Tab 状态 localStorage 持久化、弹窗 z-index 修复
99 lines
7.8 KiB
Markdown
99 lines
7.8 KiB
Markdown
# AstroResearch Troubleshooting / 常见问题与排障指南
|
||
|
||
在使用 AstroResearch 过程中可能遇到的问题及排障步骤如下：
|
||
|
||
---
|
||
|
||
## 1. 文献下载相关问题 (Download Issues)
|
||
|
||
### 1.1 下载任务遇到 "检测到 Cloudflare / 人机验证页面"
|
||
- **原因**：部分出版商对频繁的自动化下载请求实施了高强度的 IP 拦截与 CF 校验。
|
||
- **解决方法**：
|
||
1. 系统目前已经实现每两次请求间随机延迟 `maybe_delay()` (500ms~2000ms)，以防行为过于机械化。
|
||
2. 若拦截频繁，可以尝试在本地配置代理；或者检查 `.env` 中的 `LIBRARY_DIR` 路径是否正确。
|
||
3. 对于 ADS Link Gateway 路由，若跳转至 `validate.perfdrive.com`，下载器内置了解码 `ssc` 提取直链的策略，该过程自动进行，如果由于其加密机制变更导致提取失效，系统控制台会输出 `warn` 日志。
|
||
4. 下载失败后，系统会在数据库中自动记录以 `error:` 前缀的诊断信息。前端文献卡片会以红色角标标识"下载失败"，鼠标悬浮可查看具体失败原因。
|
||
|
||
### 1.2 官方 HTML (arxiv.org/html) 下载返回 404
|
||
- **原因**：arXiv 官方 HTML 正文服务仅在 **2023年12月** 之后提交的论文中默认提供。对于老文献，直接请求官方 HTML 会返回 404。
|
||
- **解决机制**：AstroResearch 的 `download_arxiv_html_with_fallback` 会在官方 HTML 请求失败时，**自动无缝降级回退**到 `ar5iv.labs.arxiv.org` 服务进行拉取。
|
||
|
||
### 1.3 通过手动上传或浏览器书签直推绕过 Cloudflare 防爬
|
||
- **原因**：部分出版商对自动化脚本下载防范严密，直接通过后台任务下载容易导致获取失败（并在数据库中存入带有 `error:` 前缀的报错描述）。
|
||
- **解决方法**：
|
||
1. **方案 A (详情弹窗手动上传)**：在文献详情弹窗中，点击文献直链（系统会使用您本人的真实浏览器和网络环境打开源站），手动下载 PDF 或 HTML，然后拖拽/上传至详情弹窗对应的上传区。
|
||
2. **方案 B (书签直推导入)**：在批量同步面板底部，点击"添加导入书签"按钮，或将其直接拖拽至您的浏览器书签栏（书签名为"导入AstroResearch"）。当您使用真实浏览器访问文献源站（如 arXiv 页面）时，点击该书签，在弹出的窗口中确认 Bibcode，即可直接将解析后的内容通过 API 直推同步到本地。
|
||
|
||
### 1.4 标记文献为"无有效全文资源"
|
||
- **原因**：部分文献（如会议摘要、天文电报、观测提案等）本身不存在可下载的全文 PDF/HTML，反复尝试下载会浪费时间。
|
||
- **解决方法**：
|
||
1. 在文献详情弹窗底部，点击"标记为无有效全文资源"按钮。
|
||
2. 标记后，文献卡片角标变为灰色"无资源"状态，后续批量下载/解析任务将自动跳过此文献。
|
||
3. 若需恢复，再次点击"恢复自动下载状态"按钮即可清除标记。
|
||
|
||
---
|
||
|
||
## 2. 文献解析与翻译问题 (Parse & Translation Issues)
|
||
|
||
### 2.1 翻译请求返回空或报错 "LLM API KEY Missing"
|
||
- **原因**：根目录下没有配置正确的 `.env` 文件，或者 LLM 提供的 Endpoint/Model 有误。
|
||
- **排查步骤**：
|
||
1. 确认项目根目录下存在 `.env` 且拥有 `LLM_API_KEY` 及 `LLM_API_BASE` 配置。
|
||
2. 使用终端运行 `cargo run`，检查启动日志中是否有关于读取环境配置的警告信息。
|
||
|
||
### 2.2 PDF 解析缺少图表或公式损坏
|
||
- **原因**：PDF 格式本身不支持结构化语义。直接提取文本会丢失公式和图表。
|
||
- **解决机制**：
|
||
1. 如果文献有 HTML/ar5iv 格式，系统会自动优先基于 HTML 解析，保留完美的 LaTeX 公式。
|
||
2. 若该文献只有 PDF 格式，系统自动降级调用本地或远程的 **MinerU** PDF 图文大模型解析。请确保本地 MinerU 解析服务已按照 API 格式运行并在 `.env` 中正确填入 `MINERU_API_URL`。
|
||
|
||
---
|
||
|
||
## 3. 检索与显示问题 (Search & Display Issues)
|
||
|
||
### 3.1 无法通过特定的 arXiv ID 或 DOI 检索到已导入的文献
|
||
- **原因**：历史版本前端本地检索仅匹配了文献的标题、作者、摘要和 `bibcode`，未对 `arxiv_id` 和 `doi` 进行全局检测过滤。
|
||
- **排障/解决**：现已在馆藏过滤逻辑中追加了 `arxiv_id` 和 `doi` 的字段检索。如果遇到由于升级导致的缓存错乱，可点击顶部的 "重新同步馆藏" 刷新本地缓存状态。
|
||
|
||
### 3.2 文献详情页的 BIBCODE 与 ARXIV ID 显示完全相同的值（如均显示 '0710.0600'）
|
||
- **原因**：当文献通过 arXiv 单独直接导入时，后端处理器无法预知其关联的 ADS Bibcode。为确保数据一致，系统在 SQLite 中临时将 `bibcode` 和 `arxiv_id` 均用 arXiv ID 填充，直到后续 ADS 元数据同步匹配成功将其"升级"。
|
||
- **解决机制**：前端已实现了防重与标识规整机制。如果检测到 `bibcode === arxiv_id`，卡片页将前缀格式化为 `arXiv:xxxx.xxxx` 形式，而文献元数据详情弹窗中 `BIBCODE` 则会直接优雅呈现为 **"暂无"** 状态，避免视觉歧义。
|
||
|
||
### 3.3 馆藏面板"重新同步馆藏"按钮点击后没有反馈
|
||
- **原因**：早期版本中同步操作是异步静默执行的，用户无法感知操作进度。
|
||
- **解决机制**：当前版本已增加同步反馈机制：
|
||
- 点击按钮后显示加载动画（旋转图标 + "正在同步..." 文字）。
|
||
- 同步完成后弹出绿色成功提示条（显示馆藏数量），或红色错误提示条。
|
||
- 反馈信息 3 秒后自动消失。
|
||
|
||
---
|
||
|
||
## 4. 数据库与运行环境问题 (Runtime & DB Issues)
|
||
|
||
### 4.1 启动提示 "Database Migration Failed"
|
||
- **原因**：本地 SQLite 数据库文件 `astro_research.db` 出现并发锁死或版本 schema 冲突。
|
||
- **解决方法**：
|
||
1. 备份并临时删除根目录下的 `astro_research.db` 数据库文件。
|
||
2. 重新启动服务：`cargo run`，系统将重新执行 `migrations/` 下的全部 SQL 迁移脚本以建立最新库结构。
|
||
|
||
### 4.2 馆藏文献健康度检查工具 (health_check)
|
||
- **原因**：大批量文献下载、解析或手动增删物理文件后，可能存在数据库状态与物理文件不一致的情况。
|
||
- **排障与修复步骤**：
|
||
1. **只读扫描**：运行 `cargo run --bin health_check`。此操作将扫描本地物理文件并验证它们是否损坏，检测数据库是否有丢失物理文件、报错记录（以 `error:` 开头）或孤立 Markdown 的文献。
|
||
2. **一键修复**：运行 `cargo run --bin health_check -- --fix` 执行修复：
|
||
- 系统将自动**删除磁盘上损坏的 PDF/HTML 物理文件**，并在数据库中将其重置为 `NULL` 以便后续重新触发下载。
|
||
- 系统将自动**删除孤立的 Markdown 物理文件**并将其重置为 `NULL`。
|
||
- **特别注意**：对于数据库中已存入的 `error:` 报错诊断信息，为了保留报错排障的有用线索，**修复程序不会删除这些报错记录**（即不会重置为 `NULL`），以便您后续查看与手动上传修复。
|
||
|
||
---
|
||
|
||
## 5. 前端界面问题 (Frontend UI Issues)
|
||
|
||
### 5.1 下拉选择框样式与浏览器原生样式不一致
|
||
- **原因**：系统使用自研的 `CustomSelect` 组件替代了原生 `<select>` 元素，以实现统一的视觉风格和交互体验。
|
||
- **说明**：所有下拉框（状态筛选、文献类型筛选、排序方式、检索条件组合等）均已统一使用 `CustomSelect` 组件，支持点击外部自动关闭、选中项高亮等交互。
|
||
|
||
### 5.2 同步面板日志自动滚动干扰全页浏览
|
||
- **原因**：早期版本中日志自动滚动使用 `scrollIntoView` 会影响整个页面。
|
||
- **解决机制**：当前版本改为仅滚动日志容器内部元素，并增加了 80px 的阈值判断，只有当用户处于接近底部的阅读位置时才自动滚动追踪最新日志。
|