# AstroResearch Architecture / 架构设计

AstroResearch 是一个集成了天文学文献检索、多通道下载（含防爬绕过与手动上传）、下载错误诊断、结构化解析、中英学术对比翻译、引文星系图谱以及馆藏健康度诊断的天文科研辅助系统。

## 3. 核心模块说明

### 3.1 API 层 (`src/api/`)

| 模块文件 | 职责 |
|:---|:---|
| **[mod.rs](../src/api/mod.rs)** | 定义全局共享状态 `AppState`（含 `active_bibcode` 追踪）和统一文献格式 `StandardPaper`（含 `pdf_error` / `html_error` 诊断字段），通过 `pub mod handlers` 保持向后兼容命名空间。 |
| **[helpers.rs](../src/api/helpers.rs)** | 共享工具函数：`convert_ads_doc_to_standard`、`convert_arxiv_to_standard`、`save_paper_to_db`、`get_paper_from_db`、`check_paper_paths_in_db`。负责数据库 CRUD 和 `error:` 前缀诊断信息的读取与解析。 |
| **[papers.rs](../src/api/papers.rs)** | 文献相关核心处理器：统一检索 (`search_papers`)、下载 (`download_paper`)、**手动上传 (`upload_paper_file`)**、**无资源标记 (`mark_no_resource`)**、解析 (`parse_paper`)、翻译 (`translate_paper`)、引文拓扑 (`get_citation_network`)、文献详情 (`get_paper_detail`)、馆藏列表 (`get_library`)、BibTeX 导出 (`export_citations`)、**活跃文献追踪 (`get/set_active_bibcode`)**。 |
| **[notes.rs](../src/api/notes.rs)** | 笔记 CRUD 处理器：创建 (`create_note`)、查询 (`get_notes`)、删除 (`delete_note`)。 |
| **[sync.rs](../src/api/sync.rs)** | 批量同步控制处理器：元数据同步启动/状态/计数、资源同步启动/停止/状态、检索条件管理。 |

### 3.2 服务层 (`src/services/`)

| 模块文件 | 职责 |
|:---|:---|
| **[batch/mod.rs](../src/services/batch/mod.rs)** | 批量同步引擎公共导出模块。 |
| **[batch/meta.rs](../src/services/batch/meta.rs)** | 元数据大批量采集引擎 (`MetaSync`)：分页检索 ADS/arXiv 并增量入库。 |
| **[batch/asset.rs](../src/services/batch/asset.rs)** | 物理资源批量处理引擎 (`AssetSync`)：后台异步执行下载/解析/翻译流水线，记录 `download_failed` / `parse_failed` 计数，保留最新 100 条日志。 |
| **[download.rs](../src/services/download.rs)** | 多通道下载器：浏览器头伪装与请求延迟控制、ADS Link Gateway 重定向追踪与 `validate.perfdrive.com` 防护解码绕过、官方 `arxiv.org/html` 优先及 `ar5iv` 兜底、**下载失败时以 `error:` 前缀记录诊断信息至数据库**。 |
| **[parser.rs](../src/services/parser.rs)** | HTML 语法树向 GFM Markdown 逆向转换，使用占位符保护 LaTeX 公式；统一图表链接；集成 MinerU PDF 解析。 |
| **[translation.rs](../src/services/translation.rs)** | 基于本地天文双语词典的 Trie 树最长匹配分词，注入 Glossary 系统提示词让 LLM 实现学术级精细翻译。 |
| **[query_parser.rs](../src/services/query_parser.rs)** | 高级检索语法解析器，将前端组合条件（AND/OR/NOT + 字段限定）转换为 ADS API 查询语法。 |
| **[logging.rs](../src/services/logging.rs)** | 全局日志记录系统，基于 `tracing-subscriber` 实现控制台美化日志输出与基于时间的每日滚动日志文件写出，使用上海时区 (+08:00) 格式化时间。 |

### 3.3 客户端层 (`src/clients/`)

| 模块文件 | 职责 |
|:---|:---|
| **[ads.rs](../src/clients/ads.rs)** | NASA ADS API 客户端：文献检索、元数据获取、BibTeX 导出。 |
| **[arxiv.rs](../src/clients/arxiv.rs)** | arXiv Atom XML API 客户端：解析 XML Feed 提取文献元数据。 |
| **[qiniu.rs](../src/clients/qiniu.rs)** | 七牛云对象存储客户端：PDF 插图上传与 CDN 外链生成。 |

### 3.4 独立工具 (`src/bin/`)

| 文件 | 职责 |
|:---|:---|
| **[health_check.rs](../src/bin/health_check.rs)** | 馆藏健康度诊断与修复工具：检测损坏文件、丢失文件、`error:` 报错记录和孤立 Markdown；`--fix` 模式自动清理并重置数据库状态。 |

### 3.5 前端核心组件 (`dashboard/src/`)

| 目录/组件文件 | 职责 |
|:---|:---|
| **[App.tsx](../dashboard/src/App.tsx)** | 全局骨架与胶水层：鉴权外壳、Tab 持久化、挂载全局弹窗，调度各页面跨组件跳转逻辑。 |
| **[pages/SearchPanel.tsx](../dashboard/src/pages/SearchPanel.tsx)** | 统一跨源检索页面：支持高级检索构造、分页排序以及下载错误状态提示与文献类型徽章显示。 |
| **[pages/LibraryPanel.tsx](../dashboard/src/pages/LibraryPanel.tsx)** | 馆藏管理页面：展现本地馆藏列表、最近阅读、同步状态、支持下载失败和“无资源”状态筛选。 |
| **[pages/ReaderPanel.tsx](../dashboard/src/pages/ReaderPanel.tsx)** | 对照阅读器视图：以 children 组合形式装配 `BilingualViewer` 与 `ReaderNotesSidebar`。 |
| **[pages/CitationPanel.tsx](../dashboard/src/pages/CitationPanel.tsx)** | 引文星系图谱视图：装配自研 Canvas 引文拓扑力导图。 |
| **[pages/SyncPanel.tsx](../dashboard/src/pages/SyncPanel.tsx)** | 批量同步控制页面：装配元数据同步面板、流水线批量任务日志流虚拟终端。 |
| **[pages/ResearchAgentPanel.tsx](../dashboard/src/pages/ResearchAgentPanel.tsx)** | 智能科研助理页面：装配 SSE 研讨消息列表、多模式选择、思维链展示与会话侧栏。 |
| **[components/](../dashboard/src/components/)** | 通用与业务子组件：如 Canvas 引擎 ([CitationGalaxyCanvas.tsx](../dashboard/src/components/CitationGalaxyCanvas.tsx))、下拉选择 ([CustomSelect.tsx](../dashboard/src/components/CustomSelect.tsx))、学术助手侧栏、智能体对话等。 |
| **[hooks/](../dashboard/src/hooks/)** | 全局与特定页面业务逻辑状态 Hook 库（如 `useLibrary`, `useSearch`, `useReaderState`, `useSyncState`, `useResearchAgent` 等），实现数据逻辑与 UI 渲染彻底解耦。 |
| **[types/index.ts](../dashboard/src/types/index.ts)** | 全局 TypeScript 静态类型定义中心。 |

---