# AstroResearch 天文科研辅助系统

AstroResearch 是一个基于 **Rust (Axum)** 后端与 **React (Vite + TypeScript)** 前端的天文文献一体化科研辅助系统。

---

## 1. 功能概述 (Overview)

AstroResearch 为天文领域的学者与研究人员提供一站式的文献管理与智能阅读解决方案，核心功能包括：

- 🌌 **统一学术检索**：一键跨源检索 NASA ADS 与 arXiv 数据库，支持去重元数据卡片式展示、高级组合条件检索与多种排序方式。
- 📥 **多通道文献同步与防爬绕过**：支持智能后台下载（官方 HTML / ar5iv 回退）、网页端本地 PDF/HTML 手动离线上传，以及浏览器书签脚本一键直推同步（无惧 Cloudflare 等高强度 WAF 拦截）。
- 🏷️ **下载错误诊断与无资源标记**：自动记录每篇文献 PDF/HTML 下载失败的具体原因（数据库 `error:` 前缀字段），支持一键标记"无有效全文资源"并从批量任务中排除。
- 📝 **结构化文献解析**：解析 HTML 或调用 MinerU (PDF 降级解析) 输出标准 GFM Markdown，对 LaTeX 公式实施占位符保护。
- 🗣️ **大模型双语翻译**：基于本地天文学词汇库 (Trie 树最长匹配) 构建翻译 Glossary，指导大模型进行公式级精准中英翻译。
- 🪐 **引文网络星系图**：基于 HTML5 Canvas 的高性能力导向拓扑渲染，双击节点支持引文深度探索。
- ✍️ **划词高亮与笔记**：在双语阅读器中自由划词、多色高亮并记录学术心得，数据与文献双向绑定。
- 🩺 **馆藏健康度检查**：内置诊断与修复工具，检测数据库与物理文件的不一致性并支持一键自动修复。

---

## 2. 快速启动 (Quickstart)

### 2.1 配置环境变量
将根目录下的 `.env.example` 复制并重命名为 `.env`：
```bash
cp .env.example .env
```
用编辑器打开填入你的 `ADS_API_KEY`、`LLM_API_KEY`、`QINIU_` 等第三方服务的认证 Token。

### 2.2 运行服务 (Run)

#### 方案一：本地开发调试模式 (Development Mode)
开发模式下分别启动后端 API 服务和前端 HMR 热更新服务：
1. **启动后端 (Rust Axum)**：
   ```bash
   cargo run
   ```
   后端服务默认运行在 `http://localhost:8000`，并会自动初始化本地 SQLite 数据库及运行 migrations 迁移。
2. **启动前端 (React Vite)**：
   ```bash
   cd dashboard
   npm install
   npm run dev
   ```
   前端开发服务器默认运行在 `http://localhost:5173`。前端的所有 `/api` 接口请求已配置反向代理，会自动转发到后端的 `8000` 端口。

#### 方案二：生产打包与单程序部署模式 (Production Mode)
生产模式下需要先编译前端静态文件，随后由后端进程统一托管分发：
1. **打包编译前端**：
   ```bash
   cd dashboard
   npm install
   npm run build
   ```
   静态资源将打包并输出在项目根目录下的 `dashboard/dist/` 目录。
2. **运行后端服务**：
   * **方式一：外部命令行模式**（默认）：
     ```bash
     cd ..
     cargo run --release
     ```
     *注意：默认模式下需下载 Obscura 二进制文件并放置在项目根目录的 `bin/` 目录下。*
   * **方式二：进程内浏览器模式**（免外部二进制分发）：
     ```bash
     cd ..
     cargo run --release --features obscura-inprocess
     ```
     *此时无头浏览器将直接编译进主二进制中，首次编译较慢但能一键运行。*

   运行后直接访问 `http://localhost:8000` 即可使用，此时所有 React 网页和后台 API 均由 Rust 进程统一分发托管，无需额外启动 Vite。详细配置说明参见 [编译与部署指南](docs/deployment.md#4-obscura-两种抓取后备部署模式选择-obscura-deployment-modes)。

### 2.3 馆藏文献健康度检查与修复 (Health Check)
系统提供内置的健康度校验脚本，可用于排查与自动修复数据库状态和物理磁盘文件的不一致问题：
- **只读扫描模式**：检测损坏文件、丢失文件、报错记录和孤立 Markdown，不改动任何数据。
  ```bash
  cargo run --bin health_check
  ```
- **自动修复模式**：物理清理磁盘损坏/无源文件，将失效路径重置为 `NULL`（安全保留 `error:` 报错诊断日志）。
  ```bash
  cargo run --bin health_check -- --fix
  ```

---

## 3. 技术文档结构 (Documentation Directory)

详细的技术和部署设计文档已集中整理至 `docs/` 目录：

- 🏗️ **[架构设计](docs/architecture.md)**：包含系统宏观流程图与序列图。
- 🌐 **[API 接口规范](docs/api.md)**：后端 Axum 路由及 HTTP 接口格式。
- 🗄️ **[数据库设计](docs/database.md)**：SQLite 表结构、ER 图与索引优化。
- 🎨 **[视觉与交互设计](docs/design.md)**：高对比度浅色中文控制台、自研 Canvas 图谱引擎说明。
- 🛠️ **[排障指南](docs/troubleshooting.md)**：人机校验、解析失败等常见问题解法。
- 🚀 **[编译与部署指南](docs/deployment.md)**：单执行文件打包与发布流程。
- 🤝 **[参与贡献指南](docs/contributing.md)**：开发规范及单元测试。

---

## 4. 项目目录结构 (Project Structure)

```
AstroResearch/
├── src/
│   ├── main.rs                  # Axum 服务入口：路由注册、中间件、静态资源托管
│   ├── lib.rs                   # 库入口：Config 配置结构体与环境变量加载
│   ├── api/                     # API 层（模块化拆分）
│   │   ├── mod.rs               # AppState / StandardPaper 定义 + handlers 兼容命名空间
│   │   ├── helpers.rs           # 共享工具函数：格式转换、数据库读写、路径校验
│   │   ├── papers.rs            # 文献相关：检索、下载、上传、解析、翻译、引文、导出
│   │   ├── notes.rs             # 笔记 CRUD：创建、查询、删除
│   │   └── sync.rs              # 批量同步：元数据同步、资源同步、查询管理
│   ├── bin/
│   │   └── health_check.rs      # 独立二进制：馆藏健康度诊断与修复工具
│   ├── clients/
│   │   ├── ads.rs               # NASA ADS API 客户端
│   │   ├── arxiv.rs             # arXiv Atom XML API 客户端
│   │   └── qiniu.rs             # 七牛云对象存储客户端
│   └── services/
│       ├── batch/               # 批量同步引擎（模块化拆分）
│       │   ├── mod.rs           # 公共导出
│       │   ├── meta.rs          # 元数据大批量采集 (MetaSync)
│       │   └── asset.rs         # 物理资源批量处理 (AssetSync)
│       ├── download.rs          # 文献下载器：反爬伪装、多级回退、错误记录
│       ├── parser.rs            # HTML/PDF → Markdown 解析器
│       ├── translation.rs       # LLM 翻译器 + Trie 词典
│       ├── query_parser.rs      # 高级检索语法解析
│       └── logging.rs           # 日志系统：控制台美化 + 滚动文件
├── dashboard/
│   └── src/
│       ├── App.tsx              # 全局状态管理与布局
│       ├── types.ts             # TypeScript 类型定义
│       ├── components/
│       │   ├── CitationGalaxyCanvas.tsx  # Canvas 力导向引文星系图
│       │   └── CustomSelect.tsx         # 可复用下拉选择组件
│       └── features/
│           ├── search/SearchPanel.tsx    # 跨源检索面板
│           ├── library/LibraryPanel.tsx  # 馆藏管理面板
│           ├── reader/ReaderPanel.tsx    # 双语对照阅读器
│           ├── citation/CitationPanel.tsx # 引文图谱面板
│           ├── sync/SyncPanel.tsx        # 批量同步控制台
│           └── settings/SettingsPanel.tsx # 系统设置
├── migrations/                  # SQLite 数据库迁移脚本
├── library/                     # 本地文献物理存储目录
│   ├── PDF/                     # 下载的 PDF 文件
│   ├── HTML/                    # 下载的 HTML 文件
│   ├── Markdown/                # 解析后的 Markdown 文件
│   └── Translation/             # 翻译后的中文 Markdown 文件
├── docs/                        # 技术文档
└── dictionary.txt               # 天文学双语名词词典
```