AstroResearch/docs/api.md

AstroResearch REST API Documentation / REST API 接口文档

AstroResearch 后端服务运行于 Rust Axum 框架之上，默认基准 URL 为 http://localhost:8000/api。

---

1. 共享类型定义 (TypeScript Type Definitions)

为了前后端类型一致，以下是主要的 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 示例:

  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:

  {
    "bibcodes": ["2024arXiv241011663H", "1984AJ.....89..374B"]
  }
  

• Response Schema:

  {
    "bibtex": "@ARTICLE{2024arXiv241011663H, ...}\n\n@ARTICLE{1984AJ.....89..374B, ...}"
  }
  

• cURL 示例:

  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 示例:

  curl "http://localhost:8000/api/library"
  

2.2.2 触发并行文献下载

• Endpoint: POST /api/download
• Description: 触发后台线程拉取文献的 PDF 及 HTML。如果是 arXiv 来源优先官方 HTML 兜底 ar5iv，并支持强制更新。
• Request Body:

  {
    "bibcode": "2024arXiv241011663H",
    "force": false
  }
  

• Response Schema (StandardPaper): Returns the updated paper structure with is_downloaded: true.
• cURL 示例:

  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:

  {
    "bibcode": "2024arXiv241011663H",
    "force": false
  }
  

• Response Schema:

  {
    "markdown": "# 论文标题\n\n## 1. 绪论\n..."
  }
  

• cURL 示例:

  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:

  {
    "paper": { ... },
    "english_content": "# Abstract...", // 若未解析，返回 null
    "translation_content": "# 摘要..." // 若未翻译，返回 null
  }
  

• cURL 示例:

  curl "http://localhost:8000/api/paper?bibcode=2024arXiv241011663H"
  

2.3.2 触发 LLM 对照翻译

• Endpoint: POST /api/translate
• Description: 将英文 Markdown 提取本地词典名词注入 Glossary 提示词，并调用大模型进行学术翻译，最后写回本地物理文件并入库。
• Request Body:

  {
    "bibcode": "2024arXiv241011663H",
    "force": false
  }
  

• Response Schema:

  {
    "translation": "# 翻译结果..."
  }
  

• cURL 示例:

  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:

  {
    "bibcode": "2024arXiv241011663H",
    "title": "...",
    "citation_count": 12,
    "reference_count": 48,
    "references": ["bibcode1", "bibcode2"],
    "citations": ["bibcode3", "bibcode4"]
  }
  

• cURL 示例:

  curl "http://localhost:8000/api/citations?bibcode=2024arXiv241011663H"
  

---

2.5 笔记高亮模块 (Notes & Highlights)

2.5.1 创建笔记与高亮

• Endpoint: POST /api/notes
• Description: 对指定文献的特定段落位置创建高亮选段，并记录文字备注。
• Request Body:

  {
    "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 示例:

  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 示例:

  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:

  {
    "status": "success"
  }
  

• cURL 示例:

  curl -X DELETE "http://localhost:8000/api/notes?id=5"
  

---

3. 常见 HTTP 状态码与异常处理 (Error Codes)

系统基于标准的 HTTP Status Codes 返回错误原因，响应的 Response Body 中通常为纯文本提示（String）：

状态码	错误类型	触发常见场景及原因说明
400 Bad Request	业务请求不合规	- 文献未下载/解析却直接调用 translate。 - 未在 .env 中提供 ADS_API_KEY 时调用 export。
404 Not Found	资源未找到	- 数据库中没有该 Bibcode 的收藏记录。
500 Internal Error	服务器内部错误	- 第三方 LLM / ADS 接口通信超时或返回异常。 - 本地磁盘 IO 失败（如写入文件权限受阻）。 - 数据库查询异常。