feat: 初始化 AstroResearch 核心系统代码及重构技术文档

docs/api.md

@@ -0,0 +1,274 @@
+# AstroResearch REST API Documentation / REST API 接口文档
+
+AstroResearch 后端服务运行于 Rust Axum 框架之上，默认基准 URL 为 `http://localhost:8000/api`。
+
+---
+
+## 1. 共享类型定义 (TypeScript Type Definitions)
+
+为了前后端类型一致，以下是主要的 TypeScript 数据接口定义：
+
+```typescript
+// 标准文献元数据
+export interface StandardPaper {
+  bibcode: string;
+  title: string;
+  authors: string[];
+  year: string;
+  pub_journal: string;
+  keywords: string[];
+  abstract_text: string;
+  doi: string;
+  arxiv_id: string;
+  citation_count: number;
+  reference_count: number;
+  is_downloaded: boolean;
+  has_markdown: boolean;
+  has_translation: boolean;
+}
+
+// 笔记记录
+export interface NoteRecord {
+  id: number;
+  bibcode: string;
+  paragraph_index: number;
+  note_text: string;
+  highlight_color: string; // 'yellow' | 'green' | 'blue' | 'pink'
+  selected_text: string;
+  created_at: string;
+}
+```
+
+---
+
+## 2. 接口分模块详述 (API Endpoints)
+
+### 2.1 检索与引文导出模块 (Search & Citations Export)
+
+#### 2.1.1 跨源文献统一搜索
+- **Endpoint**: `GET /api/search`
+- **Description**: 同时从 NASA ADS 与 arXiv XML 接口检索文献，返回去重并标准化后的文献元数据。
+- **Query Parameters**:
+  - `q` (string, required): 检索关键词。
+  - `source` (string, optional): 指定源，取值为 `all` | `ads` | `arxiv`，默认 `all`。
+  - `rows` (number, optional): 返回条数限制。
+- **Response Schema (`Vec<StandardPaper>`)**:
+  - HTTP `200 OK`
+- **cURL 示例**:
+  ```bash
+  curl -G "http://localhost:8000/api/search" \
+    --data-urlencode "q=Hertzsprung-Russell diagram" \
+    --data-urlencode "source=all"
+  ```
+
+#### 2.1.2 批量引文 BibTeX 导出
+- **Endpoint**: `POST /api/export`
+- **Description**: 将选中的文献 Bibcode 批量提交给 NASA ADS 接口，返回拼接的标准 BibTeX 文本。
+- **Request Body**:
+  ```json
+  {
+    "bibcodes": ["2024arXiv241011663H", "1984AJ.....89..374B"]
+  }
+  ```
+- **Response Schema**:
+  ```json
+  {
+    "bibtex": "@ARTICLE{2024arXiv241011663H, ...}\n\n@ARTICLE{1984AJ.....89..374B, ...}"
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/export" \
+    -H "Content-Type: application/json" \
+    -d '{"bibcodes": ["2024arXiv241011663H"]}'
+  ```
+
+---
+
+### 2.2 馆藏管理与物理文件模块 (Library & Local Storage)
+
+#### 2.2.1 获取馆藏文献列表
+- **Endpoint**: `GET /api/library`
+- **Description**: 查询本地 SQLite 数据库中已收藏入库的所有文献列表，后端会自动**实时感应物理文件是否存在**来修正 `is_downloaded` / `has_markdown` 等布尔状态。
+- **Response Schema (`Vec<StandardPaper>`)**:
+  - HTTP `200 OK`
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/library"
+  ```
+
+#### 2.2.2 触发并行文献下载
+- **Endpoint**: `POST /api/download`
+- **Description**: 触发后台线程拉取文献的 PDF 及 HTML。如果是 arXiv 来源优先官方 HTML 兜底 ar5iv，并支持强制更新。
+- **Request Body**:
+  ```json
+  {
+    "bibcode": "2024arXiv241011663H",
+    "force": false
+  }
+  ```
+- **Response Schema (`StandardPaper`)**: Returns the updated paper structure with `is_downloaded: true`.
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/download" \
+    -H "Content-Type: application/json" \
+    -d '{"bibcode": "2024arXiv241011663H", "force": true}'
+  ```
+
+#### 2.2.3 触发文献结构化解析
+- **Endpoint**: `POST /api/parse`
+- **Description**: 将本地下载的 HTML/PDF 清洗为 Markdown。支持 `force` 强制重新执行。
+- **Request Body**:
+  ```json
+  {
+    "bibcode": "2024arXiv241011663H",
+    "force": false
+  }
+  ```
+- **Response Schema**:
+  ```json
+  {
+    "markdown": "# 论文标题\n\n## 1. 绪论\n..."
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/parse" \
+    -H "Content-Type: application/json" \
+    -d '{"bibcode": "2024arXiv241011663H", "force": false}'
+  ```
+
+---
+
+### 2.3 阅读器与翻译模块 (Reader & LLM Translation)
+
+#### 2.3.1 获取文献阅读详情
+- **Endpoint**: `GET /api/paper`
+- **Description**: 获取某篇文献的标准元数据和已缓存的英文正文 Markdown 以及翻译后 Markdown。
+- **Query Parameters**:
+  - `bibcode` (string, required): 文献唯一标识符。
+- **Response Schema**:
+  ```json
+  {
+    "paper": { ... },
+    "english_content": "# Abstract...", // 若未解析，返回 null
+    "translation_content": "# 摘要..." // 若未翻译，返回 null
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/paper?bibcode=2024arXiv241011663H"
+  ```
+
+#### 2.3.2 触发 LLM 对照翻译
+- **Endpoint**: `POST /api/translate`
+- **Description**: 将英文 Markdown 提取本地词典名词注入 Glossary 提示词，并调用大模型进行学术翻译，最后写回本地物理文件并入库。
+- **Request Body**:
+  ```json
+  {
+    "bibcode": "2024arXiv241011663H",
+    "force": false
+  }
+  ```
+- **Response Schema**:
+  ```json
+  {
+    "translation": "# 翻译结果..."
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/translate" \
+    -H "Content-Type: application/json" \
+    -d '{"bibcode": "2024arXiv241011663H"}'
+  ```
+
+---
+
+### 2.4 引文网络拓扑模块 (Citation Galaxy Map)
+
+#### 2.4.1 查询文献的引文拓扑
+- **Endpoint**: `GET /api/citations`
+- **Description**: 获取某篇文献的参考文献 (References) 和施引文献 (Citations) 的 Bibcode 数组列表，用于渲染拓扑关系网。
+- **Query Parameters**:
+  - `bibcode` (string, required): 目标文献 Bibcode。
+- **Response Schema**:
+  ```json
+  {
+    "bibcode": "2024arXiv241011663H",
+    "title": "...",
+    "citation_count": 12,
+    "reference_count": 48,
+    "references": ["bibcode1", "bibcode2"],
+    "citations": ["bibcode3", "bibcode4"]
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/citations?bibcode=2024arXiv241011663H"
+  ```
+
+---
+
+### 2.5 笔记高亮模块 (Notes & Highlights)
+
+#### 2.5.1 创建笔记与高亮
+- **Endpoint**: `POST /api/notes`
+- **Description**: 对指定文献的特定段落位置创建高亮选段，并记录文字备注。
+- **Request Body**:
+  ```json
+  {
+    "bibcode": "2024arXiv241011663H",
+    "paragraph_index": 12,
+    "note_text": "这是一个重要的物理模型",
+    "highlight_color": "yellow", // 'yellow' | 'green' | 'blue' | 'pink'
+    "selected_text": "the standard model of galaxy formation"
+  }
+  ```
+- **Response Schema (`NoteRecord`)**: Returns the created note details containing auto-incremented `id` and creation timestamp.
+- **cURL 示例**:
+  ```bash
+  curl -X POST "http://localhost:8000/api/notes" \
+    -H "Content-Type: application/json" \
+    -d '{"bibcode": "2024arXiv241011663H", "paragraph_index": 12, "note_text": "My Note", "highlight_color": "green", "selected_text": "original text"}'
+  ```
+
+#### 2.5.2 获取单篇文献下的全部笔记
+- **Endpoint**: `GET /api/notes`
+- **Description**: 查询某篇文献关联的所有笔记。
+- **Query Parameters**:
+  - `bibcode` (string, required): 目标文献。
+- **Response Schema (`Vec<NoteRecord>`)**:
+  - HTTP `200 OK`
+- **cURL 示例**:
+  ```bash
+  curl "http://localhost:8000/api/notes?bibcode=2024arXiv241011663H"
+  ```
+
+#### 2.5.3 删除笔记
+- **Endpoint**: `DELETE /api/notes`
+- **Description**: 物理删除指定 ID 的笔记高亮记录。
+- **Query Parameters**:
+  - `id` (number, required): 笔记记录的唯一自增 id。
+- **Response Schema**:
+  ```json
+  {
+    "status": "success"
+  }
+  ```
+- **cURL 示例**:
+  ```bash
+  curl -X DELETE "http://localhost:8000/api/notes?id=5"
+  ```
+
+---
+
+## 3. 常见 HTTP 状态码与异常处理 (Error Codes)
+
+系统基于标准的 HTTP Status Codes 返回错误原因，响应的 Response Body 中通常为纯文本提示（String）：
+
+| 状态码 | 错误类型 | 触发常见场景及原因说明 |
+| :--- | :--- | :--- |
+| **`400 Bad Request`** | 业务请求不合规 | - 文献未下载/解析却直接调用 `translate`。<br>- 未在 `.env` 中提供 `ADS_API_KEY` 时调用 `export`。 |
+| **`404 Not Found`** | 资源未找到 | - 数据库中没有该 Bibcode 的收藏记录。 |
+| **`500 Internal Error`**| 服务器内部错误 | - 第三方 LLM / ADS 接口通信超时或返回异常。<br>- 本地磁盘 IO 失败（如写入文件权限受阻）。<br>- 数据库查询异常。 |

docs/architecture.md

@@ -0,0 +1,228 @@
+# AstroResearch Architecture / 架构设计
+
+AstroResearch 是一个集成了天文学文献检索、双通道下载、结构化解析、中英学术对比翻译以及引文星系图谱的天文科研辅助系统。
+
+## 1. 整体架构 (Overall Architecture)
+
+AstroResearch 采用 **C/S (Client-Server)** 架构，由前端 React 单页应用和后端 Axum HTTP 服务构成，核心流程及层级如下：
+
+```mermaid
+graph TD
+    subgraph Frontend ["React 前端 (Port 5173 / 8000)"]
+        UI[仪表盘 UI / ReaderPanel]
+        Canvas[引文 Canvas 拓扑图]
+        API_Client[Axum API 客户端]
+    end
+
+    subgraph Backend ["Rust Axum 后端 (Port 8000)"]
+        Router[Axum 路由与中间件]
+        Handlers[业务处理器 handlers.rs]
+        Parser[解析器 parser.rs]
+        Downloader[下载器 download.rs]
+        Translator[翻译器 translation.rs]
+        Qiniu[七牛云客户端 qiniu.rs]
+        DB[("SQLite / astro_research.db")]
+    end
+
+    subgraph External [外部第三方服务]
+        ADS[NASA ADS API]
+        arXiv[arXiv Atom XML API]
+        MinerU[MinerU PDF 解析服务]
+        QiniuCDN[七牛云对象存储 CDN]
+        LLM[LLM API]
+    end
+
+    UI -->|用户操作| API_Client
+    API_Client -->|RESTful APIs| Router
+    Router --> Handlers
+    
+    Handlers -->|查询/保存元数据| DB
+    Handlers -->|文献下载| Downloader
+    Handlers -->|结构化清洗| Parser
+    Handlers -->|LLM学术翻译| Translator
+    
+    Downloader -->|代理请求| ADS
+    Downloader -->|直连或 ar5iv| arXiv
+    
+    Parser -->|图文降级解析| MinerU
+    Parser -->|托管插图| Qiniu
+    Qiniu -->|上传图片| QiniuCDN
+    
+    Translator -->|天文术语翻译| LLM
+    
+    Canvas -->|引文网络请求| Handlers
+```
+
+---
+
+## 2. 核心工作流 (Core Workflows)
+
+### 2.1 文献下载流程 (Download Flow)
+
+本流程实现了文献的双通道流式下载，支持多级回退以及安全反爬防线绕过，其详细步骤与交互如下：
+
+```mermaid
+sequenceDiagram
+    participant U as 用户 (React 前端)
+    participant H as 处理器 (handlers.rs)
+    participant D as 下载器 (download.rs)
+    participant DB as 本地数据库 (SQLite)
+    
+    U->>H: 1. 发起下载请求 (POST /api/download, 含 bibcode, force)
+    H->>DB: 2. 查询文献元数据 (获取 arxiv_id, doi 等)
+    alt force == true
+        H->>DB: 3. 重置本地下载路径字段为 NULL
+    end
+    
+    H->>D: 4. 调度下载器执行物理拉取
+    alt 文献含有 arxiv_id (通道 A：arXiv 直连优先)
+        D->>D: 5a. 去除版本号 (strip_arxiv_version, v2 -> 无版本)
+        D->>D: 5b. 随机延时 (maybe_delay: 500-2000ms) 并伪装 UA
+        D->>D: 5c. 下载 PDF 并校验文件头 (%PDF + %%EOF)
+        D->>D: 5d. 优先请求官方 HTML (arxiv.org/html/)
+        note over D: 若官方 HTML 返回 404/错误
+        D->>D: 5e. 自动降级回退请求 ar5iv HTML (ar5iv.labs.arxiv.org)
+        D->>D: 5f. 校验 HTML 内容 (detect_anti_bot 检测反爬)
+    else 无 arxiv_id (通道 B：ADS 路由回退)
+        D->>D: 6a. 跟踪 ADS Link Gateway 重定向路由
+        note over D: 若遇到 validate.perfdrive.com 拦截
+        D->>D: 6b. 自动解析并解码 ssc 参数提取直链
+        note over D: 若指向 IOPscience / Springer
+        D->>D: 6c. IOP 专属策略：预热主页写入 Cookie，带 Referer 下载 PDF
+        D->>D: 6d. Springer 专属策略：使用 Chrome 头下载 HTML 页
+        note over D: 若网关均失败且存在 DOI
+        D->>D: 6e. CrossRef 兜底：请求 CrossRef API 获取 PDF URL 并直连下载
+    end
+    
+    D-->>H: 7. 返回下载好的本地物理 PDF & HTML 路径
+    H->>DB: 8. 更新 pdf_path & html_path 记录
+    H-->>U: 9. 返回最新文献状态 (is_downloaded: true)
+```
+
+#### 详细下载说明：
+1. **指令接收与校验**：后端 `download_paper` 接口在 `force` 参数为 `true` 时，会强行擦除数据库中已下载的文件路径，启动无缓存的物理文件重新拉取。
+2. **下载反爬伪装**：下载器 `Downloader` 请求时采用动态生成的 Firefox/Chrome 轮换 User-Agent，并在每次 HTTP 访问前强制加入随机休眠机制（500ms - 2000ms），模拟人类自然阅读行为。
+3. **内容完整性校验**：
+   - 对 PDF 严格校验前四个字节（必须是 `%PDF`）以及尾部检索（必须包含 `%%EOF` 终止符），排查登录墙、错误页伪装成 PDF 导致下载坏文件的问题。
+   - 对 HTML 文本利用 `detect_anti_bot` 流水线过滤 "cloudflare"、"captcha"、"robot check" 等拦截特征。
+
+---
+
+### 2.2 文献解析流程 (Parse Flow)
+
+本流程负责将本地下载的 HTML 或 PDF 转换为高保真的 Markdown。其详细步骤与交互如下：
+
+```mermaid
+sequenceDiagram
+    participant U as 用户 (React 前端)
+    participant H as 处理器 (handlers.rs)
+    participant P as 解析器 (parser.rs)
+    participant M as MinerU (PDF解析服务)
+    participant Q as 七牛云 (对象存储)
+    participant DB as 本地数据库 (SQLite)
+    
+    U->>H: 1. 发起解析请求 (POST /api/parse, 含 bibcode, force)
+    H->>DB: 2. 查询文献物理路径 (pdf_path, html_path, markdown_path)
+    alt force == false 且本地已存在 Markdown 物理缓存
+        H->>H: 3. 读取本地 Markdown 物理文件
+        H-->>U: 4. 直接返回缓存 Markdown，流程结束
+    end
+    
+    H->>P: 5. 触发结构化文献解析
+    alt 本地存在 HTML 文件
+        P->>P: 6a. 剥离广告/导航栏与尾页页脚噪声
+        P->>P: 6b. 公式保护：利用占位符隔离 MathJax/LaTeX 公式段
+        P->>P: 6c. 标签规范：还原 LaTeXML 特定 span 为标准 table/tr/td，修正上下标
+        P->>P: 6d. 插图处理：把相对图像路径替换为绝对 CDN 外链地址
+        P->>P: 6e. 转换 GFM Markdown 并恢复 LaTeX 公式
+        P->>P: 6f. 后处理：清除冗余的 margin 空白与前导缩进
+    else 仅有 PDF 文件 (PDF 降级解析)
+        P->>M: 7a. Multipart 格式上传 PDF 至 MinerU 服务
+        M-->>P: 7b. 返回大模型解析出的 Markdown 文本及插图包
+        loop 遍历每一个提取的插图
+            P->>Q: 7c. 上传插图文件并获取七牛云 CDN 域名外链
+        end
+        P->>P: 7d. 在 Markdown 中重写插图链接为七牛云 CDN 绝对路径
+    end
+    
+    P-->>H: 8. 返回清洗转换出的标准英文 Markdown 文本
+    H->>P: 9. 写入本地物理缓存 Markdown/ 目录
+    H->>DB: 10. 更新数据库 markdown_path 记录
+    H-->>U: 11. 返回标准 Markdown 内容渲染展示
+```
+
+#### 详细解析说明：
+1. **HTML 转换为 Markdown 保护公式**：由于 MathJax/LaTeX 在 Markdown 转换中极易被当成普通字符进行转义（例如 `_` 倾斜或 `\` 换行失效），解析器在 HTML 解析前，通过正则将 `$` / `$$` 或 `\(` / `\[` 中的内容全部替换为特定的 UUID 占位符，转换为标准 Markdown 之后，再反向替换恢复公式，确保 LaTeX 渲染无损。
+2. **PDF 复杂排版降级**：遇到无法直接提取 HTML 的老文献时，调用 MinerU 进行布局分析与公式提取，配合七牛云对象存储实现插图的自动提取、自动图床托管与正文自动替换回写。
+
+---
+
+### 2.3 智能对照翻译流程 (Translation Flow)
+
+本流程实现了基于天文学专属词汇表的 LLM 专业对比翻译，其详细步骤与交互如下：
+
+```mermaid
+sequenceDiagram
+    participant U as 用户 (React 前端)
+    participant H as 处理器 (handlers.rs)
+    participant T as 翻译器 (translation.rs)
+    participant D as 天文词典 (dictionary.rs)
+    participant L as 大模型 (LLM API)
+    participant DB as 本地数据库 (SQLite)
+    
+    U->>H: 1. 请求文献对比翻译 (POST /api/translate, 含 bibcode, force)
+    H->>DB: 2. 查询文献路径及状态
+    alt force == false 且本地已存在翻译缓存文件
+        H->>H: 3. 读取本地 Translation/{bibcode}_zh.md 物理文件
+        H-->>U: 4. 直接返回缓存译文，流程结束
+    end
+    
+    H->>H: 5. 读取对应的英文解析 Markdown 物理文件
+    H->>T: 6. 调度翻译器执行翻译工作流
+    
+    T->>D: 7. 加载本地 dictionary.txt 并初始化 Trie 树结构
+    T->>D: 8. 执行英文 Markdown 文本分词匹配
+    D->>D: 9a. 进行前缀匹配检索
+    D->>D: 9b. 遵循“最长匹配优先”原则，过滤子词去重
+    D-->>T: 10. 返回该篇文献提取出的天文学名词对照 (Glossary)
+    
+    loop 针对英文 Markdown 进行段落分块 (Token 长度控制)
+        T->>L: 11. 携带 Glossary + 英文原文段落发送 Prompt 请求
+        note over L: LLM 遵循系统 Prompt 约束：<br>1. 专业词汇严格对应 Glossary 译出<br>2. 严禁改变 LaTeX 公式及 Markdown 标签<br>3. 保持中英段落高度对齐
+        L-->>T: 12. 返回学术级双语对照翻译段落
+    end
+    
+    T->>T: 13. 拼接所有段落，生成完整的对照 Markdown
+    T->>H: 14. 写入本地物理缓存 Translation/ 目录
+    H->>DB: 15. 更新数据库中的 translation_path 字段
+    H-->>U: 16. 返回翻译后 Markdown 渲染展示
+```
+
+#### 详细步骤说明：
+1. **分级翻译缓存机制**：
+   - 第一级缓存：若未开启 `force` 且本地物理磁盘已存在对应翻译文件，直接读取并返回，避免不必要的 LLM API 调用消耗。
+   - 第二级缓存：必须先完成英文 Markdown 的结构化解析，否则接口返回 `400` 错误，引导用户先进行正文解析。
+2. **基于 Trie 树的天文学名词提取**：
+   - 字典类 `Dictionary` 会加载包含数十万词条的本地天文词表 `dictionary.txt`。
+   - 为防止短词覆盖长词（如 `Hertzsprung` 覆盖 `Hertzsprung-Russell diagram`），分词匹配采用 Trie 树的最长前缀匹配。若匹配到长词，自动忽略其包含的子词。
+   - 最终只保留文献中真实出现的名词并去重，以 JSON 的形式构建为专有提示词（Glossary）注入 LLM 提示中。
+3. **LLM 强约束 Prompt 设计**：
+   - 在向大模型发送请求时，利用 System Prompt 声明其“天文学专业翻译家”的角色。
+   - 强制约定格式要求：所有的 LaTeX 公式（`$` / `$$`）必须原封不动保留，Markdown 的标题（`#`）、列表（`-`）、加粗（`**`）等语法严禁破坏，使前端可以无缝解析双语结构并左右对齐渲染。
+
+---
+
+## 3. 核心模块说明
+
+- **[src/download.rs](../src/download.rs)**:
+  - 包含浏览器头伪装与请求延迟控制。
+  - 处理 ADS Link Gateway 路由重定向追踪与 `validate.perfdrive.com` 防护解码绕过。
+  - 实现官方 `arxiv.org/html` 优先及 `ar5iv` 兜底，自动去除版本号后缀。
+- **[src/parser.rs](../src/parser.rs)**:
+  - 实现 HTML 语法树向 GFM Markdown 的逆向转换，使用占位符保护机制防止 MathJax/LaTeX 公式被误解析。
+  - 统一相对图表链接，并集成 MinerU PDF 解析。
+- **[src/translation.rs](../src/translation.rs)**:
+  - 利用本地千万字级别的天文学双语词典对原文进行分词匹配，注入系统提示词让 LLM 实现学术级精细翻译。
+- **[dashboard/src/components/CitationGalaxyCanvas.tsx](../dashboard/src/components/CitationGalaxyCanvas.tsx)**:
+  - 基于原生 HTML5 Canvas 开发的轻量级、高性能力导向图星系物理引擎，用于文献引文网络拓扑结构的可视化渲染。
+

docs/contributing.md

@@ -0,0 +1,60 @@
+# AstroResearch Contributing Guide / 参与贡献
+
+我们欢迎社区共同参与 AstroResearch 的开发与优化。以下是关于本地开发调试、代码规范和测试的说明。
+
+---
+
+## 1. 开发者本地环境搭建 (Developer Setup)
+
+### 后端开发环境 (Rust)
+1. 准备 Rust 工具链 (Edition 2021)。
+2. 安装 SQLx CLI（可选，用于生成迁移文件）：
+   ```bash
+   cargo install sqlx-cli --no-default-features --features sqlite
+   ```
+3. 启动开发模式下的 Rust 服务：
+   ```bash
+   cargo run
+   ```
+
+### 前端开发环境 (React + TypeScript)
+1. 进入 `dashboard` 目录，安装依赖：
+   ```bash
+   cd dashboard
+   npm install
+   ```
+2. 启动开发服务器（支持 HMR 热更新及 API 请求代理转发）：
+   ```bash
+   npm run dev
+   ```
+
+---
+
+## 2. 编码规范 (Coding Style Guidelines)
+
+### Rust 规范 (Backend)
+- 遵循 Rust 官方标准样式，提交前必须执行 `cargo fmt` 与 `cargo clippy`。
+- 注释和系统日志建议统一使用中文，便于开发者追踪和阅读。
+- API handers 中的异常信息请使用 `anyhow` 或 `thiserror` 进行结构化抛出。
+
+### React & TypeScript 规范 (Frontend)
+- 严格遵循 `React 18/19` 函数式组件写法，使用 React Hooks 维护状态。
+- 为保证生产编译成功，务必开启类型安全限制（如在导入纯类型时显式使用 `import type { ... }`）。
+- CSS 层面使用 Tailwind CSS 统一的磨砂玻璃体 (Glassmorphism) 及响应式布局，所有间距、颜色严格使用 CSS 变量控制以支持主题切换。
+
+---
+
+## 3. 测试与验证 (Testing)
+
+### 运行后端单元测试
+系统为各个下载、解析、词典分词、接口提取等模块设计了健全的测试。运行测试命令：
+```bash
+cargo test
+```
+
+### 运行前端校验
+```bash
+cd dashboard
+npm run build   # 运行 TypeScript 类型检查及 Vite 打包编译
+```
+确保无编译 Error 或 Warn 警告后方可提交 PR。

docs/database.md

@@ -0,0 +1,77 @@
+# AstroResearch Database Schema / 数据库设计
+
+AstroResearch 使用轻量级、零配置的 **SQLite** 数据库作为持久化存储。数据库文件默认保存在项目根目录下的 `astro_research.db`，由 Rust 中的 `sqlx` 驱动管理并自动执行迁移。
+
+---
+
+## 1. 实体关系图 (Entity-Relationship Diagram)
+
+```mermaid
+erDiagram
+    PAPERS {
+        text bibcode PK
+        text title
+        text authors "JSON Array"
+        text year
+        text pub "Journal/Publisher"
+        text keywords "JSON Array"
+        text abstract
+        text doi
+        text arxiv_id
+        integer citation_count
+        integer reference_count
+        text pdf_path
+        text html_path
+        text markdown_path
+        text translation_path
+        datetime created_at
+    }
+
+    NOTES {
+        integer id PK
+        text bibcode FK
+        integer paragraph_index
+        text note_text
+        text highlight_color
+        text selected_text
+        datetime created_at
+    }
+
+    CITATIONS_REFERENCES {
+        text source_bibcode PK
+        text target_bibcode PK
+    }
+
+    PAPERS ||--o{ NOTES : "has"
+    PAPERS ||--o{ CITATIONS_REFERENCES : "cites / cited_by"
+```
+
+---
+
+## 2. 数据表结构详述 (Table Schema Details)
+
+### 2.1 papers 表 (文献元数据)
+存储文献的核心元数据和本地物理存储路径。
+- **索引**：
+  - `idx_papers_doi` -> 基于 `doi`
+  - `idx_papers_arxiv_id` -> 基于 `arxiv_id`
+
+### 2.2 citations_references 表 (引文与参考文献拓扑)
+多对多关联表，存储文献之间的引用网络（即拓扑星系图的基础数据）。
+- **复合主键**：`(source_bibcode, target_bibcode)`
+- **索引**：
+  - `idx_citations_ref_source` -> 优化以 `source_bibcode` 查询参考文献
+  - `idx_citations_ref_target` -> 优化以 `target_bibcode` 查询被引文献
+
+### 2.3 notes 表 (高亮与阅读笔记)
+存储学者在阅读器中对特定段落创建的高亮和笔记。
+- **外键**：`bibcode` 级联删除 (`ON DELETE CASCADE`)。
+- **索引**：
+  - `idx_notes_bibcode` -> 优化单篇文献的笔记列表查询。
+
+---
+
+## 3. 数据库迁移说明
+迁移脚本存放在 `migrations/` 下，服务启动时（`src/main.rs`）会自动调用 `sqlx::migrate!().run(&pool).await` 自动部署：
+1. `20260608000000_init.sql`：初始化 `papers` 与 `citations_references` 结构。
+2. `20260608000001_notes.sql`：添加 `notes` 笔记高亮表，并为关联建立级联删除。

docs/deployment.md

@@ -0,0 +1,46 @@
+# AstroResearch Deployment Guide / 部署指南
+
+AstroResearch 的后端服务是由 Rust 编译出的单执行文件，它内置托管了前端 React 的静态构建资源，因此生产部署十分简单。
+
+---
+
+## 1. 系统要求与环境依赖 (Requirements)
+
+- **操作系统**：Linux / macOS / Windows
+- **运行环境**：
+  - Node.js (v18+) 用以构建前端 React 资源
+  - Rust (1.75+) 用以编译后端 Axum 进程
+  - SQLite (自动内置，无需单独部署)
+
+---
+
+## 2. 生产构建步骤 (Production Build Steps)
+
+### 步骤 1：构建 React 前端静态资源
+进入 `dashboard` 文件夹，安装依赖并执行编译命令。编译产物会自动输出在 `dashboard/dist` 目录下：
+```bash
+cd dashboard
+npm install
+npm run build
+```
+
+### 步骤 2：编译 Rust 后端二进制文件
+返回项目根目录，通过 Cargo 构建 Release 版本的执行文件。编译后的程序会内置链接 `dashboard/dist` 下的全部静态资源：
+```bash
+cd ..
+cargo build --release
+```
+编译产物位于 `target/release/astroresearch`。
+
+---
+
+## 3. 服务部署与启动 (Running in Production)
+
+1. 将编译出来的 `target/release/astroresearch` 二进制文件部署到目标服务器。
+2. 在二进制文件同一目录下，创建并填写 `.env` 环境变量配置文件（可从根目录的 `.env.example` 复制模板）。
+3. 确保本地相对路径下拥有天文对照词典文件 `dictionary.txt`。
+4. 运行后端服务：
+   ```bash
+   ./astroresearch
+   ```
+5. 进程将默认在后台启动并监听 `http://localhost:8000` 端口。你可以通过 Nginx 将此端口反向代理到公网 80/443 端口。

docs/design.md

@@ -0,0 +1,44 @@
+# AstroResearch Design Systems / 设计系统与交互体验
+
+AstroResearch 的前端界面设计坚持“未来科技感与学术沉浸”的理念，结合了现代网页设计的高级质感。
+
+---
+
+## 1. 视觉系统 (Visual Palette)
+
+### 1.1 精致双色主题
+
+AstroResearch 完美适配了深色与浅色模式。使用精挑细选的 HSL 柔和色彩代替刺眼的饱和色：
+
+| 模式 | 背景色 | 主文本色 | 卡片容器 | 毛玻璃效果 (Glassmorphism) |
+| :--- | :--- | :--- | :--- | :--- |
+| **深色模式** | 深夜极光黑 (`#090d16`) | 纯净雪白 (`#f8fafc`) | 磨砂深灰 (`bg-slate-900/60`) | 边框: `border-slate-800/80`, 模糊: `backdrop-blur-md` |
+| **浅色模式** | 雅致灰石色 (`#f8fafc`) | 深石板色 (`#0f172a`) | 磨砂亮白 (`bg-white/60`) | 边框: `border-slate-200/80`, 模糊: `backdrop-blur-md` |
+
+---
+
+## 2. 核心交互组件 (Key Interactive Components)
+
+### 2.1 引文星系图谱 (Citation Galaxy Map)
+- **底层技术**：完全脱离第三方庞大的 D3/G6 依赖，基于 HTML5 `<canvas>` 开发的自研力导向算法。
+- **物理特性**：支持节点排斥力、中心引力、拖拽阻尼，双击节点可以动态多层级向外衍生（最高限制 50 节点以防止布局凌乱）。
+- **色彩微效**：中心节点使用亮色光晕，参考文献与被引文献用渐变飞线标出，鼠标滑过产生平滑的高亮微动特效。
+
+```mermaid
+graph LR
+    C((中心文献)) -->|Cites| R1((参考文献 A))
+    C -->|Cites| R2((参考文献 B))
+    B1((被引文献 X)) -->|Cites| C
+    B2((被引文献 Y)) -->|Cites| C
+    classDef center fill:#ec4899,stroke:#db2777,stroke-width:2px;
+    classDef ref fill:#3b82f6,stroke:#2563eb,stroke-width:1px;
+    classDef cite fill:#10b981,stroke:#059669,stroke-width:1px;
+    class C center;
+    class R1,R2 ref;
+    class B1,B2 cite;
+```
+
+### 2.2 双分栏阅读器 (Split Reader)
+- **结构化排版**：中英文双栏段落基准对齐，完美融合 `rehype-katex` 数学公式渲染和 `html2md` 图片嵌入。
+- **划词标注与高亮**：鼠标选中阅读器任意段落词句，即刻浮现气泡菜单（支持 4 种高亮配色）。
+- **浮动词汇浮屠**：检测到英文正文中含有天文学专业词汇时，自动显示下划线，悬浮可阅读中文释义对照。

docs/troubleshooting.md

@@ -0,0 +1,44 @@
+# 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` 日志。
+
+### 1.2 官方 HTML (arxiv.org/html) 下载返回 404
+- **原因**：arXiv 官方 HTML 正文服务仅在 **2023年12月** 之后提交的论文中默认提供。对于老文献，直接请求官方 HTML 会返回 404。
+- **解决机制**：AstroResearch 的 `download_arxiv_html_with_fallback` 会在官方 HTML 请求失败时，**自动无缝降级回退**到 `ar5iv.labs.arxiv.org` 服务进行拉取。
+
+---
+
+## 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. 数据库与运行环境问题 (Runtime & DB Issues)
+
+### 3.1 启动提示 "Database Migration Failed"
+- **原因**：本地 SQLite 数据库文件 `astro_research.db` 出现并发锁死或版本 schema 冲突。
+- **解决方法**：
+  1. 备份并临时删除根目录下的 `astro_research.db` 数据库文件。
+  2. 重新启动服务：`cargo run`，系统将重新执行 `migrations/` 下的全部 SQL 迁移脚本以建立最新库结构。